@chainlesschain/personal-data-hub 0.3.9 → 0.4.1

package/__tests__/registry-readiness.test.js

@@ -0,0 +1,233 @@
+"use strict";
+
+/**
+ * AdapterRegistry.readiness() — the "why can't I collect" surface.
+ *
+ * Uses a STUB vault (readiness only calls vault.getWatermark, defensively)
+ * so this file does NOT depend on the native SQLCipher driver and runs on
+ * every host — unlike registry.test.js which opens a real LocalVault and is
+ * auto-skipped when bs3mc's ABI doesn't match the host Node. See
+ * vitest.config.js NATIVE_DEPENDENT_TESTS.
+ */
+
+import { describe, it, expect } from "vitest";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const { AdapterRegistry } = require("../lib/registry");
+const {
+  READINESS_CATEGORY,
+  READINESS_STATUS,
+} = require("../lib/adapter-readiness");
+const { BilibiliAdapter } = require("../lib/adapters/social-bilibili");
+const { TelegramAdapter } = require("../lib/adapters/messaging-telegram");
+const { Train12306Adapter } = require("../lib/adapters/travel-12306");
+const { EmailAdapter } = require("../lib/adapters/email-imap");
+const { WechatAdapter } = require("../lib/adapters/wechat");
+
+// ─── Stub vault — readiness() only needs getWatermark ─────────────────────
+
+function stubVault(watermarks = {}) {
+  return {
+    _wm: watermarks,
+    getWatermark(adapter /*, scope */) {
+      return this._wm[adapter] || null;
+    },
+    audit() {},
+  };
+}
+
+function byName(reports, name) {
+  return reports.find((r) => r.name === name);
+}
+
+describe("AdapterRegistry.readiness()", () => {
+  it("snapshot adapter with no input → needs_setup / NO_INPUT", async () => {
+    const reg = new AdapterRegistry({ vault: stubVault() });
+    reg.register(new BilibiliAdapter());
+    const [r] = await reg.readiness();
+    expect(r.name).toBe("social-bilibili");
+    expect(r.ready).toBe(false);
+    expect(r.status).toBe(READINESS_STATUS.NEEDS_SETUP);
+    expect(r.reason).toBe("NO_INPUT");
+    expect(r.category).toBe(READINESS_CATEGORY.SNAPSHOT);
+    expect(typeof r.message).toBe("string");
+    expect(r.message.length).toBeGreaterThan(0);
+    expect(r.actionHint).toBeTruthy();
+  });
+
+  it("device-pull adapter (telegram) → needs_setup / DB_NOT_PULLED / device", async () => {
+    const reg = new AdapterRegistry({ vault: stubVault() });
+    reg.register(new TelegramAdapter());
+    const [r] = await reg.readiness();
+    expect(r.ready).toBe(false);
+    expect(r.reason).toBe("DB_NOT_PULLED");
+    expect(r.category).toBe(READINESS_CATEGORY.DEVICE);
+    expect(r.extractMode).toBe("device-pull");
+  });
+
+  it("12306 snapshot adapter → needs_setup", async () => {
+    const reg = new AdapterRegistry({ vault: stubVault() });
+    reg.register(new Train12306Adapter());
+    const [r] = await reg.readiness();
+    expect(r.ready).toBe(false);
+    expect(r.reason).toBe("NO_INPUT");
+  });
+
+  it("email snapshot stub → NO_INPUT (no live IMAP login)", async () => {
+    const reg = new AdapterRegistry({ vault: stubVault() });
+    reg.register(new EmailAdapter({ snapshotMode: true }));
+    const [r] = await reg.readiness();
+    expect(r.ready).toBe(false);
+    expect(r.reason).toBe("NO_INPUT");
+  });
+
+  it("email per-account → ready=configured WITHOUT opening an IMAP session", async () => {
+    let sessionFactoryCalled = false;
+    const adapter = new EmailAdapter({
+      account: { email: "user@gmail.com", authCode: "secret", provider: "gmail" },
+      // If readiness wrongly performed a live login it would call this.
+      sessionFactory: () => {
+        sessionFactoryCalled = true;
+        return { connect: async () => {}, close: async () => {} };
+      },
+    });
+    const reg = new AdapterRegistry({ vault: stubVault() });
+    reg.register(adapter);
+    const [r] = await reg.readiness();
+    expect(r.ready).toBe(true);
+    expect(r.status).toBe(READINESS_STATUS.READY);
+    expect(r.mode).toBe("configured");
+    expect(sessionFactoryCalled).toBe(false);
+  });
+
+  it("wechat readiness with db+keyProvider present → configured WITHOUT calling getKey", async () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "pdh-rd-wx-"));
+    const dbPath = path.join(tmp, "EnMicroMsg.db");
+    fs.writeFileSync(dbPath, "x");
+    let getKeyCalled = false;
+    const adapter = new WechatAdapter({
+      account: { uin: "12345" },
+      dbPath,
+      keyProvider: {
+        getKey: async () => {
+          getKeyCalled = true;
+          return "deadbeef";
+        },
+      },
+    });
+    const reg = new AdapterRegistry({ vault: stubVault() });
+    reg.register(adapter);
+    const [r] = await reg.readiness();
+    expect(r.ready).toBe(true);
+    expect(r.mode).toBe("configured");
+    // The whole point of readinessOnly: don't invoke the (frida) key provider.
+    expect(getKeyCalled).toBe(false);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("wechat with no db → DB_NOT_PULLED", async () => {
+    const adapter = new WechatAdapter({ account: { uin: "1" } });
+    const reg = new AdapterRegistry({ vault: stubVault() });
+    reg.register(adapter);
+    const [r] = await reg.readiness();
+    expect(r.ready).toBe(false);
+    expect(r.reason).toBe("DB_NOT_PULLED");
+    expect(r.category).toBe(READINESS_CATEGORY.DEVICE);
+  });
+
+  it("a hanging authenticate() hits the per-adapter timeout → PROBE_TIMEOUT", async () => {
+    const reg = new AdapterRegistry({ vault: stubVault() });
+    reg.register({
+      name: "hang-test",
+      version: "1.0.0",
+      capabilities: [],
+      dataDisclosure: { fields: [], sensitivity: "low" },
+      authenticate: () => new Promise(() => {}), // never resolves
+      healthCheck: async () => ({ ok: true }),
+      normalize: (r) => r,
+      // eslint-disable-next-line require-yield
+      sync: async function* () {},
+    });
+    const [r] = await reg.readiness({ timeoutMs: 200 });
+    expect(r.ready).toBe(false);
+    expect(r.reason).toBe("PROBE_TIMEOUT");
+    expect(r.status).toBe(READINESS_STATUS.ERROR);
+  });
+
+  it("an unknown reason code falls back to UNKNOWN (never crashes)", async () => {
+    const reg = new AdapterRegistry({ vault: stubVault() });
+    reg.register({
+      name: "weird",
+      version: "1.0.0",
+      capabilities: [],
+      dataDisclosure: { fields: [], sensitivity: "low" },
+      authenticate: async () => ({ ok: false, reason: "TOTALLY_NEW_CODE_42" }),
+      healthCheck: async () => ({ ok: true }),
+      normalize: (r) => r,
+      // eslint-disable-next-line require-yield
+      sync: async function* () {},
+    });
+    const [r] = await reg.readiness();
+    expect(r.ready).toBe(false);
+    expect(r.reason).toBe("TOTALLY_NEW_CODE_42");
+    expect(r.message).toBeTruthy(); // mapped via UNKNOWN fallback
+  });
+
+  it("folds last sync outcome from the watermark into the report", async () => {
+    const reg = new AdapterRegistry({
+      vault: stubVault({
+        "social-bilibili": {
+          last_synced_at: 1700000000000,
+          last_status: "error",
+          last_error: "boom from last run",
+        },
+      }),
+    });
+    reg.register(new BilibiliAdapter());
+    const [r] = await reg.readiness();
+    expect(r.lastSyncedAt).toBe(1700000000000);
+    expect(r.lastStatus).toBe("error");
+    expect(r.lastError).toBe("boom from last run");
+  });
+
+  it("attaches a step-by-step import guide to each report", async () => {
+    const reg = new AdapterRegistry({ vault: stubVault() });
+    reg.register(new BilibiliAdapter());
+    reg.register(new WechatAdapter({ account: { uin: "1" } }));
+    const reports = await reg.readiness();
+    const bili = byName(reports, "social-bilibili");
+    expect(bili.guide).toBeTruthy();
+    expect(bili.guide.displayName).toBe("哔哩哔哩");
+    expect(Array.isArray(bili.guide.methods)).toBe(true);
+    expect(bili.guide.methods.length).toBeGreaterThan(0);
+    expect(bili.guide.methods[0].steps.length).toBeGreaterThan(0);
+    // wechat gets the bespoke device override, not the generic category guide
+    const wx = byName(reports, "wechat");
+    expect(wx.guide.displayName).toBe("微信（手机）");
+    expect(wx.guide.methods[0].label).toMatch(/frida|root/);
+  });
+
+  it("reports every registered adapter in registration order", async () => {
+    const reg = new AdapterRegistry({ vault: stubVault() });
+    reg.register(new BilibiliAdapter());
+    reg.register(new TelegramAdapter());
+    reg.register(new Train12306Adapter());
+    const reports = await reg.readiness();
+    expect(reports.map((r) => r.name)).toEqual([
+      "social-bilibili",
+      "messaging-telegram",
+      "travel-12306",
+    ]);
+    // every report carries the required UI fields
+    for (const r of reports) {
+      expect(r).toHaveProperty("ready");
+      expect(r).toHaveProperty("status");
+      expect(r).toHaveProperty("category");
+      expect(r).toHaveProperty("message");
+    }
+    expect(byName(reports, "messaging-telegram").reason).toBe("DB_NOT_PULLED");
+  });
+});

package/__tests__/social-douyin-im-direct-read.test.js

@@ -0,0 +1,311 @@
+"use strict";
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+const { DouyinAdapter } = require("../lib/adapters/social-douyin");
+const { partitionBatch } = require("../lib/batch");
+
+/**
+ * 本地直读样板 (Douyin <uid>_im.db local direct-read) + the normalize
+ * message/contact gap fix.
+ *
+ * Two things this covers that nothing else did:
+ *
+ *  1. REGRESSION: DouyinAdapter.normalize() used to throw "unknown kind
+ *     message/contact" for IM events — so every 私信 + 联系人 silently
+ *     dropped (registry catches the throw → invalidCount++ → 0 rows in the
+ *     vault) even though the snapshot/ADB path "succeeded". The old snapshot
+ *     test only round-tripped `profile`, so it never caught this.
+ *
+ *  2. NEW direct-read mode: `sync({ imDbPath })` / `--input <uid>_im.db`
+ *     opens the plaintext SQLite directly (no ADB, no snapshot JSON) and
+ *     emits message/contact raws whose originalIds match the snapshot path
+ *     (idempotent across both routes).
+ *
+ * No native SQLite needed — a fake Database driver is injected via
+ * `_deps.dbDriverFactory` (the parser accepts it as `_databaseClass`).
+ */
+
+// Fake better-sqlite3-style driver answering the parser's PRAGMA + SELECTs.
+function makeFakeDb({ msgRows, userRows, msgCols, userCols }) {
+  class FakeStmt {
+    constructor(sql) {
+      this.sql = sql;
+    }
+    all() {
+      const s = this.sql;
+      if (/PRAGMA table_info\(msg\)/.test(s)) return msgCols;
+      if (/FROM msg/.test(s)) return msgRows;
+      if (/PRAGMA table_info\(SIMPLE_USER\)/.test(s)) return userCols;
+      if (/FROM SIMPLE_USER/.test(s)) return userRows;
+      return [];
+    }
+  }
+  return class FakeDb {
+    // eslint-disable-next-line no-unused-vars
+    constructor(_path, _opts) {}
+    prepare(sql) {
+      return new FakeStmt(sql);
+    }
+    close() {}
+  };
+}
+
+const DEFAULT_FAKE = {
+  msgCols: [
+    { name: "sender" },
+    { name: "created_time" },
+    { name: "content" },
+    { name: "conversation_id" },
+    { name: "read_status" },
+  ],
+  msgRows: [
+    {
+      sender: 111,
+      createdTime: 1700000000000,
+      content: JSON.stringify({ text: "你好呀" }),
+      conversationId: "conv-1",
+      readStatus: 1,
+    },
+    {
+      sender: 222,
+      createdTime: 1700000001000,
+      content: JSON.stringify({ text: "在吗" }),
+      conversationId: "conv-1",
+      readStatus: 0,
+    },
+  ],
+  userCols: [
+    { name: "UID" },
+    { name: "short_id" },
+    { name: "name" },
+    { name: "avatar_url" },
+    { name: "follow_status" },
+  ],
+  userRows: [
+    {
+      uid: 222,
+      shortId: 888,
+      name: "小明",
+      avatarUrl: "http://x/a.jpg",
+      followStatus: 2,
+    },
+  ],
+};
+
+function freshAdapter(fakeSpec = DEFAULT_FAKE, fsOverride) {
+  const a = new DouyinAdapter();
+  a._deps.fs = fsOverride || { existsSync: () => true };
+  a._deps.dbDriverFactory = () => makeFakeDb(fakeSpec);
+  return a;
+}
+
+async function collect(iter) {
+  const out = [];
+  for await (const r of iter) out.push(r);
+  return out;
+}
+
+describe("DouyinAdapter — normalize message/contact (regression)", () => {
+  it("normalizes a message raw into one MESSAGE event (no throw)", () => {
+    const a = new DouyinAdapter();
+    const raw = {
+      adapter: "social-douyin",
+      kind: "message",
+      originalId: "douyin:message:msg-conv-1-1700000000000",
+      capturedAt: 1700000000000,
+      payload: {
+        kind: "message",
+        text: "你好",
+        senderUid: "111",
+        conversationId: "conv-1",
+        readStatus: 1,
+        contentBlob: '{"text":"你好"}',
+      },
+    };
+    const n = a.normalize(raw);
+    expect(n.events).toHaveLength(1);
+    expect(n.persons).toHaveLength(0);
+    const ev = n.events[0];
+    expect(ev.subtype).toBe("message");
+    expect(ev.content.text).toBe("你好");
+    expect(ev.extra.senderUid).toBe("111");
+    expect(ev.extra.conversationId).toBe("conv-1");
+    expect(ev.extra.platform).toBe("douyin");
+  });
+
+  it("normalizes a contact raw into one CONTACT person", () => {
+    const a = new DouyinAdapter();
+    const raw = {
+      adapter: "social-douyin",
+      kind: "contact",
+      originalId: "douyin:contact:contact-222",
+      capturedAt: 1700000000000,
+      payload: {
+        kind: "contact",
+        uid: "222",
+        shortId: "888",
+        name: "小明",
+        avatarUrl: "http://x/a.jpg",
+        followStatus: 2,
+      },
+    };
+    const n = a.normalize(raw);
+    expect(n.persons).toHaveLength(1);
+    expect(n.events).toHaveLength(0);
+    const per = n.persons[0];
+    expect(per.subtype).toBe("contact");
+    expect(per.id).toBe("person-douyin-222");
+    expect(per.names).toEqual(["小明"]);
+    expect(per.identifiers["douyin-uid"]).toEqual(["222"]);
+    expect(per.extra.followStatus).toBe(2);
+  });
+
+  it("an empty-text (non-text) message still produces a valid event", () => {
+    const a = new DouyinAdapter();
+    const raw = {
+      adapter: "social-douyin",
+      kind: "message",
+      originalId: "douyin:message:x",
+      capturedAt: 1700000000000,
+      payload: { kind: "message", text: null, senderUid: "111" },
+    };
+    const n = a.normalize(raw);
+    const { valid, invalidReasons } = partitionBatch({
+      events: n.events,
+      persons: [],
+      places: [],
+      items: [],
+      topics: [],
+    });
+    expect(invalidReasons).toHaveLength(0);
+    expect(valid.events).toHaveLength(1);
+  });
+});
+
+describe("DouyinAdapter — 本地直读 <uid>_im.db", () => {
+  let tmpDir;
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "douyin-imdb-"));
+  });
+  afterEach(() => {
+    if (tmpDir && fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("sync({ imDbPath }) yields message + contact raws", async () => {
+    const a = freshAdapter();
+    const raws = await collect(a.sync({ imDbPath: "/fake/123_im.db" }));
+    expect(raws.map((r) => r.kind)).toEqual(["message", "message", "contact"]);
+  });
+
+  it("direct-read events normalize to a fully valid batch (no silent drop)", async () => {
+    const a = freshAdapter();
+    const raws = await collect(a.sync({ imDbPath: "/fake/123_im.db" }));
+    const merged = { events: [], persons: [], places: [], items: [], topics: [] };
+    for (const r of raws) {
+      const n = a.normalize(r);
+      for (const k of Object.keys(merged)) merged[k].push(...n[k]);
+    }
+    const { valid, invalidReasons } = partitionBatch(merged);
+    expect(invalidReasons).toHaveLength(0);
+    expect(valid.events).toHaveLength(2); // two messages
+    expect(valid.persons).toHaveLength(1); // one contact
+  });
+
+  it("originalIds match the snapshot composite strategy (idempotent across routes)", async () => {
+    const a = freshAdapter();
+    const raws = await collect(a.sync({ imDbPath: "/fake/123_im.db" }));
+    expect(raws.map((r) => r.originalId)).toEqual([
+      "douyin:message:msg-conv-1-1700000000000",
+      "douyin:message:msg-conv-1-1700000001000",
+      "douyin:contact:contact-222",
+    ]);
+  });
+
+  it("respects include={message:false} / limit", async () => {
+    const a = freshAdapter();
+    const onlyContacts = await collect(
+      a.sync({ imDbPath: "/fake/123_im.db", include: { message: false } }),
+    );
+    expect(onlyContacts.every((r) => r.kind === "contact")).toBe(true);
+
+    const capped = await collect(a.sync({ imDbPath: "/fake/123_im.db", limit: 1 }));
+    expect(capped).toHaveLength(1);
+  });
+
+  it("emits an im-db-parsed progress event with the diagnostic", async () => {
+    const a = freshAdapter();
+    const events = [];
+    await collect(
+      a.sync({
+        imDbPath: "/fake/123_im.db",
+        onProgress: (e) => events.push(e),
+      }),
+    );
+    const parsed = events.find((e) => e.phase === "im-db-parsed");
+    expect(parsed).toBeTruthy();
+    expect(parsed.hadMsgTable).toBe(true);
+    expect(parsed.hadSimpleUserTable).toBe(true);
+    expect(parsed.messageCount).toBe(2);
+    expect(parsed.contactCount).toBe(1);
+  });
+
+  it("missing db file yields nothing (no throw)", async () => {
+    const a = freshAdapter(DEFAULT_FAKE, { existsSync: () => false });
+    const raws = await collect(a.sync({ imDbPath: "/does/not/exist_im.db" }));
+    expect(raws).toHaveLength(0);
+  });
+});
+
+describe("DouyinAdapter — sync() input routing (sniff)", () => {
+  let tmpDir;
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "douyin-route-"));
+  });
+  afterEach(() => {
+    if (tmpDir && fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("--input <file with SQLite magic header> routes to direct IM read", async () => {
+    // Real file with the 16-byte SQLite magic header so _looksLikeSqlite
+    // (which uses real fs) returns true; the fake driver supplies the rows.
+    const dbFile = path.join(tmpDir, "123_im.db");
+    const header = Buffer.alloc(100);
+    header.write("SQLite format 3", 0, "latin1");
+    fs.writeFileSync(dbFile, header);
+
+    const a = new DouyinAdapter();
+    a._deps.dbDriverFactory = () => makeFakeDb(DEFAULT_FAKE);
+    const raws = [];
+    for await (const r of a.sync({ inputPath: dbFile })) raws.push(r);
+    expect(raws.map((r) => r.kind)).toEqual(["message", "message", "contact"]);
+  });
+
+  it("--input <JSON snapshot> routes to snapshot mode (not IM)", async () => {
+    const snapFile = path.join(tmpDir, "social-douyin.json");
+    fs.writeFileSync(
+      snapFile,
+      JSON.stringify({
+        schemaVersion: 1,
+        snapshottedAt: 1700000000000,
+        account: { secUid: "MS4abc", shortId: "9", displayName: "me" },
+        events: [
+          { kind: "profile", id: "profile-MS4abc", capturedAt: 1700000000000, secUid: "MS4abc", nickname: "me" },
+        ],
+      }),
+    );
+    const a = new DouyinAdapter();
+    const raws = [];
+    for await (const r of a.sync({ inputPath: snapFile })) raws.push(r);
+    expect(raws).toHaveLength(1);
+    expect(raws[0].kind).toBe("profile");
+  });
+});

package/__tests__/social-douyin-snapshot.test.js

@@ -33,14 +33,17 @@ describe("DouyinAdapter snapshot mode", () => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "douyin-snap-"));
   });
 
-  it("exports SNAPSHOT_SCHEMA_VERSION = 1 + 4 VALID_SNAPSHOT_KINDS", () => {
+  it("exports SNAPSHOT_SCHEMA_VERSION = 1 + 6 VALID_SNAPSHOT_KINDS", () => {
     expect(SNAPSHOT_SCHEMA_VERSION).toBe(1);
-    // v0.2 emits only profile; v0.3 will add history/favourite/like.
+    // Forward-compat list (lib index.js): profile/history/favourite/like from
+    // v0.2/v0.3, plus message/contact added in Phase 2a (3c5126401, _im.db pull).
     expect(VALID_SNAPSHOT_KINDS).toEqual([
       "profile",
       "history",
       "favourite",
       "like",
+      "message",
+      "contact",
     ]);
   });
 

package/__tests__/vault.test.js

@@ -666,3 +666,102 @@ describe("LocalVault.stats", () => {
     expect(s.auditLog).toBeGreaterThanOrEqual(1);
   });
 });
+
+describe("LocalVault.sumEventAmount", () => {
+  // shopping/travel shape: content.amount = { value, currency, direction }
+  const shopEvent = (amount, over = {}) =>
+    eventOk({
+      subtype: "order",
+      source: source({ adapter: "shopping-jd" }),
+      content: { title: "订单", amount },
+      ...over,
+    });
+  // alipay shape: extra.amountFen (cents) + extra.direction
+  const alipayEvent = (amountFen, direction, over = {}) =>
+    eventOk({
+      subtype: "payment",
+      source: source({ adapter: "finance-alipay" }),
+      content: { title: "支付" },
+      extra: { amountFen, direction },
+      ...over,
+    });
+
+  it("sums content.amount (shopping/travel) split by direction", () => {
+    freshVault();
+    vault.putEvent(shopEvent({ value: 100, currency: "CNY", direction: "out" }));
+    vault.putEvent(shopEvent({ value: 30, currency: "CNY", direction: "out" }));
+    vault.putEvent(shopEvent({ value: 50, currency: "CNY", direction: "in" }));
+    const r = vault.sumEventAmount();
+    expect(r.count).toBe(3);
+    expect(r.byDirection.out).toBe(130);
+    expect(r.byDirection.in).toBe(50);
+    expect(r.total).toBe(180);
+    expect(r.currency).toBe("CNY");
+  });
+
+  it("sums extra.amountFen (alipay), converting cents → yuan", () => {
+    freshVault();
+    vault.putEvent(alipayEvent(12345, "out"));
+    vault.putEvent(alipayEvent(5500, "in"));
+    const r = vault.sumEventAmount();
+    expect(r.count).toBe(2);
+    expect(r.byDirection.out).toBe(123.45);
+    expect(r.byDirection.in).toBe(55);
+  });
+
+  it("excludes events with no extractable amount (messages/visits)", () => {
+    freshVault();
+    vault.putEvent(eventOk({ subtype: "message", content: { text: "hi" }, source: source({ adapter: "wechat" }) }));
+    vault.putEvent(shopEvent({ value: 10, currency: "CNY", direction: "out" }));
+    const r = vault.sumEventAmount();
+    expect(r.count).toBe(1);
+    expect(r.total).toBe(10);
+  });
+
+  it("filters by adapter and by time window", () => {
+    freshVault();
+    vault.putEvent(shopEvent({ value: 10, currency: "CNY", direction: "out" }, { occurredAt: 1000, source: source({ adapter: "shopping-jd" }) }));
+    vault.putEvent(shopEvent({ value: 20, currency: "CNY", direction: "out" }, { occurredAt: 5000, source: source({ adapter: "shopping-taobao" }) }));
+    expect(vault.sumEventAmount({ adapter: "shopping-jd" }).total).toBe(10);
+    expect(vault.sumEventAmount({ since: 2000 }).total).toBe(20);
+    expect(vault.sumEventAmount({ until: 2000 }).total).toBe(10);
+  });
+
+  it("mixed shapes coexist; per-currency breakdown, NO cross-currency sum", () => {
+    freshVault();
+    vault.putEvent(shopEvent({ value: 100, currency: "CNY", direction: "out" }));
+    vault.putEvent(alipayEvent(20000, "out")); // 200 元 (CNY, alipay shape)
+    vault.putEvent(shopEvent({ value: 5, currency: "USD", direction: "out" }));
+    const r = vault.sumEventAmount();
+    expect(r.count).toBe(3);
+    // CNY has 2 events → primary; top-level reports CNY only (NOT 305 cross-sum).
+    expect(r.currency).toBe("CNY");
+    expect(r.total).toBe(300);
+    expect(r.byDirection.out).toBe(300);
+    // Full breakdown per currency.
+    expect(r.byCurrency.CNY).toEqual({ total: 300, count: 2, byDirection: { out: 300, in: 0 } });
+    expect(r.byCurrency.USD).toEqual({ total: 5, count: 1, byDirection: { out: 5, in: 0 } });
+  });
+
+  it("single currency → byCurrency has one entry matching top-level", () => {
+    freshVault();
+    vault.putEvent(shopEvent({ value: 40, currency: "CNY", direction: "out" }));
+    vault.putEvent(shopEvent({ value: 10, currency: "CNY", direction: "in" }));
+    const r = vault.sumEventAmount();
+    expect(Object.keys(r.byCurrency)).toEqual(["CNY"]);
+    expect(r.byCurrency.CNY).toEqual({ total: 50, count: 2, byDirection: { out: 40, in: 10 } });
+    expect(r.total).toBe(50);
+    expect(r.currency).toBe("CNY");
+  });
+
+  it("empty vault → zeros, CNY, count 0, empty byCurrency", () => {
+    freshVault();
+    expect(vault.sumEventAmount()).toEqual({
+      total: 0,
+      currency: "CNY",
+      byCurrency: {},
+      count: 0,
+      byDirection: { out: 0, in: 0 },
+    });
+  });
+});