fix(mcp): 세션 편집 직후 페이지 어휘 스테일 — 채움·치환 후 pageCount·텍스트·렌더·검색 주소가 편집 전 레이아웃(실측 3쪽 vs 10쪽)

[kevin9327]

요약

mcp-serve 세션 편집(#3598 hwp_doc_fill_fields / #3601 hwp_doc_replace_text) 직후, 같은 핸들의 조회 4종이 편집 전 페이지네이션을 서빙합니다. 코어 편집 경로가 recompose_section(재조판 + dirty 마킹 + 캐시 무효화)까지만 하고 pagination 벡터를 갱신하지 않는데, 세션 조회는 전부 그 벡터를 읽기 때문입니다.

실측(4,620자 채움, samples/field-01.hwp):

	세션이 보고	저장본 신규 파싱(지상 진실)
hwp_doc_info.pageCount	3	10
hwp_doc_text page=5	isError: 페이지 범위 초과: 5 (0~2)	정상 690자
hwp_doc_render_page page=7	isError: 페이지 범위 초과: 7 (0~2)	정상 SVG
hwp_doc_search matches[].page	전부 0	여러 쪽 분산

오류가 나지 않는 것이 핵심입니다. 봉투는 isError:false 에 그럴듯한 숫자를 담아 돌려주고 에이전트는 그 숫자로 다음 판단을 합니다. hwp_doc_info 는 도구 설명에서 "편집 후 페이지 수 변화를 추적할 때 쓴다"고 명시하고, hwp_doc_render_page 는 "편집 직후 눈검증(VLM) 루프가 세션 안에서 닫힌다"고 약속하는데 — 정확히 그 용도에서 값이 갱신되지 않습니다.

상세 보고서: mydocs/report/mcp_session_repaginate/README.md

결함 구조 — 편집 3종의 비대칭

세션 도구	코어 경로	재페이지네이션
hwp_doc_set_cell	text_editing.rs 셀 편집 진입점이 paginate_if_needed() 호출	✔ 이미 정상
hwp_doc_fill_fields	field_query.rs::set_field_value_by_name_at → recompose_section 까지	✘ 스테일
hwp_doc_replace_text	search_query.rs::replace_all_native → recompose_section 까지	✘ 스테일

뿌리는 무상태 전제를 상태 유지 표면이 물려받은 것입니다. grep 모듈 헤더는 "from_bytes 가 로드 시 paginate() 를 끝내므로 순수 조회다"라는 전제를 명시하는데, 무상태 CLI 에서는 참이지만 세션에서는 첫 편집 순간 깨집니다. edit fill-fields 는 편집 직후 직렬화하고 프로세스가 끝나므로 pagination 을 다시 읽을 일이 없습니다 — 세션이 도입되며 생긴 새 수명에 맞는 갱신 지점이 set_cell 경로에만 있었습니다.

실측 — BEFORE

방금 자기가 만들어 낸 쪽을 세션이 존재하지 않는다고 거부합니다. 에이전트 입장에서는 편집이 실패한 것처럼 보이지만 IR 에는 정상 반영돼 있어, 재시도하면 같은 값이 한 번 더 채워지는 이중 편집 위험까지 생깁니다.

수정

1. DocumentCore::repaginate_if_needed() 공개 표면 추가 — 내부 paginate_if_needed() 위임. batch 모드 규약 유지, dirty 구역만 증분 재처리. 새 로직을 만들지 않고 set_cell 이 이미 쓰는 그 경로를 노출만 해서 세 편집이 같은 규약을 공유하게 했습니다.
2. 세션 편집 2종에서 도구 호출당 1회 호출 — fill 은 적용 목록이 비어 있지 않을 때 2차 적용 루프가 끝난 뒤 한 번(필드마다 부르면 N회 재조판), replace 는 치환 계수 1 이상일 때 한 번(0건 치환은 IR 불변이라 부르지 않음).

실측 — AFTER

세션 pageCount 10 == 저장본 신규 파싱 10. 편집이 만든 5쪽 텍스트를 곧바로 읽고 7쪽을 SVG 로 렌더 — 약속된 VLM 눈검증 루프가 실제로 닫힙니다.

회귀 가드 (신규 계약 테스트 2종)

• session_fill_repaginates_page_vocabulary — 세션 pageCount 를 저장본 신규 파싱과 대조(보고를 믿지 않고 지상 진실 확보) + 늘어난 마지막 쪽이 hwp_doc_text 로 읽히는지. 전제 확인(truth > before) 을 별도 assert 로 둬서, 샘플이 바뀌어 채움이 더는 쪽수를 늘리지 않으면 시험이 무의미해진 사실 자체가 실패로 드러납니다.
• session_replace_repaginates_page_vocabulary — 대량 치환 후 pageCount 증가와 검색 page 주소가 편집 전 마지막 쪽을 넘어서는지.

검증

• cargo test --test mcp_session_edit_contract --test mcp_session_query_contract — 12/12 (신규 2종 포함)
• cargo test --test mcp_session_view_contract --test mcp_session_setcell_contract --test mcp_server_contract — 15/15 무회귀
• cargo clippy --profile release-test --bin rhwp — 경고 0 / cargo fmt --check — 통과
• 실기 BEFORE(upstream/devel 빌드) / AFTER(수정 빌드) 각 2프로브 stdio 실측

범위 밖 (별도 PR 로 잇겠습니다)

• 저장 결과물은 종전에도 옳았습니다 — edit_serialize 는 IR 을 직렬화하므로 스테일 pagination 이 파일에 각인되지 않습니다. 이 결함은 세션이 보고하는 값의 문제입니다.
• 더 근본적으로는 조회 쪽에서 dirty 를 보고 지연 재페이지네이션하는 방식이 낫지만, 현재 조회 경로가 전부 &self 라 시그니처 변경이 광범위합니다. 편집 지점에서 미는 이번 방식이 범위 대비 효과가 크다고 판단했습니다.
• 같은 감사에서 나온 별개 결함들(배선 없는 선언 인자 7종, hwp_doc_text 의 잘못된 page 타입이 전체 덤프로 빠지는 문제, HWP3 세션 save 의 라이브 IR 변형 등)은 범위를 섞지 않기 위해 분리합니다.

🤖 Generated with Claude Code