@chainlesschain/personal-data-hub 0.3.9 → 0.4.1

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/);
+  });
+});

package/__tests__/adapters/netease-music.test.js

@@ -0,0 +1,74 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { NeteaseMusicAdapter } = require("../../lib/adapters/netease-music");
+const { partitionBatch } = require("../../lib/batch");
+
+const SNAPSHOT = {
+  schemaVersion: 1,
+  snapshottedAt: 1700000000000,
+  account: { uid: "42", nickname: "me" },
+  events: [
+    { kind: "play", id: "p1", capturedAt: 1700000001000, song: "晴天", artist: "周杰伦", album: "叶惠美", songId: "186016", playCount: 50 },
+    { kind: "favorite", id: "f1", capturedAt: 1700000002000, song: "稻香", artist: "周杰伦", songId: "186001" },
+    { kind: "playlist", id: "pl1", capturedAt: 1700000003000, name: "我喜欢的音乐", playlistId: "999", trackCount: 200, creator: "me" },
+    { kind: "bogus", id: "x" },
+  ],
+};
+
+function adapter(snap = SNAPSHOT, { exists = true } = {}) {
+  const a = new NeteaseMusicAdapter();
+  a._deps.fs = {
+    existsSync: () => exists,
+    readFileSync: () => JSON.stringify(snap),
+    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("NeteaseMusicAdapter", () => {
+  it("readinessOnly → NO_INPUT (snapshot)", async () => {
+    const r = await new NeteaseMusicAdapter().authenticate({ readinessOnly: true });
+    expect(r.reason).toBe("NO_INPUT");
+  });
+
+  it("ingests play/favorite/playlist, skips unknown kinds", async () => {
+    const raws = await collect(adapter().sync({ inputPath: "/x" }));
+    expect(raws.map((r) => r.kind)).toEqual(["play", "favorite", "playlist"]);
+  });
+
+  it("normalizes to valid batch (events + items + topic)", async () => {
+    const a = adapter();
+    const raws = await collect(a.sync({ inputPath: "/x" }));
+    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); // play + favorite
+    expect(valid.items).toHaveLength(2); // two songs
+    expect(valid.topics).toHaveLength(1); // playlist
+    const play = valid.events.find((e) => e.subtype === "media");
+    expect(play.content.title).toContain("晴天");
+    expect(valid.topics[0].name).toBe("我喜欢的音乐");
+  });
+
+  it("schemaVersion mismatch throws", async () => {
+    const a = adapter({ schemaVersion: 99, events: [] });
+    await expect(collect(a.sync({ inputPath: "/x" }))).rejects.toThrow(/schemaVersion/);
+  });
+
+  it("missing file yields nothing", async () => {
+    expect(await collect(adapter(SNAPSHOT, { exists: false }).sync({ inputPath: "/x" }))).toHaveLength(0);
+  });
+});

package/__tests__/adapters/qq-pc-direct-read.test.js

@@ -0,0 +1,186 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { QQPcAdapter } = require("../../lib/adapters/qq-pc");
+const { partitionBatch } = require("../../lib/batch");
+
+/**
+ * QQ NT (PC desktop) local-direct-read — 本地直读样板 (ported from wechat-pc).
+ *
+ * No native SQLite: fake driver via `_deps.dbDriverFactory`. The point of
+ * these tests is the PLUMBING + honest defensiveness (resolve columns,
+ * preserve raw row, loud diagnostic, best-effort text) — not protobuf
+ * decoding, which is real-device tuning.
+ */
+
+function makeFakeDb(spec) {
+  class FakeStmt {
+    constructor(sql) {
+      this.sql = sql;
+    }
+    all() {
+      const s = this.sql;
+      const m = s.match(/PRAGMA table_info\((\w+)\)/);
+      if (m) return spec.cols[m[1]] || [];
+      const f = s.match(/FROM (\w+)/);
+      if (f) return spec.rows[f[1]] || [];
+      return [];
+    }
+    get() {
+      return { n: 1 };
+    }
+  }
+  return class FakeDb {
+    // eslint-disable-next-line no-unused-vars
+    constructor(_path, _opts) {}
+    prepare(sql) {
+      return new FakeStmt(sql);
+    }
+    pragma() {}
+    exec() {}
+    close() {}
+  };
+}
+
+// readable-name schema (decrypted/re-exported db) — text resolves cleanly
+const READABLE_SPEC = {
+  cols: {
+    c2c_msg_table: [
+      { name: "msgId" },
+      { name: "msgTime" },
+      { name: "msgType" },
+      { name: "senderUin" },
+      { name: "peerUin" },
+      { name: "content" },
+    ],
+    group_msg_table: [
+      { name: "msgId" },
+      { name: "msgTime" },
+      { name: "senderUin" },
+      { name: "peerUin" },
+      { name: "content" },
+    ],
+  },
+  rows: {
+    c2c_msg_table: [
+      { msgId: "c1", msgTime: 1700000000, msgType: 1, senderUin: "111", peerUin: "222", content: "hi there" },
+    ],
+    group_msg_table: [
+      { msgId: "g1", msgTime: 1700000100, senderUin: "333", peerUin: "9001", content: "群里大家好" },
+    ],
+  },
+};
+
+// obfuscated numeric schema + BLOB content — text is null but raw preserved
+const NUMERIC_SPEC = {
+  cols: {
+    c2c_msg_table: [
+      { name: "40001" }, // msgId
+      { name: "40050" }, // time
+      { name: "40011" }, // type
+      { name: "40033" }, // sender
+      { name: "40021" }, // peer
+      { name: "40800" }, // content (blob)
+    ],
+  },
+  rows: {
+    c2c_msg_table: [
+      { "40001": 9001, "40050": 1700000000, "40011": 1, "40033": 111, "40021": 222, "40800": Buffer.from([1, 2, 3]) },
+    ],
+  },
+};
+
+function freshAdapter(spec, { fsOverride } = {}) {
+  const a = new QQPcAdapter({ dbPath: "/fake/nt_msg.db" });
+  a._deps.fs = fsOverride || { existsSync: () => true, 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("QQPcAdapter — readiness + construction", () => {
+  it("no-arg construct + DB_NOT_PULLED readiness", async () => {
+    const a = new QQPcAdapter();
+    expect(a.name).toBe("qq-pc");
+    expect(a.dataDisclosure.legalGate).toBe(true);
+    const r = await a.authenticate({ readinessOnly: true });
+    expect(r.reason).toBe("DB_NOT_PULLED");
+  });
+});
+
+describe("QQPcAdapter — nt_msg.db (readable schema)", () => {
+  it("reads c2c + group messages → valid events, 0 invalid", async () => {
+    const a = freshAdapter(READABLE_SPEC);
+    const raws = await collect(a.sync({ dbPath: "/fake/nt_msg.db" }));
+    expect(raws).toHaveLength(2);
+    expect(raws.every((r) => r.kind === "message")).toBe(true);
+    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);
+  });
+
+  it("resolves text + flags group + preserves timestamp", async () => {
+    const a = freshAdapter(READABLE_SPEC);
+    const raws = await collect(a.sync({ dbPath: "/fake/nt_msg.db" }));
+    const group = raws.find((r) => r.payload.isGroup);
+    expect(group.payload.text).toBe("群里大家好");
+    expect(group.payload.createdTimeMs).toBe(1700000100000);
+    const ev = a.normalize(group).events[0];
+    expect(ev.extra.isGroup).toBe(true);
+    expect(ev.extra.textResolved).toBe(true);
+  });
+});
+
+describe("QQPcAdapter — nt_msg.db (numeric/obfuscated + BLOB body)", () => {
+  it("still ingests, text null, raw row preserved, loud diagnostic", async () => {
+    const a = freshAdapter(NUMERIC_SPEC);
+    const events = [];
+    const raws = await collect(
+      a.sync({ dbPath: "/fake/nt_msg.db", onProgress: (e) => events.push(e) }),
+    );
+    expect(raws).toHaveLength(1);
+    const ev = a.normalize(raws[0]).events[0];
+    // No silent drop: it's a valid event even with unresolved protobuf text.
+    const { valid, invalidReasons } = partitionBatch({
+      events: [ev], persons: [], places: [], items: [], topics: [],
+    });
+    expect(invalidReasons).toHaveLength(0);
+    expect(valid.events).toHaveLength(1);
+    expect(ev.extra.textResolved).toBe(false);
+    expect(ev.extra.rawRow).toBeTruthy(); // nothing lost
+    // diagnostic tells the user what resolved
+    const diag = events.find((e) => e.phase === "qq-nt-read");
+    expect(diag.hadC2cTable).toBe(true);
+    expect(diag.messageCount).toBe(1);
+    expect(diag.resolvedColumns.c2c_msg_table.time).toBe("40050");
+  });
+});
+
+describe("QQPcAdapter — edge cases", () => {
+  it("respects limit", async () => {
+    const a = freshAdapter(READABLE_SPEC);
+    const capped = await collect(a.sync({ dbPath: "/fake/nt_msg.db", limit: 1 }));
+    expect(capped).toHaveLength(1);
+  });
+
+  it("missing db yields nothing", async () => {
+    const a = freshAdapter(READABLE_SPEC, { fsOverride: { existsSync: () => false } });
+    expect(await collect(a.sync({ dbPath: "/nope.db" }))).toHaveLength(0);
+  });
+
+  it("unknown normalize kind throws", () => {
+    const a = new QQPcAdapter();
+    expect(() => a.normalize({ kind: "x", payload: { kind: "x" } })).toThrow(/unknown kind/);
+  });
+});

package/__tests__/adapters/system-data-adapter.test.js

@@ -350,7 +350,10 @@ describe("SystemDataAdapter.sync ADB pull flow", () => {
     });
     const adapter = new SystemDataAdapter({ supervisor: sup });
 
-    const iter = adapter.sync({ serial: "redmi", scratchDir: "/scratch" });
+    // No scratchDir → adapter defaults to fs.mkdtempSync(os.tmpdir()). Don't pass
+    // an absolute "/scratch": it mkdir's at FS root, which is EACCES on Linux CI
+    // (passed on Windows where /scratch maps to a creatable drive-relative path).
+    const iter = adapter.sync({ serial: "redmi" });
     for await (const _ of iter) { /* drain */ }
 
     expect(pullCalls).toEqual([

package/__tests__/adapters/wechat-pc-direct-read.test.js

@@ -0,0 +1,207 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { WeChatPcAdapter } = require("../../lib/adapters/wechat-pc");
+const { partitionBatch } = require("../../lib/batch");
+
+/**
+ * WeChat **PC desktop** local-direct-read (本地直读样板, ported from Douyin).
+ *
+ * No native SQLite: a fake Database driver is injected via
+ * `_deps.dbDriverFactory` (pc-db-reader accepts it as `_databaseClass`).
+ * Covers the message/contact normalize + the MSG / Contact table read +
+ * group-message sender-prefix parsing + key-vs-plaintext routing.
+ */
+
+// Fake better-sqlite3-style driver answering pc-db-reader's PRAGMA + SELECTs.
+function makeFakeDb(spec) {
+  class FakeStmt {
+    constructor(sql) {
+      this.sql = sql;
+    }
+    all() {
+      const s = this.sql;
+      if (/PRAGMA table_info\(MSG\)/.test(s)) return spec.msgCols || [];
+      if (/FROM MSG/.test(s)) return spec.msgRows || [];
+      if (/PRAGMA table_info\(Contact\)/.test(s)) return spec.contactCols || [];
+      if (/FROM Contact/.test(s)) return spec.contactRows || [];
+      return [];
+    }
+    get() {
+      return { n: 1 }; // sqlite_master probe
+    }
+  }
+  return class FakeDb {
+    // eslint-disable-next-line no-unused-vars
+    constructor(_path, _opts) {}
+    prepare(sql) {
+      return new FakeStmt(sql);
+    }
+    pragma() {}
+    exec() {}
+    close() {}
+  };
+}
+
+const MSG_SPEC = {
+  msgCols: [
+    { name: "MsgSvrID" },
+    { name: "StrTalker" },
+    { name: "IsSender" },
+    { name: "CreateTime" },
+    { name: "Type" },
+    { name: "StrContent" },
+  ],
+  msgRows: [
+    { msgSvrId: "700001", talker: "wxid_bob", isSend: 0, createTime: 1700000000, type: 1, content: "你好啊" },
+    { msgSvrId: "700002", talker: "wxid_bob", isSend: 1, createTime: 1700000010, type: 1, content: "在的" },
+    { msgSvrId: "700003", talker: "room1@chatroom", isSend: 0, createTime: 1700000020, type: 1, content: "wxid_carol:\n大家好" },
+  ],
+};
+
+const CONTACT_SPEC = {
+  contactCols: [
+    { name: "UserName" },
+    { name: "Alias" },
+    { name: "NickName" },
+    { name: "Remark" },
+    { name: "Type" },
+  ],
+  contactRows: [
+    { wxid: "wxid_bob", alias: "bob123", nickname: "Bob", remark: "老鲍", type: 3 },
+    { wxid: "gh_official01", alias: null, nickname: "某公众号", remark: null, type: 3 },
+    { wxid: "room1@chatroom", alias: null, nickname: "群", remark: null, type: 2 }, // filtered
+  ],
+};
+
+function freshAdapter(spec, { fsOverride } = {}) {
+  const a = new WeChatPcAdapter({ dbPath: "/fake/MSG0.db" });
+  a._deps.fs = fsOverride || { existsSync: () => true, 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("WeChatPcAdapter — readiness + construction", () => {
+  it("constructs no-arg and reports DB_NOT_PULLED via readinessOnly", async () => {
+    const a = new WeChatPcAdapter();
+    expect(a.name).toBe("wechat-pc");
+    expect(a.extractMode).toBe("device-pull");
+    expect(a.dataDisclosure.legalGate).toBe(true);
+    const r = await a.authenticate({ readinessOnly: true });
+    expect(r.ok).toBe(false);
+    expect(r.reason).toBe("DB_NOT_PULLED");
+  });
+
+  it("readinessOnly with a configured dbPath reports configured (no DB open)", async () => {
+    const a = new WeChatPcAdapter({ dbPath: "/some/MSG0.db" });
+    const r = await a.authenticate({ readinessOnly: true });
+    expect(r.ok).toBe(true);
+    expect(r.mode).toBe("configured");
+  });
+});
+
+describe("WeChatPcAdapter — MSG*.db messages", () => {
+  it("reads MSG rows → message raws with stable ids", async () => {
+    const a = freshAdapter(MSG_SPEC);
+    const raws = await collect(a.sync({ dbPath: "/fake/MSG0.db" }));
+    expect(raws.map((r) => r.kind)).toEqual(["message", "message", "message"]);
+    expect(raws.map((r) => r.originalId)).toEqual([
+      "wechat-pc:message:700001",
+      "wechat-pc:message:700002",
+      "wechat-pc:message:700003",
+    ]);
+  });
+
+  it("messages normalize to valid events (+ contact persons + group topic), 0 invalid", async () => {
+    const a = freshAdapter(MSG_SPEC);
+    const raws = await collect(a.sync({ dbPath: "/fake/MSG0.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(3);
+    // bob (1-on-1) + carol (group sender)
+    const personIds = valid.persons.map((p) => p.id).sort();
+    expect(personIds).toContain("person-wechat-wxid_bob");
+    expect(personIds).toContain("person-wechat-wxid_carol");
+    // the chatroom becomes a topic
+    expect(valid.topics.map((t) => t.id)).toContain("topic-wechat-group-room1@chatroom");
+  });
+
+  it("strips the group-message sender prefix from the text", async () => {
+    const a = freshAdapter(MSG_SPEC);
+    const raws = await collect(a.sync({ dbPath: "/fake/MSG0.db" }));
+    const groupRaw = raws.find((r) => r.payload.talker === "room1@chatroom");
+    expect(groupRaw.payload.senderWxid).toBe("wxid_carol");
+    expect(groupRaw.payload.text).toBe("大家好");
+    const ev = a.normalize(groupRaw).events[0];
+    expect(ev.content.text).toBe("大家好");
+    expect(ev.extra.isGroup).toBe(true);
+    expect(ev.actor).toBe("person-wechat-wxid_carol");
+  });
+
+  it("CreateTime (seconds) normalizes to ms", async () => {
+    const a = freshAdapter(MSG_SPEC);
+    const raws = await collect(a.sync({ dbPath: "/fake/MSG0.db" }));
+    expect(raws[0].payload.createdTimeMs).toBe(1700000000000);
+  });
+});
+
+describe("WeChatPcAdapter — MicroMsg.db contacts", () => {
+  it("reads Contact rows → contact persons; skips @chatroom; gh_ → merchant", async () => {
+    const a = freshAdapter(CONTACT_SPEC);
+    const raws = await collect(a.sync({ dbPath: "/fake/MicroMsg.db" }));
+    expect(raws.map((r) => r.kind)).toEqual(["contact", "contact"]); // chatroom filtered
+    const persons = raws.map((r) => a.normalize(r).persons[0]);
+    const bob = persons.find((p) => p.id === "person-wechat-wxid_bob");
+    expect(bob.subtype).toBe("contact");
+    expect(bob.names[0]).toBe("老鲍"); // remark wins
+    expect(bob.identifiers.wechatId).toBe("wxid_bob");
+    const gh = persons.find((p) => p.id === "person-wechat-gh_official01");
+    expect(gh.subtype).toBe("merchant");
+  });
+});
+
+describe("WeChatPcAdapter — options + edge cases", () => {
+  it("respects include={message:false} and limit", async () => {
+    const a = freshAdapter(MSG_SPEC);
+    const none = await collect(a.sync({ dbPath: "/fake/MSG0.db", include: { message: false } }));
+    expect(none).toHaveLength(0);
+    const capped = await collect(a.sync({ dbPath: "/fake/MSG0.db", limit: 2 }));
+    expect(capped).toHaveLength(2);
+  });
+
+  it("emits a pc-db-read progress event with the diagnostic", async () => {
+    const a = freshAdapter(MSG_SPEC);
+    const events = [];
+    await collect(a.sync({ dbPath: "/fake/MSG0.db", onProgress: (e) => events.push(e) }));
+    const parsed = events.find((e) => e.phase === "pc-db-read");
+    expect(parsed).toBeTruthy();
+    expect(parsed.hadMsgTable).toBe(true);
+    expect(parsed.messageCount).toBe(3);
+    expect(parsed.mode).toBe("plaintext"); // no key supplied
+  });
+
+  it("missing db file yields nothing (no throw)", async () => {
+    const a = freshAdapter(MSG_SPEC, { fsOverride: { existsSync: () => false } });
+    const raws = await collect(a.sync({ dbPath: "/nope/MSG0.db" }));
+    expect(raws).toHaveLength(0);
+  });
+
+  it("unknown normalize kind throws", () => {
+    const a = new WeChatPcAdapter();
+    expect(() => a.normalize({ kind: "weird", payload: { kind: "weird" } })).toThrow(
+      /unknown kind/,
+    );
+  });
+});