@chainlesschain/personal-data-hub 0.4.27 → 0.4.29

package/__tests__/analysis-skills.test.js

@@ -151,6 +151,43 @@ describe("SpendingSkill", () => {
     expect(r.summary.currency).toBe("CNY");
   });
 
+  it("headline totals come from uncapped sumEventAmount, not the 5000-capped row fetch", async () => {
+    // queryEvents caps at 5000 rows per subtype; a >5000-payment user would
+    // have totalSpend silently undercounted. Fake a vault where the row fetch
+    // returns only a sample but sumEventAmount reports the true sum.
+    const fakeVault = {
+      queryEvents: ({ subtype }) =>
+        subtype === "payment"
+          ? [
+              { id: "p1", subtype: "payment", occurredAt: ts(2026, 5, 1), content: { amount: { value: 10, direction: "out", currency: "CNY" } } },
+              { id: "p2", subtype: "payment", occurredAt: ts(2026, 5, 2), content: { amount: { value: 20, direction: "out", currency: "CNY" } } },
+            ]
+          : [],
+      sumEventAmount: ({ subtype }) =>
+        subtype === "payment"
+          ? { total: 88000, currency: "CNY", count: 5200, byDirection: { out: 88000, in: 1234 }, byCurrency: {} }
+          : { total: 0, currency: "CNY", count: 0, byDirection: { out: 0, in: 0 }, byCurrency: {} },
+    };
+    const r = await new SpendingSkill({ vault: fakeVault }).run({ commentary: false });
+    expect(r.summary.totalSpend).toBe(88000); // true sum, not the 30 from 2 sampled rows
+    expect(r.summary.totalIncome).toBe(1234);
+    expect(r.summary.eventCount).toBe(5200);
+    expect(r.summary.netFlow).toBe(Math.round((1234 - 88000) * 100) / 100);
+  });
+
+  it("with a merchant/person/direction filter it falls back to the row sample (SQL can't express it)", async () => {
+    const fakeVault = {
+      queryEvents: ({ subtype }) =>
+        subtype === "payment"
+          ? [{ id: "p1", subtype: "payment", occurredAt: ts(2026, 5, 1), content: { amount: { value: 30, direction: "out", currency: "CNY" } }, extra: { counterparty: "美团" } }]
+          : [],
+      // would be used by the accurate path — must NOT be when a filter is active
+      sumEventAmount: () => { throw new Error("sumEventAmount must not be called when a row-only filter is set"); },
+    };
+    const r = await new SpendingSkill({ vault: fakeVault }).run({ commentary: false, direction: "out" });
+    expect(r.summary.totalSpend).toBe(30); // from the row sample, not SQL
+  });
+
   it("breakdown by merchant ranks top spenders", async () => {
     setupAlipayPayments();
     const skill = new SpendingSkill({ vault: rig.vault });
@@ -498,6 +535,32 @@ describe("InterestsSkill", () => {
     expect(r.topTopics[0].name).toBe("Travel");
     expect(r.llmInterests).toBeNull();
   });
+
+  it("drops unresolved numeric group-id topics (e.g. WeChat chatroom ids) from the profile", async () => {
+    // Real interest topic
+    rig.vault.putTopic({
+      id: "topic-doubao", type: "topic", name: "豆包",
+      derivedFromEvents: ["e1"],
+      ingestedAt: Date.now(), source: defaultSource("test"),
+    });
+    // Unresolved group-chat topics named by raw numeric chatroom id — noise.
+    rig.vault.putTopic({
+      id: "topic-g1", type: "topic", name: "45498354778",
+      derivedFromEvents: [],
+      ingestedAt: Date.now() + 1, source: defaultSource("test"),
+    });
+    rig.vault.putTopic({
+      id: "topic-g2", type: "topic", name: "54346634535",
+      derivedFromEvents: [],
+      ingestedAt: Date.now() + 2, source: defaultSource("test"),
+    });
+    const skill = new InterestsSkill({ vault: rig.vault });
+    const r = await skill.run({});
+    const names = r.topTopics.map((t) => t.name);
+    expect(names).toContain("豆包");
+    expect(names).not.toContain("45498354778");
+    expect(names).not.toContain("54346634535");
+  });
 });
 
 // ─── TimelineSkill ──────────────────────────────────────────────────────
@@ -534,6 +597,44 @@ describe("TimelineSkill", () => {
     const r = await skill.run({ since: ts(2026, 4, 1) });
     expect(r.llm_narrative).toBe("你这周点了一次外卖。");
   });
+
+  it("excludes inventory-snapshot events (installed-app / contact roster) from the narrative", async () => {
+    // Real activity event (extra has no `kind` → must be kept)
+    makePayment(rig.vault, { id: "act-1", occurredAt: ts(2026, 5, 1), counterpartyName: "美团", amount: 10, adapter: "alipay-bill", title: "外卖" });
+    // Inventory-snapshot events stamped at a LATER (collection) time — these
+    // would dominate a DESC time query but must be filtered out.
+    rig.vault.putEvent({
+      id: "event-android-app-com.x", type: "event", subtype: "other",
+      occurredAt: ts(2026, 6, 1), actor: "person-self",
+      content: { title: "应用：X" },
+      ingestedAt: Date.now(), source: defaultSource("system-data-android"),
+      extra: { kind: "app-snapshot", packageName: "com.x" },
+    });
+    rig.vault.putEvent({
+      id: "event-android-contact-y", type: "event", subtype: "other",
+      occurredAt: ts(2026, 6, 1), actor: "person-self",
+      content: { title: "联系人：Y" },
+      ingestedAt: Date.now(), source: defaultSource("system-data-android"),
+      extra: { kind: "contact-snapshot" },
+    });
+    // Aggregate-baseline event (douyin app-usage-profile) — a single rolling
+    // summary, not a discrete activity, so it must be filtered from the timeline.
+    rig.vault.putEvent({
+      id: "event-douyin-usage", type: "event", subtype: "other",
+      occurredAt: ts(2026, 6, 1), actor: "person-self",
+      content: { title: "抖音使用画像：24天/108h" },
+      ingestedAt: Date.now(), source: defaultSource("social-douyin"),
+      extra: { kind: "app-usage-profile" },
+    });
+    const skill = new TimelineSkill({ vault: rig.vault });
+    const r = await skill.run({ since: ts(2026, 4, 1) });
+    const ids = r.entries.map((e) => e.id);
+    expect(ids).toContain("act-1");
+    expect(ids).not.toContain("event-android-app-com.x");
+    expect(ids).not.toContain("event-android-contact-y");
+    expect(ids).not.toContain("event-douyin-usage");
+    expect(r.summary.totalEvents).toBe(1);
+  });
 });
 
 // ─── runAnalysisSkill dispatcher ─────────────────────────────────────────
@@ -591,6 +692,34 @@ describe("OverviewSkill — cross-app unified snapshot", () => {
     expect(r.summary.appsActive).toBe(4); // alipay-bill, shopping-taobao, wechat, social-douyin
   });
 
+  it("byApp/byType/total use uncapped facetCounts, not the row-capped fetch", async () => {
+    // queryEvents hard-caps at 10k rows; on a big vault one dominant app crowds
+    // out the rest, so deriving byApp from the row fetch undercounts (real bug:
+    // social-douyin showed 10 instead of 232). Fake a vault where the capped
+    // row fetch and the SQL GROUP BY disagree, and assert overview trusts SQL.
+    const fakeVault = {
+      facetCounts: () => ({
+        byAdapter: { "social-douyin": 232, "wechat-pc": 100000 },
+        bySubtype: { browse: 232, message: 100000 },
+        byCategory: {},
+        total: 100232,
+        mode: "like",
+        shortQuery: false,
+      }),
+      // simulates the cap: only wechat rows survived the recent-10k window
+      queryEvents: () => [
+        { id: "w1", subtype: "message", occurredAt: ts(2026, 6, 1), actor: "person-self", source: { adapter: "wechat-pc" }, content: {} },
+      ],
+    };
+    const r = await new OverviewSkill({ vault: fakeVault }).run({ commentary: false });
+    const dy = r.byApp.find((a) => a.app === "social-douyin");
+    expect(dy && dy.count).toBe(232); // would be absent/0 if derived from the row fetch
+    expect(r.byApp[0].app).toBe("wechat-pc"); // 100000 sorts first
+    expect(r.summary.totalEvents).toBe(100232);
+    expect(r.summary.appsActive).toBe(2);
+    expect(r.byType.find((t) => t.type === "browse").count).toBe(232);
+  });
+
   it("counts 4 distinct apps + sums cross-app spend + top contact merged", async () => {
     const { vault } = rig;
     makePerson(vault, "p-friend", ["小明"], {}, { adapter: "wechat" });

package/__tests__/query-parser.test.js

@@ -69,6 +69,27 @@ describe("parseTimeWindow", () => {
     expect(months.since).toBeLessThan(NOW);
   });
 
+  it("最近 N 个月 does NOT month-overflow on a month-end day (regression)", () => {
+    // Naive setMonth(getMonth()-1) on Mar 31 lands on "Feb 31" → Mar 3, silently
+    // dropping all of February from the window. since must land in February.
+    const mar31 = new Date(2026, 2, 31, 12, 0, 0).getTime();
+    const since = parseTimeWindow("最近1个月", mar31).since;
+    const d = new Date(since);
+    expect(d.getFullYear()).toBe(2026);
+    expect(d.getMonth()).toBe(1); // February, NOT still March
+    expect(d.getDate()).toBe(28); // clamped to Feb's last day
+
+    // May 31 −1mo → April 30 (April has 30 days), not May 1.
+    const may31 = new Date(2026, 4, 31, 12, 0, 0).getTime();
+    const aprSince = new Date(parseTimeWindow("最近1个月", may31).since);
+    expect(aprSince.getMonth()).toBe(3); // April
+    expect(aprSince.getDate()).toBe(30);
+
+    // mid-month is unaffected: Mar 15 −1mo → Feb 15.
+    const mar15 = new Date(2026, 2, 15, 12, 0, 0).getTime();
+    expect(new Date(parseTimeWindow("最近1个月", mar15).since).getDate()).toBe(15);
+  });
+
   it("YYYY 年 M 月 → that calendar month", () => {
     const w = parseTimeWindow("2024 年 7 月在淘宝下过几单", NOW);
     expect(w.since).toBe(new Date(2024, 6, 1).getTime());
@@ -95,6 +116,17 @@ describe("parseFilters", () => {
     expect(parseFilters("我朋友圈发了啥").subtype).toBe("post");
   });
 
+  it("bare 收到 does not steal non-income subtypes (regression)", () => {
+    // 收到 ("receive") used to match income before message → "收到多少消息"
+    // was mis-classified as income.
+    expect(parseFilters("我收到多少消息").subtype).toBe("message");
+    expect(parseFilters("收到的快递").subtype).toBeUndefined();
+    expect(parseFilters("收到转账了吗").subtype).toBe("transfer"); // still transfer
+    // genuine income keywords still classify
+    expect(parseFilters("这个月工资多少").subtype).toBe("income");
+    expect(parseFilters("进账多少").subtype).toBe("income");
+  });
+
   it("identifies adapter via keywords (Chinese + English)", () => {
     expect(parseFilters("淘宝今年下了多少单").adapter).toBe("taobao");
     expect(parseFilters("支付宝账单").adapter).toBe("alipay-bill");
@@ -114,9 +146,40 @@ describe("parseIntent", () => {
     expect(parseIntent("我今年开销加起来")).toBe("sum-amount");
   });
 
+  it("sum-amount for spending questions WITHOUT an explicit 总共/合计", () => {
+    // Regression: these very common phrasings previously fell through to
+    // intent=list (→ engine returned a row sample instead of the authoritative
+    // sumEventAmount total).
+    expect(parseIntent("我这个月花了多少钱")).toBe("sum-amount");
+    expect(parseIntent("上个月在淘宝花了多少钱")).toBe("sum-amount");
+    expect(parseIntent("这个月消费多少")).toBe("sum-amount");
+    expect(parseIntent("花了多少")).toBe("sum-amount");
+  });
+
+  it("sum-amount for INCOME-side questions (收入/赚/到账)", () => {
+    // Regression: income amount words were missing → "总共收入多少" even
+    // mis-returned "count". Both with and without 总共.
+    expect(parseIntent("这个月收入多少")).toBe("sum-amount");
+    expect(parseIntent("我这个月赚了多少")).toBe("sum-amount");
+    expect(parseIntent("上个月到账多少")).toBe("sum-amount");
+    expect(parseIntent("总共收入多少")).toBe("sum-amount");
+  });
+
+  it("count for 多少X / 几X measure-word symmetry (多少条/多少单 were missed)", () => {
+    expect(parseIntent("我有多少条朋友圈")).toBe("count");
+    expect(parseIntent("下了多少单")).toBe("count");
+    expect(parseIntent("发了多少条微博")).toBe("count");
+    expect(parseIntent("多少笔交易")).toBe("count");
+    expect(parseIntent("几部电影")).toBe("count");
+  });
+
   it("count when 'how many' phrasing", () => {
     expect(parseIntent("最近多少次跟妈妈聊过")).toBe("count");
     expect(parseIntent("我下了几单")).toBe("count");
+    // the new sum-amount rule must NOT steal a count question that also
+    // mentions spending ("how many TIMES did I spend").
+    expect(parseIntent("消费了多少次")).toBe("count");
+    expect(parseIntent("花了多少次钱")).toBe("count");
   });
 
   it("latest when 'recent / latest'", () => {

package/lib/adapters/social-douyin-adb/usage-profile-reader.js

@@ -0,0 +1,253 @@
+/**
+ * Douyin on-device usage-profile reader — recovers the user's app-usage
+ * baseline (active hours / session count / total time-on-app) from the local
+ * `1128_feature_engineering.db` table `FEInternalUserActivityTable`, a plaintext
+ * SQLite table the app keeps for its own client-side feature store.
+ *
+ * Why this exists (real-device 2026-06-18, user's exported plaintext DB):
+ *   - `FEInternalUserActivityTable` rows are per-session aggregates:
+ *       { timestamp(sec), start/end_timestamp_ms, open_app_count,
+ *         launch_hour_0..23, total_duration(ms) }
+ *   - 81 rows spanning ~31 days = "how the user uses Douyin": ~175 opens,
+ *     ~108 hours total, peak 12–17h. This behavioral baseline is exactly what a
+ *     personal-AI should know, and it's plaintext (no signing/encryption).
+ *
+ * This module is the testable core (reader + pure summarizer + vault-event
+ * builder). The device pull/collector wiring (mirroring watch-history-reader's
+ * pullVideoRecordDbViaSu) is a follow-up; the remote db sub-path must be
+ * confirmed on a device first.
+ *
+ * Authorization: only on your own device/account.
+ */
+"use strict";
+
+const { newId } = require("../../ids");
+const {
+  _internals: { loadDatabaseClass },
+} = require("../social-bilibili-adb/chromium-cookies-reader");
+
+const USAGE_TABLE = "FEInternalUserActivityTable";
+const PROFILE_VERSION = "usage-profile-0.1";
+const HOUR_BUCKETS = Object.freeze([
+  { label: "0-5h", from: 0, to: 5 },
+  { label: "6-11h", from: 6, to: 11 },
+  { label: "12-17h", from: 12, to: 17 },
+  { label: "18-23h", from: 18, to: 23 },
+]);
+
+/** seconds-or-ms epoch → ms (heuristic: > 1e12 ⇒ already ms). */
+function toEpochMs(v) {
+  const n = Number(v);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  return n > 1e12 ? Math.floor(n) : Math.floor(n * 1000);
+}
+
+/**
+ * Read per-session usage rows from FEInternalUserActivityTable and aggregate
+ * them into a usage profile. Pure once a Database class is injected.
+ *
+ * @returns {{
+ *   sessions: number, days: number, from: number|null, to: number|null,
+ *   totalOpens: number, totalDurationMs: number,
+ *   hourHistogram: number[], peakHour: number|null,
+ *   peakBucket: string|null, bucketTotals: Record<string,number>
+ * }}
+ */
+function readDouyinUsageProfile(dbPath, opts = {}) {
+  const Database = opts._databaseClass || loadDatabaseClass();
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    const exists = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?")
+      .get(USAGE_TABLE);
+    if (!exists) return emptyProfile();
+
+    const cols = new Set(
+      db.prepare(`PRAGMA table_info("${USAGE_TABLE}")`).all().map((c) => c.name),
+    );
+    const hourCols = [];
+    for (let h = 0; h < 24; h++) {
+      hourCols.push(cols.has(`launch_hour_${h}`) ? `launch_hour_${h}` : null);
+    }
+    const hasOpen = cols.has("open_app_count");
+    const hasDur = cols.has("total_duration");
+    const hasTs = cols.has("timestamp");
+
+    const rows = db.prepare(`SELECT * FROM "${USAGE_TABLE}"`).all();
+    const histogram = new Array(24).fill(0);
+    const days = new Set();
+    let totalOpens = 0;
+    let totalDurationMs = 0;
+    let from = null;
+    let to = null;
+
+    for (const r of rows) {
+      if (hasOpen) totalOpens += Number(r.open_app_count) || 0;
+      if (hasDur) totalDurationMs += Number(r.total_duration) || 0;
+      for (let h = 0; h < 24; h++) {
+        if (hourCols[h]) histogram[h] += Number(r[hourCols[h]]) || 0;
+      }
+      const tsMs = hasTs ? toEpochMs(r.timestamp) : null;
+      if (tsMs != null) {
+        if (from == null || tsMs < from) from = tsMs;
+        if (to == null || tsMs > to) to = tsMs;
+        // local-day bucket (UTC day is fine for a coarse "distinct days" count)
+        days.add(Math.floor(tsMs / 86_400_000));
+      }
+    }
+
+    let peakHour = null;
+    let peakVal = -1;
+    for (let h = 0; h < 24; h++) {
+      if (histogram[h] > peakVal) {
+        peakVal = histogram[h];
+        peakHour = h;
+      }
+    }
+    if (peakVal <= 0) peakHour = null;
+
+    const bucketTotals = {};
+    let peakBucket = null;
+    let peakBucketVal = -1;
+    for (const b of HOUR_BUCKETS) {
+      let sum = 0;
+      for (let h = b.from; h <= b.to; h++) sum += histogram[h];
+      bucketTotals[b.label] = sum;
+      if (sum > peakBucketVal) {
+        peakBucketVal = sum;
+        peakBucket = b.label;
+      }
+    }
+    if (peakBucketVal <= 0) peakBucket = null;
+
+    return {
+      sessions: rows.length,
+      days: days.size,
+      from,
+      to,
+      totalOpens,
+      totalDurationMs,
+      hourHistogram: histogram,
+      peakHour,
+      peakBucket,
+      bucketTotals,
+    };
+  } finally {
+    try {
+      db.close();
+    } catch (_e) {
+      /* best-effort */
+    }
+  }
+}
+
+function emptyProfile() {
+  const bucketTotals = {};
+  for (const b of HOUR_BUCKETS) bucketTotals[b.label] = 0;
+  return {
+    sessions: 0,
+    days: 0,
+    from: null,
+    to: null,
+    totalOpens: 0,
+    totalDurationMs: 0,
+    hourHistogram: new Array(24).fill(0),
+    peakHour: null,
+    peakBucket: null,
+    bucketTotals,
+  };
+}
+
+/** Human-readable one-line summary of a usage profile (pure). */
+function summarizeUsageProfile(profile) {
+  if (!profile || profile.sessions === 0) return "抖音使用画像：无数据";
+  const hours = Math.round((profile.totalDurationMs / 3_600_000) * 10) / 10;
+  const peak = profile.peakBucket ? `，高峰时段 ${profile.peakBucket}` : "";
+  return (
+    `抖音使用画像：${profile.days} 天内 ${profile.sessions} 个会话、` +
+    `${profile.totalOpens} 次启动、累计约 ${hours} 小时${peak}`
+  );
+}
+
+/**
+ * Build a single rolling "app-usage baseline" vault event from a profile.
+ * Stable originalId → re-ingest UPDATES rather than duplicates. Tagged
+ * `extra.kind = "app-usage-profile"` so analysis.timeline can exclude it (it's
+ * a baseline, not a timeline activity) while overview/interests can use it.
+ *
+ * @returns {{events: object[]}}
+ */
+function buildUsageProfileEvents(profile, opts = {}) {
+  if (!profile || profile.sessions === 0) return { events: [] };
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const occurredAt = Number.isFinite(profile.to) ? profile.to : now;
+  const text = summarizeUsageProfile(profile);
+  const event = {
+    id: newId(),
+    type: "event",
+    subtype: "other",
+    occurredAt,
+    actor: "person-self",
+    content: { title: text, text },
+    ingestedAt: now,
+    source: {
+      adapter: "social-douyin",
+      adapterVersion: PROFILE_VERSION,
+      originalId: "social-douyin:usage-profile",
+      capturedAt: occurredAt,
+      capturedBy: "sqlite",
+    },
+    extra: {
+      platform: "douyin",
+      kind: "app-usage-profile",
+      days: profile.days,
+      sessions: profile.sessions,
+      totalOpens: profile.totalOpens,
+      totalDurationMs: profile.totalDurationMs,
+      hourHistogram: profile.hourHistogram,
+      peakHour: profile.peakHour,
+      peakBucket: profile.peakBucket,
+      bucketTotals: profile.bucketTotals,
+      rangeFrom: profile.from,
+      rangeTo: profile.to,
+    },
+  };
+  return { events: [event] };
+}
+
+/**
+ * Read a feature-engineering db and write the usage-profile baseline event into
+ * the vault. Returns counts.
+ *
+ * @param {object} vault LocalVault (must expose putBatch)
+ * @param {string} dbPath path to 1128_feature_engineering.db
+ */
+function usageProfileToVault(vault, dbPath, opts = {}) {
+  if (!vault || typeof vault.putBatch !== "function") {
+    throw new TypeError("usageProfileToVault: vault with putBatch required");
+  }
+  if (typeof dbPath !== "string" || !dbPath) {
+    throw new TypeError("usageProfileToVault: dbPath required");
+  }
+  const profile = readDouyinUsageProfile(dbPath, opts);
+  const built = buildUsageProfileEvents(profile, opts);
+  const res = built.events.length
+    ? vault.putBatch({ events: built.events })
+    : { events: 0 };
+  return {
+    ingested: res.events || 0,
+    sessions: profile.sessions,
+    days: profile.days,
+    summary: summarizeUsageProfile(profile),
+  };
+}
+
+module.exports = {
+  USAGE_TABLE,
+  HOUR_BUCKETS,
+  readDouyinUsageProfile,
+  summarizeUsageProfile,
+  buildUsageProfileEvents,
+  usageProfileToVault,
+  _internals: { toEpochMs, emptyProfile },
+};

package/lib/adapters/social-douyin-adb/watch-history-reader.js

@@ -29,6 +29,7 @@ const crypto = require("node:crypto");
 const {
   _internals: { loadDatabaseClass },
 } = require("../social-bilibili-adb/chromium-cookies-reader");
+const { DouyinAdapter } = require("../social-douyin");
 
 const DOUYIN_PACKAGE = "com.ss.android.ugc.aweme";
 const VIDEO_RECORD_DB_REMOTE_PATH =
@@ -88,9 +89,18 @@ async function pullVideoRecordDbViaSu(adb, serial, opts = {}) {
 
 /**
  * Read watch records from video_record.db. Tables are named `record_<uid>`
- * (per-account) plus an anonymous `record_0`. Picks the numeric-uid table with
- * the most rows (the logged-in account); records carry aid + view timestamp +
- * enter_from surface.
+ * (per-account) plus a default `record_0`. We MERGE every `record_*` table
+ * (record_0 included) and dedup by (awemeId, capturedAt), because the watch
+ * history is split across tables and which one holds the bulk varies by device:
+ *
+ *   - real-device 2026-06-11 (5lhyaqu8lbwstc6x): record_<uid> = 900 rows.
+ *   - real-device 2026-06-18: record_0 = 223 rows vs record_<uid> = 9 — the
+ *     anonymous/default bucket held 96% of the history.
+ *
+ * The earlier "skip record_0, pick the largest uid table" logic silently
+ * dropped the record_0 rows and lost most of the history on the 2nd device.
+ * Attribution `uid` is still the largest non-zero `record_<uid>` table (the
+ * logged-in account), or null when only record_0 exists.
  *
  * @returns {{uid: string|null, records: Array<{awemeId,capturedAt,enterFrom}>}}
  */
@@ -102,43 +112,57 @@ function readDouyinWatchHistory(dbPath, opts = {}) {
     const tables = db
       .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'record\\_%' ESCAPE '\\'")
       .all()
-      .map((t) => t.name);
-    // Candidate uid tables: record_<digits>, uid != 0. Pick the largest.
-    let best = null;
+      .map((t) => t.name)
+      .filter((name) => /^record_\d+$/.test(name));
+    if (tables.length === 0) return { uid: null, records: [] };
+
+    let bestUid = null; // largest non-zero record_<uid> table → attribution
+    const merged = new Map(); // dedupKey → record (first-seen wins)
     for (const name of tables) {
       const m = /^record_(\d+)$/.exec(name);
-      if (!m || m[1] === "0") continue;
       let count = 0;
       try {
         count = db.prepare(`SELECT COUNT(*) c FROM "${name}"`).get().c;
       } catch (_e) {
         continue;
       }
-      if (!best || count > best.count) best = { name, uid: m[1], count };
-    }
-    if (!best) return { uid: null, records: [] };
-    const cols = new Set(
-      db.prepare(`PRAGMA table_info("${best.name}")`).all().map((c) => c.name),
-    );
-    const hasEnter = cols.has("enter_from");
-    const hasTs = cols.has("view_time_timestamp");
-    const rows = db
-      .prepare(
-        `SELECT aid${hasTs ? ", view_time_timestamp" : ""}${hasEnter ? ", enter_from" : ""} ` +
-          `FROM "${best.name}"${hasTs ? " ORDER BY view_time_timestamp DESC" : ""} LIMIT ${limit}`,
-      )
-      .all();
-    const records = [];
-    for (const r of rows) {
-      const awemeId = r.aid != null ? String(r.aid) : null;
-      if (!awemeId) continue;
-      records.push({
-        awemeId,
-        capturedAt: hasTs ? toEpochMs(r.view_time_timestamp) : null,
-        enterFrom: hasEnter ? r.enter_from || null : null,
-      });
+      if (m && m[1] !== "0" && (!bestUid || count > bestUid.count)) {
+        bestUid = { uid: m[1], count };
+      }
+      const cols = new Set(
+        db.prepare(`PRAGMA table_info("${name}")`).all().map((c) => c.name),
+      );
+      const hasEnter = cols.has("enter_from");
+      const hasTs = cols.has("view_time_timestamp");
+      let rows;
+      try {
+        rows = db
+          .prepare(
+            `SELECT aid${hasTs ? ", view_time_timestamp" : ""}${hasEnter ? ", enter_from" : ""} ` +
+              `FROM "${name}"${hasTs ? " ORDER BY view_time_timestamp DESC" : ""} LIMIT ${limit}`,
+          )
+          .all();
+      } catch (_e) {
+        continue;
+      }
+      for (const r of rows) {
+        const awemeId = r.aid != null ? String(r.aid) : null;
+        if (!awemeId) continue;
+        const capturedAt = hasTs ? toEpochMs(r.view_time_timestamp) : null;
+        const key = `${awemeId}@${capturedAt == null ? "" : capturedAt}`;
+        if (merged.has(key)) continue;
+        merged.set(key, {
+          awemeId,
+          capturedAt,
+          enterFrom: hasEnter ? r.enter_from || null : null,
+        });
+      }
     }
-    return { uid: best.uid, records };
+    // Most-recent first (null timestamps sink to the end), then cap.
+    const records = Array.from(merged.values())
+      .sort((a, b) => (b.capturedAt || 0) - (a.capturedAt || 0))
+      .slice(0, limit);
+    return { uid: bestUid ? bestUid.uid : null, records };
   } finally {
     try {
       db.close();
@@ -148,6 +172,53 @@ function readDouyinWatchHistory(dbPath, opts = {}) {
   }
 }
 
+/**
+ * Read watch records from a local video_record.db and write them straight into
+ * the vault as canonical BROWSE events (via DouyinAdapter.normalize, so they
+ * match exactly what the device-bridge collector path produces). Stable
+ * per-record originalId → re-ingest UPDATES rather than duplicates.
+ *
+ * @param {object} vault LocalVault (must expose putBatch)
+ * @param {string} dbPath path to video_record.db
+ */
+function buildWatchHistoryEvents(dbPath, opts = {}) {
+  const { uid, records } = readDouyinWatchHistory(dbPath, opts);
+  const adapter = opts._adapter || new DouyinAdapter();
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const events = [];
+  for (const r of records) {
+    if (!r.awemeId) continue;
+    const occurredAt =
+      Number.isFinite(r.capturedAt) && r.capturedAt > 0 ? r.capturedAt : now;
+    const batch = adapter.normalize({
+      adapter: "social-douyin",
+      kind: "history",
+      originalId: `social-douyin:history:${r.awemeId}:${occurredAt}`,
+      capturedAt: occurredAt,
+      payload: {
+        kind: "history",
+        awemeId: r.awemeId,
+        capturedAt: occurredAt,
+        enterFrom: r.enterFrom,
+      },
+    });
+    for (const ev of batch.events) events.push(ev);
+  }
+  return { events, records: records.length, uid };
+}
+
+function watchHistoryToVault(vault, dbPath, opts = {}) {
+  if (!vault || typeof vault.putBatch !== "function") {
+    throw new TypeError("watchHistoryToVault: vault with putBatch required");
+  }
+  if (typeof dbPath !== "string" || !dbPath) {
+    throw new TypeError("watchHistoryToVault: dbPath required");
+  }
+  const { events, records, uid } = buildWatchHistoryEvents(dbPath, opts);
+  const res = events.length ? vault.putBatch({ events }) : { events: 0 };
+  return { ingested: res.events || 0, records, uid };
+}
+
 /** Bridge handler factory: `bridge.invoke("douyin.watch-history")` → {uid, records}. */
 function createDouyinWatchExtension(factoryOpts = {}) {
   const timeoutMs = factoryOpts.timeoutMs || 60_000;
@@ -178,6 +249,8 @@ function createDouyinWatchExtension(factoryOpts = {}) {
 
 module.exports = {
   createDouyinWatchExtension,
+  buildWatchHistoryEvents,
+  watchHistoryToVault,
   VIDEO_RECORD_DB_REMOTE_PATH,
   DOUYIN_PACKAGE,
   _internals: {