@chainlesschain/personal-data-hub 0.1.0 → 0.2.1

package/__tests__/e2e/full-user-journey.test.js

@@ -0,0 +1,188 @@
+"use strict";
+
+/**
+ * E2E — full Personal Data Hub user journey.
+ *
+ * Simulates a user from zero to "ask a question and get an answer":
+ *   1. Initialize fresh vault
+ *   2. Register + sync EmailAdapter (mocked IMAP session)
+ *   3. Register + import Alipay CSV
+ *   4. EntityResolver auto-merges same-email persons
+ *   5. Worker drains uncertain pairs (rule-stage only, no LLM needed)
+ *   6. SpendingSkill answers "how much did I spend?" with combined totals
+ *   7. TimelineSkill weaves events into chronological story
+ *   8. EventDetail surfaces the source raw row for a citation
+ *
+ * Avoids real network / real LLM / real device — every external boundary
+ * is mocked via DI seams (sessionFactory, csvParser, embeddingStage).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+const {
+  LocalVault, generateKeyHex, AdapterRegistry,
+  EntityResolver,
+  EmailAdapter, AlipayBillAdapter,
+  SpendingSkill, TimelineSkill, RelationsSkill,
+} = require("../../lib");
+
+describe("E2E — full Personal Data Hub user journey", () => {
+  let dir, vault, registry, resolver;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "pdh-e2e-"));
+    vault = new LocalVault({ path: path.join(dir, "v.db"), key: generateKeyHex() });
+    vault.open();
+    resolver = new EntityResolver({ vault });
+    registry = new AdapterRegistry({ vault, entityResolver: resolver });
+  });
+
+  afterEach(() => {
+    try { vault.close(); } catch (_e) {}
+    try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_e) {}
+  });
+
+  it("zero → email + alipay → entity merge → spending answer", async () => {
+    // ─── Step 1-2: Register + sync EmailAdapter with mocked IMAP ───
+    const emailEnv = {
+      uid: 1, internalDate: new Date("2026-05-15T10:00:00Z"),
+      flags: ["\\Seen"], messageId: "<msg-1@x>",
+      subject: "招商银行 11 月对账单",
+      from: [{ name: "招商银行", address: "ebank@cmbchina.com" }],
+      to: [{ address: "me@example.com" }], cc: [],
+      date: new Date("2026-05-15T10:00:00Z"), size: 1024,
+      source: Buffer.from("RAW", "utf-8"),
+    };
+    const emailSessionFactory = () => ({
+      async connect() {},
+      async openMailbox() { return { uidValidity: 1, uidNext: 9999, exists: 1 }; },
+      async *fetchFullSince() { yield emailEnv; },
+      async close() {},
+    });
+    const emailAdapter = new EmailAdapter({
+      account: { provider: "qq", email: "me@example.com", authCode: "x", folders: ["INBOX"] },
+      sessionFactory: emailSessionFactory,
+      parser: async () => ({
+        textBody: "尊敬的客户：\n您的招商银行信用卡 应还金额 ¥3,256.78 元",
+        attachments: [],
+      }),
+    });
+    registry.register(emailAdapter);
+    const emailReport = await registry.syncAdapter("email-imap");
+    expect(emailReport.status).toBe("ok");
+    expect(emailReport.entityCounts.events).toBeGreaterThanOrEqual(1);
+
+    // ─── Step 3: Register + import Alipay CSV ───
+    const alipayCsv = [
+      "支付宝交易记录明细查询",
+      "账号:[me@example.com]",
+      "起始日期:[2026-05-01 00:00:00]    终止日期:[2026-05-31 00:00:00]",
+      "---------------------------------交易记录明细列表------------------------------",
+      "交易号,商家订单号,交易创建时间,付款时间,最近修改时间,交易来源地,类型,交易对方,商品名称,金额（元）,收/支,交易状态,服务费（元）,成功退款（元）,备注,资金状态",
+      "2026051022001112345001,T1,2026-05-10 14:00:00,2026-05-10 14:00:02,2026-05-10 14:00:02,客户端,即时到账交易,美团,美团外卖订单,38.50,支出,交易成功,0.00,0.00,,已支出",
+      "2026051522001112345002,T2,2026-05-15 09:00:00,2026-05-15 09:00:05,2026-05-15 09:00:05,客户端,即时到账交易,淘宝,运动鞋,299.00,支出,交易成功,0.00,0.00,,已支出",
+      "2026052022001112345003,,2026-05-20 12:00:00,2026-05-20 12:00:02,2026-05-20 12:00:02,客户端,转账,张三,生日礼物,500.00,支出,交易成功,0.00,0.00,生日快乐,已支出",
+      "---------------------------------交易记录明细列表结束------------------------------",
+    ].join("\n");
+    const csvPath = path.join(dir, "alipay.csv");
+    fs.writeFileSync(csvPath, alipayCsv, "utf-8");
+
+    const alipayAdapter = new AlipayBillAdapter({
+      account: { email: "me@example.com" },
+    });
+    registry.register(alipayAdapter);
+    const alipayReport = await registry.syncAdapter("alipay-bill", { csvPath });
+    expect(alipayReport.status).toBe("ok");
+    expect(alipayReport.entityCounts.events).toBe(3);
+
+    // ─── Step 4-5: EntityResolver drained (rule stage only) ───
+    // Email's sender person (招商银行) is a separate identity; Alipay's
+    // 美团/淘宝/张三 are 3 new persons. None should auto-merge unless
+    // they share identifiers. The resolver should record decisions.
+    const queueStatsBefore = vault.resolveQueueStats();
+    expect(queueStatsBefore.pending + queueStatsBefore.done).toBeGreaterThanOrEqual(0);
+
+    // ─── Step 6: SpendingSkill answers "how much did I spend?" ───
+    const spendingSkill = new SpendingSkill({ vault });
+    const spending = await spendingSkill.run({});
+    expect(spending.summary.totalSpend).toBeCloseTo(38.50 + 299 + 500, 2);
+    expect(spending.summary.eventCount).toBeGreaterThanOrEqual(3);
+    expect(spending.breakdown.length).toBeGreaterThanOrEqual(3);
+    expect(spending.breakdown[0].key).toBe("张三"); // biggest
+
+    // ─── Step 7: TimelineSkill weaves into story ───
+    const timelineSkill = new TimelineSkill({ vault });
+    const timeline = await timelineSkill.run({
+      since: Date.parse("2026-05-01T00:00:00Z"),
+      until: Date.parse("2026-06-01T00:00:00Z"),
+    });
+    expect(timeline.entries.length).toBeGreaterThanOrEqual(4); // email + 3 alipay
+    expect(timeline.summary.byAdapter["email-imap"]).toBeGreaterThanOrEqual(1);
+    expect(timeline.summary.byAdapter["alipay-bill"]).toBe(3);
+    // Chronological: 5/10 first, 5/15 next, 5/20 last
+    expect(timeline.entries[0].occurredAt).toBeLessThan(timeline.entries[timeline.entries.length - 1].occurredAt);
+
+    // ─── Step 8: RelationsSkill (ranked mode) ───
+    const relationsSkill = new RelationsSkill({ vault });
+    const relations = await relationsSkill.run({}); // ranked mode
+    expect(relations.ranked.length).toBeGreaterThanOrEqual(3);
+    // Top should be 张三 (biggest transfer)
+    const zhangsan = relations.ranked.find((p) => p.name === "张三");
+    expect(zhangsan).toBeDefined();
+    expect(zhangsan.totalSpend).toBe(500);
+
+    // ─── Step 9: event-detail deep-link works ───
+    // Pull one event and verify the source row is recoverable
+    const events = vault.queryEvents({ adapter: "alipay-bill", limit: 10 });
+    expect(events.length).toBe(3);
+    // Find the Taobao transaction by counterparty (title is item name, e.g. "运动鞋")
+    const tx = events.find((e) => e.extra && e.extra.counterparty === "淘宝");
+    expect(tx).toBeDefined();
+    expect(tx.source.adapter).toBe("alipay-bill");
+    expect(tx.extra.counterpartyKind).toBe("merchant");
+  });
+
+  it("idempotent re-sync — same alipay CSV produces 0 duplicate events", async () => {
+    const alipayCsv = [
+      "支付宝交易记录明细查询",
+      "账号:[me@example.com]",
+      "---------------------------------交易记录明细列表------------------------------",
+      "交易号,商家订单号,交易创建时间,付款时间,最近修改时间,交易来源地,类型,交易对方,商品名称,金额（元）,收/支,交易状态,服务费（元）,成功退款（元）,备注,资金状态",
+      "2026051022001112345001,T1,2026-05-10 14:00:00,2026-05-10 14:00:02,2026-05-10 14:00:02,客户端,即时到账交易,美团,外卖,38.50,支出,交易成功,0.00,0.00,,已支出",
+    ].join("\n");
+    const csvPath = path.join(dir, "alipay.csv");
+    fs.writeFileSync(csvPath, alipayCsv, "utf-8");
+
+    const adapter = new AlipayBillAdapter({ account: { email: "me@example.com" } });
+    registry.register(adapter);
+    await registry.syncAdapter("alipay-bill", { csvPath });
+    await registry.syncAdapter("alipay-bill", { csvPath });
+
+    const events = vault.queryEvents({ adapter: "alipay-bill", limit: 100 });
+    expect(events.length).toBe(1); // dedup by originalId
+  });
+
+  it("vault stats reflect post-sync entity counts", async () => {
+    const csvPath = path.join(dir, "alipay.csv");
+    fs.writeFileSync(csvPath, [
+      "支付宝交易记录明细查询",
+      "账号:[me@example.com]",
+      "---------------------------------交易记录明细列表------------------------------",
+      "交易号,商家订单号,交易创建时间,付款时间,最近修改时间,交易来源地,类型,交易对方,商品名称,金额（元）,收/支,交易状态,服务费（元）,成功退款（元）,备注,资金状态",
+      "2026051022001112345001,T1,2026-05-10 14:00:00,2026-05-10 14:00:02,2026-05-10 14:00:02,客户端,即时到账交易,美团,外卖,38.50,支出,交易成功,0.00,0.00,,已支出",
+    ].join("\n"), "utf-8");
+
+    const adapter = new AlipayBillAdapter({ account: { email: "me@example.com" } });
+    registry.register(adapter);
+    await registry.syncAdapter("alipay-bill", { csvPath });
+
+    const stats = vault.stats();
+    expect(stats.events).toBe(1);
+    expect(stats.persons).toBe(1); // 美团 merchant
+    expect(stats.rawEvents).toBeGreaterThanOrEqual(1);
+  });
+});

package/__tests__/entity-resolver-ingest-hook.test.js

@@ -0,0 +1,177 @@
+"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 { AdapterRegistry } = require("../lib/registry");
+const { EntityResolver } = require("../lib/entity-resolver");
+
+// Minimal adapter that yields raw rows then normalizes to UnifiedSchema
+class FakeAdapter {
+  constructor(name, persons) {
+    this.name = name;
+    this.version = "0.1.0";
+    this.capabilities = ["sync:test"];
+    this.rateLimits = {};
+    this.dataDisclosure = { fields: [], sensitivity: "low", legalGate: false };
+    this._persons = persons;
+  }
+  async authenticate() { return { ok: true }; }
+  async healthCheck() { return { ok: true, lastChecked: Date.now() }; }
+  async *sync() {
+    for (const p of this._persons) {
+      yield { adapter: this.name, originalId: p.id, capturedAt: Date.now(), payload: { person: p } };
+    }
+  }
+  normalize(raw) {
+    const p = raw.payload.person;
+    const now = Date.now();
+    const source = {
+      adapter: this.name, adapterVersion: this.version,
+      originalId: raw.originalId, capturedAt: raw.capturedAt, capturedBy: "api",
+    };
+    return {
+      events: [{
+        id: `evt-${raw.originalId}`,
+        type: "event",
+        subtype: "interaction",
+        occurredAt: now,
+        actor: p.id,
+        ingestedAt: now,
+        source,
+      }],
+      persons: [{
+        id: p.id,
+        type: "person",
+        subtype: "contact",
+        names: p.names || [],
+        identifiers: p.identifiers || {},
+        ingestedAt: now,
+        source,
+      }],
+      places: [], items: [], topics: [],
+    };
+  }
+}
+
+function makeRig() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "er-hook-"));
+  const vault = new LocalVault({ path: path.join(dir, "v.db"), key: generateKeyHex() });
+  vault.open();
+  const resolver = new EntityResolver({ vault });
+  const registry = new AdapterRegistry({ vault, entityResolver: resolver });
+  return { vault, resolver, registry, dir };
+}
+
+function cleanup({ vault, dir }) {
+  try { vault.close(); } catch (_e) {}
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_e) {}
+}
+
+// ─── tests ────────────────────────────────────────────────────────────────
+
+describe("Phase 8.6 — registry → entity resolver ingest hook", () => {
+  let rig;
+  afterEach(() => cleanup(rig));
+
+  it("registry.syncAdapter fires resolveOnIngest with new Persons", async () => {
+    rig = makeRig();
+    const adapter = new FakeAdapter("a1", [
+      { id: "p-1", names: ["Alice"], identifiers: { email: ["alice@x.com"] } },
+      { id: "p-2", names: ["Bob"], identifiers: { email: ["bob@x.com"] } },
+    ]);
+    rig.registry.register(adapter);
+    const report = await rig.registry.syncAdapter("a1");
+    expect(report.status).toBe("ok");
+    expect(report.entityResolver).toBeDefined();
+    expect(report.entityResolver.newPersons).toBe(2);
+  });
+
+  it("cross-adapter R1 match: same email → auto-merged", async () => {
+    rig = makeRig();
+    // Adapter 1 imports Alice via email
+    rig.registry.register(new FakeAdapter("email", [
+      { id: "p-email-alice", names: ["Alice"], identifiers: { email: ["alice@x.com"] } },
+    ]));
+    await rig.registry.syncAdapter("email");
+
+    // Adapter 2 imports same Alice via different name + same email
+    rig.registry.register(new FakeAdapter("alipay", [
+      { id: "p-alipay-alice-X", names: ["A. Alice"], identifiers: { email: ["alice@x.com"] } },
+    ]));
+    const report = await rig.registry.syncAdapter("alipay");
+    expect(report.entityResolver.sameImmediate).toBeGreaterThanOrEqual(1);
+
+    // Verify merge group exists
+    const members = rig.vault.getMergeGroupMembers("p-email-alice").sort();
+    expect(members).toEqual(["p-alipay-alice-X", "p-email-alice"]);
+  });
+
+  it("uncertain pairs (name overlap only) → enqueued for async", async () => {
+    rig = makeRig();
+    rig.registry.register(new FakeAdapter("email", [
+      { id: "p-1", names: ["张三"] }, // no identifiers
+    ]));
+    await rig.registry.syncAdapter("email");
+
+    rig.registry.register(new FakeAdapter("alipay", [
+      { id: "p-2", names: ["张三"] },
+    ]));
+    const report = await rig.registry.syncAdapter("alipay");
+    expect(report.entityResolver.enqueued).toBeGreaterThanOrEqual(1);
+    expect(rig.vault.resolveQueueStats().pending).toBeGreaterThanOrEqual(1);
+  });
+
+  it("zero-overlap pair → no merge, no resolver decisions, person still ingested", async () => {
+    rig = makeRig();
+    rig.registry.register(new FakeAdapter("email", [
+      { id: "p-1", names: ["Alice"], identifiers: { email: ["a@x.com"] } },
+    ]));
+    await rig.registry.syncAdapter("email");
+
+    rig.registry.register(new FakeAdapter("alipay", [
+      { id: "p-2", names: ["Bob"], identifiers: { phone: ["13999998888"] } },
+    ]));
+    const report = await rig.registry.syncAdapter("alipay");
+    expect(report.status).toBe("ok");
+    expect(rig.vault.stats().mergeGroups).toBe(0);
+  });
+
+  it("resolver failure does NOT break ingest (audit-logged)", async () => {
+    rig = makeRig();
+    // Mock resolver that throws on resolveOnIngest
+    rig.registry.entityResolver = {
+      resolveOnIngest: () => { throw new Error("resolver boom"); },
+    };
+    rig.registry.register(new FakeAdapter("a1", [
+      { id: "p-1", names: ["Alice"], identifiers: { email: ["alice@x.com"] } },
+    ]));
+    const report = await rig.registry.syncAdapter("a1");
+    expect(report.status).toBe("ok"); // sync completes
+    expect(report.entityCounts.persons).toBe(1); // person still ingested
+    const audits = rig.vault.queryAudit({ action: "adapter.sync.entity_resolver_failed", limit: 5 });
+    expect(audits.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("no entityResolver = registry works as before (backward-compat)", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "er-hook-"));
+    const vault = new LocalVault({ path: path.join(dir, "v.db"), key: generateKeyHex() });
+    vault.open();
+    try {
+      const registry = new AdapterRegistry({ vault }); // no entityResolver
+      registry.register(new FakeAdapter("a1", [
+        { id: "p-1", names: ["x"], identifiers: { email: ["a@x.com"] } },
+      ]));
+      const report = await registry.syncAdapter("a1");
+      expect(report.status).toBe("ok");
+      expect(report.entityResolver).toBeUndefined();
+    } finally {
+      vault.close();
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});