`PackageInspector` 的 relationship Id 不做 XML entity 解碼——`Id="rId6"` 與 reader 解碼後的 `rId6` 比不上（follow-up finding from che-word-mcp#199 verify）

[kiki830621]

Problem

PackageInspector.imageRelationshipIds(inRels:) / referencedRelationshipIds(inPart:) 以正則直接抓屬性字面值（\bId\s*=\s*(["'])([^"']*)\1），不做 XML entity 解碼；而 DocxReader 走 NSXML，attribute(forName: "Id")?.stringValue 是解碼後的值。同一個 relationship Id="rId6"：reader 端是 rId6、inspector 端是 rId6。

任何把兩邊放在一起比的 consumer 都會錯：che-word-mcp#199 的 list_images 用 inspector 的 orphanImageRelationshipIds 對 getImages() 的列判定孤兒，entity 寫法的孤兒會被標 referenced: yes（security lens 實測，Direct Mode）。save gate 的 baseline 比對（qualified part:id 集合差集）兩邊都來自 inspector，所以內部一致，但同一 rel 在 reader 與 inspector 的名字不同仍是坑。

Type

bug

Expected

inspector 回傳的 id（orphanImageRelationshipIds / orphanImageRelationshipRefs.id）與 referencedRelationshipIds 的比對值都經標準 XML entity 解碼（&#NN; / &#xHH; / 五個預定義 entity），與 NSXML 讀出的值一致。

Actual

原始字面值；6 不會變成 6。

---

Source: surfaced during /idd-verify che-word-mcp#199 (Step 5b follow-up triage). Verify report: PsychQuant/che-word-mcp#218 (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

PackageInspector 用四條 NSRegularExpression 抓屬性字面值（imageRelationshipIds(inRels:) 取 Id/Type，referencedRelationshipIds(inPart:) 取 *:embed|link|id），完全不經 XML 的屬性值正規化與實體解碼；DocxReader 走 NSXML（libxml2），拿到的是解碼後的值。同一條 Id="rId6" 在兩邊是兩個名字。

這不只是 6 一種形狀。che-word-mcp#199 連三輪 verify 把整族攤開了：任意長度的補零字元參照（6）、屬性值裡的字面 TAB/CR/LF（XML 要正規化成空格）、CRLF 要先折成單一 LF 再變空格。下游試著在 consumer 端逐字模擬 libxml2 的三輪修補全部失敗——每輪都在更窄的邊界長出新形狀（verify R1→R2→R3：entity → 長參照/空白 → CRLF 折疊），因為那等於在 che-word-mcp 重寫半個 XML parser。

真正的修法在這裡：讓 inspector 用 XMLParser（同一個 libxml2）解析，屬性值的解碼與正規化由 parser 負責，語意與 DocxReader 定義上一致，不需要任何模擬。

Impact

• 影響的檔案：Sources/OOXMLSwift/IO/PackageInspector.swift（與 PackageInspector.stripComments 的 <!--.*?--> 對未閉合 <!-- 呈二次退化——5 KB 的 .docx 讓檢查跑一分鐘（follow-up finding from che-word-mcp#199 verify） #138 同檔、同一次改寫）。
• 影響的使用者流程：che-word-mcp 的 save gate（baseline 與當下報告的 id 比對）與 list_images 的孤兒判定；macdoc 經由兩者間接受益。
• 副帶收斂（同一次改寫）：CDATA 內的 <Relationship> 不再被當成宣告（XMLParser 把 CDATA 當文字）；註解由 foundComment: 忽略而非 regex 剝除。

Strategy

• PackageInspector 改用 XMLParser 掃描 rels 與 part（見 PackageInspector.stripComments 的 <!--.*?--> 對未閉合 <!-- 呈二次退化——5 KB 的 .docx 讓檢查跑一分鐘（follow-up finding from che-word-mcp#199 verify） #138 的同一次改寫）；id/type/reference 值全部取自 attributeDict（已解碼、已正規化）
• 新增 declaredImageRelationshipRefs: [ImageRelationshipRef]（每個 part 宣告的全部 image rel，宣告順序，id 已解碼）——讓 consumer 不必自己再掃一次 rels（che-word-mcp#199 的 declaredDocumentImageIds 由此刪除）
• 測試：Id="rId6" / 6 / 字面 TAB / 字面 CRLF 四種寫法，inspector 的 id 與 DocxReader 讀出的 id 逐一相等（同一份 fixture 兩邊各讀一次比對，不寫死期望字串）
• 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

「與 NSXML 完全等價」現在由「同一個 parser」保證而非由測試枚舉保證——但 XMLParser 與 XMLDocument 對不合法輸入的容錯不必然相同（例如 DTD、外部實體）。本案把不合法 part 歸入 unparsableParts 而不宣稱等價；DTD/外部實體的處置屬 #130 IO 上限那一族，不在此。

[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)