@chainlesschain/personal-data-hub 0.1.0

package/__tests__/analysis.test.js

@@ -0,0 +1,302 @@
+"use strict";
+
+import { describe, it, expect, afterEach } from "vitest";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const { LocalVault } = require("../lib/vault");
+const { generateKeyHex } = require("../lib/key-providers");
+const { newId } = require("../lib/ids");
+const { AnalysisEngine } = require("../lib/analysis");
+const { MockLLMClient } = require("../lib/llm-client");
+
+// ─── Scaffolding ─────────────────────────────────────────────────────────
+
+let tmpDir;
+let vault;
+
+function freshVault() {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pdh-ana-"));
+  vault = new LocalVault({
+    path: path.join(tmpDir, "vault.db"),
+    key: generateKeyHex(),
+    skipAudit: true,
+  });
+  vault.open();
+}
+
+afterEach(() => {
+  if (vault) { try { vault.close(); } catch (_e) {} vault = null; }
+  if (tmpDir && fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+const ts = (year, month0, day, hour = 12) =>
+  new Date(year, month0, day, hour, 0, 0, 0).getTime();
+
+const source = (adapter = "taobao", originalId) => ({
+  adapter,
+  adapterVersion: "0.1.0",
+  capturedAt: ts(2026, 3, 15),
+  capturedBy: "api",
+  ...(originalId ? { originalId } : {}),
+});
+
+function seedOrders(vault) {
+  // 3 April-2026 orders to mom, 1 in May-2026 to self.
+  const e1 = {
+    id: newId(),
+    type: "event",
+    subtype: "order",
+    occurredAt: ts(2026, 3, 9),
+    actor: "person-self",
+    participants: ["person-self", "person-mom"],
+    content: {
+      title: "蛋白粉 给妈妈",
+      amount: { value: 288.5, currency: "CNY", direction: "out" },
+    },
+    ingestedAt: Date.now(),
+    source: source("taobao", "ord-1"),
+  };
+  const e2 = {
+    id: newId(),
+    type: "event",
+    subtype: "order",
+    occurredAt: ts(2026, 3, 12),
+    actor: "person-self",
+    content: {
+      title: "按摩仪 给妈妈",
+      amount: { value: 459, currency: "CNY", direction: "out" },
+    },
+    ingestedAt: Date.now(),
+    source: source("taobao", "ord-2"),
+  };
+  const e3 = {
+    id: newId(),
+    type: "event",
+    subtype: "order",
+    occurredAt: ts(2026, 3, 12, 10),
+    actor: "person-self",
+    content: {
+      title: "鲜花 给妈妈生日",
+      amount: { value: 199, currency: "CNY", direction: "out" },
+    },
+    ingestedAt: Date.now(),
+    source: source("taobao", "ord-3"),
+  };
+  const e4 = {
+    id: newId(),
+    type: "event",
+    subtype: "order",
+    occurredAt: ts(2026, 4, 5), // May (out of window for "上个月" if now=mid-May)
+    actor: "person-self",
+    content: {
+      title: "电子产品",
+      amount: { value: 1599, currency: "CNY", direction: "out" },
+    },
+    ingestedAt: Date.now(),
+    source: source("taobao", "ord-4"),
+  };
+  vault.putBatch({ events: [e1, e2, e3, e4], persons: [], places: [], items: [], topics: [] });
+  return [e1, e2, e3, e4];
+}
+
+const NOW = new Date("2026-05-19T12:00:00Z").getTime();
+
+// ─── Construction ────────────────────────────────────────────────────────
+
+describe("AnalysisEngine construction", () => {
+  it("requires vault + llm + llm.isLocal", () => {
+    expect(() => new AnalysisEngine({})).toThrow(/vault/);
+    expect(() => new AnalysisEngine({ vault: {} })).toThrow(/llm/);
+    expect(() => new AnalysisEngine({ vault: {}, llm: {} })).toThrow(/chat/);
+    expect(() => new AnalysisEngine({
+      vault: {},
+      llm: { chat: () => {} },
+    })).toThrow(/isLocal/);
+  });
+
+  it("constructs cleanly with mock LLM", () => {
+    freshVault();
+    const llm = new MockLLMClient({ reply: "" });
+    const e = new AnalysisEngine({ vault, llm });
+    expect(e.maxFacts).toBe(80);
+  });
+});
+
+// ─── Privacy gate ────────────────────────────────────────────────────────
+
+describe("AnalysisEngine privacy gate", () => {
+  it("refuses non-local LLM without acceptNonLocal opt-in", async () => {
+    freshVault();
+    const llm = new MockLLMClient({ reply: "" });
+    llm.isLocal = false; // simulate cloud
+    const e = new AnalysisEngine({ vault, llm });
+    await expect(e.ask("hello")).rejects.toThrow(/non-local/);
+    // Explicit opt-in unlocks
+    await expect(e.ask("hello", { acceptNonLocal: true })).resolves.toBeDefined();
+  });
+});
+
+// ─── E2E: 5 typical questions from architecture-doc §8.1 / §15.1 ────────
+
+describe("AnalysisEngine E2E (mock LLM, real vault)", () => {
+  it("Q1 sum: '上个月在淘宝总共花了多少？' — facts gathered + cited", async () => {
+    freshVault();
+    const [e1, e2, e3] = seedOrders(vault);
+
+    // Mock LLM that cites e1+e2+e3 with the total. We don't compute the sum
+    // here — the LLM would do that in production. We assert the engine
+    // hands the right facts and correctly validates the citations.
+    const llm = new MockLLMClient({
+      reply: `上个月你在淘宝下了 3 单：[${e1.id}] [${e2.id}] [${e3.id}]，共 ¥946.50。`,
+    });
+    const engine = new AnalysisEngine({ vault, llm });
+    const r = await engine.ask("上个月在淘宝总共花了多少？", { now: NOW });
+
+    expect(r.warning).toBeNull();
+    expect(r.citations.length).toBe(3);
+    expect(r.citations).toContain(e1.id);
+    expect(r.citations).toContain(e2.id);
+    expect(r.citations).toContain(e3.id);
+    expect(r.hallucinatedCitations).toEqual([]);
+    // facts: exactly the 3 April orders (May order excluded by time window)
+    expect(r.facts.length).toBe(3);
+    expect(r.facts.every((f) => f.subtype === "order")).toBe(true);
+    expect(r.parsed.filters.adapter).toBe("taobao");
+    expect(r.parsed.intent).toBe("sum-amount");
+  });
+
+  it("Q2 list: '我妈生日那周买了啥' — wider window, mocked LLM cites facts", async () => {
+    freshVault();
+    const orders = seedOrders(vault);
+    const llm = new MockLLMClient({
+      reply: `你给妈妈准备了：蛋白粉 [${orders[0].id}]、按摩仪 [${orders[1].id}]、鲜花 [${orders[2].id}]。`,
+    });
+    const engine = new AnalysisEngine({ vault, llm });
+    const r = await engine.ask("2026 年 4 月买了什么给妈妈？", { now: NOW });
+
+    expect(r.facts.length).toBe(3); // April orders
+    expect(r.citations.length).toBe(3);
+    expect(r.parsed.timeWindow).not.toBeNull();
+  });
+
+  it("Q3 no-facts: empty vault yields warning='no-facts'", async () => {
+    freshVault();
+    const llm = new MockLLMClient({
+      reply: "你的本月开销记录是空的。",
+    });
+    const engine = new AnalysisEngine({ vault, llm });
+    const r = await engine.ask("本月总共花了多少？", { now: NOW });
+
+    expect(r.warning).toBe("no-facts");
+    expect(r.facts).toEqual([]);
+    expect(r.citations).toEqual([]);
+    // The mocked answer should still come through unchanged.
+    expect(r.answer).toContain("空的");
+  });
+
+  it("Q4 hallucination detection: LLM cites unknown ids → warning='hallucinated-citations'", async () => {
+    freshVault();
+    seedOrders(vault);
+    const llm = new MockLLMClient({
+      reply: "总计 ¥1234 [evt-fake-id-1] [evt-also-fake-2]。",
+    });
+    const engine = new AnalysisEngine({ vault, llm });
+    const r = await engine.ask("上个月在淘宝总共花了多少？", { now: NOW });
+
+    expect(r.warning).toBe("hallucinated-citations");
+    expect(r.hallucinatedCitations).toContain("evt-fake-id-1");
+    expect(r.hallucinatedCitations).toContain("evt-also-fake-2");
+    expect(r.citations).toEqual([]); // no known ids cited
+  });
+
+  it("Q5 LLM error propagates: vault stays intact, audit recorded", async () => {
+    freshVault();
+    seedOrders(vault);
+    const llm = new MockLLMClient({});
+    llm.chat = async () => { throw new Error("Ollama down"); };
+    llm.isLocal = true;
+    const engine = new AnalysisEngine({ vault, llm });
+
+    await expect(engine.ask("test", { now: NOW })).rejects.toThrow(/Ollama down/);
+
+    const audits = vault.queryAudit({ action: "analysis.llm_failed" });
+    expect(audits.length).toBe(1);
+  });
+
+  it("audits every successful ask with fact + citation counts", async () => {
+    freshVault();
+    const orders = seedOrders(vault);
+    const llm = new MockLLMClient({ reply: `cited [${orders[0].id}]` });
+    const engine = new AnalysisEngine({ vault, llm });
+    await engine.ask("上个月在淘宝总共花了多少？", { now: NOW });
+
+    const audits = vault.queryAudit({ action: "analysis.ask" });
+    expect(audits.length).toBe(1);
+    const details = JSON.parse(audits[0].details);
+    expect(details.factCount).toBe(3);
+    expect(details.citationsKnown).toBe(1);
+    expect(details.citationsUnknown).toBe(0);
+    expect(details.warning).toBeNull();
+  });
+
+  it("skipAudit option suppresses audit row", async () => {
+    freshVault();
+    seedOrders(vault);
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault, llm });
+    await engine.ask("test", { now: NOW, skipAudit: true });
+    expect(vault.queryAudit({ action: "analysis.ask" }).length).toBe(0);
+  });
+});
+
+// ─── RAG augmentation ────────────────────────────────────────────────────
+
+describe("AnalysisEngine RAG retriever", () => {
+  it("adds RAG-retrieved events to facts (by id lookup in vault)", async () => {
+    freshVault();
+    const orders = seedOrders(vault);
+
+    // RAG returns the May order (which falls OUTSIDE the "上个月" time window)
+    // — engine should still include it because RAG marks it semantically
+    // relevant.
+    const ragRetriever = async () => [{ id: orders[3].id, text: "fake", metadata: {} }];
+
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault, llm, ragRetriever });
+    const r = await engine.ask("上个月在淘宝总共花了多少？", { now: NOW });
+
+    // Original 3 April orders + 1 May order pulled by RAG.
+    expect(r.facts.length).toBe(4);
+    expect(r.ragContextIds).toEqual([orders[3].id]);
+  });
+
+  it("RAG failure is captured but doesn't abort the ask", async () => {
+    freshVault();
+    seedOrders(vault);
+    const ragRetriever = async () => { throw new Error("qdrant unreachable"); };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault, llm, ragRetriever });
+
+    const r = await engine.ask("test", { now: NOW });
+    expect(r.answer).toBe("ok");
+    const audits = vault.queryAudit({ action: "analysis.rag_failed" });
+    expect(audits.length).toBe(1);
+  });
+});
+
+// ─── Empty / bad input ────────────────────────────────────────────────────
+
+describe("AnalysisEngine input validation", () => {
+  it("rejects empty / non-string question", async () => {
+    freshVault();
+    const engine = new AnalysisEngine({
+      vault,
+      llm: new MockLLMClient({ reply: "" }),
+    });
+    await expect(engine.ask("")).rejects.toThrow(/non-empty/);
+    await expect(engine.ask(null)).rejects.toThrow();
+  });
+});

package/__tests__/batch.test.js

@@ -0,0 +1,133 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { emptyBatch, mergeBatches, validateBatch, partitionBatch } = require("../lib/batch");
+const { newId } = require("../lib/ids");
+
+const source = () => ({
+  adapter: "test",
+  adapterVersion: "0.1.0",
+  capturedAt: Date.now(),
+  capturedBy: "api",
+});
+
+const goodEvent = () => ({
+  id: newId(),
+  type: "event",
+  subtype: "order",
+  occurredAt: Date.now(),
+  ingestedAt: Date.now(),
+  content: { title: "X" },
+  source: source(),
+});
+
+const goodPerson = () => ({
+  id: newId(),
+  type: "person",
+  subtype: "merchant",
+  names: ["美团"],
+  ingestedAt: Date.now(),
+  source: source(),
+});
+
+const badEvent = () => ({
+  // missing required occurredAt + source + content
+  id: newId(),
+  type: "event",
+  subtype: "order",
+  ingestedAt: Date.now(),
+});
+
+describe("emptyBatch", () => {
+  it("returns shape with all 5 entity arrays", () => {
+    const b = emptyBatch();
+    expect(b).toEqual({ events: [], persons: [], places: [], items: [], topics: [] });
+  });
+});
+
+describe("mergeBatches", () => {
+  it("concatenates all 5 arrays", () => {
+    const a = { ...emptyBatch(), events: [goodEvent()], persons: [goodPerson()] };
+    const b = { ...emptyBatch(), events: [goodEvent()] };
+    const merged = mergeBatches(a, b);
+    expect(merged.events.length).toBe(2);
+    expect(merged.persons.length).toBe(1);
+    expect(merged.places.length).toBe(0);
+  });
+
+  it("tolerates missing arrays in either input", () => {
+    const merged = mergeBatches({}, { persons: [goodPerson()] });
+    expect(merged.persons.length).toBe(1);
+    expect(merged.events.length).toBe(0);
+  });
+});
+
+describe("validateBatch", () => {
+  it("returns valid=true for an all-good batch", () => {
+    const r = validateBatch({ events: [goodEvent(), goodEvent()], persons: [goodPerson()] });
+    expect(r.valid).toBe(true);
+    expect(r.entityCount).toBe(3);
+    expect(r.errorCount).toBe(0);
+  });
+
+  it("collects all errors instead of throwing", () => {
+    const r = validateBatch({ events: [goodEvent(), badEvent(), badEvent()] });
+    expect(r.valid).toBe(false);
+    expect(r.entityCount).toBe(3);
+    expect(r.errorCount).toBe(2);
+    expect(r.errors.every((e) => e.kind === "events")).toBe(true);
+    expect(r.errors[0]).toHaveProperty("index");
+    expect(r.errors[0].errors.length).toBeGreaterThan(0);
+  });
+
+  it("rejects non-array entity buckets", () => {
+    const r = validateBatch({ events: "not-an-array" });
+    expect(r.valid).toBe(false);
+    expect(r.errors[0].errors[0]).toMatch(/array/);
+  });
+
+  it("rejects non-object batch", () => {
+    expect(validateBatch(null).valid).toBe(false);
+    expect(validateBatch("string").valid).toBe(false);
+  });
+
+  it("accepts batch with only some entity types populated", () => {
+    const r = validateBatch({ persons: [goodPerson()] });
+    expect(r.valid).toBe(true);
+    expect(r.entityCount).toBe(1);
+  });
+});
+
+describe("partitionBatch", () => {
+  it("separates valid from invalid into distinct sub-batches", () => {
+    const gE = goodEvent();
+    const bE = badEvent();
+    const gP = goodPerson();
+
+    const { valid, invalid, invalidReasons } = partitionBatch({
+      events: [gE, bE],
+      persons: [gP],
+    });
+
+    expect(valid.events).toEqual([gE]);
+    expect(valid.persons).toEqual([gP]);
+    expect(invalid.events).toEqual([bE]);
+    expect(invalid.persons).toEqual([]);
+    expect(invalidReasons.length).toBe(1);
+    expect(invalidReasons[0].kind).toBe("events");
+    expect(invalidReasons[0].id).toBe(bE.id);
+  });
+
+  it("returns empty invalid sub-batch when all rows are valid", () => {
+    const { valid, invalid, invalidReasons } = partitionBatch({
+      events: [goodEvent()],
+      persons: [goodPerson()],
+    });
+    expect(invalid.events).toEqual([]);
+    expect(invalid.persons).toEqual([]);
+    expect(invalidReasons).toEqual([]);
+    expect(valid.events.length).toBe(1);
+    expect(valid.persons.length).toBe(1);
+  });
+});

package/__tests__/bridges-cc-kg.test.js

@@ -0,0 +1,231 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { CcKgSink, HUB_TO_CC_TYPE } = require("../lib/bridges/cc-kg-sink");
+
+// ─── Fake cc KG (mirrors the real addEntity/addRelation signature) ──────
+
+function makeFakeKg() {
+  const entities = new Map();
+  const relations = [];
+  return {
+    addEntity(_db, cfg) {
+      if (!cfg || !cfg.id || !cfg.name || !cfg.type) {
+        throw new Error("missing required fields");
+      }
+      if (entities.has(cfg.id)) {
+        throw new Error(`Entity already exists: ${cfg.id}`);
+      }
+      entities.set(cfg.id, { ...cfg });
+      return cfg;
+    },
+    addRelation(_db, cfg) {
+      if (!entities.has(cfg.sourceId)) throw new Error(`source not found: ${cfg.sourceId}`);
+      if (!entities.has(cfg.targetId)) throw new Error(`target not found: ${cfg.targetId}`);
+      relations.push({ ...cfg });
+      return cfg;
+    },
+    entities,
+    relations,
+  };
+}
+
+const t = (subject, predicate, opts) => {
+  const out = { subject, predicate };
+  if (opts && opts.object) out.object = opts.object;
+  else if (opts && opts.literal !== undefined) out.literal = opts.literal;
+  return out;
+};
+
+// ─── Tests ──────────────────────────────────────────────────────────────
+
+describe("CcKgSink construction", () => {
+  it("requires addEntity + addRelation", () => {
+    expect(() => new CcKgSink()).toThrow();
+    expect(() => new CcKgSink({ addRelation: () => {} })).toThrow(/addEntity/);
+    expect(() => new CcKgSink({ addEntity: () => {} })).toThrow(/addRelation/);
+  });
+});
+
+describe("CcKgSink.write entity creation", () => {
+  it("creates entities from rdf:type + has-name triples", async () => {
+    const cc = makeFakeKg();
+    const sink = new CcKgSink({ addEntity: cc.addEntity, addRelation: cc.addRelation });
+    const r = await sink.write([
+      t("p1", "rdf:type", { literal: "person" }),
+      t("p1", "subtype", { literal: "contact" }),
+      t("p1", "has-name", { literal: "妈妈" }),
+      t("p1", "has-name", { literal: "陈某某" }),
+      t("p1", "id:phone", { literal: "13800001111" }),
+    ]);
+    expect(r.entitiesUpserted).toBe(1);
+    const e = cc.entities.get("p1");
+    expect(e.type).toBe("Person");
+    expect(e.name).toBe("妈妈"); // first name wins
+    expect(e.properties.subtype).toBe("contact");
+    expect(e.properties.hubKind).toBe("person");
+    expect(e.properties.aliases).toEqual(["陈某某"]);
+    expect(e.properties["id:phone"]).toBe("13800001111");
+  });
+
+  it("maps hub place → cc Concept with hubKind", async () => {
+    const cc = makeFakeKg();
+    const sink = new CcKgSink({ addEntity: cc.addEntity, addRelation: cc.addRelation });
+    await sink.write([
+      t("pl1", "rdf:type", { literal: "place" }),
+      t("pl1", "has-name", { literal: "妈妈家" }),
+      t("pl1", "located-at", { literal: "24.5,118.1" }),
+    ]);
+    const e = cc.entities.get("pl1");
+    expect(e.type).toBe("Concept");
+    expect(e.properties.hubKind).toBe("place");
+    expect(e.properties["located-at"]).toBe("24.5,118.1");
+  });
+
+  it("maps hub item / topic → cc Concept", async () => {
+    const cc = makeFakeKg();
+    const sink = new CcKgSink({ addEntity: cc.addEntity, addRelation: cc.addRelation });
+    await sink.write([
+      t("i1", "rdf:type", { literal: "item" }),
+      t("i1", "has-name", { literal: "蛋白粉" }),
+      t("t1", "rdf:type", { literal: "topic" }),
+      t("t1", "has-name", { literal: "母亲健康" }),
+    ]);
+    expect(cc.entities.get("i1").type).toBe("Concept");
+    expect(cc.entities.get("i1").properties.hubKind).toBe("item");
+    expect(cc.entities.get("t1").type).toBe("Concept");
+    expect(cc.entities.get("t1").properties.hubKind).toBe("topic");
+  });
+
+  it("falls back to subject id when no has-name (uses Event subject as name)", async () => {
+    const cc = makeFakeKg();
+    const sink = new CcKgSink({ addEntity: cc.addEntity, addRelation: cc.addRelation });
+    await sink.write([
+      t("evt-x", "rdf:type", { literal: "event" }),
+      t("evt-x", "subtype", { literal: "order" }),
+    ]);
+    expect(cc.entities.get("evt-x").name).toBe("evt-x");
+    expect(cc.entities.get("evt-x").type).toBe("Event");
+  });
+
+  it("treats 'already exists' as upsert success (no error)", async () => {
+    const cc = makeFakeKg();
+    const sink = new CcKgSink({ addEntity: cc.addEntity, addRelation: cc.addRelation });
+    await sink.write([
+      t("p1", "rdf:type", { literal: "person" }),
+      t("p1", "has-name", { literal: "alice" }),
+    ]);
+    // Second write of same subject — cc throws "already exists"
+    const r = await sink.write([
+      t("p1", "rdf:type", { literal: "person" }),
+      t("p1", "has-name", { literal: "alice" }),
+    ]);
+    expect(r.entitiesUpserted).toBe(0);
+    expect(r.errors.length).toBe(0); // already-exists treated as upsert hit
+  });
+
+  it("captures unknown predicates under __extra", async () => {
+    const cc = makeFakeKg();
+    const sink = new CcKgSink({ addEntity: cc.addEntity, addRelation: cc.addRelation });
+    await sink.write([
+      t("evt-x", "rdf:type", { literal: "event" }),
+      t("evt-x", "weird-predicate", { literal: "foo" }),
+    ]);
+    expect(cc.entities.get("evt-x").properties.__extra).toEqual({ "weird-predicate": "foo" });
+  });
+
+  it("collects upstream errors (e.g. missing required field)", async () => {
+    const cc = makeFakeKg();
+    const sink = new CcKgSink({
+      addEntity: () => { throw new Error("upstream DB exploded"); },
+      addRelation: cc.addRelation,
+    });
+    const r = await sink.write([t("p1", "rdf:type", { literal: "person" })]);
+    expect(r.entitiesUpserted).toBe(0);
+    expect(r.errors.length).toBe(1);
+    expect(r.errors[0].error).toContain("upstream DB exploded");
+  });
+});
+
+describe("CcKgSink.write relation creation", () => {
+  it("adds relations between created entities", async () => {
+    const cc = makeFakeKg();
+    const sink = new CcKgSink({ addEntity: cc.addEntity, addRelation: cc.addRelation });
+    const r = await sink.write([
+      t("evt-1", "rdf:type", { literal: "event" }),
+      t("evt-1", "subtype", { literal: "payment" }),
+      t("p1", "rdf:type", { literal: "person" }),
+      t("p1", "has-name", { literal: "mom" }),
+      t("evt-1", "by", { object: "p1" }),
+      t("evt-1", "involves", { object: "p1" }),
+    ]);
+    expect(r.entitiesUpserted).toBe(2);
+    expect(r.relationsAdded).toBe(2);
+    expect(cc.relations).toContainEqual({ sourceId: "evt-1", targetId: "p1", relationType: "by" });
+    expect(cc.relations).toContainEqual({ sourceId: "evt-1", targetId: "p1", relationType: "involves" });
+  });
+
+  it("skips relation when endpoint not in KG (no dangling refs)", async () => {
+    const cc = makeFakeKg();
+    const sink = new CcKgSink({ addEntity: cc.addEntity, addRelation: cc.addRelation });
+    const r = await sink.write([
+      t("evt-1", "rdf:type", { literal: "event" }),
+      // p-missing was never declared with rdf:type
+      t("evt-1", "by", { object: "p-missing" }),
+    ]);
+    expect(r.relationsAdded).toBe(0);
+    expect(r.errors.length).toBe(1);
+    expect(r.errors[0].error).toContain("endpoint not in KG");
+  });
+
+  it("rejects unknown predicates (defensive — don't poison cc KG)", async () => {
+    const cc = makeFakeKg();
+    const sink = new CcKgSink({ addEntity: cc.addEntity, addRelation: cc.addRelation });
+    await sink.write([t("e", "rdf:type", { literal: "event" })]);
+    await sink.write([t("p", "rdf:type", { literal: "person" })]);
+    const r = await sink.write([t("e", "frobnicate", { object: "p" })]);
+    expect(r.relationsAdded).toBe(0);
+    expect(r.errors[0].error).toBe("unknown predicate");
+  });
+
+  it("tolerates duplicate-relation errors as success", async () => {
+    const cc = makeFakeKg();
+    const sink = new CcKgSink({
+      addEntity: cc.addEntity,
+      addRelation: () => { throw new Error("Relation already exists"); },
+    });
+    await sink.write([
+      t("e", "rdf:type", { literal: "event" }),
+      t("p", "rdf:type", { literal: "person" }),
+    ]);
+    const r = await sink.write([t("e", "by", { object: "p" })]);
+    // Even though addRelation throws "already exists", sink treats as success.
+    expect(r.errors.length).toBe(0);
+  });
+});
+
+describe("CcKgSink edge cases", () => {
+  it("returns zeros for empty input", async () => {
+    const cc = makeFakeKg();
+    const sink = new CcKgSink({ addEntity: cc.addEntity, addRelation: cc.addRelation });
+    const r = await sink.write([]);
+    expect(r).toEqual({ entitiesUpserted: 0, relationsAdded: 0, errors: [] });
+  });
+
+  it("ignores malformed triples (missing subject/predicate)", async () => {
+    const cc = makeFakeKg();
+    const sink = new CcKgSink({ addEntity: cc.addEntity, addRelation: cc.addRelation });
+    const r = await sink.write([{ predicate: "rdf:type", literal: "person" }, null, undefined]);
+    expect(r.entitiesUpserted).toBe(0);
+    expect(cc.entities.size).toBe(0);
+  });
+
+  it("HUB_TO_CC_TYPE exposes the documented mapping", () => {
+    expect(HUB_TO_CC_TYPE.person).toBe("Person");
+    expect(HUB_TO_CC_TYPE.event).toBe("Event");
+    expect(HUB_TO_CC_TYPE.place).toBe("Concept");
+    expect(HUB_TO_CC_TYPE.item).toBe("Concept");
+    expect(HUB_TO_CC_TYPE.topic).toBe("Concept");
+  });
+});