`RelationshipsOverlay.merge` 對解析後重複的 relationship id `fatalError`——一份畸形 .docx 讓任何序列化路徑 SIGTRAP 整個 process（follow-up finding from che-word-mcp#199 verify R2）

[kiki830621]

Problem

RelationshipsOverlay.merge（Sources/OOXMLSwift/IO/RelationshipsOverlay.swift:56）用 Dictionary(uniqueKeysWithValues: typedRels.map { ($0.id, $0) }) 建索引。word/_rels/document.xml.rels 只要有兩條 relationship 的 id 在 XML 解析後相同——純粹寫兩次 Id="rId5"，或 Id="rId5" 與 Id="rId5"（NSXML 在 parse 期就解碼）——這行就 Fatal error: Duplicate values for key: 'rId5'，process 以 SIGTRAP 結束。

che-word-mcp#199 verify R2 的 DA 實測：save_document 對同檔本來就 crash（gate 在 base 就呼叫 writeData）；#199 把唯讀的 list_images 也接上 writeData 後，list 也會把整個 MCP server 打死。che-word-mcp 端會在序列化前預檢重複 id 當緩解，但 library 不該對可從磁碟讀入的資料 fatalError。

Type

bug

Expected

merge 對重複 id 拋可捕捉的錯誤（具名 part 與 id），或以「後者覆蓋前者／保留第一條」的明確政策合併並在報告中具名；reader 端亦可在讀入時就拒絕／去重。

Actual

fatalError，整個 process 終止。

---

Source: surfaced during /idd-verify che-word-mcp#199 R2 (Step 5b follow-up triage). Verify report: PR PsychQuant/che-word-mcp#218 (Verify R2 comment)
Refs PsychQuant/che-word-mcp#199

Current Status

Phase: needs-fix
Last updated: 2026-09-06 by idd-verify (R3 → fix round 3 landed; R4 running) — unattended /idd-all, cluster PR #141

Key Decisions

• Verify R3 FAIL（六 lens）：cluster: PackageInspector parses XML with the reader's parser, and no serialization path traps (#137, #138, #139) #141 (comment) — 兩個根因：R2 的 B7「開 namespace 處理即拒未宣告前綴」是假修（libxml2 SAX 只記錄 nsWellFormed；守門測試把 <zz:x/> 放在根元素之後、revert 整個修法照綠）；R2 用 lowercased() 索引模擬檔案系統本身是新的靜音開關（碰撞時依封裝順序選、APFS 摺 U+017F、./ 收合）。
• fix round 3（3807b6a，在隔離 worktree 完成、ff-merge 進 cluster branch）：inspector 改走 reader 自己的 ZipHelper.unzip、part 以 OPC 位址組字串交檔案系統查（不模擬）；解壓失敗／無 word/document.xml → invalidDocx；delegate 自判未宣告前綴（真實 writer 唯一會產生的那一類）；撤回「reader 拒的 inspector 也拒」全稱宣稱（DA D1 裁決：走封閉列舉——拒絕理由四類、不模擬的 namespace 類別點名、isConsistent 是關係陳述），以 leniency 測試釘住；預檢驗完整 UTF-8、自閉合算深度；writer 以 rels 檔存在判斷、拒非 UTF-8／零長度／含註解／CDATA／前綴 <Relationship> 的 rels、訊息依成因分句（DocxWriter 把 rId1–rId4 寫死給 styles/settings/fontTable/numbering——真實封裝若把 rId1 用在圖片就無法存檔（sister concern from #139） #140 亦然）。1512 tests / 0 failures。
• 效能（release、740 份、三代）：合計 2043 → 1663 → 6204 ms、中位 0.21 → 0.14 → 5.3 ms——每份約 5 ms 固定解壓 IO，是不模擬檔案系統的價錢，CHANGELOG 照實寫。
• Follow-ups R3：ooxml-swift#143（strict namespace image type 不對稱）；xmlns 數軸與屬性密集常數併 IO 層對不受信任 .docx 無大小上限：0.56 MB 檔 → 1.7 GB RSS / 39 s；PackageInspector 新增一次不受信任讀取 #130；合法 rels 拼法 round-trip → writer 端仍以原始 rels 文字比對已解碼的 model id：hasNewTypedRelationships 與 RelationshipsOverlay.parseRels 是 #137 的同一反模式（sister concern from #137） #142；固定槽 → DocxWriter 把 rId1–rId4 寫死給 styles/settings/fontTable/numbering——真實封裝若把 rId1 用在圖片就無法存檔（sister concern from #139） #140。
• R2：https://github.com/PsychQuant/ooxml-swift/pull/141（Verify (R2) comment）；R1 同 PR。MAX_ROUND=2 已超（standing instruction：全 IDD 走完）。

Blocking

• R4 ensemble（4 lens + Codex + DA）on 3807b6a 進行中；PASS → merge PR cluster: PackageInspector parses XML with the reader's parser, and no serialization path traps (#137, #138, #139) #141、tag v3.7.0、idd-close ×3；FAIL → fix round 4。

[kiki830621]

Diagnosis

Type

bug

Root Cause / Analysis

RelationshipsOverlay.merge 第 56 行用 Dictionary(uniqueKeysWithValues: typedRels.map { ($0.id, $0) }) 建索引，對重複 key 直接 fatalError → SIGTRAP，整個 process 死。

觸發路徑比 issue 原文更寬：DocxWriter.writeDocumentRels 選 overlay 的條件是 document.archiveTempDir != nil && !originalRelsXML.isEmpty，與 overlayMode 旗標無關——所以連 writeData（文件註解說「always uses scratch mode」）在「從磁碟讀入的文件」上也走 merge。che-word-mcp#199 verify R2/R3 實測：一份 rels 宣告兩次同 id 的 .docx，讓不帶旗標的 save_document 打死整個 MCP server（rc=-5），連同所有開啟中文件的未存編輯。

typed 側的重複來源有二：rels 裡字面寫兩次同 id；或 rId5 與 rId5 經 NSXML 解碼後撞號（#137 的另一面）。

Impact

• 影響的檔案：Sources/OOXMLSwift/IO/RelationshipsOverlay.swift（+ DocxWriter 的呼叫端加 try）。
• 影響的使用者流程：所有序列化路徑——write(_:to:)、writeData、以及任何經由它們的 save gate 檢查。
• library 不該對「可從磁碟讀入的資料」fatalError：這是 #175 家族的同一條原則（回報管道不得說謊，也不得直接消失）。

Strategy

• merge 改 throws：偵測 typed rels 內重複 id → 拋具名的 WordError（列出 part 與重複的 id），不再 fatalError
• serializeScratchRels 同樣檢查（scratch 路徑重複 id 會產出違反 OPC 的封裝，只是不 trap）
• DocxWriter 呼叫端加 try 傳播；write/writeData 的 throws 契約不變（本來就 throws）
• inspector 報告新增 duplicateRelationshipRefs: [ImageRelationshipRef]（同一 part 內宣告 ≥2 次的 id，任何 type）——讓 consumer 在序列化前就能具名診斷（che-word-mcp#199 的 duplicateTypedRelationshipIds 由此刪除）
• 測試：字面重複與 entity-撞號兩種 fixture 各自 → XCTAssertThrowsError（不是 crash）、訊息含 part 與 id；正常文件不受影響
• CHANGELOG 3.7.0（明列失敗集合擴大）

Conflict Class

C_shared_module_coord — 共享資源是 Sources/OOXMLSwift/IO/PackageInspector.swift（#137/#138 同檔）與 RelationshipsOverlay.swift（#139），且三者由同一個下游 consumer（che-word-mcp#199 的 save gate 與 list_images）一起消費。三張合成一個 cluster PR（branch idd/cluster-inspector-xmlparser）序列實作，不交錯。

Complexity

Plan

Layer 2 命中（ImageConsistencyReport 是 published API、merge 的失敗語意對外可見），但 Layer 3 只命中一項（architectural decision）；依 Plan-Spectra 分界，這是既有 published surface 的加法與失敗語意收斂，不需要新的 frozen spec contract → Plan。Plan tier 的 approval gate 已由使用者在 che-word-mcp#199 verify R3 的 A/B/C 決策中滿足（使用者選 A =「根因修在 ooxml-swift、發 3.7.0、che-word-mcp 刪除模擬層」），本 diagnosis 的策略即該決定的展開。

Risks

• 改用 XMLParser = 嚴格解析：目前的 regex 掃描對非 well-formed 的 part 照樣給答案。改後解析失敗的 part 進 unparsableParts 並不產生孤兒（避免把「未知」誤報成「孤兒」而讓合法檔案存不了——che-word-mcp#199 R3-B4 正是這個形狀），由 consumer 決定 fail-closed。
• 效能：SAX 解析每個 part 比 regex 掃描重。以 17.5 MB／9 圖文件量測並記進 CHANGELOG；save gate 本來就付一次序列化（820 ms），可負擔。
• merge 改 throwing：RelationshipsOverlay 是 internal，非 public API break；但 DocxWriter.writeData / write(_:to:) 的失敗集合擴大（原本會 trap 的輸入現在拋 WordError）——這正是 RelationshipsOverlay.merge 對解析後重複的 relationship id fatalError——一份畸形 .docx 讓任何序列化路徑 SIGTRAP 整個 process（follow-up finding from che-word-mcp#199 verify R2） #139 要的，CHANGELOG 明列。

Residue

本案讓 writer 對重複 id 誠實失敗。要讓這種封裝能被修好（例如 reader 端去重並重新編號、或提供 repairRelationshipIds()）是另一件事，不在此案；#199 的下游只需要「不要死」。

[kiki830621]

Implementation Complete

Cluster PR（#137 / #138 / #139 共用一枝 branch idd/cluster-inspector-xmlparser 與一個 PR）：#141

Checklist

• PackageInspector 改用 XMLParser 掃描 rels 與 part（904d9cc）——id / type / reference 全取自 attributeDict，實體與屬性空白正規化由 parser 負責；stripComments 與四條 regex 全部刪除；註解走 foundComment:、CDATA 走字元事件
• 解析失敗的 part 進 unparsableParts 且不產生孤兒（904d9cc）
• 新增 declaredImageRelationshipRefs / duplicateRelationshipRefs / unparsableParts + public memberwise init（904d9cc）
• merge 去 Dictionary(uniqueKeysWithValues:)、first-wins 永不 trap；writeDocumentRels 序列化前具名拒絕重複 id（9cba713）
• Issue137to139InspectorParserTests 15 案例（5d77ce4）
• CHANGELOG 3.7.0（5d77ce4）
• swift test：1487 tests, 0 failures, 28 skipped

Commits

• 904d9cc fix: PackageInspector scans with the reader's XML parser, not attribute regexes (PackageInspector 的 relationship Id 不做 XML entity 解碼——Id="rId6" 與 reader 解碼後的 rId6 比不上（follow-up finding from che-word-mcp#199 verify） #137, PackageInspector.stripComments 的 <!--.*?--> 對未閉合 <!-- 呈二次退化——5 KB 的 .docx 讓檢查跑一分鐘（follow-up finding from che-word-mcp#199 verify） #138)
• 9cba713 fix: refuse duplicate relationship ids instead of trapping the process (RelationshipsOverlay.merge 對解析後重複的 relationship id fatalError——一份畸形 .docx 讓任何序列化路徑 SIGTRAP 整個 process（follow-up finding from che-word-mcp#199 verify R2） #139)
• 5d77ce4 test: pin parser-backed scanning and the duplicate-id refusal; CHANGELOG 3.7.0

Notes

• 測試不寫死期望字串：每種 id 寫法（6 / 6 / 二十二位補零 / 字面 TAB / LF / CRLF / & / 雙重編碼）都與 XMLDocument（NSXML，reader 用的同一條路）對同一份 rels 讀出的值比對——斷言的是等價，不是我對 XML 規則的猜測。
• 三種病態註解 payload（未閉合 ×20000、(-->)×N (<!--)×N、nested + 換行）現在合計數十毫秒；舊版各 35–60 s。
• writeDocumentRels 的 overlay 選擇條件是 archiveTempDir != nil、與 overlayMode 旗標無關，所以 writeData（註解說 always scratch）對從磁碟讀入的文件也走 merge——這是 trap 在唯讀路徑上也會炸的原因，diagnosis 已更正 issue 原文的觸發面。

Sister Bugs Filed

• Filed: DocxWriter 把 rId1–rId4 寫死給 styles/settings/fontTable/numbering——真實封裝若把 rId1 用在圖片就無法存檔（sister concern from #139） #140 — DocxWriter 把 rId1–rId4 寫死給 styles/settings/fontTable/numbering，真實封裝若把 rId1 用在圖片就無法存檔（RelationshipsOverlay.merge 對解析後重複的 relationship id fatalError——一份畸形 .docx 讓任何序列化路徑 SIGTRAP 整個 process（follow-up finding from che-word-mcp#199 verify R2） #139 前是 SIGTRAP，本 PR 後是具名錯誤；根治要讓固定 part 的 id 走 allocator）
• Skipped: (none)

[kiki830621]

Verify (R1, via cluster PR #141)

Result: FAIL — 6 blocking（屬性 local-name 比對、「無定論」變靜音開關、二次退化搬進 libxml2、partial rels、DTD 政策分家、O(N²) 去重），fix round 已落地為 513ede6（1497 tests），R2 六路重驗中。
Full report: #141 (comment)

[kiki830621]

Verify (R2, via cluster PR #141)

Result: FAIL on 513ede6 — R1 的 B1–B6 收掉；DA 差分測試（3095 筆）抓到未宣告前綴的 reader/inspector 分歧、Word/ 大小寫靜音開關；另 UTF-16、深度、namespace 引用、writer fail-open 四族。fix round 2 已落地為 92befb9（1505 tests），R3 重驗中。
Full report: #141 (comment)

[kiki830621]

Verify R3 — cluster PR #141 head 92befb9: FAIL（six lenses；兩個根因：B7 假修、lowercased() 索引自身是靜音開關）→ fix round 3 已提交為 3807b6a，R4 進行中。

完整報告（六 lens 合併、DA D1 裁決、fix round 3 對照表、三代效能）：#141 (comment)