@chainlesschain/personal-data-hub 0.1.0

package/__tests__/kg-derive.test.js

@@ -0,0 +1,219 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const {
+  deriveEventTriples,
+  derivePersonTriples,
+  derivePlaceTriples,
+  deriveItemTriples,
+  deriveTopicTriples,
+  deriveBatchTriples,
+  deriveEntityTriples,
+  triple,
+} = require("../lib/kg-derive");
+
+const { newId } = require("../lib/ids");
+
+const sourceOk = (adapter = "test") => ({
+  adapter,
+  adapterVersion: "0.1.0",
+  capturedAt: Date.now(),
+  capturedBy: "api",
+});
+
+describe("triple()", () => {
+  it("makes an object triple with subject + predicate + object", () => {
+    const t = triple("a", "knows", { object: "b" });
+    expect(t).toEqual({ subject: "a", predicate: "knows", object: "b" });
+  });
+  it("makes a literal triple", () => {
+    const t = triple("a", "name", { literal: "Alice" });
+    expect(t).toEqual({ subject: "a", predicate: "name", literal: "Alice" });
+  });
+  it("skips object/literal when null/undefined", () => {
+    const t = triple("a", "p", {});
+    expect(t).toEqual({ subject: "a", predicate: "p" });
+  });
+});
+
+describe("deriveEventTriples", () => {
+  it("emits the minimal set: rdf:type / subtype / occurred-at / source", () => {
+    const id = newId();
+    const e = {
+      id,
+      type: "event",
+      subtype: "message",
+      occurredAt: 1700000000000,
+      ingestedAt: 1700000000001,
+      content: { text: "hi" },
+      source: sourceOk("wechat"),
+    };
+    const ts = deriveEventTriples(e);
+    expect(ts).toContainEqual({ subject: id, predicate: "rdf:type", literal: "event" });
+    expect(ts).toContainEqual({ subject: id, predicate: "subtype", literal: "message" });
+    expect(ts).toContainEqual({ subject: id, predicate: "occurred-at", literal: 1700000000000 });
+    expect(ts).toContainEqual({ subject: id, predicate: "source", literal: "wechat" });
+  });
+
+  it("emits 'by' for actor and 'involves' for each participant", () => {
+    const id = newId();
+    const e = {
+      id,
+      type: "event",
+      subtype: "payment",
+      occurredAt: 1,
+      ingestedAt: 1,
+      actor: "person-self",
+      participants: ["person-self", "person-mom"],
+      content: { text: "transfer" },
+      source: sourceOk(),
+    };
+    const ts = deriveEventTriples(e);
+    expect(ts).toContainEqual({ subject: id, predicate: "by", object: "person-self" });
+    expect(ts).toContainEqual({ subject: id, predicate: "involves", object: "person-self" });
+    expect(ts).toContainEqual({ subject: id, predicate: "involves", object: "person-mom" });
+  });
+
+  it("emits amount components when content.amount present", () => {
+    const id = newId();
+    const e = {
+      id,
+      type: "event",
+      subtype: "order",
+      occurredAt: 1,
+      ingestedAt: 1,
+      content: { amount: { value: 288.5, currency: "CNY", direction: "out" } },
+      source: sourceOk(),
+    };
+    const ts = deriveEventTriples(e);
+    expect(ts).toContainEqual({ subject: id, predicate: "amount-value", literal: 288.5 });
+    expect(ts).toContainEqual({ subject: id, predicate: "amount-currency", literal: "CNY" });
+    expect(ts).toContainEqual({ subject: id, predicate: "amount-direction", literal: "out" });
+  });
+});
+
+describe("derivePersonTriples", () => {
+  it("emits rdf:type + subtype + every name + identifier", () => {
+    const id = newId();
+    const p = {
+      id,
+      type: "person",
+      subtype: "contact",
+      names: ["妈妈", "陈某某"],
+      identifiers: { phone: ["13800001111", "13900002222"], wechatId: "wxid_xyz" },
+      ingestedAt: 1,
+      source: sourceOk(),
+    };
+    const ts = derivePersonTriples(p);
+    expect(ts).toContainEqual({ subject: id, predicate: "rdf:type", literal: "person" });
+    expect(ts).toContainEqual({ subject: id, predicate: "subtype", literal: "contact" });
+    expect(ts).toContainEqual({ subject: id, predicate: "has-name", literal: "妈妈" });
+    expect(ts).toContainEqual({ subject: id, predicate: "has-name", literal: "陈某某" });
+    expect(ts).toContainEqual({ subject: id, predicate: "id:phone", literal: "13800001111" });
+    expect(ts).toContainEqual({ subject: id, predicate: "id:phone", literal: "13900002222" });
+    expect(ts).toContainEqual({ subject: id, predicate: "id:wechatId", literal: "wxid_xyz" });
+  });
+});
+
+describe("derivePlaceTriples", () => {
+  it("emits has-name + has-alias (deduped) + located-at + address", () => {
+    const id = newId();
+    const pl = {
+      id,
+      type: "place",
+      name: "妈妈家",
+      aliases: ["妈妈家", "妈家", "home"],
+      coordinates: { lat: 24.5, lng: 118.1 },
+      address: "厦门思明区",
+      category: "home",
+      ingestedAt: 1,
+      source: sourceOk(),
+    };
+    const ts = derivePlaceTriples(pl);
+    expect(ts).toContainEqual({ subject: id, predicate: "has-name", literal: "妈妈家" });
+    // The primary name shouldn't duplicate as alias
+    expect(ts.filter((t) => t.predicate === "has-name").length).toBe(1);
+    expect(ts.some((t) => t.predicate === "has-alias" && t.literal === "妈家")).toBe(true);
+    expect(ts).toContainEqual({ subject: id, predicate: "located-at", literal: "24.5,118.1" });
+    expect(ts).toContainEqual({ subject: id, predicate: "address", literal: "厦门思明区" });
+  });
+});
+
+describe("deriveItemTriples", () => {
+  it("emits price + merchant", () => {
+    const id = newId();
+    const i = {
+      id,
+      type: "item",
+      subtype: "product",
+      name: "蛋白粉",
+      price: { value: 288, currency: "CNY" },
+      merchant: "person-xy-store",
+      ingestedAt: 1,
+      source: sourceOk(),
+    };
+    const ts = deriveItemTriples(i);
+    expect(ts).toContainEqual({ subject: id, predicate: "priced-at", literal: "288 CNY" });
+    expect(ts).toContainEqual({ subject: id, predicate: "sold-by", object: "person-xy-store" });
+  });
+});
+
+describe("deriveTopicTriples", () => {
+  it("emits parent + derived-from for each event", () => {
+    const id = newId();
+    const e1 = newId();
+    const e2 = newId();
+    const t = {
+      id,
+      type: "topic",
+      name: "母亲健康",
+      parentTopic: "topic-family",
+      derivedFromEvents: [e1, e2],
+      ingestedAt: 1,
+      source: sourceOk(),
+    };
+    const ts = deriveTopicTriples(t);
+    expect(ts).toContainEqual({ subject: id, predicate: "parent", object: "topic-family" });
+    expect(ts).toContainEqual({ subject: id, predicate: "derived-from", object: e1 });
+    expect(ts).toContainEqual({ subject: id, predicate: "derived-from", object: e2 });
+  });
+});
+
+describe("deriveBatchTriples + deriveEntityTriples", () => {
+  it("walks all 5 entity kinds in a batch", () => {
+    const batch = {
+      events: [{ id: "e", type: "event", subtype: "message", occurredAt: 1, ingestedAt: 1, content: {}, source: sourceOk() }],
+      persons: [{ id: "p", type: "person", subtype: "contact", names: ["x"], ingestedAt: 1, source: sourceOk() }],
+      places: [{ id: "pl", type: "place", name: "home", aliases: [], ingestedAt: 1, source: sourceOk() }],
+      items: [{ id: "i", type: "item", subtype: "product", name: "thing", ingestedAt: 1, source: sourceOk() }],
+      topics: [{ id: "t", type: "topic", name: "x", ingestedAt: 1, source: sourceOk() }],
+    };
+    const ts = deriveBatchTriples(batch);
+    expect(ts.length).toBeGreaterThan(5); // at least the 5 rdf:type rows
+    expect(ts.some((x) => x.subject === "e" && x.predicate === "rdf:type")).toBe(true);
+    expect(ts.some((x) => x.subject === "p" && x.predicate === "rdf:type")).toBe(true);
+    expect(ts.some((x) => x.subject === "pl" && x.predicate === "rdf:type")).toBe(true);
+    expect(ts.some((x) => x.subject === "i" && x.predicate === "rdf:type")).toBe(true);
+    expect(ts.some((x) => x.subject === "t" && x.predicate === "rdf:type")).toBe(true);
+  });
+
+  it("deriveEntityTriples dispatches by .type and returns [] for unknown", () => {
+    expect(deriveEntityTriples(null)).toEqual([]);
+    expect(deriveEntityTriples({ type: "frobnicate" })).toEqual([]);
+    const ts = deriveEntityTriples({
+      id: "p",
+      type: "person",
+      subtype: "contact",
+      names: ["x"],
+      ingestedAt: 1,
+      source: sourceOk(),
+    });
+    expect(ts.length).toBeGreaterThan(0);
+  });
+
+  it("returns [] for non-object batch input", () => {
+    expect(deriveBatchTriples(null)).toEqual([]);
+    expect(deriveBatchTriples("oops")).toEqual([]);
+  });
+});

package/__tests__/llm-client.test.js

@@ -0,0 +1,122 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { MockLLMClient, OllamaClient } = require("../lib/llm-client");
+
+// ─── MockLLMClient ────────────────────────────────────────────────────────
+
+describe("MockLLMClient", () => {
+  it("isLocal is always true", () => {
+    expect(new MockLLMClient().isLocal).toBe(true);
+  });
+
+  it("returns the configured static reply", async () => {
+    const c = new MockLLMClient({ reply: "hello [evt-1]" });
+    const r = await c.chat([{ role: "user", content: "x" }]);
+    expect(r.text).toBe("hello [evt-1]");
+    expect(r.model).toBe("mock-llm");
+  });
+
+  it("records every call for assertion", async () => {
+    const c = new MockLLMClient({ reply: "ok" });
+    await c.chat([{ role: "user", content: "a" }]);
+    await c.chat([{ role: "user", content: "b" }]);
+    expect(c.calls.length).toBe(2);
+    expect(c.calls[0].messages[0].content).toBe("a");
+    expect(c.calls[1].messages[0].content).toBe("b");
+  });
+
+  it("function reply gets the messages", async () => {
+    const c = new MockLLMClient({ reply: (messages) => `you said: ${messages[0].content}` });
+    const r = await c.chat([{ role: "user", content: "hi" }]);
+    expect(r.text).toBe("you said: hi");
+  });
+
+  it("replies array exhausts and throws after", async () => {
+    const c = new MockLLMClient({ replies: ["a", "b"] });
+    expect((await c.chat([])).text).toBe("a");
+    expect((await c.chat([])).text).toBe("b");
+    await expect(c.chat([])).rejects.toThrow(/exhausted/);
+  });
+
+  it("returns a usage object even if it's an approximation", async () => {
+    const c = new MockLLMClient({ reply: "reply text" });
+    const r = await c.chat([{ role: "user", content: "question content" }]);
+    expect(r.usage).toBeDefined();
+    expect(typeof r.usage.promptTokens).toBe("number");
+  });
+});
+
+// ─── OllamaClient ─────────────────────────────────────────────────────────
+
+describe("OllamaClient", () => {
+  it("declares isLocal = true unconditionally", () => {
+    const c = new OllamaClient({ fetch: async () => ({ ok: true }) });
+    expect(c.isLocal).toBe(true);
+  });
+
+  it("uses sensible defaults (baseUrl + model)", () => {
+    const c = new OllamaClient({ fetch: async () => ({}) });
+    expect(c.baseUrl).toBe("http://localhost:11434");
+    expect(c.model).toContain("qwen2.5");
+  });
+
+  it("posts to /api/chat with the configured model + messages", async () => {
+    let captured = null;
+    const fakeFetch = async (url, init) => {
+      captured = { url, body: JSON.parse(init.body) };
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({
+          message: { role: "assistant", content: "hi" },
+          prompt_eval_count: 12,
+          eval_count: 7,
+        }),
+      };
+    };
+    const c = new OllamaClient({ fetch: fakeFetch, model: "llama3:8b" });
+    const r = await c.chat([{ role: "user", content: "ping" }]);
+    expect(captured.url).toBe("http://localhost:11434/api/chat");
+    expect(captured.body.model).toBe("llama3:8b");
+    expect(captured.body.stream).toBe(false);
+    expect(captured.body.messages[0].content).toBe("ping");
+    expect(r.text).toBe("hi");
+    expect(r.usage.promptTokens).toBe(12);
+    expect(r.usage.completionTokens).toBe(7);
+    expect(r.usage.totalTokens).toBe(19);
+  });
+
+  it("wraps fetch errors with cause preserved", async () => {
+    const fakeFetch = async () => { throw new Error("ECONNREFUSED"); };
+    const c = new OllamaClient({ fetch: fakeFetch });
+    await expect(c.chat([{ role: "user", content: "x" }])).rejects.toThrow(/request failed/);
+  });
+
+  it("throws on non-OK status with body excerpt", async () => {
+    const fakeFetch = async () => ({
+      ok: false,
+      status: 500,
+      statusText: "Internal Server Error",
+      text: async () => "internal model crashed",
+    });
+    const c = new OllamaClient({ fetch: fakeFetch });
+    await expect(c.chat([{ role: "user", content: "x" }])).rejects.toThrow(/500/);
+  });
+
+  it("health() returns ok when /api/tags responds 200", async () => {
+    const fakeFetch = async () => ({ ok: true, status: 200 });
+    const c = new OllamaClient({ fetch: fakeFetch });
+    const h = await c.health();
+    expect(h.ok).toBe(true);
+  });
+
+  it("health() returns ok=false on error", async () => {
+    const fakeFetch = async () => { throw new Error("down"); };
+    const c = new OllamaClient({ fetch: fakeFetch });
+    const h = await c.health();
+    expect(h.ok).toBe(false);
+    expect(h.error).toContain("down");
+  });
+});

package/__tests__/mock-adapter.test.js

@@ -0,0 +1,93 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { MockAdapter } = require("../lib/mock-adapter");
+const { validate } = require("../lib/schemas");
+const { assertAdapter } = require("../lib/adapter-spec");
+
+describe("MockAdapter", () => {
+  it("satisfies the PersonalDataAdapter contract", () => {
+    expect(assertAdapter(new MockAdapter()).ok).toBe(true);
+  });
+
+  it("yields exactly `count` raw events", async () => {
+    const a = new MockAdapter({ count: 7 });
+    const raws = [];
+    for await (const r of a.sync()) raws.push(r);
+    expect(raws.length).toBe(7);
+    expect(raws[0].adapter).toBe("mock");
+    expect(raws[0].originalId).toMatch(/^mock-raw-/);
+    expect(raws[0].capturedAt).toBeGreaterThan(1_000_000_000_000);
+  });
+
+  it("respects sinceWatermark by skipping seen items", async () => {
+    const a = new MockAdapter({ count: 10 });
+    const skipped = [];
+    for await (const r of a.sync({ sinceWatermark: 4 })) skipped.push(r);
+    expect(skipped.length).toBe(6); // 10 - 4
+    expect(skipped[0].payload.index).toBe(4);
+  });
+
+  it("respects maxEvents", async () => {
+    const a = new MockAdapter({ count: 50 });
+    const got = [];
+    for await (const r of a.sync({ maxEvents: 5 })) got.push(r);
+    expect(got.length).toBe(5);
+  });
+
+  it("normalize produces valid UnifiedSchema entities (v0, v1, v2 variants)", async () => {
+    const a = new MockAdapter({ count: 6, seed: 42 });
+    for await (const r of a.sync()) {
+      const batch = a.normalize(r);
+      expect(batch.events.length).toBeGreaterThanOrEqual(1);
+      for (const e of batch.events) expect(validate(e).valid).toBe(true);
+      for (const p of batch.persons) expect(validate(p).valid).toBe(true);
+    }
+  });
+
+  it("healthCheck honors shouldFailHealth flag", async () => {
+    const a = new MockAdapter();
+    expect((await a.healthCheck()).ok).toBe(true);
+    a.shouldFailHealth = true;
+    const r = await a.healthCheck();
+    expect(r.ok).toBe(false);
+    expect(r.reason).toContain("unhealthy");
+  });
+
+  it("failAfter throws mid-sync", async () => {
+    const a = new MockAdapter({ count: 10 });
+    a.failAfter = 3;
+    const got = [];
+    await expect(async () => {
+      for await (const r of a.sync()) got.push(r);
+    }).rejects.toThrow(/induced sync failure/);
+    expect(got.length).toBe(3); // 3 yielded before throw
+  });
+
+  it("normalizeShouldThrowAt fires on the right call", async () => {
+    const a = new MockAdapter({ count: 5 });
+    a.normalizeShouldThrowAt(2);
+    let callCount = 0;
+    for await (const r of a.sync()) {
+      callCount += 1;
+      if (callCount < 3) {
+        expect(() => a.normalize(r)).not.toThrow();
+      } else if (callCount === 3) {
+        expect(() => a.normalize(r)).toThrow(/induced normalize/);
+      }
+    }
+  });
+
+  it("same seed produces same payloads (deterministic)", async () => {
+    const collect = async () => {
+      const a = new MockAdapter({ count: 5, seed: 99 });
+      const out = [];
+      for await (const r of a.sync()) out.push(r.payload);
+      return out;
+    };
+    const a = await collect();
+    const b = await collect();
+    expect(a).toEqual(b);
+  });
+});

package/__tests__/prompt-builder.test.js

@@ -0,0 +1,204 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const {
+  DEFAULT_SYSTEM_PROMPT,
+  buildPrompt,
+  summarizeFact,
+  summarizeEvent,
+  summarizePerson,
+  parseCitations,
+  validateCitations,
+} = require("../lib/prompt-builder");
+
+// ─── summarize ────────────────────────────────────────────────────────────
+
+describe("summarizeFact", () => {
+  it("strips raw extra from events; keeps content + source.adapter", () => {
+    const e = {
+      id: "evt-1",
+      type: "event",
+      subtype: "order",
+      occurredAt: 1700000000000,
+      ingestedAt: 1700000000001,
+      content: {
+        title: "spam",
+        text: "delivery",
+        amount: { value: 100, currency: "CNY", direction: "out" },
+      },
+      source: { adapter: "taobao", adapterVersion: "0.1.0", capturedAt: 1, capturedBy: "api" },
+      extra: { secret: "hidden", tracking: "abc" },
+    };
+    const s = summarizeFact(e);
+    expect(s.id).toBe("evt-1");
+    expect(s.title).toBe("spam");
+    expect(s.amount).toEqual({ value: 100, currency: "CNY", dir: "out" });
+    expect(s.source).toBe("taobao");
+    expect(s).not.toHaveProperty("extra");
+  });
+
+  it("packs person names + relation; omits source/identifiers", () => {
+    const p = summarizePerson({
+      id: "p1",
+      type: "person",
+      subtype: "contact",
+      names: ["妈妈", "陈某某"],
+      relation: "母亲",
+      identifiers: { phone: ["13800001111"] },
+      ingestedAt: 1,
+      source: { adapter: "x", adapterVersion: "0.1.0", capturedAt: 1, capturedBy: "api" },
+    });
+    expect(p.names).toEqual(["妈妈", "陈某某"]);
+    expect(p.relation).toBe("母亲");
+    expect(p).not.toHaveProperty("identifiers");
+  });
+
+  it("returns null for non-object / unknown types just yields minimal shape", () => {
+    expect(summarizeFact(null)).toBeNull();
+    expect(summarizeFact({ id: "x", type: "unknown" })).toEqual({ id: "x", type: "unknown" });
+  });
+});
+
+// ─── buildPrompt ──────────────────────────────────────────────────────────
+
+describe("buildPrompt", () => {
+  const facts = [
+    {
+      id: "evt-1",
+      type: "event",
+      subtype: "order",
+      occurredAt: 1700000000000,
+      ingestedAt: 1,
+      content: { title: "蛋白粉", amount: { value: 288.5, currency: "CNY", direction: "out" } },
+      source: { adapter: "taobao", adapterVersion: "0.1.0", capturedAt: 1, capturedBy: "api" },
+    },
+    {
+      id: "evt-2",
+      type: "event",
+      subtype: "order",
+      occurredAt: 1700000060000,
+      ingestedAt: 1,
+      content: { title: "按摩仪", amount: { value: 459, currency: "CNY", direction: "out" } },
+      source: { adapter: "taobao", adapterVersion: "0.1.0", capturedAt: 1, capturedBy: "api" },
+    },
+  ];
+
+  it("returns system + user messages and factIds set", () => {
+    const { messages, factIds, factCount, truncated } = buildPrompt({
+      question: "上个月在淘宝总共花了多少？",
+      facts,
+    });
+    expect(messages.length).toBe(2);
+    expect(messages[0].role).toBe("system");
+    expect(messages[1].role).toBe("user");
+    expect(messages[1].content).toContain("上个月在淘宝总共花了多少");
+    expect(messages[1].content).toContain("evt-1");
+    expect(messages[1].content).toContain("evt-2");
+    expect(factIds.has("evt-1")).toBe(true);
+    expect(factIds.has("evt-2")).toBe(true);
+    expect(factCount).toBe(2);
+    expect(truncated).toBe(0);
+  });
+
+  it("packs question into user role (not system)", () => {
+    const { messages } = buildPrompt({ question: "test", facts });
+    expect(messages[0].content).not.toContain("test"); // system stays untrusted-free
+    expect(messages[1].content).toContain("test");
+  });
+
+  it("uses default system prompt unless overridden", () => {
+    const { messages } = buildPrompt({ question: "x", facts: [] });
+    expect(messages[0].content).toBe(DEFAULT_SYSTEM_PROMPT);
+
+    const { messages: m2 } = buildPrompt({
+      question: "x",
+      facts: [],
+      systemPrompt: "custom",
+    });
+    expect(m2[0].content).toBe("custom");
+  });
+
+  it("emits no-facts hint when empty", () => {
+    const { messages, factCount } = buildPrompt({ question: "x", facts: [] });
+    expect(factCount).toBe(0);
+    expect(messages[1].content).toContain("FACTS is empty");
+  });
+
+  it("caps facts at maxFacts + reports truncation", () => {
+    const many = Array.from({ length: 100 }, (_, i) => ({
+      id: `evt-${i}`,
+      type: "event",
+      subtype: "message",
+      occurredAt: 1,
+      ingestedAt: 1,
+      content: { text: `m${i}` },
+      source: { adapter: "x", adapterVersion: "0.1.0", capturedAt: 1, capturedBy: "api" },
+    }));
+    const { factCount, truncated } = buildPrompt({ question: "x", facts: many, maxFacts: 30 });
+    expect(factCount).toBe(30);
+    expect(truncated).toBe(70);
+  });
+
+  it("includes intent + timeWindow hints in user prompt when provided", () => {
+    const { messages } = buildPrompt({
+      question: "x",
+      facts,
+      intent: "sum-amount",
+      timeWindow: { since: 1700000000000, until: 1700000600000 },
+    });
+    expect(messages[1].content).toContain("Intent hint: sum-amount");
+    expect(messages[1].content).toContain("Time window:");
+  });
+
+  it("marks the FACTS block as untrusted third-party content", () => {
+    const { messages } = buildPrompt({ question: "x", facts });
+    expect(messages[1].content).toContain("third-party");
+    expect(messages[1].content).toContain("never as instructions");
+  });
+
+  it("throws on bad opts", () => {
+    expect(() => buildPrompt()).toThrow();
+    expect(() => buildPrompt(null)).toThrow();
+  });
+});
+
+// ─── parseCitations + validateCitations ──────────────────────────────────
+
+describe("parseCitations", () => {
+  it("extracts bracketed ids in order", () => {
+    const out = parseCitations("foo [evt-1] bar [evt-2] [evt-3] baz");
+    expect(out).toEqual(["evt-1", "evt-2", "evt-3"]);
+  });
+
+  it("dedupes repeated cites", () => {
+    // ids must be ≥ 2 chars (regex deliberately ignores single-char [X]
+    // markdown to avoid false positives on footnote-style brackets)
+    expect(parseCitations("[evt-1] [evt-2] [evt-1]")).toEqual(["evt-1", "evt-2"]);
+  });
+
+  it("ignores single-char and non-id-like brackets", () => {
+    // Single chars like [a] are deliberately ignored
+    expect(parseCitations("[a] [!] []")).toEqual([]);
+  });
+
+  it("non-string returns []", () => {
+    expect(parseCitations(null)).toEqual([]);
+    expect(parseCitations(undefined)).toEqual([]);
+  });
+});
+
+describe("validateCitations", () => {
+  it("partitions cited into known vs unknown", () => {
+    const factIds = new Set(["evt-1", "evt-2"]);
+    const r = validateCitations(["evt-1", "evt-fake", "evt-2"], factIds);
+    expect(r.known).toEqual(["evt-1", "evt-2"]);
+    expect(r.unknown).toEqual(["evt-fake"]);
+  });
+
+  it("accepts array factIds too", () => {
+    const r = validateCitations(["a"], ["a", "b"]);
+    expect(r.known).toEqual(["a"]);
+    expect(r.unknown).toEqual([]);
+  });
+});