@chainlesschain/personal-data-hub 0.4.28 → 0.4.30

package/README.md

@@ -16,13 +16,21 @@ middleware.
 > Ollama / Volcengine / Anthropic / Gemini / DeepSeek), **CcKgSink**, **CcRagSink**
 > — injected at the desktop/CLI entry so this package stays decoupled (Phase 3.5).
 >
-> **51 adapters are now live** (no longer "later phases"): Email IMAP,
+> **89 adapters are now live** (no longer "later phases"): Email IMAP,
 > Alipay bill, 9 AI-chat vendors, WeChat / QQ / Weibo / Bilibili / Douyin /
-> Xiaohongshu / Toutiao / Kuaishou social, Telegram / WhatsApp messaging,
-> Taobao / JD / Meituan / Pinduoduo shopping, Amap / Baidu-map / Tencent-map /
-> Ctrip / 12306 travel, system-data (contacts / calls / sms / location),
+> Xiaohongshu / Toutiao / Kuaishou / Douban social, Telegram / WhatsApp messaging,
+> Taobao / JD / Meituan / Pinduoduo / Eleme / Xianyu / Vipshop shopping, Amap /
+> Baidu-map / Tencent-map / Ctrip / 12306 / Didi travel, Kugou / Ximalaya audio,
+> Keep / Joyrun fitness, system-data (contacts / calls / sms / location),
 > and the developer-activity set (git / shell / vscode / browser-history /
-> local-files / win-recent).
+> local-files / win-recent). See `lib/adapters/` for the full list.
+>
+> **On-device root forensics (rooted devices):** beyond cookie/sign-based
+> collection, PDH can pull a logged-in app's local encrypted DB directly via
+> **method B** (key-free `/proc/<pid>/mem` memory scan — engine-agnostic,
+> anti-debug-resistant) or **method C** (frida `sqlcipher_export` online decrypt),
+> plus a SQLite leaf-page **salvager** (`--unaligned`) that recovers plaintext
+> pages from corrupt mem dumps. See `docs/internal/pdh-db-decryption-runbook.md`.
 >
 > **New in v0.4.0 (v5.0.3.99):** adapter **readiness** — split out from the
 > loose `healthCheck` sync gate into a real ready/needs_setup/unavailable

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: {

package/lib/adapters/social-toutiao-adb/article-reader.js

@@ -0,0 +1,202 @@
+/**
+ * Toutiao on-device article reader — recovers the user's feed/read articles
+ * from the app's local `news_article.db` (table `article`), a plaintext SQLite
+ * DB. No signing/encryption needed.
+ *
+ * Why this exists (real-device 2026-06-18, user's exported plaintext DB):
+ *   - `article` rows are the local feed cache (48 rows on the test export). The
+ *     title is NOT a column — it lives in the `share_info` JSON blob
+ *     ({title, share_url, ...}); `ext_json` is a heavier fallback. `behot_time`
+ *     is when the item surfaced; `read_timestamp>0` ⇒ actually opened;
+ *     `is_user_digg`/`is_user_repin` ⇒ engagement.
+ *   - Modest signal (feed-shown ≈ weak interest; digg/read ≈ strong), but
+ *     titled + plaintext, so it's a usable "articles I browsed" stream.
+ *
+ * Emits BROWSE events under source.adapter `social-toutiao` (the canonical
+ * adapter name, so byApp aggregation attributes correctly). Stable originalId
+ * (`social-toutiao:article:<group_id>`) → re-ingest UPDATES, not duplicates.
+ *
+ * Authorization: only on your own device/account.
+ */
+"use strict";
+
+const { newId } = require("../../ids");
+const {
+  _internals: { loadDatabaseClass },
+} = require("../social-bilibili-adb/chromium-cookies-reader");
+
+const ARTICLE_TABLE = "article";
+const READER_VERSION = "toutiao-article-0.1";
+const TITLE_SUFFIX = /\s*-\s*今日头条\s*$/;
+
+/** 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);
+}
+
+function safeParse(s) {
+  if (typeof s !== "string" || s.length < 2) return null;
+  try {
+    return JSON.parse(s);
+  } catch (_e) {
+    return null;
+  }
+}
+
+/** Title lives in share_info.title (or ext_json.title); strip the brand suffix. */
+function extractTitle(row) {
+  const si = safeParse(row.share_info);
+  let title = si && (si.title || si.share_title);
+  if (!title) {
+    const ej = safeParse(row.ext_json);
+    title = ej && (ej.title || ej.share_title || (ej.article && ej.article.title));
+  }
+  if (typeof title !== "string" || !title.trim()) return null;
+  return title.replace(TITLE_SUFFIX, "").trim();
+}
+
+function extractUrl(row) {
+  const si = safeParse(row.share_info);
+  const u = (si && si.share_url) || row.share_url || null;
+  if (typeof u !== "string" || !u) return null;
+  // Drop the noisy share/tracking query so the same article dedups by url too.
+  return u.split("?")[0];
+}
+
+function extractCategory(row) {
+  const u = row.share_url || "";
+  const m = /[?&]category_new=([^&]+)/.exec(u);
+  return m ? decodeURIComponent(m[1]) : null;
+}
+
+/**
+ * Read article rows + parse them into structured records (pure once a Database
+ * class is injected). Newest-first.
+ *
+ * @returns {{articles: Array<{groupId,title,url,category,behotTime,readTimestamp,digg,repin}>}}
+ */
+function readToutiaoArticles(dbPath, opts = {}) {
+  const Database = opts._databaseClass || loadDatabaseClass();
+  const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 5000;
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    const exists = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?")
+      .get(ARTICLE_TABLE);
+    if (!exists) return { articles: [] };
+
+    const cols = new Set(
+      db.prepare(`PRAGMA table_info("${ARTICLE_TABLE}")`).all().map((c) => c.name),
+    );
+    const hasBehot = cols.has("behot_time");
+    const rows = db
+      .prepare(
+        `SELECT * FROM "${ARTICLE_TABLE}"${hasBehot ? " ORDER BY behot_time DESC" : ""} LIMIT ${limit}`,
+      )
+      .all();
+
+    const articles = [];
+    for (const r of rows) {
+      const groupId =
+        r.group_id != null ? String(r.group_id) : r.item_id != null ? String(r.item_id) : null;
+      if (!groupId) continue;
+      const title = extractTitle(r);
+      if (!title) continue; // untitled cache rows carry no signal
+      articles.push({
+        groupId,
+        title,
+        url: extractUrl(r),
+        category: extractCategory(r),
+        behotTime: hasBehot ? toEpochMs(r.behot_time) : null,
+        readTimestamp: cols.has("read_timestamp") ? toEpochMs(r.read_timestamp) : null,
+        digg: cols.has("is_user_digg") ? !!r.is_user_digg : false,
+        repin: cols.has("is_user_repin") ? !!r.is_user_repin : false,
+      });
+    }
+    return { articles };
+  } finally {
+    try {
+      db.close();
+    } catch (_e) {
+      /* best-effort */
+    }
+  }
+}
+
+/**
+ * Map article records → BROWSE events tagged with the toutiao source.
+ * @returns {{events: object[]}}
+ */
+function buildArticleEvents(articles, opts = {}) {
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const events = [];
+  for (const a of articles || []) {
+    if (!a || !a.groupId || !a.title) continue;
+    const occurredAt =
+      (Number.isFinite(a.readTimestamp) && a.readTimestamp) ||
+      (Number.isFinite(a.behotTime) && a.behotTime) ||
+      now;
+    events.push({
+      id: newId(),
+      type: "event",
+      subtype: "browse",
+      occurredAt,
+      actor: "person-self",
+      content: { title: a.title, text: a.title },
+      ingestedAt: now,
+      source: {
+        adapter: "social-toutiao",
+        adapterVersion: READER_VERSION,
+        originalId: `social-toutiao:article:${a.groupId}`,
+        capturedAt: occurredAt,
+        capturedBy: "sqlite",
+      },
+      extra: {
+        platform: "toutiao",
+        kind: "article",
+        groupId: a.groupId,
+        url: a.url || null,
+        category: a.category || null,
+        digg: a.digg,
+        repin: a.repin,
+        read: Number.isFinite(a.readTimestamp) && a.readTimestamp > 0,
+      },
+    });
+  }
+  return { events };
+}
+
+/**
+ * Read news_article.db and write the article BROWSE events into the vault.
+ * @param {object} vault LocalVault (must expose putBatch)
+ * @param {string} dbPath path to news_article.db
+ */
+function articlesToVault(vault, dbPath, opts = {}) {
+  if (!vault || typeof vault.putBatch !== "function") {
+    throw new TypeError("articlesToVault: vault with putBatch required");
+  }
+  if (typeof dbPath !== "string" || !dbPath) {
+    throw new TypeError("articlesToVault: dbPath required");
+  }
+  const { articles } = readToutiaoArticles(dbPath, opts);
+  const built = buildArticleEvents(articles, opts);
+  const res = built.events.length
+    ? vault.putBatch({ events: built.events })
+    : { events: 0 };
+  return {
+    ingested: res.events || 0,
+    articles: articles.length,
+    digg: articles.filter((a) => a.digg).length,
+    read: articles.filter((a) => Number.isFinite(a.readTimestamp) && a.readTimestamp > 0).length,
+  };
+}
+
+module.exports = {
+  ARTICLE_TABLE,
+  readToutiaoArticles,
+  buildArticleEvents,
+  articlesToVault,
+  _internals: { toEpochMs, extractTitle, extractUrl, extractCategory },
+};