docs(sdd): 立 ingest-contract SDD + 搬入 ingest-candidate 契約 (T3.1+T3.8)

對應 issue #1（頂層 mira-dissolve T3）。 - contracts/ingest-candidate.json：ingest→graph 邊界契約（自頂層搬入） - contracts/README.md：標明候選(輸入)≠已存(triplet) - docs/3-specs/ingest-contract/design.md + tasks.md： - ensureTemplate 改 slot-diff 補丁（取代 early-return，免遷移腳本） - 補 KbdbClient.updateRecord（base PATCH /records/:id） - ingest 流程：驗證(422)→idempotency(uri+hash)→先 append 後 deprecate - triplet template 增 source_uri+content_hash slot 承載 idempotency - 跨 repo 協調點（3.6 圖工具併 KBDB MCP）明列需 arcrun 配合總管已認可四個設計決定（issue #1 comment）。鐵律：零建表/零 SQL/零 migration。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-26 18:07:12 +08:00
parent 2dd80cd703
commit 98b221b435
4 changed files with 243 additions and 0 deletions
@@ -0,0 +1,26 @@
+# contracts/ — graph 插件邊界契約
+
+> 本目錄放 graph 插件對外的 JSON Schema 契約。兩份契約是**不同方向的東西，別混**。
+
+## 兩份契約的分工
+
+| 檔案 | 是什麼 | 方向 | 誰產 / 誰收 |
+|------|--------|------|-------------|
+| `ingest-candidate.json` | **輸入候選**（envelope）| ingest 插件 **→** graph 插件 | ingest 萃取後送進來，graph 收下處理 |
+| `triplet.json` | **已存三元組**（graph 內部存的單筆 S-P-O）| graph 內部 / 對查詢面 | graph 寫進基本盤 records 後的形態 |
+
+**核心區別**：`ingest-candidate` 是「還沒進庫的一批原始萃取」，`triplet` 是「已經正規化、存好、可查的單筆」。
+
+- ingest 只送原始 `(subject, predicate, object) + confidence`，**禁送** graph 領域欄位（`id` / `clusters` / `bridge_score` / `created_at` / triplet 上的 `*_entity_type`）。送了 → graph 以 422 拒收（`additionalProperties: false`）。
+- 正規化、clusters、bridge_score、embed、`status`/`superseded_by` 取代邏輯——全是 **graph 領域**，ingest 一無所知（純餵食器）。
+
+## ingest-candidate envelope 重點
+
+- **一個 envelope = 一個來源檔（canonical MD）一次萃取的產物**。
+- `source.uri`（穩定識別）+ `source.content_hash`（快照鍵）共同決定 idempotency：
+  - 同 uri + 同 hash → no-op（`{skipped:true}`）。
+  - 同 uri + 新 hash → **deprecate-then-append**（舊 active 翻 `status=deprecated` + `superseded_by`，append 新批 active）。
+- `nodes[]`（選填）帶 `gloss` / `entity_type` —— **節點屬性**，不是邊屬性，故獨立於 `triplets[]`。graph 用 gloss 去 embed（每節點一句，非裸詞）。
+
+完整 schema 與欄位說明見 `ingest-candidate.json` 的 `description` / `$comment`。
+本 repo 對此契約的實作（端點、取代邏輯、測試）見 `docs/3-specs/ingest-contract/`。
@@ -0,0 +1,104 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "IngestCandidateEnvelope",
+  "description": "ingest 插件 → graph 插件 的唯一邊界契約。一個 envelope = 一個來源檔(canonical MD)一次萃取的產物。graph 收下後負責正規化/clusters/bridge_score/embed,並以『翻 triplet template 實例的 status slot』做取代:同 source.uri 出新 content_hash 時,graph 把舊 active 實例 PATCH 成 deprecated、append 新批 active(可查、可 rollback、可清),ingest 對這些一無所知。注意:這是【輸入候選】,不是【已存三元組】(後者見 triplet.json)。",
+  "type": "object",
+  "required": ["source", "extractor", "triplets"],
+  "additionalProperties": false,
+  "properties": {
+    "source": {
+      "type": "object",
+      "description": "這批候選來自哪個 canonical MD。同時是『指回原文的指標』與『append-only 快照鍵』。",
+      "required": ["uri", "content_hash"],
+      "additionalProperties": false,
+      "properties": {
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "description": "來源的穩定識別 = 快照鍵 + get_source 指標。格式: 'github:<owner>/<repo>@<path>' 例如 'github:uncle6me-web/LLM-Wiki-for-n8n@.claude/wiki/graph-rag.md'。同一 uri 的後續 envelope 會【取代】(latest-wins)前一批,而非疊加。"
+        },
+        "content_hash": {
+          "type": "string",
+          "minLength": 1,
+          "description": "來源檔內容的 hash(快照鍵)。graph 比對: 與該 uri 現存快照同 hash → no-op 跳過;不同 → 寫新快照。"
+        },
+        "anchor": {
+          "type": "string",
+          "description": "檔內定位(heading slug / block id),供 get_source 精準回跳。選填。"
+        },
+        "commit": {
+          "type": "string",
+          "description": "git commit sha(可追溯)。選填。"
+        },
+        "block_id": {
+          "type": "string",
+          "description": "向後相容: Logseq Block ID(= 既有 triplet.json 的 source_block_id)。非 git 來源時用。選填。"
+        }
+      }
+    },
+    "extractor": {
+      "type": "object",
+      "description": "萃取出處。供『升級率』觀測與『要不要重萃』判斷;不影響圖結構。",
+      "required": ["model", "tier"],
+      "additionalProperties": false,
+      "properties": {
+        "model": {
+          "type": "string",
+          "minLength": 1,
+          "description": "產生這批的模型,例如 'workers-ai/@cf/...' 或 'claude-sonnet-4-6'。"
+        },
+        "tier": {
+          "type": "string",
+          "enum": ["shallow", "deep"],
+          "description": "shallow = Workers AI 淺萃;deep = Claude API 深萃(淺萃 JSON-fail/過稀時升級)。"
+        },
+        "extracted_at": {
+          "type": "integer",
+          "description": "萃取的 unix 時間(秒)。快照排序用。選填(graph 收件時可補)。"
+        }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "description": "節點層附帶資訊(選填)。entity_type 與 gloss 是【節點】屬性,不是【邊】屬性 → 放這裡,不放 triplets。graph 用 gloss 去 embed(每節點一句,不是裸詞)、用 entity_type 去 typing。",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "節點名(須對應某 triplet 的 subject 或 object 原字面)。"
+          },
+          "gloss": {
+            "type": "string",
+            "description": "一句話描述,供 embedding。例如 'Graph RAG — 用關係遍歷檢索、保住異見的 RAG 變體'。選填(建議 deep tier 產出)。"
+          },
+          "entity_type": {
+            "type": "string",
+            "enum": ["person", "event", "product", "market", "org"],
+            "description": "節點類型提示。graph 最終決定;ingest 只提示。選填。"
+          }
+        }
+      }
+    },
+    "triplets": {
+      "type": "array",
+      "minItems": 1,
+      "description": "邊(關係)。ingest 只產原始 (s,p,o) + confidence。",
+      "items": {
+        "type": "object",
+        "required": ["subject", "predicate", "object"],
+        "additionalProperties": false,
+        "properties": {
+          "subject":   { "type": "string", "minLength": 1, "description": "主詞(實體名,須與 nodes[].name 對得上若有提供)" },
+          "predicate": { "type": "string", "minLength": 1, "description": "謂詞(關係)" },
+          "object":    { "type": "string", "minLength": 1, "description": "受詞(目標實體或值)" },
+          "confidence":{ "type": "number", "minimum": 0, "maximum": 1, "default": 1.0, "description": "萃取可信度。淺萃可附自評;graph 不據此過濾,只記錄。" }
+        }
+      }
+    }
+  },
+  "$comment": "禁止欄位(graph 領域,ingest 絕不可送): id / clusters / bridge_score / created_at / updated_at / 以及 triplet 上的 subject_entity_type|object_entity_type(類型只走 nodes[])。送了即違反 ingest=純餵食器的邊界,graph 應拒收或忽略。"
+}
@@ -0,0 +1,79 @@
+# ingest-contract — 設計
+
+> **藍圖在頂層**：本 SDD 只放 **kbdb-graph-plugin 內部實作細節**。跨專案脈絡（為什麼拆 ingest/graph、mira 蒸發、整體資料流）見 InkStoneCo `docs/3-specs/mira-dissolve/`（design + requirements）。
+> **對應交辦**：[kbdb-graph-plugin #1](https://github.com/uncle6me-web/kbdb-graph-plugin/issues/1)（T3）。
+> **鐵律**：API-as-Wall / 零建表 / 零 SQL / 零 migration。embedding/語義 normalize 屬 base 模組，graph 只調不自算。圖在插件層記憶體組裝。
+
+---
+
+## 1. 範圍
+
+graph 插件補上**寫入端**：收 ingest 送來的 `ingest-candidate` envelope，正規化後以「翻 triplet 的 `status` slot」做 **deprecate-then-append** 取代，並讓查詢面 active-only。查詢面（search/traverse/neighbors）已成熟，本批只補 active 過濾。
+
+不在本批：圖工具併入 KBDB MCP 的**註冊薄殼**（需 arcrun 配合，見 §6）；semantic normalize 端到端（依賴 base embed 部署）。
+
+## 2. 邊界契約
+
+唯一入口契約 = `contracts/ingest-candidate.json`（已搬入，T3.1）。要點見 `contracts/README.md`。
+graph 收件後負責的領域欄位（ingest 禁送）：`id` / `clusters` / `bridge_score` / `created_at` / triplet 上的 `*_entity_type`。`additionalProperties:false` → 違規欄位 422。
+
+## 3. template slot 變更（T3.2 / 3.2b）
+
+現況（`src/lib/templates.ts`，已核實）：
+- `TRIPLET_SLOTS` 無 `status` / `superseded_by`。
+- `ENTITY_SLOTS` 無 `gloss`。
+
+要加：
+- triplet：`status`（`active` | `deprecated`，預設 `active`）、`superseded_by`（指向取代它的新 record id，空＝未被取代）。
+- entity：`gloss`（一句話描述，供「詞+gloss」語義 normalize 的 embedding 對象）。
+
+### ⚠️ ensureTemplate early-return 陷阱（前置警示 1，已核實）
+
+`KbdbClient.ensureTemplate`（`src/lib/kbdb-client.ts:120`）命中既有 template 即 `return`，**不會把新 slot 補進已 seed 的 template**。只改 `TRIPLET_SLOTS` 陣列對既有環境無效。
+
+**對策**：`ensureTemplate` 改為「命中既有 → 比對 slot 差集 → 缺的走 base `PATCH /templates/:id` 補上」，而非 early-return。新環境（template 不存在）走原 `POST /templates` 路徑不變。如此既有 + 全新環境都正確收斂，不需另跑一次性遷移腳本。
+
+## 4. KbdbClient.updateRecord（前置警示 2，已核實）
+
+client 現有 `createRecord` / `getRecord` / `listRecordsByTemplate`，**無 record 層 PATCH**（`updateEntry` 是 entry 層，不是 record）。
+
+新增 `updateRecord(recordId, values)` → 呼叫 base `PATCH /records/:id`（base #6 已就緒）。deprecate（翻 status）與 rollback（翻回 status）都靠它。
+
+## 5. POST /triplets/ingest（核心，T3.3）
+
+純函式 action（`src/actions/triplet-ingest.ts`，<100 行，第一參數收 `KbdbClient`），route 只驗證 + 呼叫。流程：
+
+1. **驗證 envelope**：Zod schema 鏡射 `ingest-candidate.json`，`additionalProperties:false` → 禁送欄位（如 `bridge_score`）回 422。
+2. **idempotency**：以 `source.uri` 為鍵查該來源現存 active triplet 的 `content_hash`（存進 triplet 的某 slot，見下）。同 hash → no-op 回 `{skipped:true}`。
+3. **deprecate-then-append**：新 hash → 查該 uri 所有 active triplet，逐筆 `updateRecord(id, {status:'deprecated', superseded_by:<新批暫不知 id，二階段或留空>})`，再 append 新批 active。
+4. **回應**：`{ ingested: N, deprecated: M, skipped: false }`。
+
+### content_hash / source.uri 存哪
+
+triplet record 需記住它來自哪個 snapshot 才能做 idempotency 與 active-only。沿用既有 `source_block_id` 不夠（那是 Logseq block）。設計：triplet template 增記 `source_uri` + `content_hash` slot（屬 §3 同批 slot 變更，非建表）。active-only 與 deprecate 都按 `source_uri` 分組。
+
+> 註：`superseded_by` 指向「取代它的新 record id」。新批 record 是 append 後才有 id → 若要精確回填，deprecate 分兩步（先 append 拿 id，再翻舊批 status + superseded_by）。先 append 後 deprecate 比較安全（中途失敗不會留下「全無 active」的空窗）。
+
+## 6. 查詢 active-only（T3.5）
+
+traverse / search / neighbors 從 records 組鄰接表前，先 `filter(status === 'active')`（預設值缺省視為 active，相容舊資料）。active 集合永遠乾淨，deprecated 仍可查（rollback / 考古）但不進圖遍歷。
+
+## 7. 跨 repo 協調點：圖工具併入 KBDB MCP（T3.6，需 arcrun 配合）
+
+圖工具（traverse / neighbors / get_source）+ `refresh` 要**併進 arcrun 的 KBDB MCP**（`u6u-mcp-server`），**不另起 graph 獨立 MCP**。
+
+- **graph repo 端能備好的**：圖查詢的 HTTP API + 邏輯、`get_source` 端點（T3.7）、`refresh` 代轉 ingest 的端點。
+- **需 arcrun 端動的**：MCP 工具註冊薄殼那層 → 標清在 issue #1，由總管協調。本批不擅自開獨立 graph MCP。
+- **`refresh` 紅線**（T3.6b）：只能人發起的 MCP 調用觸發，**禁掛排程/webhook 自動 refresh**（否則變回 fan-out，踩 flag 紅線）。
+- **T3.6d**：整合時移除 `search-query.ts` 代理 base 關鍵字那條（重複，關鍵字歸 KBDB MCP）。
+
+## 8. 不做 / 延後
+
+- **graph CLI**（T3.7b）：延後。人少在命令行 traverse、AI 用不到 → 不做（非省工，是不誤導 AI 以為有這條路）。
+- **semantic normalize**（T3.2c）：本批先 exact-only，semantic 留接口。base embed（Arcrun #7）部署後才端到端，屆時標「待 base embed 部署驗」。
+
+## 9. 樂高法遵循
+
+- 每個 action <100 行、一檔一事、無狀態（狀態走 base API 持久化）。
+- route 不含業務邏輯，只 `makeKbdbClient(c.env)` + 驗證 + 呼叫 action。
+- 測試走 `tests/mock-client.ts`，不打真網路。
@@ -0,0 +1,34 @@
+# ingest-contract — tasks
+
+> **唯一進度來源**，不靠對話記憶。對應 [issue #1](https://github.com/uncle6me-web/kbdb-graph-plugin/issues/1)（頂層 mira-dissolve T3）。
+> 完成一項即時打勾 + 註記證據。端到端需 leo21c 部署的，標「待部署驗」，不假綠。
+
+## A. 契約 + template slot
+
+- [x] **3.1** 搬 `contracts/ingest-candidate.json` 進本 repo + `contracts/README.md` 標明候選≠已存（2026-06-26）
+- [ ] **3.2** `ensureTemplate` 改 slot-diff 補丁（命中既有 → base `PATCH /templates/:id` 補缺 slot，不再 early-return）；`TRIPLET_SLOTS` 加 `status` + `superseded_by` + `source_uri` + `content_hash`
+- [ ] **3.2b** `ENTITY_SLOTS` 加 `gloss`（已核實現無）
+- [ ] **3.2c** normalize 分層 fallback 接口：exact-only 先做；semantic 留接口（待 base embed，Arcrun #7）
+
+## B. 寫入端 + 取代（核心）
+
+- [ ] **3.3a** `KbdbClient.updateRecord(id, values)` → base `PATCH /records/:id`（已核實現無）
+- [ ] **3.3b** `src/actions/triplet-ingest.ts`：驗證 envelope（422 擋禁送欄位）→ idempotency（uri+hash）→ deprecate-then-append（先 append 後翻舊批 status）。<100 行純函式
+- [ ] **3.3c** `POST /triplets/ingest` route（只驗證 + 呼叫 action）
+- [ ] **3.4** 測試（mock，不打真網路）：正常 envelope / 同 hash no-op / 新 hash deprecate / 污染 envelope(帶 bridge_score) 422 / rollback(翻回 status)
+- [ ] **3.5** 查詢 active-only：traverse/search/neighbors 組圖前 filter `status==='active'`（缺省視為 active，相容舊資料）
+
+## C. MCP（⚠️ 跨 repo，需 arcrun 配合 → issue 標清）
+
+- [ ] **3.6** 圖查詢 + `refresh` HTTP API/邏輯備好（graph 端）；MCP 註冊薄殼併入 arcrun KBDB MCP（協調後接，**不另起 graph MCP**）
+- [ ] **3.6b** `refresh` 紅線：只人發起 MCP 觸發，禁排程/webhook 自動
+- [ ] **3.6d** 移除 `search-query.ts` 代理 base 關鍵字那條（重複，歸 KBDB MCP）
+- [ ] **3.7** `get_source` 端點（指回 source.uri + anchor）
+- [ ] **3.7b** ~~graph CLI~~ 延後不做（人少用、AI 用不到 → 不誤導）
+
+## 完成準則
+
+- 全程 zero SQL / zero migration / 無 D1·Vectorize·AI 綁定（`wrangler deploy --dry-run` bundle 乾淨）
+- 所有 action ≤100 行；`vitest run` 全綠（mock client）
+- 端到端 ingest→graph 走通需 base 上線 + ingest repo（T4）就緒 → 標「待部署驗」
+- issue #1 留 open，待實證綠燈才結案