Leo
98b221b435
對應 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>
80 lines
5.8 KiB
Markdown
80 lines
5.8 KiB
Markdown
# 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`，不打真網路。
|