每 build 固定項改維護式記帳——#44 閘的 Q1 逐列探查與 chunkCount() 全表 COUNT 隨索引總量成長（設計決定）

[kiki830621]

Problem

#58 歸因後，no-op build（也就是每次查詢前的增量併入）剩下兩個隨索引總量成長、與改動量無關的固定項：

1. 全量 build 跑在單一交易裡：中斷全丟、寫鎖握滿全程、向量全量累積在記憶體 #44 正確性閘 sourcesWithoutCursor() 的 Q1（orphan chunks：chunk_sources 裡沒有對應 chunk 的列）——逐列 b-tree 探查。查詢剩餘 ~1.0–1.3s 的 profile——「1 秒以內」的下一步落點 #58 試過 EXCEPT（3.08 s，更糟）與 count-diff（0.072 s 但不 sound：等價性假設「chunk_sources 無懸空引用」，而那正是本閘要稽核的不變式家族）。
2. chunkCount() 的 SELECT COUNT(*) 全表走訪。

Q2 已在 #58 改成 EXCEPT（≈2.7×）。#58 之後查詢仍約 1.6 s（當晚語料），「1 秒以內」（#56 的目標）未達。

Type

enhancement（設計決定，非 Simple——動到 #44 閘的語意）

Expected

決定並實作「維護式記帳」：

• 計數器／增量 orphan 簿記由寫入交易維護，閘改讀簿記而非每 build 全表稽核；
• 必須回答：簿記本身如何被稽核（它與資料是否一致），否則只是把「稽核者假設待稽核物」搬到另一層——查詢剩餘 ~1.0–1.3s 的 profile——「1 秒以內」的下一步落點 #58 棄 count-diff 的理由要在這裡被正面處理；
• 不變式 2（增量 ≡ 全量重建）與 全量 build 跑在單一交易裡：中斷全丟、寫鎖握滿全程、向量全量累積在記憶體 #44 的拒絕語意不可弱化；
• 前後量測落 docs/measurements/（同時點 A/B）。

建議走 Plan／Spectra 路徑（/idd-diagnose 會判）。

Actual

每 build 付兩個 O(索引總量) 的固定成本；#58 的 Simple 範圍刻意沒有偷渡這個設計決定（見其 closing summary）。

Source: surfaced during /idd-close #58 closing summary scan (Step 3.5)

---

Current Status

• Phase: diagnosed
• Updated: 2026-09-07（diagnosis 已 post；更正：chunkCount 0.01 s 非固定成本；方向：trigger 維護 source_count＋partial index＋按需 --audit；Complexity Spectra；Conflict Class A）

Tasks

• 1. spec：閘 Q1 改讀結構性計數；完整稽核改 --audit／--full；source_count 衍生欄；layout 6
• 2. IndexDatabase：欄＋trigger＋partial index；layoutVersion = 6
• 3. sourcesWithoutCursor() Q1 讀索引；auditOrphans() 跑舊 Q1
• 4. IndexBuilder／CLI --audit
• 5. 測試：trigger ≡ 重算（四條路）＋變異；IncrementalEquivalence snapshot 含新欄
• 6. docs/measurements/ 同時點 A/B（含 chunkCount 更正）
• 7. CHANGELOG／release notes：升版要 --full

[kiki830621]

Diagnosis

Type

enhancement（設計決定：#44 閘的 O(索引總量) 固定項改成結構性保證＋按需稽核）

Root Cause / Analysis

先量現況（真實索引 647,408 chunk／659,060 chunk_sources，sqlite3 唯讀、OS 快取暖、各 3 次）：

固定項	現行 SQL	計畫	牆鐘
Q1 orphan chunks	COUNT(*) FROM chunks WHERE id NOT IN (SELECT chunk_id FROM chunk_sources)	SCAN chunks（covering chunks_by_project）＋ 對 sqlite_autoindex_chunk_sources_1 逐列 IN 探查	0.16–0.17 s（首輪冷 0.60）
同上改 NOT EXISTS	correlated subquery	同形	0.19 s（不會更好）
chunkCount()	COUNT(*) FROM chunks	SCAN covering index	0.01 s

issue 的第 2 項要更正：chunkCount() 在 SQLite 是走 covering index 的 b-tree 計數，647k 列 10 ms，不是值得動的固定成本；動它換不到什麼。真正的固定項只剩 Q1（＋#58 已改 EXCEPT 的 Q2 ≈ 0.07 s）——CLI 暖 ≈ 0.25 s，行程內依 #60 的 2× 缺口約 0.5 s，佔查詢 1.6 s 的三分之一。

為什麼每 build 的 sound 稽核必然是 O(N)：Q1 稽核的命題是「每個 chunk 至少有一個 source」——一個全稱命題，任何不掃描全部 chunk 的檢查都得假設某個東西（計數器、簿記、上一次的結果），而 #58 棄 count-diff 的理由正是「稽核者不得假設待稽核物」。所以「維護式記帳＋每 build 讀簿記」在稽核這個角色上永遠不 sound，issue 的 Expected 第二點沒有繞路。

能繞的是角色本身：把不變式從「事後稽核」改成「結構上不可違反」——

• chunks 加 source_count INTEGER NOT NULL DEFAULT 0，由 SQLite trigger 在 chunk_sources 的 INSERT／DELETE 同交易內 ±1（引擎執行，任何 SQL 寫入路徑都逃不掉，app code 沒有第二份實作可漂移）；加 partial index WHERE source_count = 0 → 「有沒有 orphan」變成 O(orphan 數) 的索引查詢，正常情況 O(1)。
• 簿記如何被稽核（issue 要求正面回答）：三層——(1) trigger 是 schema 的一部分、與資料同交易，app 層無法讓兩者分岔；(2) fixture 測試對 insert／deleteChunks／invalidated 重寫／--full 各做一次「trigger 計數 vs 全表重算」的等價斷言，變異（拿掉 trigger）→ 紅；(3) 保留現行 O(N) 的 Q1 作為按需命令 ltm build --audit（或 --full 時必跑），不再每 build 跑。也就是把「稽核者不得假設待稽核物」滿足在按需稽核這一層，而每 build 走的是結構保證——這是 查詢剩餘 ~1.0–1.3s 的 profile——「1 秒以內」的下一步落點 #58 count-diff 沒有的東西：count-diff 是 app 算的推論，trigger 計數是引擎維護的事實。
• 不變式 2：source_count 是純衍生欄位（由 chunk_sources 決定），--full 重建會重算；增量路徑由 trigger 維護 → 增量 ≡ 全量。要在 IncrementalEquivalenceTests 的 snapshot 裡加這一欄。
• 全量 build 跑在單一交易裡：中斷全丟、寫鎖握滿全程、向量全量累積在記憶體 #44 拒絕語意不弱化：閘仍在每 build 檢查 orphan（讀 partial index），命中照樣具名拒絕；差別只是成本。

代價：schema 變更 → layout_version 5→6 → 既有索引要 ltm build --full（本機 64 萬 chunk 約幾分鐘，且每個使用者都要付一次）。這是本 issue 最大的成本，要在 CHANGELOG／release notes 明寫。

Impact

• 影響的檔案：Sources/LTMIndex/IndexDatabase.swift（schema、trigger、partial index、sourcesWithoutCursor 的 Q1 改讀索引、新的 auditOrphans()）、Sources/LTMIndex/IndexBuilder.swift（閘呼叫、--audit／--full 時跑完整 Q1）、Sources/ltm/Commands.swift（--audit 旗標）、openspec/specs/ltm-cli/spec.md（閘語意、layout 升版拒絕）、openspec/specs/corpus-indexing/spec.md（source_count 衍生欄位）、Tests/LTMIndexTests/（IncrementalEquivalence snapshot、trigger 等價、變異）、docs/measurements/（前後同時點 A/B）、CHANGELOG。
• 影響的使用者流程：升版後第一次 ltm build 具名拒絕、要求 --full（既有機制）；之後每次查詢前併入少約 0.2–0.5 s。

Strategy

• spec（ltm-cli＋corpus-indexing）：全量 build 跑在單一交易裡：中斷全丟、寫鎖握滿全程、向量全量累積在記憶體 #44 閘 Q1 改為讀結構性計數；完整 O(N) 稽核改為 ltm build --audit 與 --full 必跑；source_count 為衍生欄位、trigger 維護；layout 6 的拒絕語意
• IndexDatabase：source_count 欄＋兩個 trigger（INSERT／DELETE on chunk_sources）＋ partial index；layoutVersion = 6
• sourcesWithoutCursor() Q1 改讀 partial index；新增 auditOrphans() 跑舊 Q1
• IndexBuilder／CLI：每 build 讀計數；--audit 跑完整稽核並具名報告
• 測試：trigger 計數 ≡ 全表重算（insert／deleteChunks／invalidated／--full 四條路）；變異拿掉 trigger → 紅；IncrementalEquivalence snapshot 含新欄
• docs/measurements/2026-09-xx-gate-structural-count.md：同時點 A/B（no-op build ×3、query ×3、行程內），並把 chunkCount() 0.01 s 的更正記進去
• CHANGELOG／release notes：升版要 --full

Conflict Class

A_parallel_safe —— 程式碼面只有 IndexDatabase／IndexBuilder／CLI 旗標；目前無其他 open issue 改 schema。但 layout 升版是一次性、全使用者的成本：與下一個 release 協調（同一版只升一次 layout），這是 release 層的序列化，不是 issue 間的。

Complexity

Spectra

• Layer 2：改 ltm build 的已發布行為（閘語意、--audit 新旗標、layout 升版拒絕）與 derived schema。
• Layer 3：修改 ltm-cli／corpus-indexing spec 的 normative 句；架構決定（不變式從事後稽核改成結構保證＋按需稽核）有長期維護含意。
• Hard-gate: triggered — 單一概念散佈 ≥ 6 檔；shared abstraction：chunk_sources 寫入路徑（insert／deleteChunks／invalidated）被三個 build 路徑共用。被 Spectra 涵蓋。

→ /spectra-discuss（default）——要拍板：trigger vs app 維護、--audit 的觸發時機（僅按需／--full 必跑／每 N 次 build）、layout 升版的時點
⚠ Spectra 路徑不產生任何 phase-bearing comment，所以：artifacts 完成後請貼一則 ## Implementation Complete，並跑 /idd-update #61 --tasks-file openspec/changes/<change-name>/tasks.md
→ 建議 pre-implementation staging: superpowers:brainstorming（非綁定）

Risks

• --full 對所有使用者：升版成本是真的；若 v0.6.0 還有別的 schema 需求（84% 的 chunk 是零內容工具殘影（⟨tool_result ok⟩／metadata-only），照樣進向量通道擠掉實質 turn（sister concern from #62） #67 若走索引時不產出零內容 chunk 也要 --full），應合併成一次升版。
• trigger 定義錯就是全域錯——靠等價測試四條路＋變異；再加 --audit 給使用者自查。
• 行程內的 2× 缺口（行程內 no-op build 閘 ~0.9s vs sqlite3 CLI 暖 0.44s——約 2× 差距的機理未解釋（residue from #58） #60）不會因本 issue 消失；本 issue 只砍固定項的絕對量。
• 「1 秒以內」是否達成要看量測；本 issue 不預先宣稱。

Residue

「查詢前併入的固定成本應該多低才夠」沒有使用者層的預算——#56 的「1 秒」是工程目標不是量出來的需求。這層留著。

Vagueness Pre-check

• V1: 2 — 要做什麼明確：把兩個 O(N) 固定項改維護式記帳，且要正面回答簿記如何被稽核。
• V4: 3 — 完成定義含「前後量測」但無門檻（「1 秒以內」是 查詢穩態延遲 ~4 秒、成本大宗在查詢前增量掃描——能否降到 1 秒以內 #56 的目標，不是本 issue 的驗收）。
• Triggered: no — both axes ≤ 3

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

• Not filed: 「chunkCount() 不是固定成本（0.01 s）」——是對本 issue 前提的更正，寫在 diagnosis 內。
• Not filed: 「layout 升版要與 84% 的 chunk 是零內容工具殘影（⟨tool_result ok⟩／metadata-only），照樣進向量通道擠掉實質 turn（sister concern from #62） #67 的可能 schema 需求合併」——記在 Risks，release 層協調。

[kiki830621]

Dashboard — #61

現況：已 diagnose（2026-09-07）。量到：Q1 orphan 檢查 0.17 s（暖）、chunkCount() 只有 0.01 s（前提更正：它不是固定成本）。方向：不變式從「每 build 事後稽核」改成「trigger 維護 source_count＋partial index」的結構保證，完整 O(N) 稽核改 --audit／--full 按需——這樣才正面回答「簿記如何被稽核」。代價：layout 升版、所有人要 --full。Complexity Spectra，Conflict Class A。

你該做什麼：審 diagnosis；同意的話 idd-all 會接 /spectra-discuss（要拍板：trigger vs app 維護、--audit 時機、升版時點與 #67 合併）。