feat: ingest 寫入端 + deprecate + get_source/refresh + wiki 合併 (issue #1 T3) (#2)

* chore(wiki): 導入 system-dev-template + 合併 wiki 到新位置 - system-dev/ 模板包進版控（VERSION/docs/scripts/wiki 骨架） - 逐檔合併舊 .claude/wiki/ → system-dev/wiki/： - status/mistakes/decisions-summary 真資料覆蓋空範本 - INDEX 新「多角度視圖」結構 + 舊決策/導航併入（過時詞「萬物皆 Block」改 API-as-Wall） - principles/TAXONOMY 為新位置獨有，保留 - 刪舊 .claude/wiki/（git 識別為 rename，內容完整搬移） - 三層機敏防護 hooks + wiki 命令更新 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * 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> * feat(ingest): POST /triplets/ingest 寫入端 + deprecate-then-append (T3.2-3.5) 對應 issue #1 T3 B 段。 - templates: TRIPLET_SLOTS 加 status/superseded_by/source_uri/content_hash； ENTITY_SLOTS 加 gloss；recordToTriplet 映射新欄位（缺省 status=active 相容舊資料） - kbdb-client: ensureTemplate 改 slot-diff 補丁（既有 template 走 PATCH /templates/:id 補缺 slot，取代 early-return → 免遷移腳本）；新增 updateRecord（PATCH /records/:id） - triplet-ingest action（88 行純函式）：Zod strict 鏡射 ingest-candidate 契約 → idempotency（uri+hash 同→no-op）→ 先 append 後 deprecate（無「全無 active」空窗） - POST /triplets/ingest route：strict 驗證失敗 → 422（禁送 graph 領域欄位） - queryTriplets 預設 active-only（traverse/search/neighbors 皆經此）， includeDeprecated opt-out 供 rollback/考古 - 6 測試案全綠（vitest 16 passed）；mock-client 同步 slot-diff + updateRecord gates: zero SQL / zero migration / 無 D1·Vectorize·AI 綁定 / dry-run bundle 乾淨 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(graph): get_source + refresh 端點 + keyword 收斂 (T3.6-3.7) 對應 issue #1 T3 C 段（圖工具 HTTP API 備好，MCP 註冊薄殼待 arcrun）。 - get_source (3.7): graph-source.ts + GET /graph/source/:name — 回節點的 active triplet 來源指標（uri/anchor/block_id/content_hash），去重。連帶加 source_anchor slot，ingest 從 source.anchor 帶入 - refresh (3.6/3.6b): graph-refresh.ts + POST /graph/refresh — 純被動代轉 ingest（KBDB_INGEST_URL），只人發起、無排程/webhook（fan-out 紅線）。未設 URL → 誠實 forwarded:false，不假綠 - 3.6d: POST /search 移除公開 keyword 模式（重複 KBDB MCP），收斂 suggest-only； keywordSearch helper 留作 suggest 內部建構塊 - 3 新測試（get_source uri+anchor / active-only / refresh 未就緒誠實回報） gates: vitest 19 passed / zero SQL / 無新綁定 / dry-run bundle 乾淨待接：MCP 註冊薄殼併 arcrun u6u-mcp-server；refresh 端到端待 ingest(T4) 部署 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: richblack <leo21c@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-26 19:00:54 +08:00
parent 3a1faf19f4
commit 7a29dee357
44 changed files with 2773 additions and 96 deletions
@@ -0,0 +1,49 @@
+// get_source + refresh（C 段）— 走 mock，零 SQL、不打真網路。
+import { describe, it, expect } from 'vitest';
+import { ingestEnvelope } from '../src/actions/triplet-ingest';
+import { getSource } from '../src/actions/graph-source';
+import { refreshSource } from '../src/actions/graph-refresh';
+import { mockClient } from './mock-client';
+
+describe('getSource — 回節點的原文來源指標', () => {
+  it('回觸及節點的 triplet 的 uri + anchor', async () => {
+    const c = mockClient();
+    await ingestEnvelope(c, {
+      source: { uri: 'github:u/w@a.md', content_hash: 'h1', anchor: '#graph-rag' },
+      extractor: { model: 'm', tier: 'deep' },
+      triplets: [{ subject: 'GraphRAG', predicate: '是', object: 'RAG 變體' }],
+    });
+
+    const refs = await getSource(c, 'GraphRAG');
+    expect(refs.length).toBe(1);
+    expect(refs[0].uri).toBe('github:u/w@a.md');
+    expect(refs[0].anchor).toBe('#graph-rag');
+    expect(refs[0].edge).toEqual({ subject: 'GraphRAG', predicate: '是', object: 'RAG 變體' });
+  });
+
+  it('deprecated triplet 不出現在 get_source（active-only）', async () => {
+    const c = mockClient();
+    await ingestEnvelope(c, {
+      source: { uri: 'github:u/w@a.md', content_hash: 'h1', anchor: '#old' },
+      extractor: { model: 'm', tier: 'deep' },
+      triplets: [{ subject: 'X', predicate: 'r', object: 'old' }],
+    });
+    await ingestEnvelope(c, {
+      source: { uri: 'github:u/w@a.md', content_hash: 'h2', anchor: '#new' },
+      extractor: { model: 'm', tier: 'deep' },
+      triplets: [{ subject: 'X', predicate: 'r', object: 'new' }],
+    });
+
+    const refs = await getSource(c, 'X');
+    expect(refs.length).toBe(1);
+    expect(refs[0].anchor).toBe('#new'); // 只見 active 批
+  });
+});
+
+describe('refreshSource — 代轉 ingest（人發起）', () => {
+  it('KBDB_INGEST_URL 未設 → 誠實回 forwarded:false，不假裝成功', async () => {
+    const res = await refreshSource({ uri: 'github:u/w@a.md' }, undefined);
+    expect(res.forwarded).toBe(false);
+    expect(res.note).toMatch(/未就緒|未設/);
+  });
+});
@@ -50,12 +50,19 @@ export class MockKbdbClient {
  }

  async ensureTemplate(name: string, slots: string[]): Promise<void> {
-    if (!this.templates.has(name)) this.templates.set(name, slots);
+    // 對齊真 client 的 slot-diff 行為：既有 template 補缺 slot（不 early-return）。
+    const have = this.templates.get(name);
+    if (!have) {
+      this.templates.set(name, [...slots]);
+      return;
+    }
+    const set = new Set(have);
+    for (const s of slots) if (!set.has(s)) have.push(s);
  }

  async createRecord(template: string, values: Record<string, string>, owner_id?: string): Promise<string> {
    const id = this.id('rec');
-    this.records.set(id, { template, values, owner_id });
+    this.records.set(id, { template, values: { ...values }, owner_id });
    return id;
  }

@@ -65,6 +72,11 @@ export class MockKbdbClient {
    return { record_id: recordId, template: r.template, values: r.values };
  }

+  async updateRecord(recordId: string, values: Record<string, string>): Promise<void> {
+    const r = this.records.get(recordId);
+    if (r) Object.assign(r.values, values);
+  }
+
  async listRecordsByTemplate(template: string, owner_id?: string): Promise<BaseRecord[]> {
    return [...this.records.entries()]
      .filter(([, r]) => r.template === template && (!owner_id || r.owner_id === owner_id))
@@ -0,0 +1,102 @@
+// ingest 寫入端 — 走 mock KbdbClient（API-as-Wall），零 SQL、不打網路。
+// 覆蓋 T3.4 五案：正常 envelope / 同 hash no-op / 新 hash deprecate / 污染 envelope 422 / rollback。
+import { describe, it, expect } from 'vitest';
+import { ingestEnvelope, IngestEnvelopeSchema, type IngestEnvelope } from '../src/actions/triplet-ingest';
+import { queryTriplets } from '../src/actions/triplet-crud';
+import { mockClient } from './mock-client';
+
+function envelope(hash: string, triplets: IngestEnvelope['triplets']): IngestEnvelope {
+  return {
+    source: { uri: 'github:uncle6me-web/wiki@a.md', content_hash: hash },
+    extractor: { model: 'claude-sonnet-4-6', tier: 'deep' },
+    triplets,
+  };
+}
+
+describe('ingestEnvelope — 正常 envelope', () => {
+  it('append 全部 triplet 為 active，記 source_uri/content_hash', async () => {
+    const c = mockClient();
+    const res = await ingestEnvelope(c, envelope('h1', [
+      { subject: 'A', predicate: 'rel', object: 'B' },
+      { subject: 'B', predicate: 'rel', object: 'C' },
+    ]));
+    expect(res).toEqual({ skipped: false, ingested: 2, deprecated: 0 });
+
+    const { triplets } = await queryTriplets(c, {});
+    expect(triplets.length).toBe(2);
+    expect(triplets.every((t) => t.status === 'active')).toBe(true);
+    expect(triplets[0].source_uri).toBe('github:uncle6me-web/wiki@a.md');
+    expect(triplets[0].content_hash).toBe('h1');
+  });
+});
+
+describe('ingestEnvelope — 同 hash no-op', () => {
+  it('同 uri+hash 再送 → skipped，不新增', async () => {
+    const c = mockClient();
+    await ingestEnvelope(c, envelope('h1', [{ subject: 'A', predicate: 'r', object: 'B' }]));
+    const res = await ingestEnvelope(c, envelope('h1', [{ subject: 'A', predicate: 'r', object: 'B' }]));
+    expect(res.skipped).toBe(true);
+
+    const { triplets } = await queryTriplets(c, {});
+    expect(triplets.length).toBe(1); // 沒有重複 append
+  });
+});
+
+describe('ingestEnvelope — 新 hash deprecate-then-append', () => {
+  it('同 uri 新 hash → 舊批轉 deprecated、新批 active；查詢 active-only', async () => {
+    const c = mockClient();
+    await ingestEnvelope(c, envelope('h1', [{ subject: 'A', predicate: 'r', object: 'old' }]));
+    const res = await ingestEnvelope(c, envelope('h2', [{ subject: 'A', predicate: 'r', object: 'new' }]));
+    expect(res).toEqual({ skipped: false, ingested: 1, deprecated: 1 });
+
+    // active-only 查詢只見新批。
+    const active = await queryTriplets(c, {});
+    expect(active.triplets.length).toBe(1);
+    expect(active.triplets[0].object).toBe('new');
+
+    // 舊批仍在（deprecated），可考古/rollback。
+    const all = await queryTriplets(c, { includeDeprecated: true });
+    expect(all.triplets.length).toBe(2);
+    const deprecated = all.triplets.find((t) => t.status === 'deprecated');
+    expect(deprecated?.object).toBe('old');
+    expect(deprecated?.superseded_by).toBe('h2');
+  });
+});
+
+describe('ingestEnvelope — 污染 envelope 422（契約 strict）', () => {
+  it('triplet 帶 graph 領域欄位 bridge_score → schema 拒收', () => {
+    const polluted = {
+      source: { uri: 'u', content_hash: 'h' },
+      extractor: { model: 'm', tier: 'deep' },
+      triplets: [{ subject: 'A', predicate: 'r', object: 'B', bridge_score: 3 }],
+    };
+    const parsed = IngestEnvelopeSchema.safeParse(polluted);
+    expect(parsed.success).toBe(false);
+  });
+
+  it('envelope 頂層帶禁止欄位 id → 拒收', () => {
+    const polluted = {
+      id: 'should-not-send',
+      source: { uri: 'u', content_hash: 'h' },
+      extractor: { model: 'm', tier: 'deep' },
+      triplets: [{ subject: 'A', predicate: 'r', object: 'B' }],
+    };
+    expect(IngestEnvelopeSchema.safeParse(polluted).success).toBe(false);
+  });
+});
+
+describe('ingestEnvelope — rollback（翻回 status）', () => {
+  it('把 deprecated 翻回 active 後，active 查詢重新見到它', async () => {
+    const c = mockClient();
+    await ingestEnvelope(c, envelope('h1', [{ subject: 'A', predicate: 'r', object: 'old' }]));
+    await ingestEnvelope(c, envelope('h2', [{ subject: 'A', predicate: 'r', object: 'new' }]));
+
+    // 取出被 deprecate 的舊批 id，手動 rollback（翻回 active、清 superseded_by）。
+    const all = await queryTriplets(c, { includeDeprecated: true });
+    const old = all.triplets.find((t) => t.status === 'deprecated')!;
+    await c.updateRecord(old.id, { status: 'active', superseded_by: '' });
+
+    const active = await queryTriplets(c, {});
+    expect(active.triplets.map((t) => t.object).sort()).toEqual(['new', 'old']);
+  });
+});