@chainlesschain/personal-data-hub 0.4.25 → 0.4.27

package/__tests__/analysis-skills.test.js

@@ -14,6 +14,7 @@ const {
   FootprintSkill,
   InterestsSkill,
   TimelineSkill,
+  OverviewSkill,
   runAnalysisSkill,
   ANALYSIS_SKILL_NAMES,
 } = require("../lib/analysis-skills");
@@ -105,13 +106,14 @@ describe("AnalysisSkill base", () => {
     expect(skill.resolveTimeWindow({}).since).toBeNull();
   });
 
-  it("ANALYSIS_SKILL_NAMES lists exactly 5", () => {
-    expect(ANALYSIS_SKILL_NAMES).toHaveLength(5);
+  it("ANALYSIS_SKILL_NAMES lists exactly 6", () => {
+    expect(ANALYSIS_SKILL_NAMES).toHaveLength(6);
     expect(ANALYSIS_SKILL_NAMES).toContain("analysis.spending");
     expect(ANALYSIS_SKILL_NAMES).toContain("analysis.relations");
     expect(ANALYSIS_SKILL_NAMES).toContain("analysis.footprint");
     expect(ANALYSIS_SKILL_NAMES).toContain("analysis.interests");
     expect(ANALYSIS_SKILL_NAMES).toContain("analysis.timeline");
+    expect(ANALYSIS_SKILL_NAMES).toContain("analysis.overview");
   });
 
   it("base.run() throws (subclasses must override)", async () => {
@@ -554,3 +556,70 @@ describe("runAnalysisSkill", () => {
     await expect(runAnalysisSkill({}, "analysis.spending", {})).rejects.toThrow(/vault/);
   });
 });
+
+// ─── OverviewSkill (cross-app de-silo aggregation) ──────────────────────
+describe("OverviewSkill — cross-app unified snapshot", () => {
+  let rig;
+  beforeEach(() => { rig = makeVault(); });
+  afterEach(() => cleanup(rig));
+
+  function makeMsg(vault, opts) {
+    vault.putEvent({
+      id: opts.id, type: "event", subtype: opts.subtype || "message",
+      occurredAt: opts.occurredAt, actor: opts.actor || "person-self",
+      participants: opts.participants || [],
+      content: { title: opts.title || "msg" },
+      ingestedAt: Date.now(), source: defaultSource(opts.adapter || "test"),
+    });
+  }
+
+  it("aggregates events/spend/contacts across multiple apps", async () => {
+    const { vault } = rig;
+    makePerson(vault, "p-friend", ["小明"], {}, { adapter: "wechat" });
+    // payments from 2 finance/shopping apps
+    makePayment(vault, { id: "e1", amount: 30, occurredAt: ts(2026, 5, 1), adapter: "alipay-bill", subtype: "payment" });
+    makePayment(vault, { id: "e2", amount: 70, occurredAt: ts(2026, 5, 2), adapter: "shopping-taobao", subtype: "order" });
+    // messages from 2 social/im apps, same friend
+    makeMsg(vault, { id: "e3", occurredAt: ts(2026, 5, 3), adapter: "wechat", participants: ["p-friend"] });
+    makeMsg(vault, { id: "e4", occurredAt: ts(2026, 5, 4), adapter: "social-douyin", participants: ["p-friend"] });
+    makeMsg(vault, { id: "e5", occurredAt: ts(2026, 6, 1), adapter: "social-douyin", subtype: "post", participants: [] });
+
+    const skill = new OverviewSkill({ vault });
+    const r = await skill.run({ commentary: false });
+
+    expect(r.summary.totalEvents).toBe(5);
+    expect(r.summary.appsActive).toBe(4); // alipay-bill, shopping-taobao, wechat, social-douyin
+  });
+
+  it("counts 4 distinct apps + sums cross-app spend + top contact merged", async () => {
+    const { vault } = rig;
+    makePerson(vault, "p-friend", ["小明"], {}, { adapter: "wechat" });
+    makePayment(vault, { id: "a", amount: 30, occurredAt: ts(2026, 5, 1), adapter: "alipay-bill", subtype: "payment" });
+    makePayment(vault, { id: "b", amount: 70, occurredAt: ts(2026, 5, 2), adapter: "shopping-taobao", subtype: "order" });
+    makeMsg(vault, { id: "c", occurredAt: ts(2026, 5, 3), adapter: "wechat", participants: ["p-friend"] });
+    makeMsg(vault, { id: "d", occurredAt: ts(2026, 5, 4), adapter: "social-douyin", participants: ["p-friend"] });
+
+    const r = await new OverviewSkill({ vault }).run({ commentary: false });
+    const apps = r.byApp.map((x) => x.app).sort();
+    expect(apps).toContain("wechat");
+    expect(apps).toContain("social-douyin");
+    expect(apps).toContain("alipay-bill");
+    expect(apps).toContain("shopping-taobao");
+    expect(r.summary.appsActive).toBe(4);
+    expect(r.spending.total).toBe(100); // 30 + 70 across two apps
+    // the friend appears in wechat + douyin → one merged top contact w/ byApp breakdown
+    const friend = r.topContacts.find((c) => c.personId === "p-friend");
+    expect(friend).toBeTruthy();
+    expect(friend.interactions).toBe(2);
+    expect(Object.keys(friend.byApp).sort()).toEqual(["social-douyin", "wechat"]);
+    // byType has payment/order/message
+    const types = r.byType.map((t) => t.type);
+    expect(types).toContain("message");
+  });
+
+  it("is registered + runnable via runAnalysisSkill", async () => {
+    expect(ANALYSIS_SKILL_NAMES).toContain("analysis.overview");
+    const r = await runAnalysisSkill({ vault: rig.vault }, "analysis.overview", { commentary: false });
+    expect(r.skill).toBe("analysis.overview");
+  });
+});

package/__tests__/analysis.test.js

@@ -1797,3 +1797,49 @@ describe("AnalysisEngine._gatherFacts intent=count routing", () => {
     expect(r.facts.filter((f) => f.type === "item").length).toBe(3);
   });
 });
+
+// ─── ① cross-app overview injected into ask() prompt (decision grounding) ──
+describe("AnalysisEngine.ask crossApp overview context", () => {
+  function seedMultiApp(vault) {
+    vault.putPerson({
+      id: "person-friend", type: "person", subtype: "contact",
+      names: ["小明"], identifiers: {}, ingestedAt: Date.now(), source: source("wechat-pc"),
+    });
+    vault.putEvent({
+      id: newId(), type: "event", subtype: "order", occurredAt: ts(2026, 3, 10),
+      actor: "person-self",
+      content: { title: "鞋", amount: { value: 200, currency: "CNY", direction: "out" } },
+      ingestedAt: Date.now(), source: source("shopping-taobao", "o1"),
+    });
+    vault.putEvent({
+      id: newId(), type: "event", subtype: "message", occurredAt: ts(2026, 3, 11),
+      actor: "person-self", participants: ["person-friend"],
+      content: { title: "hi", text: "hi" },
+      ingestedAt: Date.now(), source: source("wechat-pc", "m1"),
+    });
+  }
+
+  it("injects CROSS_APP_OVERVIEW block when crossApp:true", async () => {
+    freshVault();
+    seedMultiApp(vault);
+    const llm = new MockLLMClient({ reply: "建议：…" });
+    const engine = new AnalysisEngine({ vault, llm });
+    await engine.ask("综合我各 app 的数据，我最近重心在哪？", { crossApp: true });
+    const userMsg = llm.calls[0].messages.find((m) => m.role === "user").content;
+    expect(userMsg).toContain("CROSS_APP_OVERVIEW");
+    expect(userMsg).toContain("活跃 app");
+    // both apps surface in the cross-app aggregation
+    expect(userMsg).toMatch(/shopping-taobao|wechat-pc/);
+    expect(userMsg).toContain("跨 app 消费合计");
+  });
+
+  it("omits CROSS_APP_OVERVIEW when crossApp not set", async () => {
+    freshVault();
+    seedMultiApp(vault);
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault, llm });
+    await engine.ask("随便问问", {});
+    const userMsg = llm.calls[0].messages.find((m) => m.role === "user").content;
+    expect(userMsg).not.toContain("CROSS_APP_OVERVIEW");
+  });
+});

package/__tests__/salvage-ingest.test.js

@@ -0,0 +1,97 @@
+"use strict";
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+const { LocalVault } = require("../lib/vault");
+const { generateKeyHex } = require("../lib/key-providers");
+const {
+  buildSalvageEvents,
+  salvageDumpToVault,
+  resolveApp,
+} = require("../lib/forensics/salvage-ingest");
+
+// Build a real SQLite DB and treat its bytes as a memory dump; verify the
+// generic salvage→vault path recovers messages AND tags them with the correct
+// per-app source.adapter (multi-app de-silo). Real LocalVault → proves the
+// hand-built events pass schema validation + are searchable.
+describe("salvage-ingest — generic multi-app salvage → vault", () => {
+  let dir, dumpPath, vault, vdir;
+  const COLUMNS = ["msg_uuid", "conversation_id", "sender", "content", "created_time"];
+
+  beforeAll(() => {
+    const Database = require("better-sqlite3-multiple-ciphers");
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "salvage-ing-"));
+    dumpPath = path.join(dir, "u.db");
+    const db = new Database(dumpPath);
+    db.exec("CREATE TABLE msg(msg_uuid TEXT, conversation_id TEXT, sender INTEGER, content TEXT, created_time INTEGER)");
+    const ins = db.prepare("INSERT INTO msg VALUES(?,?,?,?,?)");
+    ins.run("u1", "conv-1", 111, "今天的会议改到下午三点 hi", 1700000000000);
+    ins.run("u2", "conv-1", 222, "收到 👌", 1700000001000);
+    db.close();
+
+    vdir = fs.mkdtempSync(path.join(os.tmpdir(), "salvage-vault-"));
+    vault = new LocalVault({ path: path.join(vdir, "v.db"), key: generateKeyHex() });
+    vault.open();
+  });
+
+  afterAll(() => {
+    try { vault.close(); } catch (_e) {}
+    try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_e) {}
+    try { fs.rmSync(vdir, { recursive: true, force: true }); } catch (_e) {}
+  });
+
+  it("resolveApp maps known apps to canonical source adapters; unknown → salvage:<app>", () => {
+    expect(resolveApp("douyin").sourceAdapter).toBe("social-douyin");
+    expect(resolveApp("toutiao").sourceAdapter).toBe("social-toutiao");
+    expect(resolveApp("wechat").sourceAdapter).toBe("wechat");
+    expect(resolveApp("kuaishou").sourceAdapter).toBe("social-kuaishou");
+    expect(resolveApp("bogusapp").sourceAdapter).toBe("salvage:bogusapp");
+  });
+
+  it("buildSalvageEvents tags per-app source + builds valid message events", () => {
+    const recs = [{ rowid: "1", cols: ["u1", "conv-1", 111, "hello 世界", 1700000000000] }];
+    const built = buildSalvageEvents(recs, { app: "toutiao", columns: COLUMNS, now: 1700000099000 });
+    expect(built.events.length).toBe(1);
+    const e = built.events[0];
+    expect(e.source.adapter).toBe("social-toutiao");
+    expect(e.source.capturedBy).toBe("sqlite"); // schema enum; provenance in extra.salvaged
+    expect(e.subtype).toBe("message");
+    expect(e.content.text).toBe("hello 世界");
+    expect(e.extra.platform).toBe("toutiao");
+    expect(e.extra.salvaged).toBe(true);
+  });
+
+  it("salvageDumpToVault ingests with douyin source + events are searchable", () => {
+    const r = salvageDumpToVault(vault, dumpPath, { app: "douyin", columns: COLUMNS, now: 1700000099000 });
+    expect(r.app).toBe("douyin");
+    expect(r.sourceAdapter).toBe("social-douyin");
+    expect(r.ingested).toBe(2);
+    // events landed under the correct source + are searchable
+    const events = vault.queryEvents({ limit: 100 }) || [];
+    const douyin = events.filter((e) => e.source && e.source.adapter === "social-douyin");
+    expect(douyin.length).toBe(2);
+    const texts = douyin.map((e) => e.content && e.content.text).sort();
+    expect(texts).toContain("收到 👌"); // UTF-8 emoji survives
+  });
+
+  it("same dump under a different app tags a different source (no cross-attribution)", () => {
+    const r = salvageDumpToVault(vault, dumpPath, { app: "toutiao", columns: COLUMNS, now: 1700000099000 });
+    expect(r.sourceAdapter).toBe("social-toutiao");
+    expect(r.ingested).toBe(2);
+    const events = vault.queryEvents({ limit: 100 }) || [];
+    expect(events.filter((e) => e.source && e.source.adapter === "social-toutiao").length).toBe(2);
+    // douyin events from prior test remain distinct
+    expect(events.filter((e) => e.source && e.source.adapter === "social-douyin").length).toBe(2);
+  });
+
+  it("re-ingesting the same dump dedups (stable originalId)", () => {
+    const before = (vault.queryEvents({ limit: 200 }) || []).length;
+    salvageDumpToVault(vault, dumpPath, { app: "douyin", columns: COLUMNS, now: 1700000099000 });
+    const after = (vault.queryEvents({ limit: 200 }) || []).length;
+    expect(after).toBe(before); // ON CONFLICT(source_adapter, source_original_id) updates, no dupes
+  });
+});

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

@@ -31,7 +31,7 @@ const { partitionBatch } = require("../lib/batch");
  */
 
 // Fake better-sqlite3-style driver answering the parser's PRAGMA + SELECTs.
-function makeFakeDb({ msgRows, userRows, msgCols, userCols }) {
+function makeFakeDb({ msgRows, userRows, msgCols, userCols, partCols, partRows, convCols, convRows }) {
   class FakeStmt {
     constructor(sql) {
       this.sql = sql;
@@ -40,8 +40,12 @@ function makeFakeDb({ msgRows, userRows, msgCols, userCols }) {
       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;
+      if (/PRAGMA table_info\(SIMPLE_USER\)/.test(s)) return userCols || [];
+      if (/FROM SIMPLE_USER/.test(s)) return userRows || [];
+      if (/PRAGMA table_info\(participant\)/.test(s)) return partCols || [];
+      if (/FROM participant/.test(s)) return partRows || [];
+      if (/PRAGMA table_info\(conversation_list\)/.test(s)) return convCols || [];
+      if (/FROM conversation_list/.test(s)) return convRows || [];
       return [];
     }
   }
@@ -261,6 +265,68 @@ describe("DouyinAdapter — 本地直读 <uid>_im.db", () => {
     const raws = await collect(a.sync({ imDbPath: "/does/not/exist_im.db" }));
     expect(raws).toHaveLength(0);
   });
+
+  // device-verified 2026-06-16: real Douyin IM schema uses `participant`
+  // (conversation_id, user_id), not SIMPLE_USER → contacts must come from it.
+  it("extracts contacts from `participant` when SIMPLE_USER absent (real schema)", async () => {
+    const spec = {
+      msgCols: DEFAULT_FAKE.msgCols,
+      msgRows: DEFAULT_FAKE.msgRows,
+      userCols: [], // no SIMPLE_USER table on a real device
+      userRows: [],
+      partCols: [{ name: "conversation_id" }, { name: "user_id" }, { name: "sort_order" }],
+      partRows: [{ uid: 111 }, { uid: 222 }, { uid: 222 }], // dup 222 → deduped
+    };
+    const a = freshAdapter(spec);
+    const raws = await collect(a.sync({ imDbPath: "/fake/123_im.db" }));
+    const contacts = raws.filter((r) => r.kind === "contact");
+    expect(contacts.map((r) => r.payload.uid).sort()).toEqual(["111", "222"]);
+    // each participant uid → a CONTACT person keyed by douyin-uid
+    const n = a.normalize(contacts[0]);
+    expect(n.persons[0].identifiers["douyin-uid"]).toEqual([contacts[0].payload.uid]);
+  });
+
+  // device-verified: conversation_list row → PDH TOPIC (one chat thread).
+  it("maps conversation_list rows to TOPIC entities", async () => {
+    const spec = {
+      msgCols: DEFAULT_FAKE.msgCols,
+      msgRows: DEFAULT_FAKE.msgRows,
+      userCols: [], userRows: [],
+      convCols: [
+        { name: "conversation_id" }, { name: "type" },
+        { name: "last_msg_create_time" }, { name: "stranger" },
+      ],
+      convRows: [
+        { convId: "conv-1", convType: 0, lastMsgTime: 1700000002000, stranger: 0 },
+        { convId: "conv-2", convType: 1, lastMsgTime: 1700000003000, stranger: 1 },
+      ],
+    };
+    const a = freshAdapter(spec);
+    const raws = await collect(a.sync({ imDbPath: "/fake/123_im.db" }));
+    const convs = raws.filter((r) => r.kind === "conversation");
+    expect(convs.map((r) => r.payload.conversationId)).toEqual(["conv-1", "conv-2"]);
+    const n = a.normalize(convs[1]);
+    expect(n.topics).toHaveLength(1);
+    expect(n.topics[0].type).toBe("topic");
+    expect(n.topics[0].extra.conversationId).toBe("conv-2");
+    expect(n.topics[0].extra.stranger).toBe(true);
+    expect(n.topics[0].extra.lastMsgTimeMs).toBe(1700000003000);
+  });
+
+  it("participant dedups against SIMPLE_USER contacts (no double-count)", async () => {
+    const spec = {
+      msgCols: DEFAULT_FAKE.msgCols,
+      msgRows: DEFAULT_FAKE.msgRows,
+      userCols: DEFAULT_FAKE.userCols,
+      userRows: DEFAULT_FAKE.userRows, // uid 222 from SIMPLE_USER
+      partCols: [{ name: "conversation_id" }, { name: "user_id" }],
+      partRows: [{ uid: 222 }, { uid: 333 }], // 222 already seen, only 333 is new
+    };
+    const a = freshAdapter(spec);
+    const raws = await collect(a.sync({ imDbPath: "/fake/123_im.db" }));
+    const uids = raws.filter((r) => r.kind === "contact").map((r) => r.payload.uid).sort();
+    expect(uids).toEqual(["222", "333"]); // 222 not duplicated
+  });
 });
 
 describe("DouyinAdapter — sync() input routing (sniff)", () => {

package/__tests__/social-douyin-salvage-collector.test.js

@@ -0,0 +1,98 @@
+"use strict";
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+const {
+  salvageDumpToSnapshot,
+  salvageAndSync,
+} = require("../lib/adapters/social-douyin-adb/collector");
+
+// Build a real (UTF-8) SQLite DB via the SQLCipher-capable driver and treat its
+// raw bytes as a "memory dump" — proving the salvage → snapshot → ingest path
+// recovers message rows with no key (the Method-B capstone). The msg-table
+// column order matches the device-verified Douyin IM schema.
+describe("social-douyin-adb salvage collector", () => {
+  let dir, dbPath;
+  const COLUMNS = ["msg_uuid", "conversation_id", "sender", "content", "created_time"];
+
+  beforeAll(() => {
+    const Database = require("better-sqlite3-multiple-ciphers");
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "salvage-col-"));
+    dbPath = path.join(dir, "u.db");
+    const db = new Database(dbPath);
+    db.exec(
+      "CREATE TABLE msg(msg_uuid TEXT, conversation_id TEXT, sender INTEGER, content TEXT, created_time INTEGER)",
+    );
+    const ins = db.prepare("INSERT INTO msg VALUES(?,?,?,?,?)");
+    ins.run("uuid-1", "conv-1", 111, "你好呀 hello", 1700000000000);
+    ins.run("uuid-2", "conv-1", 222, "在吗？晚上一起吃饭", 1700000001000);
+    ins.run("uuid-3", "conv-2", 333, "ok 👍", 1700000002000);
+    db.close();
+  });
+
+  afterAll(() => {
+    try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+  });
+
+  it("salvageDumpToSnapshot recovers msg rows → snapshot JSON (explicit columns)", () => {
+    const res = salvageDumpToSnapshot(dbPath, {
+      uid: "1234567890123456789",
+      columns: COLUMNS,
+      now: () => 1700000099000,
+    });
+    expect(res.uid).toBe("1234567890123456789");
+    expect(res.eventCounts.message).toBe(3);
+    expect(res.salvage.recordsSalvaged).toBeGreaterThanOrEqual(3);
+
+    const snap = JSON.parse(fs.readFileSync(res.snapshotPath, "utf-8"));
+    const msgs = snap.events.filter((e) => e.kind === "message");
+    expect(msgs.length).toBe(3);
+    const texts = msgs.map((m) => m.text).sort();
+    expect(texts).toContain("你好呀 hello");
+    expect(texts).toContain("ok 👍"); // UTF-8 emoji survives
+    const m1 = msgs.find((m) => m.text === "你好呀 hello");
+    expect(m1.conversationId).toBe("conv-1");
+    expect(m1.senderUid).toBe("111");
+    fs.rmSync(res.snapshotPath, { force: true });
+  });
+
+  it("infers columns heuristically when none given (content + created_time)", () => {
+    const res = salvageDumpToSnapshot(dbPath, { now: () => 1700000099000 });
+    expect(res.eventCounts.message).toBe(3);
+    const snap = JSON.parse(fs.readFileSync(res.snapshotPath, "utf-8"));
+    const texts = snap.events.filter((e) => e.kind === "message").map((m) => m.text);
+    expect(texts).toContain("在吗？晚上一起吃饭");
+    fs.rmSync(res.snapshotPath, { force: true });
+  });
+
+  it("salvageAndSync feeds the snapshot to registry.syncAdapter then cleans up", async () => {
+    let captured = null;
+    const fakeRegistry = {
+      syncAdapter: async (name, opts) => {
+        captured = { name, opts };
+        // verify the snapshot file exists at sync time
+        const snap = JSON.parse(fs.readFileSync(opts.inputPath, "utf-8"));
+        return { ingested: snap.events.length, adapter: name, kgTriples: 0, ragDocs: 0 };
+      },
+    };
+    const report = await salvageAndSync(fakeRegistry, dbPath, {
+      uid: "1234567890123456789",
+      columns: COLUMNS,
+    });
+    expect(captured.name).toBe("social-douyin");
+    expect(report.ingested).toBe(3);
+    expect(report.douyin.mode).toBe("salvage");
+    expect(report.douyin.eventCounts.message).toBe(3);
+    expect(report.douyin.cleanupFailed).toBe(false);
+    // snapshot file cleaned up in finally
+    expect(fs.existsSync(captured.opts.inputPath)).toBe(false);
+  });
+
+  it("throws on missing dumpPath", () => {
+    expect(() => salvageDumpToSnapshot("")).toThrow();
+  });
+});

package/__tests__/social-douyin-salvage-mapper.test.js

@@ -0,0 +1,90 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const {
+  mapMsgRecords,
+  mapParticipantRecords,
+  mapConversationRecords,
+  inferMsgColumns,
+  mapSalvaged,
+} = require("../lib/adapters/social-douyin-adb/salvage-mapper");
+const { DouyinAdapter } = require("../lib/adapters/social-douyin");
+
+// End-to-end glue: leaf-salvaged {rowid,cols} → parseImDb shape → adapter.normalize
+// → PDH entities. Closes Method-B: dump → salvage → mapper → ingest.
+describe("salvage-mapper — salvaged records → PDH entities", () => {
+  // msg column order (device-verified subset, see pdh-app-db-schemas.md)
+  const MSG_COLS = ["msg_uuid", "conversation_id", "sender", "content", "created_time"];
+  const msgRecords = [
+    { rowid: "1", cols: ["u1", "conv-1", 111, JSON.stringify({ text: "你好呀 hello" }), 1700000000000] },
+    { rowid: "2", cols: ["u2", "conv-1", 222, JSON.stringify({ text: "在吗" }), 1700000001000] },
+  ];
+
+  it("maps msg records → message objects (im-db-parser shape)", () => {
+    const msgs = mapMsgRecords(msgRecords, MSG_COLS);
+    expect(msgs).toHaveLength(2);
+    expect(msgs[0].senderUid).toBe("111");
+    expect(msgs[0].conversationId).toBe("conv-1");
+    expect(msgs[0].createdTimeMs).toBe(1700000000000);
+    expect(msgs[0].text).toBe("你好呀 hello"); // content JSON → text extracted
+  });
+
+  it("mapped messages normalize through DouyinAdapter → MESSAGE events", () => {
+    const a = new DouyinAdapter();
+    const msgs = mapMsgRecords(msgRecords, MSG_COLS);
+    const raw = {
+      adapter: "social-douyin",
+      kind: "message",
+      originalId: "douyin:message:x",
+      capturedAt: msgs[0].createdTimeMs,
+      payload: { kind: "message", ...msgs[0] },
+    };
+    const n = a.normalize(raw);
+    expect(n.events).toHaveLength(1);
+    expect(n.events[0].subtype).toBe("message");
+    expect(n.events[0].content.text).toBe("你好呀 hello");
+    expect(n.events[0].extra.senderUid).toBe("111");
+  });
+
+  it("maps participant records → deduped contacts (uid only)", () => {
+    const recs = [
+      { rowid: "1", cols: ["conv-1", "111", 0] },
+      { rowid: "2", cols: ["conv-1", "222", 1] },
+      { rowid: "3", cols: ["conv-2", "222", 0] },
+    ];
+    const contacts = mapParticipantRecords(recs, ["conversation_id", "user_id", "sort_order"]);
+    expect(contacts.map((c) => c.uid).sort()).toEqual(["111", "222"]);
+    expect(contacts.every((c) => c.fromParticipant)).toBe(true);
+  });
+
+  it("maps conversation records → conversations (→ TOPIC)", () => {
+    const recs = [{ rowid: "1", cols: ["conv-9", 1, 1700000002000, 1] }];
+    const convs = mapConversationRecords(recs, ["conversation_id", "type", "last_msg_create_time", "stranger"]);
+    expect(convs[0].conversationId).toBe("conv-9");
+    expect(convs[0].stranger).toBe(true);
+    expect(convs[0].lastMsgTimeMs).toBe(1700000002000);
+  });
+
+  it("inferMsgColumns heuristically locates content + created_time", () => {
+    const cols = inferMsgColumns(msgRecords);
+    // content = the JSON string col (index 3), created_time = the epoch int (index 4)
+    expect(cols[3]).toBe("content");
+    expect(cols[4]).toBe("created_time");
+    // round-trips through mapMsgRecords
+    const msgs = mapMsgRecords(msgRecords, cols);
+    expect(msgs[0].text).toBe("你好呀 hello");
+    expect(msgs[0].createdTimeMs).toBe(1700000000000);
+  });
+
+  it("mapSalvaged one-shot returns parseImDb shape", () => {
+    const out = mapSalvaged({
+      msg: { records: msgRecords, columns: MSG_COLS },
+      participant: { records: [{ rowid: "1", cols: ["conv-1", "999"] }], columns: ["conversation_id", "user_id"] },
+      conversation: { records: [{ rowid: "1", cols: ["conv-1"] }], columns: ["conversation_id"] },
+    });
+    expect(out.messages).toHaveLength(2);
+    expect(out.contacts).toHaveLength(1);
+    expect(out.conversations).toHaveLength(1);
+  });
+});