import-zotero：authorsOverwritten／fieldsRemovedByPull 在寫入之前就記下，寫入失敗的那一筆被報成已覆寫

[kiki830621]

Problem

ZoteroImporter 主來源的更新分支，在 guardedWrite 之前就把該筆記進 authorsPreserved、authorsOverwritten 與 fieldsRemovedByPull。所以寫入失敗（writeFailed）或目的檔被隔離（quarantineConflicts）的那一筆，報告照樣說它的作者被覆寫、欄位被拿掉了，實際上那一筆沒有寫。

#696 R1 修正起，MCP 回應也帶 authorsOverwritten 與 fieldsRemovedByPull，所以這個誤報在兩個面都看得到。

Type

bug

Expected

• 三個清單只在寫入成功之後才記下那一筆。
• 加一支測試：以隔離目的檔造成寫入失敗，斷言那一筆不在這三個清單裡、只在失敗清單裡。

Actual

寫入失敗的那一筆同時出現在失敗清單與「已覆寫」清單。

---

Source: b16v verify 修正輪（#608／#694／#696，2026-09-30）

---

Current Status

Phase: verified（R2 ensemble：HIGH 0、MEDIUM 0；九則 LOW 落在 #705 同一塊程式，轉 #705 一起處理）
Last updated: 2026-09-30 by idd-update

Blocking

• 無（close 由使用者執行）

Commits

• 921b8353（實作）
• 2e9d5c67（R1 修正；tag idd-702-verified）

[kiki830621]

Implementation Complete

#702：import-zotero 的「已保留／已覆寫／已拿掉」清單只記寫進去的那一筆。

• 已推上 main
• Commit：921b8353 fix: import-zotero 的作者保留／覆寫與拿掉的欄位只在寫入成功後記下 (import-zotero：authorsOverwritten／fieldsRemovedByPull 在寫入之前就記下，寫入失敗的那一筆被報成已覆寫 #702)

根因

ZoteroImporter.run 主來源的更新分支，在呼叫 guardedWrite 之前就把該筆記進 authorsPreserved、authorsOverwritten，並把拿掉的欄位與識別碼算進 fieldsRemovedByPull。guardedWrite 回 false 的兩種情形（目的檔被隔離→quarantineConflicts；encode／寫檔擲錯→writeFailed）都不會撤回這些紀錄，所以沒有寫的那一筆同時出現在失敗清單與「作者已覆寫、欄位已拿掉」清單。

同形檢查：附加來源分支（#605，R1 verify #6 時已改成寫入後才記）、新建、orphan 標記、清除 orphan 標記（#682）這四個分支都已在 guardedWrite 成功之後才記，沒有同樣的問題，沒改。

改了什麼

• Sources/AkashicZoteroImport/ZoteroImporter.swift：拿掉的欄位、拿掉的識別碼、作者覆寫與否先算進區域變數（removedFields、removedIdentifiers、authorsOverwritten；保留與否本來就是 hadResolvedAuthors），guardedWrite 成功之後才進報告。改寫的內容與寫入時機不變。ImportReport 三個欄位的說明補上「只記寫入成功的」。
• Sources/AkashicMCPKit/AkashicService.swift：importReportCappedLists 的說明原本寫「在寫入之前就記下」，改成 import-zotero：authorsOverwritten／fieldsRemovedByPull 在寫入之前就記下，寫入失敗的那一筆被報成已覆寫 #702 之後的事實。
• .claude/rules/mcp-cli-parity.md 的 akashic_import_zotero 列：第 (c) 點那句劃掉並指向列末，列末加「import-zotero：authorsOverwritten／fieldsRemovedByPull 在寫入之前就記下，寫入失敗的那一筆被報成已覆寫 #702 重新確認，裁決不變、契約有改」一段。
• plugin/CHANGELOG.md：加一段 import-zotero：authorsOverwritten／fieldsRemovedByPull 在寫入之前就記下，寫入失敗的那一筆被報成已覆寫 #702（鍵名與形狀不變，只是寫入失敗的那一筆不再出現在三個清單裡）。
• changelog/2026-09-30-zotero-report-after-write.md。

MCP payload 的鍵名、形狀、上限都沒變，工具描述沒動，tools/list 的位元組不受影響（全套測試含 testToolsListResponseStaysWithinByteBudget）。CLI 印的文字沒變。

測試

Tests/AkashicKitTests/ZoteroImportReportAfterWriteTests.swift（ZoteroImportTests 的 extension，沿用它的 fixture）加兩支，各讓一筆寫不進去、另一筆寫得進去：

1. testQuarantinedDestinationIsNotReportedAsOverwrittenOrPruned：文章換成別的 literal 作者並加一個 Zotero 不會給的欄位；在 entries/<citekey>.yaml 放一份讀不出來的 legacy 殘留（load 隔離它，importer 的寫入閘因此拒寫這個 citekey，與既有 testQuarantineGuardIsCaseInsensitive 同一個手法）。書改成已歸戶的作者、同樣加欄位、寫得進去。斷言：quarantineConflicts == [文章]、authorsOverwritten == []、fieldsRemovedByPull == ["annotation": 1]、authorsPreserved == [書]、updated == [書]，磁碟上文章的作者與欄位沒動。
2. testWriteFailureIsNotReportedAsPreservedOrPruned：書的 entity 檔換成帶 encode 平移不變式會拒寫的未知欄位（既有 testWriteFailureContainedPerItem 的手法）、已歸戶作者、加欄位。文章照第 1 支的方式改、寫得進去。斷言：writeFailed[書] != nil、authorsPreserved == []、fieldsRemovedByPull == ["annotation": 1]、authorsOverwritten == [文章]、updated == [文章]，磁碟上的書沒被毀。

兩支合起來，三個清單各有一筆失敗的（不得出現）與一筆成功的（照常記下）。

修之前：兩支都紅，4 個斷言失敗（失敗的那一筆出現在 authorsOverwritten／authorsPreserved，annotation 算成 2），正面的斷言都綠。修之後：兩支綠；ZoteroImportTests、ZoteroSourceRouting、ImportZoteroReportSurface、WorkFieldProvenance 共 114 支綠。

負控（反向編輯，每次 cmp 確認還原）

反向編輯	結果
拿掉的欄位移回寫入之前記	兩支紅（annotation 2 ≠ 1）
authorsPreserved 移回寫入之前記	寫入擲錯那支紅（書出現在 authorsPreserved）
authorsOverwritten 移回寫入之前記	隔離那支紅（文章出現在 authorsOverwritten）
寫入成功後不記 authorsPreserved	隔離那支紅（正面斷言，「一律不記」過不了）

沒做的事

• 識別碼被拿掉（fieldsRemovedByPull 的 doi／pmid／isbn）在寫入失敗時不記的這一半，沒有專屬測試。它與 fields 的減法在同一個 if 裡；成功那一半由既有 testClearingAnIdentifierUpstreamIsReported 釘住。
• residualFields 仍在每個 Zotero 條目讀進來時計數，不論這一趟有沒有寫（含未變動、被多筆宣稱而略過、寫入失敗的條目）。說明寫的是「以原名入庫的欄位」，對寫入失敗的那一筆不精確。它的實際語意是「讀到的條目帶哪些未對映欄位」，改成只算寫入成功會連未變動的條目一起拿掉，超出 import-zotero：authorsOverwritten／fieldsRemovedByPull 在寫入之前就記下，寫入失敗的那一筆被報成已覆寫 #702 的範圍，沒改。要不要另開 issue 請使用者決定。
• 沒有跑 idd-verify。

[kiki830621]

Verify R1（#702）

這一輪

六席：requirements、logic、security、regression、devil's advocate、Codex。全輪 44 則：HIGH 0、MEDIUM 6、LOW 23、INFO 15。logic、regression、devil's advocate 三席第一次因網路錯誤失敗，從快取重跑。

屬 #702 的：LOW 2（第 15、26 則）、INFO 2（第 31、37 則）。Codex 對 #702 沒有報告（第 29 則）。

修正 commit：2e9d5c67。

做了什麼

• 識別碼那一半的測試：testWriteFailureIsNotReportedAsPreservedOrPruned 的書另帶一個 Zotero 沒給的 DOI，那一筆寫不進去，fieldsRemovedByPull 必須不含 doi。反向編輯（識別碼的記錄移回寫入之前）時紅，量到 ["annotation": 1, "doi": 1]。
• 寫了之後才擲錯的那一筆：DA 席指出的角落確實存在——LibraryStore.writeEntry 先 atomicWrite 到 entities/<id>.yaml，之後才刪 writeEntry／rename 在 entities 佈局下留下 legacy 拷貝，自己造出同 id 的重複（sister concern from #627） #631 搬移的 legacy 檔；atomicWrite 在搬進目的檔之後沒有會擲錯的步驟，所以這是寫入之後唯一會擲錯的地方。處置：
  • writeEntry／writePerson 刪 legacy 檔失敗時改擲 StoreIOError.legacyCopyNotRemoved（訊息：已寫入哪個檔、哪個 legacy 檔沒刪、原因、兩份並存的後果）。
  • ZoteroImporter.guardedWrite 遇到它時回 true，那一筆照寫入成功記（updated、authorsOverwritten、fieldsRemovedByPull），writeFailed 同時帶那句以「已寫入」開頭的訊息。ImportReport.writeFailed 的說明、CLI import-zotero 那一行的標題（不再說「已略過」）、mcp-cli-parity 的 akashic_import_zotero 列、plugin/CHANGELOG.md 同步。
  • 新測試 testWriteThatLandsBeforeLegacyRemovalFailsIsReportedAsWritten：文章只剩一份受 git 追蹤的 legacy 檔、entries/ 設成唯讀，import 後內容在 entities/、legacy 還在，文章在三個清單裡，writeFailed 以「已寫入」開頭。以 root 執行時 skip。
  • 反向編輯：guardedWrite 把它當成沒寫 → 紅；writeEntry 擲原始錯誤 → 紅。
• ImportReport.residualFields 的說明補上計數的時機。

逐則處置

則	席	嚴重度	內容	處置
15	logic	LOW	(1) 識別碼被拿掉遇上寫入失敗沒有測試（突變存活）；(2) residualFields 的說明對失敗那一筆不精確	修（2e9d5c67）：(1) 見上；(2) 說明補上「讀進每個條目時計數，不論寫沒寫」
26	devil's advocate	LOW	guardedWrite 回 false 不等於沒寫——寫入後才擲錯的路徑漏報；識別碼那一半的存活突變	修（2e9d5c67）：見上
31	requirements	INFO	需求已涵蓋；plugin CHANGELOG 的 #608／#694／#696 段夾在 #690 的 commit	不動；夾帶一事記在 #690 的 changelog
37	security	INFO	安全面無發現	不動

待裁

• 報告的雙重記錄是一個判斷：寫了、但留下兩份的那一筆同時在「寫入成功」的清單與 writeFailed。另一條路是加一個新欄位（例如「寫了但留下 legacy 檔」），那會動到 MCP 回應的形狀與 tool 描述的位元組預算，這一輪沒有做。
• 其餘寫入者沒有逐一檢查：legacyCopyNotRemoved 對所有經 writeEntry／writePerson 的寫入者都會擲，它們的錯誤訊息因此說得出「已寫入」；但只有 import-zotero 的報告改成照寫入成功記。resolve-people、enrich 等遇到它時仍把那一筆算成失敗。要不要另開 issue 逐一處理，由使用者決定（觸發條件窄：legacy 殘留加上刪檔失敗，live store 的 legacy 殘留為 0）。

[kiki830621]

Verify R2（#702）

這一輪

六席：requirements、logic、security、regression、devil's advocate、Codex，六席都有結果。全輪 45 則：HIGH 0、MEDIUM 4（都屬 #689／#690）、LOW 22、INFO 19。

屬 #702 的：HIGH 0、MEDIUM 0、LOW 9（第 7、8、9、15、16、19、20、22、26 則）、INFO 5（第 27、32、35、36、41 則）。R1 的兩則 LOW 三席各自確認已關閉（第 32、35、41 則）；logic 席在副本上重建並跑過新測試，也確認 atomicWrite 在搬進目的檔之後沒有會擲錯的步驟，removeMovedLegacy 是寫入後唯一的擲錯點（第 35 則）。Codex 對 #702 沒有報告（第 27 則）。

判定：verified（HIGH 0、MEDIUM 0）。tag idd-702-verified 打在 2e9d5c67。

逐則處置

九則 LOW 落在 #705 正在改的同一塊程式（使用者 2026-09-30 裁決 #705 採 (a)：「寫了、legacy 拷貝沒刪掉」那一筆記在成功那一側的新欄位），所以轉到 #705 的分支一起處理，本 issue 不另修。

則	席	嚴重度	內容	處置
7、22	requirements、regression	LOW	「寫了但在 writeFailed」只能靠「已寫入」前綴辨認；akashic_import_zotero 的描述仍說 writeFailed 就是寫入失敗	轉 #705：新欄位落地後描述照實改
8、36	requirements、logic	LOW／INFO	legacy 檔已經不在（例如被並行刪掉）時，訊息仍說「現在有兩份」	轉 #705：區分「已經不在」
9、16	requirements、logic	LOW	writePerson 那一半沒有測試走到	轉 #705：補 StoreIO 層的測試
15、19、20、26	logic、security、regression、devil's advocate	LOW	同一趟匯入對同一筆 entry 寫兩次（主來源＋附加來源、orphan 清除＋更新）時，第二次被 legacyCopyPresent 拒絕，並覆寫 writeFailed 裡那句「已寫入」，寫了的那一筆看起來像沒寫	轉 #705：成功側的新欄位不得被後一次拒絕蓋掉
27、32、35、41	Codex、requirements、logic、security	INFO	無缺陷；R1 已關閉	不動