Zotero 附件複製進 Akashic 檔案區（為日後切斷 Zotero 匯入鋪路）(sibling concern from #605)

[kiki830621]

Problem

Original text:
「附件複製進 Akashic 檔案區（為日後切斷 Zotero 鋪路）要在 #605 一起做嗎？」→「拆成另一個 issue」
— Source: #605 Clarity Surface，使用者 2026-09-23 裁決

(sibling concern from #605)

store 內有附件記錄指向 Zotero 的 storage/ 資料夾（2026-09-23 量測：52 個）。PDF 本體只存在 Zotero 那邊，Akashic 只記路徑。只要日後停用 Zotero 匯入或清理 Zotero，這些附件就會失聯。

Type

feature

Expected

提供把 Zotero 附件複製進 Akashic 自己檔案區的路徑（CLI 指令即可）：複製 PDF、改寫附件記錄指向新位置，保留原 Zotero 來源作為 provenance。可逆、可重跑（已複製的不重複）。

Actual

附件記錄只保存 zotero: storage/... 相對路徑，沒有 Akashic 端的副本。

Impact

這是 #605 定位「Zotero 是上游之一、日後可切斷」的另一半：#605 解決記錄層的多來源，本 issue 解決檔案層的依賴。

---

Parent context: #605

---

Current Status

Phase: verified（b16v R2：R1 的 HIGH 由 requirements、logic、security、regression、DA 五席確認關閉；本輪 HIGH 0）
Last updated: 2026-09-30 by idd-update

Blocking

• Expected「改寫附件記錄指向新位置」改成以 akashic.sources 連結，是代裁；要不要照 Expected 字面改寫 attachments，待你裁決
• 存檔大小上限與既有 blob 內容驗證另案 sources/ 存檔沒有大小上限；copy-zotero-attachments 不驗既有 blob 的內容 #703

Commits

• 700a48e3、94877a51（實作）
• aaed106a（R1 修正）
• a3c8aed5、4fe671fc（R2 後的 LOW 修正）

[kiki830621]

Implementation Complete

**2026-09-29（+08:00）**｜已推上 main：700a48e3、94877a51

• 設計盤點：不必改 store format，也不需要新的附件形狀。
  • 附件記錄的鍵域只有 zotero:（一份 PDF 是 source 還是 attachment？——兩份文件各自自洽，但沒有交集判準 #223）。
  • 可存進 store 的內容以 digest 住在 akashic.sources（store-format §2.4.1），feat: 缺少寫入 akashic.sources 的正規入口——內容存得進 store，卻宣告不了是哪篇作品的副本（sister concern from #613） #614 已有寫入面。
• 新命令 akashic copy-zotero-attachments [--zotero-db] [--citekeys] [--apply]，預設乾跑：
  • 每個附件檔經 SourceStore.storeSource 存進 sources/，不繞過版控排除的 fail-closed 閘；
  • 把 digest 追加到那筆 work 的 akashic.sources；
  • 被改寫的 work 檔要已 commit 且乾淨；
  • 任一道閘過不了，整批零寫入；
  • 路徑不合、檔案不在、0 byte 等，逐筆具名略過；
  • 可重跑，已連過的 digest 不重複。
• 兩面：CLI-only，理由寫進 mcp-cli-parity；單檔的同一件事 MCP 本來就有（akashic_store_source 加 add_sources）。two-kinds-of-edits 歸為程式編輯，WriteGateRulings 過閘。
• 代裁（可翻）：
  • 沒有照字面改寫附件記錄。zotero: 那一段由 Zotero 擁有，下一次 import-zotero 會把它還原；位元組的位置改由 akashic.sources 表達。
  • retrieved 用複製當下的時間。
• 誠實邊界：
  • 沒有對真的 Zotero 目錄跑過，測試用的是假目錄；
  • HTML snapshot 的資源檔不複製；
  • 別台 clone 的 sources/ 沒有這些位元組。

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

驗證：batch14 的 ensemble R1 接著跑。

[kiki830621]

Verify R1（#606）

2026-09-29（+08:00）｜batch14 cluster（#663、#608、#606、#674、#683、#672、#684、#675）ensemble 六席齊：requirements、logic、security、regression、devil's advocate、Codex（跨模型）。合併後 53 則：HIGH 1（在 #606）、MEDIUM 15、LOW 20、INFO 17。本則只列 #606 的發現與處置。#606 有 1 個 HIGH，已修；待 R2。

處置

已推上 main，commit aaed106a。列號是 b14f 報告的列號。

列	嚴重度	處置
0	HIGH	修。實跑寫 work 之前讀可回溯閘回傳的那個記錄檔（新的 LibraryStore.rereadEntry，與 load 同一份解碼；load 對 akashic.libraries 的去重抽成 normalizedAfterDecode 一份，兩條 load 路徑與重讀共用），與計畫時的快照不同就不寫、記進 writeFailed（「計畫之後這筆 work 的記錄檔被改過」），其餘照跑；位元組已存進 sources/，重跑以新內容重新計畫、補上連結。先例是 App #609 的 changedDuringCheck；那邊重 load 整個 store，批次每筆重 load 太貴（live store 副本上一次 validate 約 6 秒，debug 建置），所以只讀單一檔。
1	MEDIUM	修（與 6、11、14 同一件事）。
3	MEDIUM	待裁，行為不動。changelog 的代裁 1 改寫成「待使用者裁決，issue 上沒有使用者對這一條的裁決紀錄」。requirements 席說「沒有記錄的核可」屬實；DA 席（第 49 列）說代裁已明文記錄、理由可獨立驗證，也屬實——兩者不矛盾：記錄了取捨，但沒有使用者的裁決。
6	MEDIUM	修。「已連過」改成看本機位元組：已連過的 digest 一次查 sourcePresence（#614）；位元組在（含只缺取得記錄的孤兒 blob）才進 alreadyLinked，不在的進新的 restoredLocally——只存位元組與取得記錄、不改連結、不寫 work 檔（所以不過可回溯閘，只過存檔前置）；判不出的（位置上是目錄或 symlink、分片讀不到、index 壞到判不出）以新的略過原因 localCopyUnverifiable 具名、不重存。
7	MEDIUM	修（同第 0 列）。
11	MEDIUM	修（同第 6 列）。
14	MEDIUM	修。前半同第 6 列；CLI 在這種情形不再印「沒有新東西要複製」，另一段印「已連過、但本機 sources/ 沒有位元組——要補存／已補存」。後半（discardedProvenance 被當成計數吞掉）：逐檔列在新的 provenanceNotRecorded，附 index 保留的那一條的 origin，CLI 逐行印；blobsAlreadyStored 改成它的個數。
25	LOW	修。新的 ZoteroStorageFile.read：O_NOFOLLOW｜O_NONBLOCK 開一次、fstat 確認非空普通檔、以 F_GETPATH 問 kernel 真實位置在 storage/ 之內（storage/ 自己也經 descriptor 問）、從同一個 descriptor 讀完；不再 mmap（截短時的 SIGBUS）。計畫與實跑兩次讀都走它。代價：每個檔整份讀進記憶體、存完即釋放（誠實邊界改寫）。
42（後半）	INFO	同第 3 列，待裁。
49	INFO	對第 3 列的更正，見上。
52	INFO	無缺陷的探測；其中點出的兩個 TOCTOU（路徑重讀、閘後直接寫回）即第 25、0 列，已修。

測試（全部新增）：ZoteroAttachmentCopyTests +4——閘之後改過並 commit 的 work 不被覆寫、重跑補上；連結在而本機缺位元組的補存、不改連結、不要求 work 檔乾淨；本機那一份位置上是目錄時具名略過；丟棄的取得記錄附保留的 origin。CopyZoteroAttachmentsCLITests +1（真 binary：模擬第二份 clone 拿掉 sources/，重跑補回、work 檔位元組不變、validate 不再報「本機缺承重存檔」）。ZoteroStorageFileTests +6（讀回位元組；定位後換成 symlink；KEY 目錄換成指出去的 symlink；換成 FIFO 不卡住；被清空；storage/ 本身是 symlink）。

負控（反向編輯、cmp 確認還原）：拿掉重讀比對 → 1 支紅；.absent 當已連過 → 2 支紅（服務層與 CLI）；不記丟棄的取得記錄 → 3 支紅；read 拿掉 O_NOFOLLOW → 1 支紅；拿掉 kernel 真實位置的前綴比對 → 1 支紅。O_NONBLOCK 沒有負控（拿掉的結果是測試卡住，不是紅）。

TDD 的誠實記錄：這幾支是實作之後寫的，「測試守得住」由上面的負控證明，不是先看到紅。

文件同步：changelog（R1 節、代裁 1、兩條誠實邊界）、README、docs/store-format.md §2.4.1、two-kinds-of-edits 的 copy-zotero-attachments 列。

仍在的邊界：重讀與寫入之間仍有很短的窗（沒有 store 層的鎖）；補存的前提是那台機器的 Zotero 資料目錄裡還有那個檔。

[kiki830621]

Verify（#606 copy-zotero-attachments，第二輪）

這一輪

六席：requirements、logic、security、regression、devil's advocate、Codex。全輪 62 則：HIGH 0、MEDIUM 2、LOW 30、INFO 30。#606 R1 的 HIGH（以計畫時的快照覆寫 work）已關閉：requirements（第 33 則）、logic（第 39 則）、security（第 47 則）、regression（第 52 則）、devil's advocate（第 58 則）五席各自確認；Codex 沒有對它下判斷（第 32 則）。#629 R2 的 HIGH 同樣由五席確認關閉。

屬 #606 的：MEDIUM 1、LOW 11、INFO 9。

逐則處置

則	席	嚴重度	內容	處置
1	requirements	MEDIUM	Expected「改寫附件記錄指向新位置」仍未照字面實作	待裁（交辦：等使用者裁決）：行為不動，仍是 issue Blocking 裡的代裁 1
5	logic	LOW	.unindexed（blob 在、index 沒有條目）被當成做完了，工具手上就有補記需要的資料	修（a3c8aed5）：另列 recordRestored（乾跑「要補記」、實跑「已補記」），走同一個 storeSource——blob 不重寫、補上取得記錄；不改連結、不動 work 檔。只有真的寫進 index 的才算進這一格
16	security	LOW	「已連過」只看 blob 在不在，不驗內容；孤兒 blob 不補	部分修（a3c8aed5）：孤兒 blob 那一半同第 5 則。內容比對那一半不修：不在交辦範圍；型別 doc 改寫成「只看存在與條目，不重算既有 blob 的 digest」，先前那句「位元組層的語意」拿掉
6	logic	LOW	補存那一條路只以路徑去重：同一筆 work 兩個內容相同的已連附件都進補存，第二個被報成取得記錄沒寫進去	修（a3c8aed5）：與新連結那一條路同形，第二個列在「已連過」
7	logic	LOW	補存擲錯記在 writeFailed[citekey]，同一個 citekey 可同時在 written 與 writeFailed	修（a3c8aed5）：另列 restoreFailed（檔、訊息），CLI 另一段，照樣非零結束。測試接縫多一個 internal 的 beforeStore
8	logic	LOW	只補存的 --apply 結尾仍叫人 validate 之後 commit	修（a3c8aed5）：沒有改寫 work 檔時說「沒有東西要 commit（sources/ 不進 git）」
20	regression	LOW	只補存而全部略過時標題仍說「已寫入」、結束碼 0	修標題（a3c8aed5）：有改寫 work 才說「已寫入」；只補存說「已補存本機 sources/，沒有改寫任何 work 檔」；全部略過說「沒有改寫任何 work 檔、也沒有補存任何檔」。結束碼不改：略過逐行具名、與新連結那一條路同一個規則（交辦只要求措辭）；真的失敗（writeFailed、restoreFailed）才非零
27	devil's advocate	LOW	index 留著、blob 被清過時，補存寫出位元組，而丟棄的取得記錄那一行說「位元組早就在 sources/」	修（a3c8aed5）：SourceReceipt 多 bytesWritten（這次呼叫有沒有寫出 blob，與 indexEntryCreated 是兩件事）；ProvenanceNotRecorded 帶 bytesWereAlreadyStored；CLI 的標題改成「index 已有這份內容的取得記錄、這次的 Zotero 來源沒有寫進去」，每一行說位元組是已在還是這一次才存；blobsAlreadyStored 只數前者
18	regression	LOW	計畫階段仍註解「mmap，不常駐」	修（a3c8aed5）
15	security	LOW	ZoteroStorageFile.read 整份讀進記憶體、沒有大小上限，乾跑也一樣	寫成誠實邊界（a3c8aed5）：store-source 與 SourceStore 本來就沒有大小上限，不另立一個數字（交辦）；型別 doc 補「乾跑也一樣」，changelog 寫明
17	security	LOW	public 的 rereadEntry／rereadVenue 沒有路徑包含檢查；rereadVenue 沒人用	不修（交辦）：rereadVenue 在 main 頂端由 #675 使用（第 59 則）；輸入只來自可回溯閘自己列舉的檔名
19	regression	LOW	rereadVenue 是 #675 的範圍漏進 #606	不修（交辦）：同上，它是兩張共用的 helper
33、39、47、52、58	五席	INFO	R1 的 HIGH 已關閉；重讀比對是解碼後的值（canonical 相等），不是位元組；閘到重讀之間的窗隨複製量成長、重讀到寫入之間的窗很短	不動（誠實邊界已在型別 doc）
34	requirements	INFO	R1 其餘項目如宣稱；內容相同的已連附件會重複補存	不動；後半隨第 6 則修
40	logic	INFO	Expected 仍未照字面滿足	同第 1 則
49	security	INFO	descriptor 檢查站得住；網路／FUSE 卷上 F_GETPATH 可能失敗而 fail-closed	不動
59	devil's advocate	INFO	更正第 17、19 則：rereadVenue 在 main 頂端有人用	採納，見第 17、19 則

測試與負控

• ZoteroAttachmentCopyTests +4：孤兒 blob 補記取得記錄（乾跑、實跑、再跑一次變成已連過）；內容相同的已連附件只補存一次；補存失敗不算 work 的寫入失敗（新連結照寫、writeFailed 空、restoreFailed 點名那個檔）；index 留著而 blob 被清過時丟棄照列、標明位元組是這一次才存的。
• CopyZoteroAttachmentsCLITests +1（真 binary：同一個情形的輸出沒有「早就在」、說「位元組這一次才存進 sources/」），既有的第二份 clone 那一支多驗標題不說「已寫入」、結尾不叫人 commit。
• 負控（反向編輯、以備份逐位元組還原）：孤兒 blob 回到「已連過」→ 1 支紅；拿掉補存那一條路的去重 → 1 支；補存失敗記回 writeFailed → 1 支；bytesWereAlreadyStored 一律 true → 2 支（服務層 1 支的兩則斷言、CLI 1 支）；CLI 標題改回「applied 就說已寫入」→ 1 支；結尾改回一律叫人 commit → 1 支；丟棄那一行改回「位元組早就在 sources/」→ 1 支。

文件

docs/store-format.md §2.4.1 的第二個寫入者、two-kinds-of-edits 的 copy-zotero-attachments 列補上「缺取得記錄的只補記」；changelog/2026-09-29-zotero-attachments-and-hash-drift.md 加「Verify R2 修正（#606）」一節。README 不在可改範圍，沒動。

mcp-cli-parity 的 copy-zotero-attachments 列（CLI-only 表）補「#606 R2 verify 重新確認，裁決不變、契約有改」。

全套測試第一次跑時 DisplaySinkCoverageTests 紅了一支：新加的補存失敗那一行，消毒豁免的註記沒有具名運算式（寫了 message，應為 f.message）。改正後重跑綠（4fe671fc）；那次紅就是這條修正的負控。

Commit

• a3c8aed5 fix: copy-zotero-attachments 補記孤兒 blob 的取得記錄、已連附件只補存一次、補存失敗另列、報告不再說早就在或已寫入 (Zotero 附件複製進 Akashic 檔案區（為日後切斷 Zotero 匯入鋪路）(sibling concern from #605) #606)
• 4fe671fc fix: 補存失敗那一行的消毒豁免具名運算式，copy-zotero-attachments 的 parity 列重新確認 (Zotero 附件複製進 Akashic 檔案區（為日後切斷 Zotero 匯入鋪路）(sibling concern from #605) #606)