@chainlesschain/personal-data-hub 0.3.8 → 0.4.0

package/__tests__/adapters/apple-health.test.js

@@ -0,0 +1,95 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { AppleHealthAdapter } = require("../../lib/adapters/apple-health");
+const { partitionBatch } = require("../../lib/batch");
+
+const XML = [
+  '<?xml version="1.0" encoding="UTF-8"?>',
+  '<HealthData locale="zh_CN">',
+  ' <Record type="HKQuantityTypeIdentifierStepCount" sourceName="iPhone" unit="count" creationDate="2024-01-15 08:36:00 +0800" startDate="2024-01-15 08:30:00 +0800" endDate="2024-01-15 08:35:00 +0800" value="123"/>',
+  ' <Record type="HKCategoryTypeIdentifierSleepAnalysis" sourceName="Watch" startDate="2024-01-15 23:00:00 +0800" endDate="2024-01-16 07:00:00 +0800" value="HKCategoryValueSleepAnalysisAsleep"/>',
+  ' <Workout workoutActivityType="HKWorkoutActivityTypeRunning" duration="30" durationUnit="min" totalDistance="5" totalDistanceUnit="km" startDate="2024-01-15 18:00:00 +0800" endDate="2024-01-15 18:30:00 +0800"/>',
+  ' <SomethingElse foo="bar"/>',
+  "</HealthData>",
+].join("\n");
+
+function adapter(xml = XML, { exists = true } = {}) {
+  const a = new AppleHealthAdapter();
+  a._deps.fs = {
+    existsSync: () => exists,
+    readFileSync: () => xml,
+    accessSync: () => {},
+    constants: { R_OK: 4 },
+  };
+  return a;
+}
+
+async function collect(iter) {
+  const out = [];
+  for await (const r of iter) out.push(r);
+  return out;
+}
+
+describe("AppleHealthAdapter", () => {
+  it("readinessOnly → NO_FILE (file-import, not 手机采集)", async () => {
+    const a = new AppleHealthAdapter();
+    const r = await a.authenticate({ readinessOnly: true });
+    expect(r.reason).toBe("NO_FILE");
+    expect(a.extractMode).toBe("file-import");
+  });
+
+  it("parses Record + Workout lines, ignores other elements", async () => {
+    const raws = await collect(adapter().sync({ inputPath: "/fake/export.xml" }));
+    expect(raws.map((r) => r.kind)).toEqual(["record", "record", "workout"]);
+  });
+
+  it("normalizes to valid events (metrics → other, workout → trip)", async () => {
+    const a = adapter();
+    const raws = await collect(a.sync({ inputPath: "/fake/export.xml" }));
+    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(3);
+    const subtypes = valid.events.map((e) => e.subtype).sort();
+    expect(subtypes).toEqual(["other", "other", "trip"]);
+    const steps = valid.events.find((e) => e.extra.metric === "HKQuantityTypeIdentifierStepCount");
+    expect(steps.content.title).toContain("步数");
+    expect(steps.content.title).toContain("123");
+    const workout = valid.events.find((e) => e.subtype === "trip");
+    expect(workout.extra.activityType).toBe("Running");
+    expect(workout.content.title).toContain("5km");
+  });
+
+  it("parses the +0800 timezone offset correctly", async () => {
+    const a = adapter();
+    const raws = await collect(a.sync({ inputPath: "/fake/export.xml" }));
+    // 2024-01-15 08:30:00 +0800 == 2024-01-15T00:30:00Z
+    expect(raws[0].capturedAt).toBe(Date.parse("2024-01-15T00:30:00Z"));
+  });
+
+  it("respects limit + include", async () => {
+    const a = adapter();
+    const capped = await collect(a.sync({ inputPath: "/x", limit: 1 }));
+    expect(capped).toHaveLength(1);
+    const noWorkout = await collect(a.sync({ inputPath: "/x", include: { workout: false } }));
+    expect(noWorkout.every((r) => r.kind === "record")).toBe(true);
+  });
+
+  it("emits truncated progress when maxRecords exceeded", async () => {
+    const a = adapter();
+    const events = [];
+    await collect(a.sync({ inputPath: "/x", maxRecords: 1, onProgress: (e) => events.push(e) }));
+    expect(events.find((e) => e.phase === "truncated")).toBeTruthy();
+  });
+
+  it("missing file yields nothing", async () => {
+    const raws = await collect(adapter(XML, { exists: false }).sync({ inputPath: "/x" }));
+    expect(raws).toHaveLength(0);
+  });
+});

package/__tests__/adapters/email-templates.test.js

@@ -262,6 +262,129 @@ describe("extractBill — bank statement", () => {
   });
 });
 
+// ─── bill.js Phase 5.5 — LLM gap-fill ─────────────────────────────────────
+
+describe("extractBill — Phase 5.5 LLM gap-fill", () => {
+  // A body the regex can't crack (HTML-stripped marketing-style prose with
+  // no recognizable keywords) so coverage stays under 0.6 and the LLM fires.
+  // from:[] so even `institution` (otherwise derived from sender domain)
+  // is missing — keeps regex coverage at 0 so the LLM path is exercised.
+  const opaqueEmail = () => emailOf({
+    from: [],
+    subject: "Your statement is ready",
+    textBody: "Hello, your latest statement is now available. Please sign in to view the details of your account activity for this period.",
+  });
+
+  const llmReturning = (obj, sink) => ({
+    async chat(messages, _opts) {
+      if (sink) sink.messages = messages;
+      return { text: JSON.stringify(obj) };
+    },
+  });
+
+  it("fills missing fields from LLM when regex coverage < 60%", async () => {
+    const r = await extractBill(opaqueEmail(), {
+      llm: llmReturning({
+        amount: { value: 1234.5, currency: "CNY" },
+        dueAmount: { value: 1000, currency: "CNY" },
+        dueDate: "2026-12-20",
+        billingPeriod: { start: "2026-11-01", end: "2026-11-30" },
+        accountIdentifier: "6225 8801 2345 6789",
+        institution: "Example Bank",
+        billingMonth: "2026-11",
+      }),
+    });
+    expect(r.fields.amount.value).toBe(1234.5);
+    expect(r.fields.amount.direction).toBe("out");
+    expect(r.fields.dueAmount.value).toBe(1000);
+    expect(r.fields.dueDate).toBeGreaterThan(0);
+    expect(r.fields.billingPeriod.startMs).toBeLessThan(r.fields.billingPeriod.endMs);
+    // accountIdentifier coerced to last-4 only — never the full PAN
+    expect(r.fields.accountIdentifier).toBe("**** 6789");
+    expect(r.fields.institution).toBe("Example Bank");
+    expect(r.fields.billingMonth).toBe("2026-11");
+    expect(r.llmFilled).toEqual(
+      expect.arrayContaining(["amount", "dueAmount", "dueDate", "accountIdentifier", "institution", "billingMonth"]),
+    );
+  });
+
+  it("regex wins: LLM fills only the gaps, never overwrites a regex field", async () => {
+    // Only an amount is regex-extractable → coverage 1/7 < 0.6, LLM fires.
+    const r = await extractBill(emailOf({
+      from: [],
+      subject: "statement",
+      textBody: "您的账单金额为 ¥3,256.78。",
+    }), {
+      llm: llmReturning({ amount: { value: 99999, currency: "USD" }, institution: "LLM Bank" }),
+    });
+    // regex amount retained, LLM's bogus 99999/USD ignored
+    expect(r.fields.amount.value).toBe(3256.78);
+    expect(r.fields.amount.currency).toBe("CNY");
+    // institution was missing → LLM allowed to fill it
+    expect(r.fields.institution).toBe("LLM Bank");
+    expect(r.llmFilled).toEqual(["institution"]);
+  });
+
+  it("does NOT call the LLM when regex coverage already ≥ 60%", async () => {
+    let called = false;
+    const r = await extractBill(emailOf({
+      from: [{ address: "ebank@ccb.com.cn" }],
+      subject: "建设银行 11 月对账单",
+      textBody: "本期应还金额 ¥800 元，尾号 5555，账单周期 2026-10-01 至 2026-10-31，最后还款日 2026-11-25。",
+    }), {
+      llm: { async chat() { called = true; return { text: "{}" }; } },
+    });
+    expect(called).toBe(false);
+    expect(r.llmFilled).toBeUndefined();
+  });
+
+  it("drops malformed LLM values (bad dates, zero amounts, short account)", async () => {
+    const r = await extractBill(opaqueEmail(), {
+      llm: llmReturning({
+        amount: { value: 0 },              // non-positive → dropped
+        dueDate: "2026-13-45",             // impossible date → dropped
+        accountIdentifier: "12",           // < 4 digits → dropped
+        billingMonth: "2026-99",           // bad month → dropped
+        institution: "   ",                // blank → dropped
+      }),
+    });
+    expect(r.fields.amount).toBeUndefined();
+    expect(r.fields.dueDate).toBeUndefined();
+    expect(r.fields.accountIdentifier).toBeUndefined();
+    expect(r.fields.billingMonth).toBeUndefined();
+    expect(r.fields.institution).toBeUndefined();
+    expect(r.llmFilled).toBeUndefined();
+  });
+
+  it("records a warning when the LLM returns unparseable output", async () => {
+    const r = await extractBill(opaqueEmail(), {
+      llm: { async chat() { return { text: "sorry, I can't help with that" }; } },
+    });
+    expect(r.warnings.some((w) => w.includes("not parseable JSON"))).toBe(true);
+  });
+
+  it("records a warning when the LLM call throws", async () => {
+    const r = await extractBill(opaqueEmail(), {
+      llm: { async chat() { throw new Error("rate limited"); } },
+    });
+    expect(r.warnings.some((w) => w.includes("LLM bill fill failed") && w.includes("rate limited"))).toBe(true);
+  });
+
+  it("tolerates LLM output wrapped in ```json fences", async () => {
+    const r = await extractBill(opaqueEmail(), {
+      llm: { async chat() { return { text: "```json\n{\"institution\":\"Fenced Bank\"}\n```" }; } },
+    });
+    expect(r.fields.institution).toBe("Fenced Bank");
+    expect(r.llmFilled).toEqual(["institution"]);
+  });
+
+  it("no LLM provided → behaves exactly as before (no llmFilled, no warning)", async () => {
+    const r = await extractBill(opaqueEmail());
+    expect(r.llmFilled).toBeUndefined();
+    expect(r.warnings.every((w) => !w.includes("LLM"))).toBe(true);
+  });
+});
+
 // ─── order.js ───────────────────────────────────────────────────────────
 
 describe("extractOrder — e-commerce", () => {

package/__tests__/adapters/family-23-collectors-scaffold.test.js

@@ -0,0 +1,178 @@
+/**
+ * FAMILY-23 v0.1 — 王者荣耀 / 作业帮 / 支付宝 / 华为学习中心 collector scaffold 测试。
+ * 各平台: 契约 + extractUid + sync NO_INPUT throw + snapshot sync + normalize → 合法 batch。
+ */
+import { describe, it, expect } from "vitest";
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const lib = require("../../lib");
+const { assertAdapter } = require("../../lib/adapter-spec");
+const { validateBatch } = require("../../lib/batch");
+
+const {
+  HonorOfKingsApiClient,
+} = require("../../lib/adapters/game-honor-of-kings/api-client");
+const {
+  ZuoyebangApiClient,
+} = require("../../lib/adapters/edu-zuoyebang/api-client");
+const { AlipayApiClient } = require("../../lib/adapters/finance-alipay/api-client");
+const {
+  HuaweiLearningApiClient,
+} = require("../../lib/adapters/edu-huawei-learning/api-client");
+
+function writeSnapshot(obj) {
+  const p = path.join(
+    os.tmpdir(),
+    `fam23-snap-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
+  );
+  fs.writeFileSync(p, JSON.stringify(obj), "utf-8");
+  return p;
+}
+
+// platform → { Adapter, name, sensitivity, eventKind, eventSubtype, idKey }
+const PLATFORMS = [
+  {
+    label: "王者荣耀",
+    Adapter: lib.HonorOfKingsAdapter,
+    name: "game-honor-of-kings",
+    sensitivity: "medium",
+    eventKind: "play",
+    eventSubtype: "media",
+    idKey: "hok-uid",
+    sample: { kind: "play", id: "p1", durationMs: 1800000, mode: "rank", startAt: 1700000000000 },
+  },
+  {
+    label: "作业帮",
+    Adapter: lib.ZuoyebangAdapter,
+    name: "edu-zuoyebang",
+    sensitivity: "medium",
+    eventKind: "study",
+    eventSubtype: "other",
+    idKey: "zuoyebang-uid",
+    sample: { kind: "study", id: "s1", subject: "math", durationMs: 1200000, startAt: 1700000000000 },
+  },
+  {
+    label: "支付宝",
+    Adapter: lib.AlipayAdapter,
+    name: "finance-alipay",
+    sensitivity: "high",
+    eventKind: "order",
+    eventSubtype: "payment",
+    idKey: "alipay-uid",
+    sample: { kind: "order", id: "o1", merchant: "便利店", amountFen: 350, direction: "out", startAt: 1700000000000 },
+  },
+  {
+    label: "华为学习中心",
+    Adapter: lib.HuaweiLearningAdapter,
+    name: "edu-huawei-learning",
+    sensitivity: "medium",
+    eventKind: "study",
+    eventSubtype: "other",
+    idKey: "huawei-learning-uid",
+    sample: { kind: "study", id: "h1", course: "物理", durationMs: 900000, startAt: 1700000000000 },
+  },
+];
+
+for (const P of PLATFORMS) {
+  describe(`${P.label} (${P.name}) — FAMILY-23 v0.1`, () => {
+    it("contract conformance + sensitivity", () => {
+      const a = new P.Adapter();
+      expect(assertAdapter(a).ok).toBe(true);
+      expect(a.name).toBe(P.name);
+      expect(a.version).toBe("0.1.0");
+      expect(a.dataDisclosure.sensitivity).toBe(P.sensitivity);
+      expect(a.capabilities).toContain("sync:snapshot");
+    });
+
+    it("sync throws NO_INPUT without inputPath", async () => {
+      const a = new P.Adapter();
+      await expect(async () => {
+        for await (const _ of a.sync({})) void _;
+      }).rejects.toThrow(/inputPath/);
+    });
+
+    it("sync via snapshot yields profile + platform event", async () => {
+      const snapPath = writeSnapshot({
+        schemaVersion: 1,
+        snapshottedAt: 1700000000000,
+        account: { uid: "12345", displayName: "kid" },
+        events: [
+          { kind: "profile", id: "profile-12345", uid: "12345", nickname: "kid" },
+          P.sample,
+        ],
+      });
+      try {
+        const a = new P.Adapter();
+        const raws = [];
+        for await (const r of a.sync({ inputPath: snapPath })) raws.push(r);
+        expect(raws).toHaveLength(2);
+        expect(raws[0].kind).toBe("profile");
+        expect(raws[1].kind).toBe(P.eventKind);
+      } finally {
+        fs.unlinkSync(snapPath);
+      }
+    });
+
+    it("normalize profile → person-self with platform uid; event → valid subtype", () => {
+      const a = new P.Adapter();
+      const profileBatch = a.normalize({
+        adapter: P.name,
+        kind: "profile",
+        originalId: `${P.name}:profile:12345`,
+        capturedAt: 1700000000000,
+        payload: { kind: "profile", uid: "12345", nickname: "kid" },
+      });
+      expect(validateBatch(profileBatch).valid).toBe(true);
+      expect(profileBatch.persons[0].subtype).toBe("self");
+      expect(profileBatch.persons[0].identifiers[P.idKey]).toEqual(["12345"]);
+
+      const eventBatch = a.normalize({
+        adapter: P.name,
+        kind: P.eventKind,
+        originalId: `${P.name}:${P.eventKind}:1`,
+        capturedAt: 1700000000000,
+        payload: P.sample,
+      });
+      expect(validateBatch(eventBatch).valid).toBe(true);
+      expect(eventBatch.events[0].subtype).toBe(P.eventSubtype);
+    });
+
+    it("normalize throws on missing payload", () => {
+      const a = new P.Adapter();
+      expect(() => a.normalize({})).toThrow(/payload missing/);
+    });
+  });
+}
+
+describe("FAMILY-23 extractUid cookie scrape", () => {
+  it("王者荣耀: openid > uin > tencent_uid", () => {
+    const c = new HonorOfKingsApiClient();
+    expect(c.extractUid("openid=oABC1234XYZ; foo=bar")).toBe("oABC1234XYZ");
+    expect(c.extractUid("uin=o0012345; x=y")).toBe("12345");
+    expect(c.extractUid("tencent_uid=678; z=1")).toBe("678");
+    expect(c.extractUid("foo=bar")).toBeNull();
+    expect(c.lastError.code).toBe(-7);
+  });
+
+  it("作业帮: uid / student_id / passport_uid (opaque ZYBUSS → null)", () => {
+    const c = new ZuoyebangApiClient();
+    expect(c.extractUid("uid=111; ZYBUSS=opaque")).toBe("111");
+    expect(c.extractUid("student_id=222")).toBe("222");
+    expect(c.extractUid("ZYBUSS=onlyopaquetoken")).toBeNull();
+  });
+
+  it("支付宝: alipay_uid / userId / loginUserId", () => {
+    const c = new AlipayApiClient();
+    expect(c.extractUid("alipay_uid=2088123; t=x")).toBe("2088123");
+    expect(c.extractUid("userId=999")).toBe("999");
+    expect(c.extractUid("ALIPAYJSESSIONID=abc")).toBeNull();
+  });
+
+  it("华为学习中心: accountId / userId / huaweiUid", () => {
+    const c = new HuaweiLearningApiClient();
+    expect(c.extractUid("accountId=555; deviceId=abc")).toBe("555");
+    expect(c.extractUid("huaweiUid=777")).toBe("777");
+    expect(c.extractUid("deviceId=nonnumeric")).toBeNull();
+  });
+});

package/__tests__/adapters/game-genshin-scaffold.test.js

@@ -0,0 +1,107 @@
+/**
+ * FAMILY-23 v0.1 — game-genshin adapter scaffold tests.
+ * 契约 + extractUid cookie scrape + snapshot sync + normalize → 合法 batch。
+ */
+import { describe, it, expect } from "vitest";
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { GenshinAdapter } = require("../../lib");
+const { GenshinApiClient } = require("../../lib/adapters/game-genshin/api-client");
+const { assertAdapter } = require("../../lib/adapter-spec");
+const { validateBatch } = require("../../lib/batch");
+
+function writeSnapshot(obj) {
+  const p = path.join(
+    os.tmpdir(),
+    `genshin-snap-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
+  );
+  fs.writeFileSync(p, JSON.stringify(obj), "utf-8");
+  return p;
+}
+
+describe("GenshinAdapter — FAMILY-23 v0.1 cookie-scrape placeholder", () => {
+  it("contract conformance + sensitivity medium", () => {
+    const a = new GenshinAdapter();
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.name).toBe("game-genshin");
+    expect(a.version).toBe("0.1.0");
+    expect(a.extractMode).toBe("web-api");
+    expect(a.dataDisclosure.sensitivity).toBe("medium");
+    expect(a.capabilities).toContain("sync:snapshot");
+  });
+
+  it("extractUid parses HoYoLAB cookie keys (priority + null)", () => {
+    const c = new GenshinApiClient();
+    expect(c.extractUid("account_id_v2=12345; ltoken_v2=abc")).toBe("12345");
+    expect(c.extractUid("ltuid_v2=67890; foo=bar")).toBe("67890");
+    expect(c.extractUid("account_id=111; x=y")).toBe("111");
+    expect(c.extractUid("ltuid=222")).toBe("222");
+    // 优先级: account_id_v2 先于 ltuid
+    expect(c.extractUid("ltuid=999; account_id_v2=12345")).toBe("12345");
+    expect(c.extractUid("foo=bar")).toBeNull();
+    expect(c.lastError.code).toBe(-7);
+    expect(c.extractUid("")).toBeNull();
+    expect(c.lastError.code).toBe(-1);
+  });
+
+  it("sync throws NO_INPUT without inputPath (v0.1 no live HTTP)", async () => {
+    const a = new GenshinAdapter();
+    await expect(async () => {
+      for await (const _ of a.sync({})) void _;
+    }).rejects.toThrow(/inputPath/);
+  });
+
+  it("sync via snapshot yields profile + play raws", async () => {
+    const snapPath = writeSnapshot({
+      schemaVersion: 1,
+      snapshottedAt: 1700000000000,
+      account: { uid: "12345", displayName: "旅行者" },
+      events: [
+        { kind: "profile", id: "profile-12345", uid: "12345", nickname: "旅行者", level: 58 },
+        { kind: "play", id: "play-s1", durationMs: 3600000, mode: "single", startAt: 1700000000000 },
+      ],
+    });
+    try {
+      const a = new GenshinAdapter();
+      const raws = [];
+      for await (const r of a.sync({ inputPath: snapPath })) raws.push(r);
+      expect(raws).toHaveLength(2);
+      expect(raws[0].kind).toBe("profile");
+      expect(raws[0].originalId).toBe("genshin:profile:profile-12345");
+      expect(raws[1].kind).toBe("play");
+    } finally {
+      fs.unlinkSync(snapPath);
+    }
+  });
+
+  it("normalize profile → person-self with genshin-uid; play → MEDIA event (valid batch)", () => {
+    const a = new GenshinAdapter();
+    const profileBatch = a.normalize({
+      adapter: "game-genshin",
+      kind: "profile",
+      originalId: "genshin:profile:profile-12345",
+      capturedAt: 1700000000000,
+      payload: { kind: "profile", uid: "12345", nickname: "旅行者", level: 58 },
+    });
+    expect(validateBatch(profileBatch).valid).toBe(true);
+    expect(profileBatch.persons[0].subtype).toBe("self");
+    expect(profileBatch.persons[0].identifiers["genshin-uid"]).toEqual(["12345"]);
+
+    const playBatch = a.normalize({
+      adapter: "game-genshin",
+      kind: "play",
+      originalId: "genshin:play:play-s1",
+      capturedAt: 1700000000000,
+      payload: { kind: "play", durationMs: 3600000, mode: "single", startAt: 1700000000000 },
+    });
+    expect(validateBatch(playBatch).valid).toBe(true);
+    expect(playBatch.events[0].subtype).toBe("media");
+    expect(playBatch.events[0].extra.durationMs).toBe(3600000);
+  });
+
+  it("normalize throws on missing payload", () => {
+    const a = new GenshinAdapter();
+    expect(() => a.normalize({})).toThrow(/payload missing/);
+  });
+});

package/__tests__/adapters/git-activity.test.js

@@ -1,11 +1,17 @@
 "use strict";
 
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
 
+// Every test here spawns real `git` (init/config/commit) across throwaway
+// repos. On Windows, under the full-suite parallel worker pool, that subprocess
+// fan-out routinely blows past the 10s default and flakes. Give the whole file
+// generous headroom — the work is real, the default timeout is just too tight.
+vi.setConfig({ testTimeout: 30000, hookTimeout: 30000 });
+
 const {
   GitActivityAdapter,
   GIT_ACTIVITY_NAME,

package/__tests__/adapters/local-im-pc.test.js

@@ -0,0 +1,149 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { DingTalkPcAdapter } = require("../../lib/adapters/dingtalk-pc");
+const { FeishuPcAdapter } = require("../../lib/adapters/feishu-pc");
+const { readLocalImDb } = require("../../lib/adapters/_local-im-db-reader");
+const { partitionBatch } = require("../../lib/batch");
+
+// fake driver answering sqlite_master + table_info + SELECT * by table
+function makeFakeDb(spec) {
+  class FakeStmt {
+    constructor(sql) {
+      this.sql = sql;
+    }
+    all() {
+      const s = this.sql;
+      if (/type='table'/.test(s)) return (spec.tables || []).map((n) => ({ name: n }));
+      const ti = s.match(/table_info\("(\w+)"\)/);
+      if (ti) return spec.cols[ti[1]] || [];
+      const fr = s.match(/FROM "(\w+)"/);
+      if (fr) return spec.rows[fr[1]] || [];
+      return [];
+    }
+    get() {
+      return { n: 1 };
+    }
+  }
+  return class FakeDb {
+    // eslint-disable-next-line no-unused-vars
+    constructor(_p, _o) {}
+    prepare(sql) {
+      return new FakeStmt(sql);
+    }
+    pragma() {}
+    exec() {}
+    close() {}
+  };
+}
+
+const SPEC = {
+  // msg_table matches + has time/content → ingested
+  // msg_meta  matches pattern but no time/content → skipped (loud diagnostic)
+  // contact_meta doesn't match pattern → not scanned
+  // sqlite_sequence → filtered (sqlite_*)
+  tables: ["msg_table", "msg_meta", "contact_meta", "sqlite_sequence"],
+  cols: {
+    msg_table: [
+      { name: "msgId" },
+      { name: "createTime" },
+      { name: "senderId" },
+      { name: "conversationId" },
+      { name: "content" },
+    ],
+    msg_meta: [{ name: "uid" }, { name: "name" }],
+    contact_meta: [{ name: "uid" }, { name: "name" }],
+  },
+  rows: {
+    msg_table: [
+      { msgId: "m1", createTime: 1700000000, senderId: "u1", conversationId: "c1", content: "开会通知" },
+      { msgId: "m2", createTime: 1700000010, senderId: "u2", conversationId: "c1", content: "收到" },
+    ],
+  },
+};
+
+// opaque schema — time resolves, but body is a BLOB → text null, raw kept
+const OPAQUE_SPEC = {
+  tables: ["chat_msg"],
+  cols: { chat_msg: [{ name: "id" }, { name: "timestamp" }, { name: "body" }] },
+  rows: { chat_msg: [{ id: 7, timestamp: 1700000000, body: Buffer.from([1, 2]) }] },
+};
+
+function adapter(Cls, spec, { exists = true } = {}) {
+  const a = new Cls({ dbPath: "/fake.db" });
+  a._deps.fs = { existsSync: () => exists, accessSync: () => {}, constants: { R_OK: 4 } };
+  a._deps.dbDriverFactory = () => makeFakeDb(spec);
+  return a;
+}
+
+async function collect(iter) {
+  const out = [];
+  for await (const r of iter) out.push(r);
+  return out;
+}
+
+describe("readLocalImDb (generic honest reader)", () => {
+  it("discovers message tables, skips metadata + sqlite_*", () => {
+    const { messages, diagnostic } = readLocalImDb("/x", { _databaseClass: makeFakeDb(SPEC) });
+    expect(diagnostic.messageTables).toEqual(["msg_table"]);
+    expect(diagnostic.skippedTables).toEqual(["msg_meta"]);
+    expect(messages).toHaveLength(2);
+    expect(messages[0].text).toBe("开会通知");
+    expect(messages[0].createdTimeMs).toBe(1700000000000);
+  });
+
+  it("opaque body → text null but rawRow preserved + loud diagnostic", () => {
+    const { messages, diagnostic } = readLocalImDb("/x", { _databaseClass: makeFakeDb(OPAQUE_SPEC) });
+    expect(messages).toHaveLength(1);
+    expect(messages[0].text).toBeNull();
+    expect(messages[0].rawRow).toBeTruthy();
+    expect(diagnostic.textCount).toBe(0);
+    expect(diagnostic.messageTables).toEqual(["chat_msg"]);
+  });
+});
+
+describe.each([
+  ["DingTalkPcAdapter", DingTalkPcAdapter, "dingtalk"],
+  ["FeishuPcAdapter", FeishuPcAdapter, "feishu"],
+])("%s (honest best-effort)", (_label, Cls, platform) => {
+  it("no-arg construct + DB_NOT_PULLED readiness + legalGate", async () => {
+    const a = new Cls();
+    expect(a.extractMode).toBe("device-pull");
+    expect(a.dataDisclosure.legalGate).toBe(true);
+    const r = await a.authenticate({ readinessOnly: true });
+    expect(r.reason).toBe("DB_NOT_PULLED");
+  });
+
+  it("reads messages → valid events, platform tag, raw preserved", async () => {
+    const a = adapter(Cls, SPEC);
+    const raws = await collect(a.sync({ dbPath: "/fake.db" }));
+    expect(raws).toHaveLength(2);
+    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);
+    expect(valid.events[0].extra.platform).toBe(platform);
+    expect(valid.events[0].extra.textResolved).toBe(true);
+    expect(valid.events[0].extra.rawRow).toBeTruthy();
+  });
+
+  it("emits local-im-read progress diagnostic", async () => {
+    const a = adapter(Cls, SPEC);
+    const ev = [];
+    await collect(a.sync({ dbPath: "/fake.db", onProgress: (e) => ev.push(e) }));
+    const d = ev.find((e) => e.phase === "local-im-read");
+    expect(d.messageTables).toContain("msg_table");
+    expect(d.messageCount).toBe(2);
+  });
+
+  it("missing db yields nothing; unknown kind throws", async () => {
+    const a = adapter(Cls, SPEC, { exists: false });
+    expect(await collect(a.sync({ dbPath: "/no.db" }))).toHaveLength(0);
+    expect(() => new Cls().normalize({ kind: "x", payload: { kind: "x" } })).toThrow(/unknown kind/);
+  });
+});