Document genoffice DOCX round-trip tradeoffs

[kiki830621]

Summary

• document genoffice docx-engine's no-op identity path, substring-splice edit path, and ZIP payload boundary
• compare its guarantees and failure modes with ooxml-swift/macdoc and python-docx
• record Word-canonical edge cases, render-fidelity limits, and practices worth borrowing
• link the full research note from the reference index

Verification

• git diff --cached --check before commit
• pinned-source assertions: genoffice commit, TypeScript line/test counts, save/patch/test anchors
• relative Markdown link targets verified
• changed-content privacy and secret-pattern scan passed
• docs-only change; no Swift or upstream TypeScript test suite was required or run

Refs #143

[kiki830621]

Not merged — this branch and main hold two different write-ups, not a draft and its revision

Asked to merge this after mergeable settled. It settled to CONFLICTING, and the conflict is not the ordinary kind.

docs/genoffice-roundtrip-comparison.md already exists on main

Landed by two direct commits, both tagged (#143):

1a43e59  2026-08-14  docs: genoffice round-trip 對照筆記 — substring-splice vs op log vs mutate-tree (#143)
1289739  2026-08-14  docs: verify in-scope fixes for genoffice round-trip 筆記 (#143)

So #143's output reached main by the direct-commit path while this PR was open. That alone would be routine — except the two versions have since diverged in both directions:

main   : 210 lines
branch : 314 lines
lines only on main   : 169
lines only on branch : 237

Neither is a subset of the other.

They are not the same document

Zero shared section headings:

only on main	only on this branch
7. 對 #142 的旁證（verify 後修正版）	Word-canonical 邊界：躲掉還是踩到 — with five sub-sections: root namespace 雲, rsid/w14:paraId/w14:textId, xml:space, pPr, rPr
9. 誠實邊界	最終判斷, 不宜直接移植的部分

Even the titles differ (genoffice round-trip 對照：substring-splice vs op log vs mutate-tree vs genoffice DOCX 窄幅修補與 macdoc round-trip 對照).

main's exclusive material is the verification round — patch.ts line references, the UTF-16 code-unit index detail, the test invariants. The branch's exclusive material includes the Word-canonical boundary analysis, which is directly relevant to #131.

Why I stopped

Merging this needs an editorial decision: which structure survives, and which passages from the other get folded in. Both are your research notes on the same investigation, and a mechanical resolution would either clobber the verified refinements on main or produce a stitched-together union that reads as neither.

Three ways out, none of which I should pick for you:

1. Close this PR. main already carries a verified version; the branch's extra material gets ported deliberately, in its own change, where the Word-canonical section can be aimed at Word-canonical forms 對齊 — 讓真實 Word 文件升級 DSL channel（format-alignment step 2） #131.
2. Rebase and reconcile by hand — keep main as the base and fold in the branch's sections, resolving each overlap.
3. Replace — decide the branch version is the better document and let it supersede, re-applying the verify-round corrections on top.

The other two conflicting hunks (reference/README.md) are the same shape: main already has a pointer note to the doc that this branch also adds, worded differently.

Unrelated, but in this diff

The branch also carries ae6aa3f chore: MeasureOCR 遷出至 bestOCR umbrella（submodule 解除） — .gitmodules and cli/FastOCR removals plus a CLAUDE.md edit. Whether that is still wanted is a separate question from the docs; CLAUDE.md on main has moved since (it now records the MeasureOCR migration in prose).

Meanwhile

#139's ### Blocking block was stale — it still named PR #152 and #153, both merged today. Updated: the real remaining gate is PR #151, whose leader #135 waits on owner-provided authority.