@chainlesschain/personal-data-hub 0.1.0 → 0.2.1

package/__tests__/entity-resolver.test.js

@@ -0,0 +1,526 @@
+"use strict";
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+
+const path = require("node:path");
+const fs = require("node:fs");
+const os = require("node:os");
+const { LocalVault } = require("../lib/vault");
+const { generateKeyHex } = require("../lib/key-providers");
+const { newId } = require("../lib/ids");
+const {
+  EntityResolver,
+  entityResolverRuleStage: ruleStage,
+  entityResolverSharedIdentifier: findSharedIdentifier,
+  entityResolverNormalizeIdValue: normalizeIdValue,
+} = require("../lib/entity-resolver");
+
+// ─── ruleStage (pure) ────────────────────────────────────────────────────
+
+function person(overrides = {}) {
+  return {
+    id: overrides.id || `person-${Math.random().toString(36).slice(2, 8)}`,
+    type: "person",
+    subtype: "contact",
+    names: overrides.names || [],
+    identifiers: overrides.identifiers || {},
+    source: overrides.source || { adapter: "test", originalId: "tx-" + Math.random() },
+    ...overrides,
+  };
+}
+
+describe("ruleStage — R1 strong identifier match", () => {
+  it("same email → same", () => {
+    const a = person({ identifiers: { email: ["mom@163.com"] } });
+    const b = person({ identifiers: { email: ["MOM@163.COM"] } }); // case + array
+    expect(ruleStage(a, b).verdict).toBe("same");
+  });
+
+  it("same phone (different formatting) → same", () => {
+    const a = person({ identifiers: { phone: ["+86 138 0000 1111"] } });
+    const b = person({ identifiers: { phone: ["13800001111"] } });
+    expect(ruleStage(a, b).verdict).toBe("same");
+  });
+
+  it("same wechatId → same", () => {
+    const a = person({ identifiers: { wechatId: "wxid_xyz" } });
+    const b = person({ identifiers: { wechatId: ["wxid_xyz"] } });
+    expect(ruleStage(a, b).verdict).toBe("same");
+  });
+
+  it("same did → same", () => {
+    const a = person({ identifiers: { did: "did:cc:abc" } });
+    const b = person({ identifiers: { did: "did:cc:abc" } });
+    expect(ruleStage(a, b).verdict).toBe("same");
+  });
+
+  it("same idHash → same", () => {
+    const a = person({ identifiers: { idHash: "sha-id-hash-123" } });
+    const b = person({ identifiers: { idHash: "sha-id-hash-123" } });
+    expect(ruleStage(a, b).verdict).toBe("same");
+  });
+});
+
+describe("ruleStage — R2 zero overlap → different", () => {
+  it("no shared field → different", () => {
+    const a = person({
+      names: ["张三"],
+      identifiers: { email: ["a@x.com"] },
+      source: { adapter: "email", originalId: "1" },
+    });
+    const b = person({
+      names: ["李四"],
+      identifiers: { phone: ["13900001234"] },
+      source: { adapter: "alipay", originalId: "2" },
+    });
+    expect(ruleStage(a, b).verdict).toBe("different");
+  });
+
+  it("identical content but no identifier overlap + different adapters → uncertain", () => {
+    // Note: same name → overlap=1 → uncertain
+    const a = person({ names: ["张三"], source: { adapter: "email", originalId: "1" } });
+    const b = person({ names: ["张三"], source: { adapter: "alipay", originalId: "2" } });
+    expect(ruleStage(a, b).verdict).toBe("uncertain");
+  });
+});
+
+describe("ruleStage — R3 same-adapter internal dup", () => {
+  it("same adapter + different originalId + shared name → same", () => {
+    const a = person({
+      names: ["张三"],
+      source: { adapter: "email", originalId: "1" },
+    });
+    const b = person({
+      names: ["张三"],
+      source: { adapter: "email", originalId: "2" },
+    });
+    expect(ruleStage(a, b).verdict).toBe("same");
+    expect(ruleStage(a, b).reason).toMatch(/same-adapter/);
+  });
+
+  it("same adapter + same originalId is NOT a R3 case (different id implies different row)", () => {
+    const a = person({
+      id: "p1",
+      names: ["张三"],
+      source: { adapter: "email", originalId: "1" },
+    });
+    const b = person({
+      id: "p2",
+      names: ["张三"],
+      source: { adapter: "email", originalId: "1" },
+    });
+    // R3 requires DIFFERENT originalId — same originalId falls through
+    // but uniqueIndex on source.originalId means we don't see this case
+    // in practice.
+    const r = ruleStage(a, b);
+    expect(r.verdict).toBe("uncertain"); // because there's overlap (name + adapter)
+  });
+
+  it("same adapter + DIFFERENT name → uncertain (not R3)", () => {
+    const a = person({
+      names: ["张三"],
+      source: { adapter: "email", originalId: "1" },
+    });
+    const b = person({
+      names: ["李四"],
+      source: { adapter: "email", originalId: "2" },
+    });
+    expect(ruleStage(a, b).verdict).toBe("uncertain");
+  });
+});
+
+describe("ruleStage — R4 uncertain fall-through", () => {
+  it("name overlap only → uncertain", () => {
+    const a = person({ names: ["张三"], source: { adapter: "email", originalId: "1" } });
+    const b = person({ names: ["张三"], source: { adapter: "alipay", originalId: "2" } });
+    expect(ruleStage(a, b).verdict).toBe("uncertain");
+  });
+
+  it("same person id → same vacuously", () => {
+    const a = person({ id: "p1" });
+    const b = person({ id: "p1" });
+    expect(ruleStage(a, b).verdict).toBe("same");
+  });
+
+  it("invalid input → different", () => {
+    expect(ruleStage(null, person()).verdict).toBe("different");
+    expect(ruleStage(person(), undefined).verdict).toBe("different");
+  });
+});
+
+// ─── normalizeIdValue ────────────────────────────────────────────────────
+
+describe("normalizeIdValue", () => {
+  it("email → lowercase + trim", () => {
+    expect(normalizeIdValue("email", "  MOM@163.COM ")).toBe("mom@163.com");
+  });
+  it("phone → digits only, strips +86 country code", () => {
+    expect(normalizeIdValue("phone", "+86 138-0000 1111")).toBe("13800001111");
+    expect(normalizeIdValue("phone", "13800001111")).toBe("13800001111");
+  });
+  it("other keys → trim only", () => {
+    expect(normalizeIdValue("did", "  did:cc:abc ")).toBe("did:cc:abc");
+  });
+});
+
+// ─── findSharedIdentifier ────────────────────────────────────────────────
+
+describe("findSharedIdentifier", () => {
+  it("finds shared email across array vs string", () => {
+    const r = findSharedIdentifier(
+      { email: ["a@x.com", "b@x.com"] },
+      { email: "B@X.COM" },
+    );
+    expect(r).toBeTruthy();
+    expect(r.key).toBe("email");
+    expect(r.value).toBe("b@x.com");
+  });
+
+  it("returns null when no overlap", () => {
+    const r = findSharedIdentifier({ email: ["a@x.com"] }, { email: ["b@x.com"] });
+    expect(r).toBeNull();
+  });
+
+  it("ignores empty / missing identifier groups", () => {
+    const r = findSharedIdentifier({}, { email: ["a@x.com"] });
+    expect(r).toBeNull();
+  });
+});
+
+// ─── EntityResolver wired against a real vault ───────────────────────────
+
+function makeVaultWithPersons(persons) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hub-er-test-"));
+  const dbPath = path.join(dir, "vault.db");
+  const key = generateKeyHex();
+  const vault = new LocalVault({ path: dbPath, key });
+  vault.open();
+  for (const p of persons) {
+    // Build a complete source (the rule-stage tests use a 2-field
+    // shorthand for brevity; vault.putPerson needs the full 5-field).
+    const inputSrc = p.source || {};
+    const source = {
+      adapter: inputSrc.adapter || "test",
+      adapterVersion: inputSrc.adapterVersion || "0.1.0",
+      originalId: inputSrc.originalId || p.id,
+      capturedAt: inputSrc.capturedAt || Date.now(),
+      capturedBy: inputSrc.capturedBy || "api",
+    };
+    vault.putPerson({
+      id: p.id,
+      type: "person",
+      subtype: p.subtype || "contact",
+      names: p.names || [],
+      identifiers: p.identifiers || {},
+      ingestedAt: Date.now(),
+      source,
+      extra: p.extra || {},
+    });
+  }
+  return { vault, dir };
+}
+
+function cleanup(vault, dir) {
+  try { vault.close(); } catch (_e) {}
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_e) {}
+}
+
+describe("EntityResolver.resolveOnIngest", () => {
+  let vault, dir;
+  afterEach(() => cleanup(vault, dir));
+
+  it("R1 same-email pair → immediate merge", () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-email-mom", names: ["妈"], identifiers: { email: ["mom@163.com"] } },
+    ]));
+    const er = new EntityResolver({ vault });
+    const newPerson = {
+      id: "p-alipay-陈x",
+      type: "person",
+      names: ["陈X"],
+      identifiers: { email: ["mom@163.com"] }, // same email
+      source: { adapter: "alipay", originalId: "TX1" },
+    };
+    vault.putPerson({
+      ...newPerson,
+      subtype: "contact",
+      ingestedAt: Date.now(),
+      source: { adapter: "alipay", adapterVersion: "0.1.0", originalId: "TX1", capturedAt: Date.now(), capturedBy: "export" },
+    });
+    const summary = er.resolveOnIngest([newPerson]);
+    expect(summary.newPersons).toBe(1);
+    expect(summary.sameImmediate).toBe(1);
+    expect(vault.getMergeGroupMembers("p-email-mom").sort()).toEqual(["p-alipay-陈x", "p-email-mom"]);
+  });
+
+  it("R2 zero-overlap pair → candidate filter excludes; no merge, person enqueued for async", () => {
+    // The candidate-finder filters out zero-overlap rows for perf — they
+    // never reach rule-stage. Behavior is equivalent ("different" verdict
+    // never recorded but no merge happens either). Async pipeline gets
+    // a chance later in case embedding catches a name variant.
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-x", names: ["张三"], identifiers: { email: ["a@x.com"] }, source: { adapter: "email", originalId: "1" } },
+    ]));
+    const er = new EntityResolver({ vault });
+    const newPerson = {
+      id: "p-y",
+      type: "person",
+      names: ["李四"],
+      identifiers: { phone: ["13900001234"] },
+      source: { adapter: "alipay", originalId: "2" },
+    };
+    vault.putPerson({
+      ...newPerson, subtype: "contact", ingestedAt: Date.now(),
+      source: { adapter: "alipay", adapterVersion: "0.1.0", originalId: "2", capturedAt: Date.now(), capturedBy: "export" },
+    });
+    const summary = er.resolveOnIngest([newPerson]);
+    expect(summary.differentImmediate).toBe(0);
+    expect(summary.sameImmediate).toBe(0);
+    expect(summary.enqueued).toBe(1);
+    expect(vault.stats().mergeGroups).toBe(0);
+  });
+
+  it("uncertain pair → enqueues for async", () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-1", names: ["张三"], source: { adapter: "email", originalId: "1" } },
+    ]));
+    const er = new EntityResolver({ vault });
+    const newPerson = {
+      id: "p-2",
+      type: "person",
+      names: ["张三"], // name overlap → uncertain
+      source: { adapter: "alipay", originalId: "2" },
+    };
+    vault.putPerson({
+      ...newPerson, subtype: "contact", ingestedAt: Date.now(),
+      source: { adapter: "alipay", adapterVersion: "0.1.0", originalId: "2", capturedAt: Date.now(), capturedBy: "export" },
+    });
+    const summary = er.resolveOnIngest([newPerson]);
+    expect(summary.enqueued).toBe(1);
+    expect(vault.resolveQueueStats().pending).toBe(1);
+  });
+
+  it("respects existing same-decision (idempotent on retry)", () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-a", names: ["x"], identifiers: { email: ["a@x.com"] } },
+      { id: "p-b", names: ["x"], identifiers: { email: ["a@x.com"] } },
+    ]));
+    const er = new EntityResolver({ vault });
+    const summary1 = er.resolveOnIngest([{ id: "p-b", names: ["x"], identifiers: { email: ["a@x.com"] } }]);
+    const summary2 = er.resolveOnIngest([{ id: "p-b", names: ["x"], identifiers: { email: ["a@x.com"] } }]);
+    expect(summary1.sameImmediate).toBeGreaterThanOrEqual(1);
+    expect(summary2.sameImmediate).toBeGreaterThanOrEqual(1); // still records same path
+    // Members stable
+    expect(vault.getMergeGroupMembers("p-a").sort()).toEqual(["p-a", "p-b"]);
+  });
+
+  it("handles error in single person without breaking batch", () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-a", names: ["x"], identifiers: { email: ["a@x.com"] } },
+    ]));
+    const er = new EntityResolver({ vault });
+    const batch = [
+      null, // will trigger error path
+      { id: "p-b", names: ["x"], identifiers: { email: ["a@x.com"] } },
+    ];
+    const summary = er.resolveOnIngest(batch);
+    expect(summary.newPersons).toBe(2);
+    expect(summary.errored).toBeGreaterThanOrEqual(1);
+    expect(summary.sameImmediate).toBeGreaterThanOrEqual(0);
+  });
+});
+
+describe("EntityResolver.drain (rule-only, no embedding/llm)", () => {
+  let vault, dir;
+  afterEach(() => cleanup(vault, dir));
+
+  it("returns processed:0 when queue empty", async () => {
+    ({ vault, dir } = makeVaultWithPersons([]));
+    const er = new EntityResolver({ vault });
+    const r = await er.drain();
+    expect(r.processed).toBe(0);
+  });
+
+  it("processes queued person — rule stage finds same identifier", async () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-a", names: ["x"], identifiers: { email: ["a@x.com"] } },
+      { id: "p-b", names: ["x"], identifiers: { email: ["a@x.com"] } },
+    ]));
+    const er = new EntityResolver({ vault });
+    vault.enqueueResolve("p-b");
+    const r = await er.drain();
+    expect(r.processed).toBe(1);
+    expect(r.same).toBe(1);
+    expect(vault.getMergeGroupMembers("p-a").sort()).toEqual(["p-a", "p-b"]);
+  });
+
+  it("processes uncertain pair without embedding stage → no decision", async () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-a", names: ["x"], source: { adapter: "email", originalId: "1" } },
+      { id: "p-b", names: ["x"], source: { adapter: "alipay", originalId: "2" } },
+    ]));
+    const er = new EntityResolver({ vault });
+    vault.enqueueResolve("p-b");
+    const r = await er.drain();
+    expect(r.processed).toBe(1);
+    expect(r.same).toBe(0);
+    expect(r.different).toBe(0);
+    expect(r.skipped).toBeGreaterThanOrEqual(0); // no embedding wired
+  });
+});
+
+describe("EntityResolver.drain with embedding + LLM stages", () => {
+  let vault, dir;
+  afterEach(() => cleanup(vault, dir));
+
+  it("embedding sim ≥ high threshold → auto same", async () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-a", names: ["张三"], source: { adapter: "email", originalId: "1" } },
+      { id: "p-b", names: ["张三"], source: { adapter: "alipay", originalId: "2" } },
+    ]));
+    const er = new EntityResolver({
+      vault,
+      embeddingStage: async () => ({ sim: 0.91 }),
+    });
+    vault.enqueueResolve("p-b");
+    const r = await er.drain();
+    expect(r.same).toBe(1);
+  });
+
+  it("embedding sim < low threshold → auto different", async () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-a", names: ["张三"], source: { adapter: "email", originalId: "1" } },
+      { id: "p-b", names: ["张三"], source: { adapter: "alipay", originalId: "2" } },
+    ]));
+    const er = new EntityResolver({
+      vault,
+      embeddingStage: async () => ({ sim: 0.4 }),
+    });
+    vault.enqueueResolve("p-b");
+    const r = await er.drain();
+    expect(r.different).toBe(1);
+  });
+
+  it("embedding mid-range + LLM yes → same", async () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-a", names: ["张三"], source: { adapter: "email", originalId: "1" } },
+      { id: "p-b", names: ["张三"], source: { adapter: "alipay", originalId: "2" } },
+    ]));
+    const er = new EntityResolver({
+      vault,
+      embeddingStage: async () => ({ sim: 0.7 }),
+      llmStage: async () => ({ verdict: "yes", confidence: 0.85, reason: "looks same" }),
+    });
+    vault.enqueueResolve("p-b");
+    const r = await er.drain();
+    expect(r.same).toBe(1);
+  });
+
+  it("embedding mid-range + LLM maybe → review queue", async () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-a", names: ["张三"], source: { adapter: "email", originalId: "1" } },
+      { id: "p-b", names: ["张三"], source: { adapter: "alipay", originalId: "2" } },
+    ]));
+    const er = new EntityResolver({
+      vault,
+      embeddingStage: async () => ({ sim: 0.7 }),
+      llmStage: async () => ({ verdict: "maybe", confidence: 0.5, reason: "unclear" }),
+    });
+    vault.enqueueResolve("p-b");
+    const r = await er.drain();
+    expect(r.review).toBe(1);
+    expect(vault.listReviewQueue()).toHaveLength(1);
+  });
+
+  it("embedding stage throws → error counted, no infinite retry", async () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-a", names: ["张三"], source: { adapter: "email", originalId: "1" } },
+      { id: "p-b", names: ["张三"], source: { adapter: "alipay", originalId: "2" } },
+    ]));
+    const er = new EntityResolver({
+      vault,
+      embeddingStage: async () => { throw new Error("ollama down"); },
+    });
+    vault.enqueueResolve("p-b");
+    const r = await er.drain();
+    expect(r.error).toBe(1);
+    expect(vault.resolveQueueStats().pending).toBe(1); // retry-eligible
+  });
+});
+
+describe("EntityResolver.applyUserDecision", () => {
+  let vault, dir;
+  afterEach(() => cleanup(vault, dir));
+
+  it("user says same → merge + record decision", () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-a", names: ["x"] },
+      { id: "p-b", names: ["x"] },
+    ]));
+    const er = new EntityResolver({ vault });
+    const reviewId = vault.enqueueReview({ aId: "p-a", bId: "p-b", embedSim: 0.7 });
+    er.applyUserDecision({ reviewId, decision: "same" });
+    expect(vault.getMergeGroupMembers("p-a").sort()).toEqual(["p-a", "p-b"]);
+    expect(vault.getResolveDecision("p-a", "p-b")).toBeDefined();
+    expect(vault.getResolveDecision("p-a", "p-b").decided_by).toBe("user");
+  });
+
+  it("user says different → record decision, no merge", () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-a", names: ["x"] },
+      { id: "p-b", names: ["x"] },
+    ]));
+    const er = new EntityResolver({ vault });
+    const reviewId = vault.enqueueReview({ aId: "p-a", bId: "p-b", embedSim: 0.7 });
+    er.applyUserDecision({ reviewId, decision: "different" });
+    expect(vault.stats().mergeGroups).toBe(0);
+    expect(vault.getResolveDecision("p-a", "p-b").verdict).toBe("different");
+  });
+
+  it("user says skip → just marks reviewed", () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-a", names: ["x"] },
+      { id: "p-b", names: ["x"] },
+    ]));
+    const er = new EntityResolver({ vault });
+    const reviewId = vault.enqueueReview({ aId: "p-a", bId: "p-b", embedSim: 0.7 });
+    er.applyUserDecision({ reviewId, decision: "skip" });
+    expect(vault.stats().mergeGroups).toBe(0);
+    expect(vault.getResolveDecision("p-a", "p-b")).toBeUndefined();
+    expect(vault.listReviewQueue()).toHaveLength(0); // marked reviewed
+  });
+});
+
+describe("EntityResolver manual merge / unmerge", () => {
+  let vault, dir;
+  afterEach(() => cleanup(vault, dir));
+
+  it("manualMerge creates the group + records same decision", () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-a", names: ["x"] },
+      { id: "p-b", names: ["x"] },
+    ]));
+    const er = new EntityResolver({ vault });
+    er.manualMerge({ aId: "p-a", bId: "p-b" });
+    expect(vault.getMergeGroupMembers("p-a").sort()).toEqual(["p-a", "p-b"]);
+  });
+
+  it("manualUnmerge dissolves group + records different decision", () => {
+    ({ vault, dir } = makeVaultWithPersons([
+      { id: "p-a", names: ["x"] },
+      { id: "p-b", names: ["x"] },
+    ]));
+    const er = new EntityResolver({ vault });
+    er.manualMerge({ aId: "p-a", bId: "p-b" });
+    er.manualUnmerge("p-a");
+    expect(vault.stats().mergeGroups).toBe(0);
+    expect(vault.getResolveDecision("p-a", "p-b").verdict).toBe("different");
+  });
+});
+
+describe("EntityResolver constructor", () => {
+  it("requires vault", () => {
+    expect(() => new EntityResolver()).toThrow();
+    expect(() => new EntityResolver({})).toThrow(/vault/);
+  });
+});

package/__tests__/fixtures/entity-resolver-200-mock.json

@@ -0,0 +1,96 @@
+{
+  "schema": 1,
+  "description": "Mock 200-pair labeled set for Phase 8 EntityResolver evaluation. Synthetic data (no real PII). 100 'same' positives + 100 'different' negatives across Email/Alipay/WeChat-style profiles. Real 200-pair set lives in user vault and is gitignored (see design doc §7.3).",
+  "generatedAt": "2026-05-20",
+  "categories": {
+    "cross-source-same-identifier": "Same email/phone/wechatId across two adapters; rule stage should catch",
+    "cross-source-same-name-different-adapter": "Same 中文 name only; needs embedding+LLM",
+    "cross-source-different-identifier": "Clearly distinct identifiers; should be 'different'",
+    "same-adapter-same-name": "Same adapter, different originalId, shared name (adapter internal dup)",
+    "homonym-trap": "Same common 中文 name but different people (different identifiers)"
+  },
+  "pairs": [
+    {
+      "id": "p001",
+      "category": "cross-source-same-identifier",
+      "groundTruth": "same",
+      "a": { "id": "p-email-mom-001", "type": "person", "names": ["妈"], "identifiers": { "email": ["mom001@163.com"] }, "source": { "adapter": "email", "originalId": "1" } },
+      "b": { "id": "p-alipay-001", "type": "person", "names": ["陈XX"], "identifiers": { "email": ["mom001@163.com"] }, "source": { "adapter": "alipay-bill", "originalId": "2" } }
+    },
+    {
+      "id": "p002",
+      "category": "cross-source-same-identifier",
+      "groundTruth": "same",
+      "a": { "id": "p-email-dad-002", "type": "person", "names": ["爸"], "identifiers": { "phone": ["13800001111"] }, "source": { "adapter": "email", "originalId": "1" } },
+      "b": { "id": "p-alipay-002", "type": "person", "names": ["陈父亲"], "identifiers": { "phone": ["+86 138 0000 1111"] }, "source": { "adapter": "alipay-bill", "originalId": "2" } }
+    },
+    {
+      "id": "p003",
+      "category": "cross-source-different-identifier",
+      "groundTruth": "different",
+      "a": { "id": "p-email-alice-003", "type": "person", "names": ["Alice"], "identifiers": { "email": ["alice@x.com"] }, "source": { "adapter": "email", "originalId": "1" } },
+      "b": { "id": "p-alipay-003", "type": "person", "names": ["Bob"], "identifiers": { "phone": ["13900001234"] }, "source": { "adapter": "alipay-bill", "originalId": "2" } }
+    },
+    {
+      "id": "p004",
+      "category": "cross-source-same-name-different-adapter",
+      "groundTruth": "same",
+      "a": { "id": "p-email-zs-004", "type": "person", "names": ["张三"], "identifiers": { "email": ["zs@x.com"] }, "source": { "adapter": "email", "originalId": "1" } },
+      "b": { "id": "p-alipay-004", "type": "person", "names": ["张三"], "identifiers": {}, "source": { "adapter": "alipay-bill", "originalId": "2" } }
+    },
+    {
+      "id": "p005",
+      "category": "homonym-trap",
+      "groundTruth": "different",
+      "a": { "id": "p-email-zs1-005", "type": "person", "names": ["张三"], "identifiers": { "email": ["zhang1@a.com"], "phone": ["13800001111"] }, "source": { "adapter": "email", "originalId": "1" } },
+      "b": { "id": "p-email-zs2-005", "type": "person", "names": ["张三"], "identifiers": { "email": ["zhang2@b.com"], "phone": ["13900002222"] }, "source": { "adapter": "email", "originalId": "2" } }
+    },
+    {
+      "id": "p006",
+      "category": "same-adapter-same-name",
+      "groundTruth": "same",
+      "a": { "id": "p-email-li-006a", "type": "person", "names": ["李四"], "identifiers": {}, "source": { "adapter": "email", "originalId": "1" } },
+      "b": { "id": "p-email-li-006b", "type": "person", "names": ["李四"], "identifiers": {}, "source": { "adapter": "email", "originalId": "2" } }
+    },
+    {
+      "id": "p007",
+      "category": "cross-source-same-identifier",
+      "groundTruth": "same",
+      "a": { "id": "p-wechat-007", "type": "person", "names": ["王五"], "identifiers": { "wechatId": "wxid_wangwu" }, "source": { "adapter": "wechat", "originalId": "1" } },
+      "b": { "id": "p-alipay-007", "type": "person", "names": ["王XX"], "identifiers": { "wechatId": "wxid_wangwu" }, "source": { "adapter": "alipay-bill", "originalId": "2" } }
+    },
+    {
+      "id": "p008",
+      "category": "cross-source-different-identifier",
+      "groundTruth": "different",
+      "a": { "id": "p-email-ceo-008", "type": "person", "names": ["陈总"], "identifiers": { "email": ["ceo@bigco.com"] }, "source": { "adapter": "email", "originalId": "1" } },
+      "b": { "id": "p-email-ceo2-008", "type": "person", "names": ["陈总"], "identifiers": { "email": ["chen@xiaobu.com"] }, "source": { "adapter": "email", "originalId": "2" } }
+    },
+    {
+      "id": "p009",
+      "category": "cross-source-same-name-different-adapter",
+      "groundTruth": "same",
+      "a": { "id": "p-wechat-009", "type": "person", "names": ["小明"], "identifiers": {}, "source": { "adapter": "wechat", "originalId": "1" } },
+      "b": { "id": "p-alipay-009", "type": "person", "names": ["小明"], "identifiers": {}, "source": { "adapter": "alipay-bill", "originalId": "2" } }
+    },
+    {
+      "id": "p010",
+      "category": "homonym-trap",
+      "groundTruth": "different",
+      "a": { "id": "p-email-lijun1-010", "type": "person", "names": ["李军"], "identifiers": { "email": ["lijun.eng@coA.com"] }, "source": { "adapter": "email", "originalId": "1" } },
+      "b": { "id": "p-email-lijun2-010", "type": "person", "names": ["李军"], "identifiers": { "email": ["lijun.sales@coB.com"] }, "source": { "adapter": "email", "originalId": "2" } }
+    }
+  ],
+  "summary": {
+    "totalPairs": 10,
+    "byGroundTruth": { "same": 5, "different": 5 },
+    "byCategory": {
+      "cross-source-same-identifier": 3,
+      "cross-source-same-name-different-adapter": 2,
+      "cross-source-different-identifier": 2,
+      "same-adapter-same-name": 1,
+      "homonym-trap": 2
+    },
+    "note": "This is a 10-pair smoke fixture (committed to git, synthetic). The real 200-pair set lives at __tests__/fixtures/entity-resolver-200.json which is gitignored — generated from user vault via scripts/gen-entity-resolver-fixture.js."
+  }
+}