bug: 任何 mutation 都會清空 <w:tblPr> — table style/borders/look 靜默遺失（純 save round-trip 無損）

[kiki830621]

Problem

任何一個 mutation 操作（update_cell / replace_text …）都會讓 <w:tbl> 的 <w:tblPr> 被清空到只剩 <w:tblW>（與 <w:jc>，若原本有）。<w:tblStyle>、<w:tblBorders>、<w:tblLook> 全部靜默消失 —— 工具回報成功、檔案照常開得起來，只是表格框線與樣式不見了。

關鍵區分：純 save round-trip 無損。 只 open_document → save_document（零編輯）產出的 word/document.xml 與原檔 byte-identical。一旦文件被標記 dirty、改走「從解析後的模型重新序列化」，tblPr 就被截斷。這指向 parse 階段沒有把 tblPr 的子元素收進模型，而非 writer 的問題。

Reproduction

從零建立最小 fixture（python-docx），不依賴任何既有檔案：

from docx import Document
from docx.oxml.ns import qn
from docx.oxml import OxmlElement

d = Document()
t = d.add_table(rows=2, cols=2)
t.style = 'Table Grid'                       # -> <w:tblStyle w:val="TableGrid"/>
t.cell(0,0).text = 'A'; t.cell(0,1).text = 'B'
t.cell(1,0).text = 'C'

tblPr = t._tbl.tblPr
b = OxmlElement('w:tblBorders')              # explicit borders, as Word writes them
for edge, sz in (('top','12'),('left','12'),('bottom','12'),('right','12'),
                 ('insideH','6'),('insideV','6')):
    e = OxmlElement(f'w:{edge}')
    e.set(qn('w:val'),'single'); e.set(qn('w:sz'),sz)
    e.set(qn('w:space'),'0'); e.set(qn('w:color'),'auto')
    b.append(e)
tblPr.append(b)
d.save('minimal_bordered.docx')

然後：

open_document(path='minimal_bordered.docx', doc_id='x', track_changes=false)
update_cell(doc_id='x', table_index=0, row=1, col=1, text='D')
save_document(doc_id='x', path='minimal_bordered_after.docx')

Expected

<w:tblPr> 內容不變 —— 一次 cell 文字更新不應觸碰表格層級屬性。

Actual

BEFORE（逐字取自 fixture 的 word/document.xml）：

<w:tblPr><w:tblStyle w:val="TableGrid"/><w:tblW w:type="auto" w:w="0"/><w:tblLook w:firstColumn="1" w:firstRow="1" w:lastColumn="0" w:lastRow="0" w:noHBand="0" w:noVBand="1" w:val="04A0"/><w:tblBorders><w:top w:val="single" w:sz="12" w:space="0" w:color="auto"/><w:left w:val="single" w:sz="12" w:space="0" w:color="auto"/><w:bottom w:val="single" w:sz="12" w:space="0" w:color="auto"/><w:right w:val="single" w:sz="12" w:space="0" w:color="auto"/><w:insideH w:val="single" w:sz="6" w:space="0" w:color="auto"/><w:insideV w:val="single" w:sz="6" w:space="0" w:color="auto"/></w:tblBorders><w:tblLook w:val="04A0" w:firstRow="1" w:lastRow="0" w:firstColumn="1" w:lastColumn="0" w:noHBand="0" w:noVBand="1"/></w:tblPr>

AFTER（同一份，只跑過一次 update_cell）：

<w:tblPr><w:tblW w:w="0" w:type="auto"/></w:tblPr>

tblStyle 1→0、tblBorders 1→0、tblLook 2→0。

Evidence matrix

同一份真實 Word 表單（2 欄 8 列表格，tblStyle + tblBorders + tblLook 齊全）跑四種變體，word/document.xml 字元數與元素計數：

變體	document.xml (chars)	tblStyle	tblBorders	tblLook
原始	49,865	1	1	1
open → save，零編輯	49,865	1	1	1
只跑一次 update_cell	43,297	0	0	0
只跑一次 replace_text	42,367	0	0	0
兩者都跑	38,816	0	0	0

tcPr / trPr / tcW / vAlign / gridCol 計數在所有變體都不變 —— 只有 table 層級屬性遺失，cell/row 層級完好。這進一步把嫌疑收斂到 tblPr 的 parse/model 覆蓋範圍。

Round-trip 同時也會把 <w:szCs> 大量補寫進每個帶 <w:sz> 的 run（33 → 176）。那是 normalization、不是遺失，但顯示 rPr 也在被重寫，值得一併確認覆蓋範圍。

Impact

• 靜默資料破壞：無錯誤、無警告，工具回報 Updated cell at table[0][1][1]。使用者只能靠肉眼在 Word 裡發現框線消失。
• 打擊主要使用情境：填寫既有表單（政府／機構／公司的制式 .docx）是 Word MCP 最常見的用途，而這類表單幾乎必然帶 tblBorders。任何一次 cell 填寫就毀掉整份表格外觀。
• 不可逆：若直接覆寫原檔，原始框線設定無法還原（除非另有備份）。
• 與 feat: 文件修改可信層 — 將三層方法論升格為所有修改的認證式交易閘門 #137（文件修改可信層）、Tracking: word-aligned-state-sync round-trip 驗證線（XmlNode tree + .mdocx Swift 腳本） #127（round-trip 驗證線）、docs: OPC zip 手術論述 — .xlsm 巨集注入、vbaProject.bin 工作流與 byte 級保真驗證 #136（byte 級保真驗證）同一條保真度主線；本 issue 提供一個具體、可自動化的 regression 案例。

Suggested direction

1. 修：把 tblPr 的完整子元素集合納入 model（或對未建模的子元素採 pass-through 保留原 XML node）。tblPr 的合法子元素還包含 tblpPr / tblOverlap / bidiVisual / tblStyleRowBandSize / tblStyleColBandSize / tblCellMar / tblCaption / tblDescription / shd 等，建議一次檢查完整清單而非只補這三個。
2. 測：加一條 regression test —— 帶 tblStyle + tblBorders + tblLook 的 fixture，跑任一 mutation 後 assert tblPr 子元素集合不變。理想上對 tcPr / pPr / rPr / sectPr 做同樣的「mutation 不得改變未觸碰的屬性」不變式測試。
3. 防：pass-through 保留未建模節點，比逐一補齊 model 更能防住同類問題（tblPr 只是第一個被發現的，其他容器很可能有相同缺口）。

Workaround

在修好之前，對含框線表格的既有 .docx 填表，改走 OPC zip 手術（直接改 word/document.xml 後原樣重打包，其餘 part 逐一 byte-for-byte 複製）。實測：14 個 zip part 中 13 個 byte-identical，只有 document.xml 變動，tblPr 完整保留。

Environment

• plugin che-word-mcp 3.22.0（macdoc marketplace；mcp/che-word-mcp submodule 位於 v3.20.0-26-gb59d5f2）
• macOS 26（Darwin 27.0.0）
• fixture 由 python-docx 1.2.0 產生
• 觸發工具：update_cell、replace_text（推測所有標記 dirty 的 mutation 皆會觸發，未逐一驗證）

Type

bug

[kiki830621]

已完成實作並送出堆疊 PR：PsychQuant/ooxml-swift#97（基底為 #96）。

重點：

• 保留來源 <w:tblPr> 的完整子節點、命名空間、wrapper 屬性與 CT_TblPr 順序。
• unrelated cell/text mutation 不再清掉 tblStyle、tblBorders、tblLook 或其他未建模合法內容。
• typed mutation 僅替換明確變更的屬性，涵蓋 conditional style、mc:AlternateContent、mc:ProcessContent、QName alias、Unicode prefix 與 prefix shadowing。

實際驗證：

• 原始回歸先出現 6 項缺漏；修正後核心 11/11 綠燈。
• 相關測試 131/131 綠燈。
• 完整套件 1,373 tests、0 failures、28 skipped。
• 效能 median：insertParagraph 1.029、setBold 1.016，均低於 1.25 預算。
• requirements、logic、security/data-integrity 三方審查皆 PASS。

Issue 保持開啟，等待 PR review。

[kiki830621]

Note（來自 #143 研究，2026-08-14）：genoffice 對「mutation 不清空未建模屬性」的做法是 raw-passthrough——numbering/styles 走 append-only upsert（既有條目 bytes 不動，patch.ts:649-723）、run/paragraph 屬性走 rawRPr/rawPPr 屬性群組級複製（沒被編輯的群組直接搬原始 bytes）。本 issue 的 tblPr 清空正是「重建時丟掉沒建模的子樹」的形狀，修復方向可參考同款心法：沒建模的子樹，搬運而非重建。詳見 docs/genoffice-roundtrip-comparison.md §7。

[kiki830621]

Errata（更正 2026-08-14 的 Note，來自 #143 verify）

原文（前一則 note）：
「genoffice 對「mutation 不清空未建模屬性」的做法是 raw-passthrough——numbering/styles 走 append-only upsert（既有條目 bytes 不動，patch.ts:649-723）」

styles 那半是錯的（#143 六 AI verify 抓出，logic lens + Devil's Advocate 各自獨立複驗）：

• numbering：append-only 正確（patch.ts:697-700，既有條目 bytes 不動）✓
• styles：patch.ts:718-720 對既有 styleId 是整個取代——buildStyleXml 純從 model 生成 minimal stub，原 style 的未建模屬性（w:link/w:uiPriority/w:next/w:basedOn/w:semiHidden…）全數被清掉，且 regex 也匹配 Word 內建樣式 ✗
• rawRPr/rawPPr 群組級 passthrough：正確 ✓

對本 issue 的含意反而更強：genoffice 在 styles upsert 上踩的正是本 issue 的同一個坑（重建時丟掉沒建模的子樹）。#142 不是孤例，是 mutate-rebuild 路徑的系統性風險——兩個獨立實作各踩一次。修復方向不變：沒建模的子樹，搬運而非重建；但請以 numbering append 與 rawRPr merge 為正面參照，styles upsert 為反面教材。

詳見更正後的 docs/genoffice-roundtrip-comparison.md §7。

[kiki830621]

追加證據：<w:tcPr> 子元素同樣被清空，且 <w:tblLayout> 會被重複輸出

在 ntu-claude-plugins #16（REC 表單代填對映）探測時獨立撞到本 bug，取得的證據把本 issue 的範圍往外推了兩格。原文聚焦 <w:tblPr> 的子元素（tblStyle／tblBorders／tblLook）；實測顯示 <w:tcPr> 的子元素也全滅，而且那才是某些真實文件唯一的框線載體。

樣本

一份真實的官方 Word 表單（單一表格、20 列 × 2 欄）。關鍵特徵：表格層級沒有 <w:tblBorders>，全部框線都寫在 cell 層級的 <w:tcBorders>（40 格各一份）。這類文件在本 issue 現有的 evidence matrix 裡沒有代表。

四變體對照（word/document.xml）

變體	bytes	tcBorders	tcMar	tblCellMar	tblLook	tblLayout
原檔	103,206	40	40	1	1	1
open → save（零編輯）	103,206	40	40	1	1	1
replace_text（單一命中）	76,578	0	0	0	0	2
update_cell（單格）	74,582	0	0	0	0	2

純 save round-trip byte-identical，與本 issue 原文一致。但任何一次 mutation，即使只取代一處字串，就讓整份文件的 40 個 cell 框線與邊距全部消失 —— 包含從未被觸碰的 39 格。

逐字對照

<w:tcPr>（第一格）——

BEFORE

<w:tcPr><w:tcW w:w="1701" w:type="dxa"/><w:tcBorders><w:top w:val="single" w:sz="4" w:space="0" w:color="000000"/><w:left w:val="single" w:sz="4" w:space="0" w:color="000000"/><w:bottom w:val="double" w:sz="4" w:space="0" w:color="000000"/><w:right w:val="single" w:sz="2" w:space="0" w:color="000000"/></w:tcBorders><w:shd w:val="clear" w:color="auto" w:fill="auto"/><w:tcMar>…</w:tcMar>…

AFTER

<w:tcPr><w:tcW w:w="1701" w:type="dxa"/><w:shd w:fill="auto" w:color="auto" w:val="clear"/></w:tcPr>

→ 存活的只有 tcW 與 shd，其餘子元素整批消失。形狀與本 issue 描述的 tblPr 截斷一致（parse 階段沒把子元素收進模型），只是換一個容器。

<w:tblPr> ——

BEFORE

<w:tblPr><w:tblW w:w="10026" w:type="dxa"/><w:tblInd w:w="-108" w:type="dxa"/><w:tblLayout w:type="fixed"/><w:tblCellMar><w:left w:w="10" w:type="dxa"/><w:right w:w="10" w:type="dxa"/></w:tblCellMar><w:tblLook w:val="0000" …/></w:tblPr>

AFTER

<w:tblPr><w:tblW w:w="10026" w:type="dxa"/><w:tblLayout w:type="fixed"/><w:tblInd w:w="-108" w:type="dxa"/><w:tblLayout w:type="fixed"/></w:tblPr>

這裡有兩個獨立於截斷的新缺陷：

1. <w:tblLayout> 被輸出兩次（計數 1 → 2，已用 grep -c 單獨核對，非 regex 假象）。CT_TblPrBase 是 sequence，各子元素最多一次 —— 這是無效 OOXML，不是資訊遺失。
2. 子元素順序改變：tblInd 從 tblLayout 之前移到之後。CT_TblPrBase 的 schema 順序是 tblStyle → tblpPr → tblOverlap → bidiVisual → tblStyleRowBandSize → tblStyleColBandSize → tblW → jc → tblCellSpacing → tblInd → tblBorders → shd → tblLayout → tblCellMar → tblLook。輸出順序不符 sequence 同樣是 schema 違規。

對修法範圍的影響（本則的重點）

只修 tblPr 子元素的話，這一類文件仍然全壞。 建議把本 issue 的驗收條件從「tblPr 內容不變」擴成：

• w:tblPr 子元素集合、順序、基數皆不變（含 tblCellMar／tblLook；tblLayout 不得重複）
• w:tcPr 子元素集合不變（含 tcBorders／tcMar）
• 迴歸樣本需含一份框線只寫在 tcBorders、表格層無 tblBorders 的文件 —— 現有 fixture（python-docx + Table Grid + 表格層 tblBorders）驗不到這一類

為什麼這條的實務後果很重

下游（ntu-claude-plugins 的 rec-fill）的用途是把官方送審表單複製一份後定點填寫再送出。在本 bug 存在的前提下，任何自動填寫都會產出沒有框線的表單，而且：

• 工具全程回報成功
• 文件開得起來
• 既有的文字層 fidelity 閘（compare_documents_markdown／get_tables 逐格比對）對此完全盲 —— 它們比的是文字，框線不在比對範圍

也就是說這個失效是靜默的，要到人肉打開檔案才看得見。下游因此暫時把「自動填寫」整條路標為不可用（詳見 PsychQuant/ntu-claude-plugins#16）。

附註：byte-equal 閘測得到，但測不出是哪裡壞

export_script → execute_script --verify_byte_equal_against 可以抓到「有東西變了」（broken_parts: ["word/document.xml"]），但因為 document.xml 本來就允許改變，它無法區分「只改了該改的」與「順便清空了 40 組框線」。要擋住本 bug 需要 part 內部的元素級斷言，不是 part 級 byte-equal。

[kiki830621]

根因定位：tcBorders 這一半是純 reader 缺口，修法很小

接續上一則的取證。追進 code path 後，tcBorders 的遺失原因與 tblPr 那一半不同，且比預期單純——model 與 writer 都已具備能力，只有 reader 從不填值。

讀寫不對稱

Writer — packages/ooxml-swift/Sources/OOXMLSwift/Models/Table.swift:861-872，四個邊框都寫得出來：

// 邊框
if let borders = borders {
    parts.append("<w:tcBorders>")
    if let top    = borders.top    { parts.append(top.toXML(name: "top")) }
    if let bottom = borders.bottom { parts.append(bottom.toXML(name: "bottom")) }
    if let left   = borders.left   { parts.append(left.toXML(name: "left")) }
    if let right  = borders.right  { parts.append(right.toXML(name: "right")) }
    // v0.17.0+ (#49): diagonal borders
    if let tl2br  = borders.tl2br  { parts.append(tl2br.toXML(name: "tl2br")) }
    if let tr2bl  = borders.tr2bl  { parts.append(tr2bl.toXML(name: "tr2bl")) }
    parts.append("</w:tcBorders>")
}

Reader — packages/ooxml-swift/Sources/OOXMLSwift/IO/DocxReader.swift:2924-2933，只讀對角線：

// v0.17.0+ (#49): diagonal borders
if let tcBorders = element.elements(forName: "w:tcBorders").first {
    let tl2br = parseBorder(tcBorders.elements(forName: "w:tl2br").first)
    let tr2bl = parseBorder(tcBorders.elements(forName: "w:tr2bl").first)
    if tl2br != nil || tr2bl != nil {
        if props.borders == nil { props.borders = CellBorders() }
        props.borders?.tl2br = tl2br
        props.borders?.tr2bl = tr2bl
    }
}

top／bottom／left／right（以及 insideH／insideV）從未被解析，所以
props.borders 對真實 Word 文件永遠只可能帶對角線。一旦文件 dirty、改走
「解析後模型重新序列化」，writer 拿到的 borders 就是空的（或只有對角線）——
40 格框線因此整批消失。

grep -rn "tcBorders" packages/ooxml-swift/Sources 只有這兩處，沒有第二條解析路徑。

這解釋了為什麼「純 save round-trip 無損」

零編輯時走 raw byte channel，根本不經過 model；一旦 mutation 觸發重新序列化，
reader 沒收進來的東西就再也回不去。與本 issue 原文對 tblPr 的判斷（「parse 階段
沒有把子元素收進模型，而非 writer 的問題」）同一個機制，只是這次連 writer 側
都已經寫好了，缺口純粹在 reader。

建議修法（tcBorders 這一半）

在 parseCellProperties 補齊六個方向即可，形狀與現有對角線分支相同：

if let tcBorders = element.elements(forName: "w:tcBorders").first {
    let top     = parseBorder(tcBorders.elements(forName: "w:top").first)
    let bottom  = parseBorder(tcBorders.elements(forName: "w:bottom").first)
    let left    = parseBorder(tcBorders.elements(forName: "w:left").first)
    let right   = parseBorder(tcBorders.elements(forName: "w:right").first)
    let tl2br   = parseBorder(tcBorders.elements(forName: "w:tl2br").first)
    let tr2bl   = parseBorder(tcBorders.elements(forName: "w:tr2bl").first)
    // 任一非 nil 才建 CellBorders（維持現有分支的「全 nil 就不碰 props.borders」語意）
    if [top, bottom, left, right, tl2br, tr2bl].contains(where: { $0 != nil }) {
        if props.borders == nil { props.borders = CellBorders() }
        props.borders?.top = top       // …其餘同理
    }
}

⚠️ 注意 parseBorder 目前對缺席屬性給預設值（val 預設 single、sz 預設 4、
color 預設 000000）。要真正 round-trip 保真，這些預設會把「原本沒寫的屬性」
補成有寫的——修 reader 的同時要決定是否改為保留 nil，否則會從「掉框線」變成
「框線被改成別的樣子」。這是另一種安靜的不保真，方向相反但同樣難察覺。

另外兩項（不在上面那段修法範圍內）

1. <w:tcMar> 是 reader／writer 兩側皆無。上一則的實測是 tcMar 40 → 0；
   writer 的 TableCellProperties.toXML() 也沒有任何 tcMar 輸出分支。這一項要先
   在 model 加欄位，比 tcBorders 大一級。
2. <w:tcPr> 的子元素輸出順序不符 schema。writer 目前的順序是
   tcW → gridSpan → vMerge → vAlign → tcBorders → shd，但 CT_TcPr 的 sequence 是
   cnfStyle → tcW → gridSpan → hMerge → vMerge → tcBorders → shd → noWrap → tcMar → textDirection → tcFitText → vAlign → hideMark —— vAlign 應在最後段、卻被排在
   tcBorders 之前。與上一則指出的 tblPr 順序問題（tblInd 被排到 tblLayout 之後）
   同族。目前因為 vAlign 多半是 nil 而不顯眼，但一旦有值就會產出不符 schema 的輸出。

驗收建議

除了上一則列的元素集合／順序／基數斷言，補一條讀寫對稱性的機械檢查會更耐久：

對 w:tcPr／w:tblPr 的每一個 writer 寫得出來的子元素，reader 必須讀得進來。
這條可以寫成測試（枚舉 writer 的 parts.append 分支 vs reader 的
elements(forName:) 呼叫），比逐一列舉元素名更難漏——因為本 bug 的形狀正是
「writer 會寫、reader 不讀」，而那個不對稱是可機械偵測的。

[kiki830621]

修法落點在上游：PsychQuant/ooxml-swift#99

追進 code path 後確認，tcBorders 這一半的修改點不在 macdoc——packages/ooxml-swift 是被
.gitignore 擋掉的本機開發 checkout，macdoc 以版本化 SPM 依賴消費它（Package.swift:45，
from: "1.4.0"）。所以已在 PsychQuant/ooxml-swift#99 開立技術面 issue，含：

• 三處逐字對照（model 欄位齊全／writer 寫得出六個方向／reader 只讀兩條對角線）
• parseBorder 的預設值陷阱（修 reader 時若不一併處理，會從「掉框線」變成「框線被改成別的樣子」）
• tcMar 在 model／reader／writer 三側皆無（grep -rn "tcMar" Sources/ 零命中），比 tcBorders 大一級
• CT_TcPr 的 writer 輸出順序不符 schema（vAlign 排在 tcBorders 之前）
• 一條比逐一列舉元素更耐久的驗收檢查：「writer 寫得出的每個子元素，reader 必須讀得進」
  ——本 bug 與 ooxml-swift fix: PageOCRRunner uses OCRCore.backend API (unblocks main build) #84／OCR: Metal shader (metallib) must be manually compiled for SwiftPM CLI #67／feat: 支援 HTML → PDF 轉換 (macdoc convert --to pdf) #69 都是同一個不對稱的不同實例，這條可一次覆蓋整族

本 issue（macdoc 側）建議保留為症狀與下游影響的追蹤，修好後在此驗收：升 ooxml-swift 版本、
重跑本則稍早那張四變體對照表，tcBorders／tcMar 應在 mutation 後維持 40。

[kiki830621]

進度：cell 層框線已修（ooxml-swift PR #100），但本 issue 尚未可關

已修：<w:tcBorders> 的四個邊框 — PsychQuant/ooxml-swift#99 / PR #100。
根因是 reader 只讀兩條對角線；model 與 writer 早已支援六個方向。真實樣本端到端驗證：
修復前讀回 0/40 格有邊框，修復後 40/40，write→read 後維持 40。全套迴歸 1301 tests / 0 failures。

與既有 PR #97 的分工（兩邊都需要，缺一不可）：

PR	涵蓋
ooxml-swift #97（idd/142-preserve-table-properties，5 天前開）	<w:tblPr> 子元素（表格層）
ooxml-swift #100（本次）	<w:tcBorders>（cell 層）

已核對 #97 未動 parseCellProperties、merge-tree 無文字衝突，兩者可獨立合併。
另指出 #97 的迴歸 fixture 用的是表格層 <w:tblBorders>，驗不到 cell 層這一類——
本 issue 的樣本正是「表格層無 tblBorders、框線全在 40 個 tcBorders」的形狀。

仍未解，本 issue 的驗收條件尚未滿足：

1. <w:tcMar> 在 model / reader / writer 三側皆無（grep -rn "tcMar" Sources/ 零命中）。
   本則稍早的實測表格裡 tcMar 同樣是 40 → 0。這一項要先在 TableCellProperties 加欄位。
2. tblCellMar / tblLook 遺失與 tblLayout 重複輸出（無效 OOXML）— 應由 Propose script-variant anchor matching #97 涵蓋，
   合併後值得用本則的四變體對照表複驗。
3. CT_TcPr 的 writer 輸出順序不符 schema（vAlign 排在 tcBorders 之前）。

下游狀態：PsychQuant/ntu-claude-plugins#16 的 rec-fill 仍維持「產出只能當草稿、不可直接
送件」的封鎖——即使 tcBorders 修好，tcMar 與 tblPr 面未落地前，產出的官方表單仍非完好。
待 #97 + #100 + tcMar 三者齊備並發版、che-word-mcp 升依賴後，再以四變體對照表複驗一次才解除。

[kiki830621]

進度：cell 層（<w:tcPr>）兩個元素都已修復並合併；剩表格層

完成度對照

面	元素	狀態
cell（tcPr）	tcBorders	✅ ooxml-swift #99 / PR #100 已合併（c03d984）
cell（tcPr）	tcMar	✅ ooxml-swift #101 / PR #102（CI 待完成後合併）
表格（tblPr）	tblCellMar / tblLook / tblLayout 重複輸出	⏳ #97 → 需你 review

cell 層的實測結果（本 issue 稍早那張四變體對照表的對應項）

真實樣本（本 issue 的表單，20 列 × 2 欄 = 40 格）：

修復前:  tcBorders 40 → 0,  tcMar 40 → 0
修復後:  READ-BACK        40/40 borders, 40/40 margins
         AFTER WRITE→READ 40 borders,    40 margins

兩者的根因略有不同，值得記錄：

• tcBorders：純 reader 缺口——model 欄位與 writer 早已支援六個方向，reader 只讀兩條
  對角線（tl2br/tr2bl，feat: implement word-to-html-swift converter #49 當初只為對角線加的）。修法約 10 行。
• tcMar：三側皆無（grep -rn "tcMar" Sources/ 零命中）。型別可複用
  （TableCellMargins 已用於表格層 tblCellMar、同樣四 twips 形狀），所以仍是小改動。

順帶修掉一個 schema 違規：writer 原本把 vAlign 排在 tcBorders／shd 之前，
不符 CT_TcPr 的 sequence。tcMar 的正確位置在 shd 之後、vAlign 之前，
所以那個排序修正是插入 tcMar 的前提、不是額外 scope。

驗證規模：#100 → RED 10 assertion / GREEN 5-5、全套 1301 綠；#102 → RED 11 assertion /
GREEN 6-6、全套 1307 綠。兩者都另做真實表單端到端。

表格層為什麼我沒動

#97 不能直接合進 main——它 stack 在 #96 上：

#96: idd/127-roundtrip-acceptance → main                        +4711/−523、72 檔、status UNKNOWN
#97: idd/142-preserve-table-properties → idd/127-roundtrip-acceptance

三個理由讓它不該由我處理：

1. Propose R wordbuilder MVP #96 是 72 檔／約 5,200 行我沒寫也沒驗證的變更，且 mergeability 是 UNKNOWN
2. 合併有先後順序（Propose R wordbuilder MVP #96 先、Propose script-variant anchor matching #97 後）
3. 合 Propose R wordbuilder MVP #96 時若刪除來源分支會直接關閉 Propose script-variant anchor matching #97 且救不回

另外值得肯定的是 #97 的策略比我用的更強：它保留 source XML、只替換真正改動的子元素
（sourceOrder(forWMLName:)／marginsChanged），而我走的是「解析進 model」路線。
兩者互補；若日後把 #97 的策略延伸到 tcPr，#99 與 #101 都可被整併掉——那會是簡化，不是回歸。

本 issue 的驗收建議

#97／#96 落地後，用本 issue 稍早那張四變體對照表重跑一次即可驗收全部：
tcBorders／tcMar／tblCellMar／tblLook 在 mutation 後都應維持原數量，
且 tblLayout 不得從 1 變 2。

下游狀態

PsychQuant/ntu-claude-plugins#16 的 rec-fill 仍維持「產出只能當草稿、不可直接送件」。
cell 層修好不足以解封——表格層未落地前，產出的官方表單仍會掉 tblCellMar／tblLook
並帶一個重複的 tblLayout（無效 OOXML）。

解封的完整鏈：#97/#96 合併 → ooxml-swift 發版 → che-word-mcp 升依賴並發版 →
重跑四變體對照表複驗 → 才改 ntu-rec 的文件。

[kiki830621]

Verified fixed — ready to close

Reproduced this issue's own repro (python-docx fixture with tblStyle + explicit tblBorders + tblLook) against the released che-word-mcp v4.0.1 / ooxml-swift 3.1.0, mutated via update_cell, saved, and compared with an XML parse:

element      count   attrs-same   children-same   order-same
tblStyle     1 → 1      YES           YES            YES
tblLook      1 → 1      YES           YES            YES
tblBorders   1 → 1      YES           YES            YES

All six tblBorders children (top/left/bottom/right/insideH/insideV) survive with attributes intact. The mutation landed, so this is the dirty re-serialisation path the issue identified — not the pure-save path it correctly excluded.

The mechanism is Sources/OOXMLSwift/Models/Table.swift:533 — internal var rawChildren: [PreservedTableProperty], documented as "Complete source-loaded <w:tblPr> children". That is the architecture this issue asked for, and it landed after the issue was filed.

One caveat on method, because it nearly produced the opposite report. An element-count check ("tblBorders 1 → 1") looks like a pass but says nothing about content. A regex check then said all six children had vanished — false, caused by the writer switching from self-closing to explicit-close tags while the regex only matched self-closing. Only the XML parse gave the result above. If anyone re-verifies this family, parse the XML; do not count elements and do not regex them.

Closing is the maintainer's call; posting the evidence rather than closing it here.

[kiki830621]

Closing Summary

Problem

Any mutation (update_cell, replace_text, …) truncated a table's <w:tblPr> down to <w:tblW> and <w:jc>. <w:tblStyle>, <w:tblBorders> and <w:tblLook> disappeared silently — the tool reported success, the file still opened, only the borders and style were gone.

The issue drew the distinguishing line correctly: a zero-edit open → save was byte-identical, because that path replays raw bytes. The truncation only appeared once the document was dirty and re-serialised from the parsed model, which pointed at the parse stage rather than the writer.

Root Cause

The reader collected only the tblPr children it had typed fields for. Everything else was dropped on read and therefore absent on write. The parse-stage diagnosis in the issue was right.

Solution

Fixed upstream of this closing, in work that landed after the issue was filed: Sources/OOXMLSwift/Models/Table.swift:533 now carries internal var rawChildren: [PreservedTableProperty], documented as "Complete source-loaded <w:tblPr> children". That is the architecture this issue asked for — the reader keeps every child, typed or not, and the writer replays them.

Verification

Reproduced this issue's own python-docx repro (a table with tblStyle + explicit six-edge tblBorders + tblLook) against the released che-word-mcp v4.0.1 binary, mutated through update_cell, saved, and compared with an XML parse:

element      count   attrs-same   children-same   order-same
tblStyle     1 → 1      YES           YES            YES
tblLook      1 → 1      YES           YES            YES
tblBorders   1 → 1      YES           YES            YES

All six tblBorders children (top/left/bottom/right/insideH/insideV) survive with attributes intact. The mutation landed, so this is the dirty re-serialisation path — not the pure-save path the issue excluded.

One methodological caveat, because it nearly produced the opposite report. An element-count check ("tblBorders 1 → 1") looks like a pass and says nothing about content. A regex check then reported all six children gone — false, caused by the writer switching from self-closing to explicit-close tags while the regex matched only the former. Two methods, two confident and opposite wrong answers. Only the XML parse was right. If this family is ever re-verified, parse the XML.

Changes

Fixed before this verification, in the rawChildren / PreservedTableProperty work in packages/ooxml-swift. No commit was made for this closing.

Related

• PsychQuant/ooxml-swift#101 — verified fixed in the same round, closed alongside.
• PsychQuant/ooxml-swift#99 — same family, only partially fixed; its residue (cell insideH/insideV dropped, emission out of CT_TcBorders sequence) was fixed and shipped as ooxml-swift v3.2.0 → che-word-mcp v4.0.2.
• The three issues looked like one uniform family because the evidence for all of them was gathered by counting elements. Two were already fixed; the third was fixed in a different place than described.