feat(office): add bounded DOCX page layout contract

[seonghobae]

Closes #140.
Closes #341.

Purpose

Implement the bounded DOCX page-layout slice as next-release Inkspan work while protected main remains the release authority tracked by #118.

Current source identity

• Live protected base: main@3b38ead2d00f44eb578d0689087b9293b3dabe1e.
• Current exact Draft head: aa5b10ff9a5b0c35f1840b881ca4f2c06707b636 on feat/docx-page-layout.
• The branch already contains the non-destructive synchronization with protected main. All predecessor identities and their checks/reviews are historical only and do not pass the current head.

Test-first lineage

• Original RED 634d1ed1a7f7a29cd6681872a42ac49d330717d6 reached the Office product boundary and failed because the renderer rejected page_layout.
• Preflight-order RED ce809c3485e92729a9115c5d685fe187b313f7d3 / CI 31567029574 proved invalid layout was rejected only after content rendering; the repair validates layout first.
• Diagnostic-privacy RED 05475267ee3eb0d535af07ac828998611c8b89bb / CI 31587583073 proved caller-controlled unknown member names leaked into ordinary errors; the repair retains only structural path/category diagnostics.
• 4bd144047b9e573859097e29c17ae569b34a1817 bounded unknown-key scanning; d1148b4980c689e1a1a0fb6e7dc092f17ac60225 added the repeated-iterator-key regression so exotic mappings cannot evade progress indefinitely.
• ad497ed4150d4648206afd65487bf0a8b3d14a40 added payload-redaction for hostile page-layout mapping failures.
• New realistic RED c26e03fd2786019001ed1936538b631abc9b653d / CI 32577803247 proved a host Mapping whose validated page_layout value may be read only once was redundantly read by the safety facade. Office Python 3.11 job 97042606441 failed in safe_renderer.py on the second page_layout access with the test sentinel; the failure is causal evidence, not a generic infrastructure failure.
• Narrow repair aa5b10ff9a5b0c35f1840b881ca4f2c06707b636 snapshots the top-level page_layout value once, validates that snapshot, and builds the renderer payload without rereading that key. It does not weaken hostile-mapping validation or widen Inkspan authority.

Implemented boundary

The branch provides a bounded machine-readable DOCX page-layout contract: A4/Letter, portrait/landscape, integer 0–100 mm margins, fail-fast validation, bounded hostile-mapping handling, deterministic single-section OOXML application/canonicalization, payload-redacted diagnostics, single-read snapshot semantics for the top-level layout value, no partial publication on failure, real round-trip matrix coverage, structural-fidelity regressions, and explicit DOCX-only format enforcement. It does not add arbitrary page dimensions, multiple-section authority, headers/footers, durable print/PDF authority, network, persistence, credentials, tenancy, model, transport, authorization, or durable-audit authority.

Exact-current-head repository evidence

For exact head aa5b10ff9a5b0c35f1840b881ca4f2c06707b636 against live base main@3b38ead2d00f44eb578d0689087b9293b3dabe1e:

• repository CI 32577971012: completed / success;
• Security Scan 32577970957: completed / success;
• SAST Semgrep 32577970975: completed / success;
• Office Python 3.11 97043010867, 3.12 97043010776, 3.13 97043010879, and 3.14 97043010864: completed / success;
• the Python 3.11 log explicitly checked out exact aa5b10ff9a5b0c35f1840b881ca4f2c06707b636, passed 210 tests, reported 100% statement and branch coverage, built the wheel, and verified packaged schema/license;
• cross-engine Clipboard / Playwright 1.62.0 97043010860: completed / success;
• build-and-test completed under repository CI success, including typecheck, 100% coverage, library build, packed-consumer verification, and demo build;
• formal reviews: one historical Cursor COMMENTED review, explicitly non-approving;
• qualifying approving reviews: 0;
• unresolved inline review threads: 0.

No predecessor central/OpenCode/coverage/security status is transferred to this pushed head. Any separately applicable central/live-governance evidence must be reacquired for this exact head before lifecycle advancement. Pending, queued, skipped, cancelled, absent, neutral, failed, stale, predecessor, status-only, or model-only evidence is non-passing.

Governance and integration boundary

The product/source lane is repository-exact-head green, but this is not merge-ready: qualifying independent approval is absent and #118 still freezes protected v0.6.0 publication identity. Keep this PR Draft and unmerged. Refetch live rules, head/base, review/thread state, exact checkout SHAs, and every applicable current-head workflow before any future lifecycle transition; never transfer predecessor evidence, self-approve, weaken gates, force-push, destructively rebase, or synthesize tag/release identity from a branch ref.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 122a1949-9cbb-42b9-9e89-b3e8033e42c4

📥 Commits

Reviewing files that changed from the base of the PR and between af14e5c and aa98785.

📒 Files selected for processing (18)

• docs/TRACEABILITY.md
• docs/adr/0027-bounded-docx-page-layout.md
• docs/adr/README.md
• docs/doctoring/docx-page-layout.md
• docs/docx-page-layout.md
• office/src/inkspan_office/page_layout.py
• office/src/inkspan_office/safe_renderer.py
• office/src/inkspan_office/schema.json
• office/tests/test_page_layout.py
• office/tests/test_page_layout_content_fidelity.py
• office/tests/test_page_layout_error_privacy.py
• office/tests/test_page_layout_format_boundary.py
• office/tests/test_page_layout_matrix.py
• office/tests/test_page_layout_omission.py
• office/tests/test_page_layout_ooxml.py
• office/tests/test_page_layout_preflight.py
• office/tests/test_page_layout_structural_fidelity.py
• src/docxPageLayoutDocumentation.test.ts

---

📝 Walkthrough

Walkthrough

선택적 page_layout 계약을 DOCX 요청에 추가했습니다. 런타임은 입력을 검증하고 단일 섹션 DOCX에 레이아웃을 적용합니다. 스키마, 출력 충실도, 오류 처리, 문서 상태와 롤백 절차를 테스트하고 문서화했습니다.

Changes

DOCX 페이지 레이아웃

Layer / File(s)	Summary
계약과 상태 문서 docs/TRACEABILITY.md, docs/adr/..., docs/doctoring/..., docs/docx-page-layout.md, src/docxPageLayoutDocumentation.test.ts	A4 또는 Letter 용지, 세로 또는 가로 방향, 0~100mm 정수 여백을 사용하는 단일 섹션 DOCX 계약을 문서화했습니다. 기능 상태를 Proposed 및 implemented_on_active_pr로 유지합니다.
검증과 DOCX 적용 office/src/inkspan_office/page_layout.py, office/src/inkspan_office/safe_renderer.py, office/src/inkspan_office/schema.json	page_layout을 정규화하고 잘못된 입력과 다중 섹션 문서를 거부합니다. 검증된 레이아웃을 콘텐츠 렌더링 후 DOCX에 적용합니다.
계약 및 경계 검증 office/tests/test_page_layout.py, office/tests/test_page_layout_matrix.py, office/tests/test_page_layout_omission.py, office/tests/test_page_layout_preflight.py, office/tests/test_page_layout_format_boundary.py, office/tests/test_page_layout_error_privacy.py	용지와 방향 조합, 레이아웃 생략, 사전 검증, XLSX/PPTX 거부, 오류 메시지 비공개, 결정성을 검증합니다.
DOCX 출력 충실도 office/tests/test_page_layout_ooxml.py, office/tests/test_page_layout_content_fidelity.py, office/tests/test_page_layout_structural_fidelity.py	OOXML 페이지 속성과 여백을 확인합니다. 페이지 나누기, 메타데이터, 목록, 표, 외부 링크 및 이미지를 검증합니다.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related issues

• ContextualWisdomLab/inkspan 이슈 140 — 이 PR의 스키마, 렌더러, 검증, 문서 및 테스트 변경이 해당 bounded DOCX page_layout 계약을 구현합니다.

Possibly related PRs

• ContextualWisdomLab/inkspan#75 — 이 PR은 기존 문서 및 추적성 체계에 DOCX 페이지 레이아웃 ADR, 계약 문서 및 상태 추적을 추가합니다.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 64.52% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 제한된 DOCX 페이지 레이아웃 계약을 추가하는 변경 사항을 간결하고 정확하게 요약합니다.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/docx-page-layout

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

@coderabbitai review

Please review the exact current head aa987858e115340ccacf87eac299a386d0796e51. This remains Draft only because protected main is frozen for the 0.6.0 registry operational-acceptance boundary; review findings should still be evaluated against this exact head.

[coderabbitai]

@seonghobae I will review pull request #141 at exact head aa987858e115340ccacf87eac299a386d0796e51. I will evaluate findings against that commit, independent of the frozen protected main boundary.

---

🧠 Learnings used

Learnt from: CR
Repo: ContextualWisdomLab/inkspan PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-08-12T02:31:03.922Z
Learning: Do not infer shipped behavior from conversation history, PR bodies, model output, or predecessor-head evidence. Keep Proposed/Active-PR behavior distinct from implementation on Protected `main`, preserve fail-closed security and deterministic conversion boundaries, and update the smallest affected canonical documents plus tests when a durable contract changes.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cursor]

Review

This is the earliest open ADR 0027 claimant (0027-bounded-docx-page-layout, 2026-08-10). Later lanes #248/#249/#285, #320, and #360 reused 0027 for unrelated decisions.

Keep 0027 here. Do not renumber this record to make room for later collisions. Keep Draft while #118 owns v0.6.0. This comment is not a qualifying independent approval of the page-layout product slice.

  

_{Sent by Cursor Automation: Fix Issues}

[seonghobae]

Current-head triage for Strix run 32577970990 / job 97043047541 (aa5b10ff9a5b0c35f1840b881ca4f2c06707b636): no source mutation is warranted for VULN-0001 as reported.

• write_office_document accepts a caller-selected filesystem destination by contract. The package does not define a safe root; path authorization, tenant isolation, and directory permissions remain host/caller responsibilities (ADR 0013, lines 7, 17, and 31; office/README.md, lines 81-86). Strix's path-traversal PoC demonstrates that an explicitly supplied path is honored, but does not demonstrate crossing an Inkspan-owned boundary.
• The path.exists() check at safe_renderer.py:88-89 is only a fast user-facing conflict check. The non-overwrite commit at safe_renderer.py:104-108 is os.link(temporary, path), whose destination creation fails atomically with FileExistsError; the existing race regression office/tests/test_hardening.py::test_non_overwrite_write_is_race_safe exercises this boundary.
• I also reproduced the relevant filesystem semantics on this exact source: racing an existing destination symlink leaves its target unchanged; explicit overwrite uses Path.replace, which replaces the directory entry rather than following that symlink. The report's proposed O_CREAT|O_EXCL does not address the separate caller-owned safe-root question.

The report is retained as a blocked security-gate finding pending authoritative review, but its supplied PoC is not a demonstrated vulnerability under the documented path/ownership contract. No waiver, dismissal, ready, or merge action was taken.