secondarySourceChanged 分不出 Zotero 端有人改內容，還是 mapping hash 的定義變了 (follow-up finding from #605)

[kiki830621]

Problem

附加來源的變動偵測用 mapping hash。mapping 邏輯演進時 hash 全面改變，報告會把每個附加來源都列成「有變動」。#605 的 store 副本端對端驗證就是這樣：三筆全列出，其實 Zotero 端沒有人改。

Expected

區分「內容真的變了」與「hash 定義變了」——例如比對時用同一版 mapping 重算舊 hash，或報告附上 Zotero version 是否前進。

---

Source: surfaced during /idd-verify #605 R1 (follow-up finding, #605 (comment))

---

Current Status

Phase: verified（b16v R1：修正後的判準沒有 HIGH；MEDIUM／LOW 當輪修掉）
Last updated: 2026-09-30 by idd-update

Blocking

• (none)——等你 /idd-close

Commits

• 9552394c、ad64cd81（實作）
• 82f02f07、a447b6d3（R1 修正）
• 23a22959（R1 後的修正）

[kiki830621]

Implementation Complete

**2026-09-29（+08:00）**｜已推上 main：9552394c（登記表 94877a51、描述補鍵 ad64cd81）

• 根因：mappingHash 是拿現行 mapping 算的，mapping 一演進，每個附加來源的 hash 都變，全部被報成「有變動」。
• 做法：issue 的兩個候選裡只有一個不必改 store format。
  • 採用：比較 Zotero 的 version。來源本來就存 zotero_version。
  • 不採用：「用同一版 mapping 重算舊 hash」要多存版本戳。
• 行為：附加來源的 hash 不同、而 version 沒動時，報在新的一格 secondarySourceHashOnly。它只陳述觀察到的事實，不宣稱原因：mapping 變了與子項附件變了分不開。version 前進或倒退時，仍報 secondarySourceChanged。
• 兩面同契約：同一個 ZoteroImporter，mcp-cli-parity 已同步。
• 沒處理的：主來源的 updated 有同樣的歧義，issue 只談附加來源，記在 主來源的 updated 也分不出「內容變了」與「只有 mapping hash 不同」（#608 的姊妹缺口） #694。

測試：整合後（rebase 到 main 上的 #664，並疊上本輪全部修正）全套 swift test 4,319 個、1 個 skipped、0 失敗；run-guards.sh rc=0；各項負控反向編輯後都轉紅。

驗證：batch14 的 ensemble R1 接著跑。

[kiki830621]

Verify R1 修正（#608）

Commit：82f02f07（程式、測試、store-format）、a447b6d3（mcp-cli-parity 列與 changelog）。與 #694、#696 同一組 commit——#694 的主來源分格用的是同一份判準，拆開做會在同一段程式上衝突。

發現與處置

1. 判準錯了：「version 沒變」不等於「沒有人改」 → 已修。

secondarySourceHashOnly 原本只看「hash 不同 且 item.version == 存下的 version」。Zotero 本機資料庫的 items.version 只在同步時才寫，兩種情形因此被誤判：

• (a) 還沒同步的本機修改：synced = 0、version 不動；
• (b) 從未同步的 library：每個條目的 version 都是 0。

兩者都是內容變動，#608 之前在 secondarySourceChanged。本 repo 自己的 docs/store-format.md §2.5.2 早就寫著 hash 比對「同時抓到本機未同步修改」。

現在的判準只有一份 ZoteroImporter.isHashOnlyDifference，四個條件都成立才算「只有 hash 不同」：有舊 hash 且與現在不同；Zotero 那一列 synced = 1；version > 0；version 與存下的相同。其餘一律在 secondarySourceChanged，包括資料庫沒有 synced 欄（讀成 nil＝無從判斷）。

• ZoteroReader 先以 PRAGMA table_info(items) 確認有 synced 欄，有才讀進 ZoteroItem.synced（Bool?）。這個欄位不參與相等、不進 mapping hash、不存進 store，所以不改 store format。
• 主來源的 updated 也分不出「內容變了」與「只有 mapping hash 不同」（#608 的姊妹缺口） #694 的主來源分格（updatedHashOnly）用同一份判準。

2. 說法宣稱了它不知道的原因 → 已改。

以下各處改成只說觀察到的事實（hash 不同；Zotero 那一列已同步、version 沒變）、不宣稱原因（多半是 mapping 定義演進，或子項附件增減），不再有「沒有人改」：ImportReport 的兩段註解、importer 的註解、CLI 那一行、MCP 工具描述、docs/store-format.md §2.5.3、mcp-cli-parity 的 akashic_import_zotero 列（原句以刪除線保留）、#608 那組測試的文件註解與斷言訊息。

3. 測試 → 已補。

ZoteroImportTests 附加來源新增三支：(a) 本機改了內容、synced = 0、version 沒變 → secondarySourceChanged；(b) version 0（synced 設 1，單獨釘住 version > 0 這一條）→ secondarySourceChanged；(d) 資料庫沒有 synced 欄 → secondarySourceChanged。(c) 已同步、version 沒變、hash 不同 → secondarySourceHashOnly：原本那支測試加上 synced = 1。testTwoAdditionalSourcesAreClassifiedIndependently 與 payload 那支同樣加上 synced = 1。主來源的同一組情形在 #694。

fixture：ZoteroFixture.setSynced(_:itemIDs:)——實際的 Zotero schema 有這一欄（預設 0），最小 fixture 沒有；加欄之後五個值的 INSERT INTO items VALUES 會失敗，所以在 item 都插入之後才呼叫。

先紅後綠與負控

新測試對舊判準是紅的：把判準改回 #608 初版（只看 version 相同），7 支轉紅——附加來源三支、主來源三支、testContentChangeWithoutVersionBumpIsCaught。其他負控（反向編輯、以備份逐位元組還原）：

• 不看 synced → 5 支紅（兩面的本機修改與沒有欄位、testContentChangeWithoutVersionBumpIsCaught）。
• 不看 version > 0 → 2 支紅（兩面的 version 0）。
• reader 不讀 synced → 7 支紅（所有「只有 hash 不同」的正向測試，含 CLI 與 payload）。

全套與守衛

全套 swift test --build-system native（在上述兩個 commit 上跑）：XCTest 單一 bundle AkashicKitPackageTests.xctest 執行 4,227 支、0 失敗、1 支 skipped；Swift Testing 0 支。rc=0。第一次全套跑到一半被 RealHomeSandboxGuard 中止——同一時間有另一條工作線在寫 live store（一筆 work 在 15:00 寫入並 commit），不是本變更的測試逃出沙箱；等 live store 靜止之後重跑即綠。

bash .githooks/run-guards.sh rc=0。

沒做的事／誠實邊界

• 判準是觀察、不是證明：synced 與 version 是 Zotero 自己記的狀態，Akashic 不驗證它們。報告因此只說觀察到的事實、不宣稱原因。
• 沒有對照 Zotero 官方文件驗證 synced／version 的語意，依據是 verify 的發現與本 repo 的設計文件。
• secondarySourceChanged 分不出 Zotero 端有人改內容，還是 mapping hash 的定義變了 (follow-up finding from #605) #608 的歷史 changelog（changelog/2026-09-29-zotero-attachments-and-hash-drift.md）裡的舊說法沒改：changelog 是當時的記錄，更正寫在這次的 changelog。
• 行為面的後果要說清楚：沒開同步的 library（或本機有未同步修改的條目）遇到 mapping 定義演進時，附加來源會全部列在 secondarySourceChanged、主來源全部列在 updated——和 secondarySourceChanged 分不出 Zotero 端有人改內容，還是 mapping hash 的定義變了 (follow-up finding from #605) #608 之前一樣多報。那是這個判準刻意選的方向：分不清的時候寧可多報。

[kiki830621]

Verify（#608、#694、#696 Zotero 匯入報告：只有 hash 不同的判準、主來源的 updatedHashOnly、MCP 清單上限）

這一輪

六席：requirements、logic、security、regression、devil's advocate、Codex。全輪 62 則：HIGH 0、MEDIUM 2、LOW 30、INFO 30。前一輪的 HIGH 都確認已關閉——#606 R1 的 HIGH（以計畫時的快照覆寫）由 requirements、logic、security、regression、devil's advocate 五席確認；#629 R2 的 HIGH（同源檢查可被繞過）由同樣五席確認。Codex 只回一則（本報告的第 0 則），對其餘問題沒有下判斷（第 32 則）。

屬這三張的：MEDIUM 1、LOW 5、INFO 4；另收 #578 整合的第 26、61 (f) 則（改動落在這三張的 changelog）。

逐則處置

則	席	嚴重度	內容	處置
0	Codex	MEDIUM	MCP 報告每個清單截到 20 筆，同一趟截掉的拿不回來；建議存完整報告並回 id，或加不重跑的分頁	部分修（23a22959）：失敗清單（writeFailed、quarantineConflicts）改成不截——沒寫進去的記錄在 store 裡沒有痕跡、原因只在這份報告，重跑是再寫一次、不是重播。其餘清單仍截：它們描述的都是寫進去了的記錄，結果在 store 裡、這一趟改了哪些檔在 store 的 git diff 裡看得到，截掉的成員找得回來（找不回來的只有它落在哪一格）。不加分頁、不存完整報告（交辦範圍）。parity 列寫明這一點
31	devil's advocate	LOW	「形照 akashic_enrich」對失敗清單是過度宣稱——那個先例只截明細；index rebuild 失敗的訊息仍說「完整報告如下」	修（23a22959）：同第 0 則；listTotals 只含有上限的清單；錯誤訊息改成「報告如下——清單有上限，被截的見 truncatedLists」；parity 列把那句「形照」劃掉並寫理由
11	logic	LOW	CLI 說「不宣稱原因」接著說「多半是 mapping 定義演進」；updatedHashOnly 讀起來無害，而 MCP payload 沒有 authorsOverwritten／fieldsRemovedByPull	修（23a22959）：兩行 CLI、ImportReport 與判準的註解、store-format 兩處、parity 列都改成可能的原因並列、不排序；主來源那一行指向 authors overwritten／fields removed by pull。payload 的部分見第 30 則
30	devil's advocate	LOW	MCP 報告沒有 authorsOverwritten／fieldsRemovedByPull（測試還以 XCTAssertNil 釘住它們不在），lossless-intake 要求丟棄必須可見；parity 列只寫「既有差異」、沒有 issue	修（23a22959）：payload 多兩格——authorsOverwritten（citekeys，有上限、進 listTotals）與 fieldsRemovedByPull（欄位名 → 次數，不截，同 residualFields），都只在非空時出現；工具描述點名兩個鍵（tools/list 50,004 → 50,233 bytes，預算 52,000）；ToolPayloadKeyGuardTests 多一個情境；parity 列刪掉那句既有差異。原先那個 XCTAssertNil 改成「每個集合欄位都要進 payload」
10	logic	LOW	從未同步的 Zotero library 永遠落不進「只有 hash 不同」	不修（交辦）：version 只在同步時才動，沒同步的 library 每個條目都是 0，「沒變」不帶資訊。R1 更正的結果，文件已寫；changelog 寫明 #608 的目的只對有同步的 library 達成，issue 另提的重算 hash 做法要另外存舊內容
25	regression	LOW	同第 10 則	不修，同上
26	regression	LOW	預算調高到 52,000 之後，規則段落、StdioE2ETests 註解與一份 changelog 仍把 49,000 寫成現行	修（73f9fa17）：規則與測試註解改成「當時預算維持 49,000」；changelog 那一句見下
61 (f)	devil's advocate	INFO	2026-09-29-zotero-hash-only-synced-and-list-caps.md 的「48,150 → 48,357（預算 49,000）」在自己的 commit 裡就過期——寫下它的 commit 的祖先已調高預算；48,357 量的是合併 #664／#672 之前的樹	修（73f9fa17）：git merge-base --is-ancestor 56b6657b a447b6d3 確認為真；改成照實寫。其餘 changelog 的「預算 49,000」是當天的量測，照留
36	requirements	INFO	覆蓋完整；synced／version 的依據以唯讀讀本機 Zotero 的 schema 核對過	不動
37	requirements	INFO	截斷揭露用的是 listTotals／truncatedLists 兩個總鍵，不是 issue 寫的逐清單 …Total／…Truncated	不動；理由（tools/list 預算）已在 changelog 與 parity 列
45	logic	INFO	清單上限的行為正確	不動
54	regression	INFO	寫入行為不變，只動報告分類與 MCP payload 形狀	不動
32	Codex	INFO	Codex 只做了靜態閱讀，對 R1 的判準沒有下判斷	不動
46、51、57	logic、security、regression	INFO	整合 commit 沒有副作用；沒有注入、授權或秘密問題；diff 裡沒有 prompt injection	不動

本輪另外看到、沒有修的

authorsPreserved、authorsOverwritten 與 fieldsRemovedByPull 在 guardedWrite 之前就記下（ZoteroImporter.swift 的主來源更新分支）。寫入失敗或目的檔被隔離的那一筆，照樣被報成「覆寫了／拿掉了」，而實際上沒有寫。兩面都如此，不是本輪造成的；那一筆同時在不截的 writeFailed／quarantineConflicts 裡。記在 changelog，建議開後續（見總報告）。

測試與負控

• ImportZoteroReportSurfaceTests +3、既有五支改成新的清單集合；ZoteroReportCLITests 一支改驗措辭；ToolPayloadScenarios 多一個情境。
• 負控（反向編輯、以備份逐位元組還原）：writeFailed 再截 → 1 支紅；quarantineConflicts 再截 → 1 支；payload 不放 fieldsRemovedByPull → 3 支；authorsOverwritten 不進有上限的清單 → 多支；錯誤訊息改回「完整報告如下」→ 1 支；CLI 那一行改回「不宣稱原因——多半是」→ 1 支；描述不點名兩個新鍵 → ToolPayloadKeyGuardTests 紅（改描述之前實際跑出來的）。

Commit

• 23a22959 fix: MCP 匯入報告的失敗清單不截、補上 authorsOverwritten 與 fieldsRemovedByPull，只有 hash 不同的說明不排原因 (secondarySourceChanged 分不出 Zotero 端有人改內容，還是 mapping hash 的定義變了 (follow-up finding from #605) #608, 主來源的 updated 也分不出「內容變了」與「只有 mapping hash 不同」（#608 的姊妹缺口） #694, import_zotero 報告的其他清單在 MCP 面仍無上限（#684 follow-up） #696)
• 73f9fa17 docs: CLAUDE.md 的 web-access 列不寫類別數、鎖法改 --url-endswith；49,000 的舊預算只以當時的值出現 (MCP tool manifest 在 #554 一張 issue 裡長了 28%——沒有位元組預算也沒有守衛 #578, [refactor] 既有的 Python／shell 領域邏輯移植成 Swift（swift-is-the-implementation-language 的既有檔清單） #629)

沒做、留給整合者

plugin 的 CHANGELOG 沒有記 #696（初版就沒記）。本輪對 MCP 呼叫端的改變——listTotals 不再有 writeFailed／quarantineConflicts、兩個失敗清單不截、多兩個鍵——若要照 #674 那一節的慣例記在 plugin CHANGELOG，要一起補上 #696 本身。