@chainlesschain/personal-data-hub 0.4.24 → 0.4.26

package/lib/adapters/social-weibo/index.js

@@ -9,10 +9,23 @@
  *      — account.uid is OPTIONAL at construction (the snapshot file carries
  *      account in payload).
  *
- *   2. sqlite mode (opts.dbPath, legacy): Phase 13.2 device-pull path —
- *      reads Weibo Android app's SQLite (history / post / status / search_
- *      history). Preserved for backward compat with desktop sqlite-mode
- *      users; account.uid REQUIRED in this mode.
+ *   2. sqlite mode (opts.dbPath): desktop device-pull path — reads the Weibo
+ *      Android app's plain SQLite DB `com.sina.weibo/databases/sina_weibo`.
+ *      account.uid REQUIRED in this mode.
+ *
+ *      Table/column names are DEVICE-VERIFIED against a real install
+ *      (Redmi M2104K10AC, 微博 16.5.3, 2026-06-16):
+ *        - posts      → `home_table` (timeline cache; own posts = uid==selfUid)
+ *                       cols: mblogid / uid / content / time / rtnum /
+ *                       commentnum / attitudenum / src / longitude / latitude
+ *        - favourites → `like_table`   cols: mblogid / content / time / nick
+ *        - follows    → `follower_table` (following=1 ⇒ accounts the user
+ *                       follows) cols: user_id / screen_name / remark / gender
+ *      The legacy `post`/`status`/`search_history` queries are kept as
+ *      FALLBACKS (older builds) — on a modern device those tables don't
+ *      exist so the adapter previously collected ZERO. Row VALUES were not
+ *      validated (verification account was empty); column semantics use the
+ *      standard Weibo schema. See memory pdh_collector_completeness_audit.
  *
  * Snapshot schema (mirrors WeiboLocalCollector.SNAPSHOT_SCHEMA_VERSION):
  *
@@ -44,7 +57,7 @@ const {
 } = require("../../constants");
 
 const NAME = "social-weibo";
-const VERSION = "0.6.0";
+const VERSION = "0.7.0";
 const SNAPSHOT_SCHEMA_VERSION = 1;
 
 const KIND_POST = "post";
@@ -246,21 +259,64 @@ class WeiboAdapter {
       ? this._deps.dbDriverFactory()
       : require("better-sqlite3-multiple-ciphers");
     const db = new Driver(dbPath, { readonly: true });
+    // selfUid sanitised to digits — interpolated into a WHERE clause and
+    // sourced from wiring config (numeric uin). Defensive against injection.
+    const selfUid = String(this.account.uid).replace(/[^0-9]/g, "");
 
     try {
+      // POSTS — device-verified `home_table` (own posts = uid==selfUid);
+      // legacy `post`/`status` kept as fallback for older builds.
       const posts =
-        trySelect(db, "SELECT * FROM post ORDER BY created_at DESC LIMIT 5000")
-        || trySelect(db, "SELECT * FROM status ORDER BY created_at DESC LIMIT 5000")
-        || [];
+        (selfUid &&
+          trySelect(
+            db,
+            `SELECT * FROM home_table WHERE uid='${selfUid}' ORDER BY time DESC LIMIT 5000`,
+          )) ||
+        trySelect(db, "SELECT * FROM post ORDER BY created_at DESC LIMIT 5000") ||
+        trySelect(db, "SELECT * FROM status ORDER BY created_at DESC LIMIT 5000") ||
+        [];
       for (const row of posts) {
         yield {
           adapter: NAME,
-          originalId: `post-${row.id || row.mid || row.idstr}`,
-          capturedAt: parseTime(row.created_at || row.time),
+          originalId: `post-${row.mblogid || row.id || row.mid || row.idstr}`,
+          capturedAt: parseTime(row.time || row.created_at),
           payload: { row, kind: KIND_POST },
         };
       }
 
+      // FAVOURITES — device-verified `like_table` (the account's likes).
+      // Legacy sqlite had no favourite path (folded into posts pre-A8).
+      const favourites =
+        trySelect(db, "SELECT * FROM like_table ORDER BY time DESC LIMIT 5000") || [];
+      for (const row of favourites) {
+        yield {
+          adapter: NAME,
+          originalId: `fav-${row.mblogid || row.id}`,
+          capturedAt: parseTime(row.time),
+          payload: { row, kind: KIND_FAVOURITE },
+        };
+      }
+
+      // FOLLOWS — device-verified `follower_table`; following=1 ⇒ accounts
+      // the user follows (vs followers). Fallback to the whole table.
+      const follows =
+        trySelect(
+          db,
+          "SELECT * FROM follower_table WHERE following=1 ORDER BY user_id LIMIT 5000",
+        ) ||
+        trySelect(db, "SELECT * FROM follower_table LIMIT 5000") ||
+        [];
+      for (const row of follows) {
+        yield {
+          adapter: NAME,
+          originalId: `follow-${row.user_id || row.id}`,
+          capturedAt: parseTime(row.time) || Date.now(),
+          payload: { row, kind: KIND_FOLLOW },
+        };
+      }
+
+      // SEARCH — legacy only (`search_history` doesn't exist on modern
+      // weibo; trySelect returns null gracefully, loop is skipped).
       const searches =
         trySelect(db, "SELECT * FROM search_history ORDER BY time DESC LIMIT 5000")
         || [];
@@ -342,8 +398,9 @@ function normalizePost(p, raw, ingestedAt) {
   // Sqlite mode:   { kind:"post", row: { text, mid, ... } }
   const row = p.row || p;
   const isSnapshot = !p.row;
-  const text = row.text || "";
-  const mid = row.mid || row.id || row.idstr || null;
+  // home_table (device-verified) stores body in `content`, id in `mblogid`.
+  const text = row.text || row.content || "";
+  const mid = row.mid || row.mblogid || row.id || row.idstr || null;
   const occurredAt =
     parseTime(row.created_at || row.createdAt || row.time || raw.capturedAt) ||
     ingestedAt;
@@ -369,13 +426,13 @@ function normalizePost(p, raw, ingestedAt) {
         weiboMid: mid,
         repostsCount:
           row.repostsCount != null ? row.repostsCount
-            : row.reposts_count || row.repost || 0,
+            : row.reposts_count || row.repost || row.rtnum || 0,
         commentsCount:
           row.commentsCount != null ? row.commentsCount
-            : row.comments_count || row.comments || 0,
+            : row.comments_count || row.comments || row.commentnum || 0,
         likesCount:
           row.likesCount != null ? row.likesCount
-            : row.attitudes_count || row.likes || 0,
+            : row.attitudes_count || row.likes || row.attitudenum || 0,
         picCount: row.picCount || row.pic_num || 0,
         source: row.source || null,
         location: row.location || row.geo || null,
@@ -387,13 +444,21 @@ function normalizePost(p, raw, ingestedAt) {
 }
 
 function normalizeFavourite(p, raw, ingestedAt) {
-  // Snapshot only — sqlite mode has no favourite kind (legacy parser merged
-  // favourites into posts pre-A8). Payload: { kind:"favourite", mid, text,
-  // capturedAt, authorScreenName }
-  const text = p.text || "";
-  const mid = p.mid || null;
-  const occurredAt = parseTime(p.capturedAt) || raw.capturedAt || ingestedAt;
-  const source = buildSource(raw, occurredAt, CAPTURED_BY.API);
+  // Snapshot: { kind:"favourite", mid, text, capturedAt, authorScreenName }
+  // Sqlite (device-verified `like_table`): { row: { mblogid, content, time,
+  // nick } }. Both shapes handled below.
+  const row = p.row || null;
+  const isSqlite = !!row;
+  const text = isSqlite ? (row.content || "") : (p.text || "");
+  const mid = isSqlite ? (row.mblogid || row.id || null) : (p.mid || null);
+  const occurredAt = isSqlite
+    ? (parseTime(row.time) || raw.capturedAt || ingestedAt)
+    : (parseTime(p.capturedAt) || raw.capturedAt || ingestedAt);
+  const source = buildSource(
+    raw,
+    occurredAt,
+    isSqlite ? CAPTURED_BY.SQLITE : CAPTURED_BY.API,
+  );
   return {
     events: [{
       id: newId(),
@@ -410,7 +475,9 @@ function normalizeFavourite(p, raw, ingestedAt) {
       extra: {
         platform: "weibo",
         weiboMid: mid,
-        authorScreenName: p.authorScreenName || null,
+        authorScreenName: isSqlite
+          ? (row.nick || null)
+          : (p.authorScreenName || null),
       },
     }],
     persons: [], places: [], items: [], topics: [],
@@ -418,15 +485,28 @@ function normalizeFavourite(p, raw, ingestedAt) {
 }
 
 function normalizeFollow(p, raw, ingestedAt) {
-  // Snapshot only — payload: { kind:"follow", uid, screenName, description,
-  // avatarUrl, capturedAt }
+  // Snapshot: { kind:"follow", uid, screenName, description, avatarUrl,
+  //   capturedAt }
+  // Sqlite (device-verified `follower_table`): { row: { user_id|id,
+  //   screen_name, remark, gender } }. Both shapes handled below.
+  const row = p.row || null;
+  const isSqlite = !!row;
+  const rawUid = isSqlite ? (row.user_id || row.id) : p.uid;
   const followUid =
-    (typeof p.uid === "number" && p.uid) ||
-    (typeof p.uid === "string" && p.uid.length > 0 && p.uid) ||
+    (typeof rawUid === "number" && rawUid) ||
+    (typeof rawUid === "string" && rawUid.length > 0 && rawUid) ||
     `unknown-${newId()}`;
-  const screenName = p.screenName || "(unnamed)";
-  const occurredAt = parseTime(p.capturedAt) || raw.capturedAt || ingestedAt;
-  const source = buildSource(raw, occurredAt, CAPTURED_BY.API);
+  const screenName = isSqlite
+    ? (row.screen_name || row.remark || "(unnamed)")
+    : (p.screenName || "(unnamed)");
+  const occurredAt = isSqlite
+    ? (parseTime(row.time) || raw.capturedAt || ingestedAt)
+    : (parseTime(p.capturedAt) || raw.capturedAt || ingestedAt);
+  const source = buildSource(
+    raw,
+    occurredAt,
+    isSqlite ? CAPTURED_BY.SQLITE : CAPTURED_BY.API,
+  );
   const person = {
     id: `person-weibo-${followUid}`,
     type: ENTITY_TYPES.PERSON,

package/lib/analysis-skills/index.js

@@ -14,6 +14,7 @@ const { RelationsSkill } = require("./relations");
 const { FootprintSkill } = require("./footprint");
 const { InterestsSkill } = require("./interests");
 const { TimelineSkill } = require("./timeline");
+const { OverviewSkill } = require("./overview");
 
 const SKILL_REGISTRY = Object.freeze({
   "analysis.spending": SpendingSkill,
@@ -21,6 +22,7 @@ const SKILL_REGISTRY = Object.freeze({
   "analysis.footprint": FootprintSkill,
   "analysis.interests": InterestsSkill,
   "analysis.timeline": TimelineSkill,
+  "analysis.overview": OverviewSkill,
 });
 
 const SKILL_NAMES = Object.freeze(Object.keys(SKILL_REGISTRY));
@@ -50,6 +52,7 @@ module.exports = {
   FootprintSkill,
   InterestsSkill,
   TimelineSkill,
+  OverviewSkill,
   SKILL_REGISTRY,
   SKILL_NAMES,
   ANALYSIS_SKILL_NAMES: SKILL_NAMES,

package/lib/analysis-skills/overview.js

@@ -0,0 +1,157 @@
+/**
+ * analysis.overview — cross-app unified snapshot for decision support.
+ *
+ * The de-silo capstone: every adapter normalizes into one vault, so this single
+ * skill aggregates ALL apps' Events into one picture — activity by app + by type,
+ * top relationships (merge-group aware, so the same person across WeChat/Douyin/
+ * Weibo counts once), spending across shopping/finance apps, and time trend.
+ * Gives the personal AI a unified "基于跨 app 数据" basis for decisions.
+ *
+ * Output:
+ *   {
+ *     skill, summary: { totalEvents, appsActive, period, topAppName },
+ *     byApp: [{ app, count }], byType: [{ type, count }],
+ *     monthlyActivity: [{ monthKey, count }],
+ *     topContacts: [{ personId, name, interactions, byApp }],
+ *     spending: { total, byDirection, currency },
+ *     citations, llm_commentary,
+ *   }
+ */
+"use strict";
+
+const { AnalysisSkill } = require("./base");
+
+const SPEND_SUBTYPES = new Set([
+  "payment", "transfer", "refund", "utility", "redenvelope", "investment", "income", "order",
+]);
+
+class OverviewSkill extends AnalysisSkill {
+  constructor(opts) {
+    super({ ...opts, name: "analysis.overview" });
+  }
+
+  async run(options = {}) {
+    const { since, until } = this.resolveTimeWindow(options);
+    const topN = Number.isFinite(options.topN) && options.topN > 0 ? options.topN : 10;
+
+    const q = { limit: Number.isFinite(options.limit) ? options.limit : 50_000 };
+    if (since != null) q.since = since;
+    if (until != null) q.until = until;
+    const events = this.vault.queryEvents(q) || [];
+
+    const byApp = new Map();
+    const byType = new Map();
+    const byMonth = new Map();
+    const contacts = new Map(); // canonicalPersonId → { interactions, byApp:Map }
+    let spendTotal = 0;
+    const spendByDir = new Map();
+    let currency = null;
+    const citations = [];
+
+    for (const e of events) {
+      const app = (e.source && e.source.adapter) || "unknown";
+      byApp.set(app, (byApp.get(app) || 0) + 1);
+      const type = e.subtype || "other";
+      byType.set(type, (byType.get(type) || 0) + 1);
+      if (Number.isFinite(e.occurredAt)) {
+        const d = new Date(e.occurredAt);
+        if (Number.isFinite(d.getTime())) {
+          const m = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
+          byMonth.set(m, (byMonth.get(m) || 0) + 1);
+        }
+      }
+      // relationships (actor + participants), merge-group canonicalized
+      const ids = (Array.isArray(e.participants) ? e.participants : []).concat(e.actor ? [e.actor] : []);
+      for (const pid of ids) {
+        if (!pid || pid === "person-self") continue;
+        const canon = this._canon(pid);
+        const cur = contacts.get(canon) || { interactions: 0, byApp: new Map() };
+        cur.interactions += 1;
+        cur.byApp.set(app, (cur.byApp.get(app) || 0) + 1);
+        contacts.set(canon, cur);
+      }
+      // spending
+      if (SPEND_SUBTYPES.has(type) && e.content && e.content.amount && Number.isFinite(e.content.amount.value)) {
+        const v = e.content.amount.value;
+        spendTotal += v;
+        const dir = e.content.amount.direction || "unknown";
+        spendByDir.set(dir, (spendByDir.get(dir) || 0) + v);
+        if (!currency && e.content.amount.currency) currency = e.content.amount.currency;
+      }
+      if (citations.length < 50) citations.push(e.id);
+    }
+
+    const byAppArr = [...byApp.entries()].map(([app, count]) => ({ app, count })).sort((a, b) => b.count - a.count);
+    const topContacts = [...contacts.entries()]
+      .map(([personId, v]) => ({
+        personId,
+        name: this._lookupName(personId),
+        interactions: v.interactions,
+        byApp: Object.fromEntries(v.byApp),
+      }))
+      .sort((a, b) => b.interactions - a.interactions)
+      .slice(0, topN);
+
+    const summary = {
+      totalEvents: events.length,
+      appsActive: byApp.size,
+      period: { since: since || null, until: until || null },
+      topAppName: byAppArr.length ? byAppArr[0].app : null,
+    };
+
+    const result = {
+      skill: "analysis.overview",
+      summary,
+      byApp: byAppArr,
+      byType: [...byType.entries()].map(([type, count]) => ({ type, count })).sort((a, b) => b.count - a.count),
+      monthlyActivity: [...byMonth.entries()].map(([monthKey, count]) => ({ monthKey, count })).sort((a, b) => a.monthKey.localeCompare(b.monthKey)),
+      topContacts,
+      spending: {
+        total: Math.round(spendTotal * 100) / 100,
+        byDirection: Object.fromEntries(spendByDir),
+        currency: currency || null,
+      },
+      citations,
+      llm_commentary: null,
+    };
+
+    if (options.commentary !== false && this.llm && events.length > 0) {
+      result.llm_commentary = await this._commentary(result, options);
+    }
+    return result;
+  }
+
+  _canon(personId) {
+    const members = this.expandToMergeGroup(personId);
+    if (!members || members.length === 0) return personId;
+    // canonical = smallest id (stable across the group)
+    return [...members].sort()[0];
+  }
+
+  _lookupName(personId) {
+    try {
+      if (typeof this.vault.getPerson === "function") {
+        const p = this.vault.getPerson(personId);
+        if (p && Array.isArray(p.names) && p.names.length) return p.names[0];
+      }
+    } catch (_e) { /* optional */ }
+    return null;
+  }
+
+  async _commentary(result, options) {
+    const apps = result.byApp.slice(0, 5).map((a) => `${a.app}(${a.count})`).join(", ");
+    const types = result.byType.slice(0, 5).map((t) => `${t.type}(${t.count})`).join(", ");
+    const msg = `用户跨 ${result.summary.appsActive} 个 app 的数据汇总：
+- 共 ${result.summary.totalEvents} 条事件；活跃 app(Top5): ${apps}
+- 事件类型(Top5): ${types}
+- 跨 app 消费合计: ${result.spending.total} ${result.spending.currency || ""}
+- 高频联系人数: ${result.topContacts.length}
+请用 3-4 句话，从「为个人决策提供依据」的角度，概括其数字生活重心与可关注点。中文。`;
+    return await this.callLlmCommentary([
+      { role: "system", content: "你是个人数据中台的跨 app 洞察助手，基于事实给决策参考，克制不臆测。" },
+      { role: "user", content: msg },
+    ], { acceptNonLocal: options.acceptNonLocal });
+  }
+}
+
+module.exports = { OverviewSkill };

package/lib/analysis.js

@@ -22,6 +22,7 @@
 "use strict";
 
 const { parseQuery, extractEntityTerm, extractPersonNameCandidate } = require("./query-parser");
+const { OverviewSkill } = require("./analysis-skills/overview");
 const {
   buildPrompt,
   parseCitations,
@@ -212,6 +213,27 @@ class AnalysisEngine {
       }
     }
 
+    // Optional cross-app overview context (opt-in via options.crossApp) — runs
+    // the OverviewSkill aggregation and injects a compact summary so the LLM
+    // can answer cross-app / decision questions grounded in ALL apps' data.
+    let crossAppOverview;
+    if (options.crossApp) {
+      try {
+        const ov = await new OverviewSkill({ vault: this.vault }).run({
+          commentary: false,
+          topN: 5,
+          ...(parsed.timeWindow &&
+          Number.isFinite(parsed.timeWindow.since) &&
+          Number.isFinite(parsed.timeWindow.until)
+            ? { since: parsed.timeWindow.since, until: parsed.timeWindow.until }
+            : {}),
+        });
+        crossAppOverview = formatCrossAppOverview(ov);
+      } catch (_e) {
+        /* overview is best-effort context; never abort the ask */
+      }
+    }
+
     // Build prompt.
     const { messages, factIds, factCount, truncated } = buildPrompt({
       question,
@@ -223,6 +245,7 @@ class AnalysisEngine {
       vaultTotals: this._gatherVaultTotals(),
       amountSummary:
         parsed.intent === "sum-amount" ? this._gatherAmountSummary(parsed) : undefined,
+      crossAppOverview,
     });
 
     // Telemetry: post-cap prompt size + truncation count. If `truncated` > 0
@@ -820,8 +843,35 @@ class AnalysisEngine {
   }
 }
 
+/**
+ * Compact, prompt-friendly rendering of an OverviewSkill result for the
+ * CROSS_APP_OVERVIEW context block. Aggregate signals only (no raw content).
+ */
+function formatCrossAppOverview(ov) {
+  if (!ov || !ov.summary) return null;
+  const top = (arr, k, v) =>
+    (arr || []).slice(0, 5).map((x) => `${x[k]}(${x[v]})`).join(", ") || "无";
+  const lines = [
+    `共 ${ov.summary.totalEvents} 事件，跨 ${ov.summary.appsActive} 个 app`,
+    `活跃 app(Top): ${top(ov.byApp, "app", "count")}`,
+    `事件类型(Top): ${top(ov.byType, "type", "count")}`,
+  ];
+  if (ov.spending && Number.isFinite(ov.spending.total) && ov.spending.total !== 0) {
+    lines.push(`跨 app 消费合计: ${ov.spending.total} ${ov.spending.currency || ""}`.trim());
+  }
+  if (Array.isArray(ov.topContacts) && ov.topContacts.length > 0) {
+    const c = ov.topContacts
+      .slice(0, 5)
+      .map((x) => `${x.name || x.personId}(${x.interactions})`)
+      .join(", ");
+    lines.push(`高频联系人(Top): ${c}`);
+  }
+  return lines.join("\n");
+}
+
 module.exports = {
   AnalysisEngine,
+  formatCrossAppOverview,
   DEFAULT_MAX_FACTS,
   DEFAULT_MAX_QUERY_LIMIT,
   LATEST_INTENT_FACT_LIMIT,

package/lib/forensics/leaf-salvage.js

@@ -0,0 +1,185 @@
+"use strict";
+/*
+ * PDH SQLite leaf-page record salvager — library form.
+ *
+ * Method B (`/proc/<pid>/mem` 内存扫描) dumps decrypted pages, but for DBs whose
+ * page cache is SCATTERED (not contiguous mmap) the rebuilt file is "malformed"
+ * (valid header, broken b-tree). This salvages the DATA anyway: it scans a dump
+ * (or concatenated dumps) for SQLite **table b-tree leaf pages** (type 0x0D) and
+ * parses each page's records directly — order-independent, exactly what sqlite3
+ * `.recover` does, but standalone (platform-tools sqlite3 lacks .recover).
+ *
+ * This file is the bundle-able home for the parser; the standalone CLI tool
+ * `scripts/android/pdh-sqlite-leaf-salvage.js` re-exports from here. Lives in
+ * pdh lib so the Android cc bundle (and `cc hub salvage`) can call it on-device.
+ *
+ * Output: array of {rowid, cols:[...]} — raw positional column tuples (leaf
+ * pages carry no column names). Map to a schema downstream (salvage-mapper.js).
+ *
+ * Authorization: only on data you are entitled to (your own device/account).
+ * Docs: docs/internal/pdh-db-decryption-runbook.md (Method B + reconstruction).
+ */
+const fs = require("node:fs");
+
+function readVarint(buf, off) {
+  // SQLite varint: up to 9 bytes, big-endian, high bit = continuation.
+  let result = 0n;
+  let i = 0;
+  for (; i < 8; i++) {
+    const b = buf[off + i];
+    if (b === undefined) return [null, off + i];
+    result = (result << 7n) | BigInt(b & 0x7f);
+    if ((b & 0x80) === 0) return [result, off + i + 1];
+  }
+  // 9th byte uses all 8 bits
+  const b9 = buf[off + 8];
+  if (b9 === undefined) return [null, off + 9];
+  result = (result << 8n) | BigInt(b9);
+  return [result, off + 9];
+}
+
+function serialTypeSize(t) {
+  // t is a BigInt
+  const n = Number(t);
+  if (n === 0 || n === 8 || n === 9 || n === 12 || n === 13) {
+    return n >= 12 ? (n % 2 === 0 ? (n - 12) / 2 : (n - 13) / 2) : 0;
+  }
+  if (n === 1) return 1;
+  if (n === 2) return 2;
+  if (n === 3) return 3;
+  if (n === 4) return 4;
+  if (n === 5) return 6;
+  if (n === 6) return 8;
+  if (n === 7) return 8;
+  if (n >= 12) return n % 2 === 0 ? (n - 12) / 2 : (n - 13) / 2;
+  return 0;
+}
+
+function readValue(buf, off, t) {
+  const n = Number(t);
+  const sz = serialTypeSize(t);
+  if (n === 0) return [null, off];
+  if (n === 8) return [0, off];
+  if (n === 9) return [1, off];
+  if (n >= 1 && n <= 6) {
+    let v = 0n;
+    for (let i = 0; i < sz; i++) v = (v << 8n) | BigInt(buf[off + i] || 0);
+    // sign-extend
+    const bits = BigInt(sz * 8);
+    if (v >= 1n << (bits - 1n)) v -= 1n << bits;
+    const num = Number(v);
+    return [Number.isSafeInteger(num) ? num : v.toString(), off + sz];
+  }
+  if (n === 7) return [buf.readDoubleBE(off), off + 8];
+  if (n >= 13 && n % 2 === 1) {
+    // text
+    return [buf.toString("utf8", off, off + sz), off + sz];
+  }
+  // blob (n>=12 even) — return length marker, not raw bytes
+  return [`<blob:${sz}>`, off + sz];
+}
+
+// Parse one table-leaf page at `base`. Returns array of {rowid, cols} or null.
+function parseLeafPage(buf, base, pageSize, minCols) {
+  if (buf[base] !== 0x0d) return null; // 0x0D = table b-tree leaf
+  if (base + pageSize > buf.length) return null;
+  const numCells = (buf[base + 3] << 8) | buf[base + 4];
+  if (numCells <= 0 || numCells > Math.floor(pageSize / 4)) return null;
+  // cell-content-start (bytes 5-6; 0 means 65536) — must sit after the cell
+  // pointer array and within the page. This guard rejects the false positives a
+  // finer (unaligned) stride would otherwise hit on random 0x0D bytes.
+  let cellStart = (buf[base + 5] << 8) | buf[base + 6];
+  if (cellStart === 0) cellStart = 65536;
+  const hdrEndMin = 8 + numCells * 2;
+  if (cellStart < hdrEndMin || cellStart > pageSize) return null;
+  const out = [];
+  const ptrBase = base + 8;
+  for (let c = 0; c < numCells; c++) {
+    const ptr = (buf[ptrBase + c * 2] << 8) | buf[ptrBase + c * 2 + 1];
+    if (ptr < 8 || ptr >= pageSize) continue;
+    let off = base + ptr;
+    try {
+      const [payloadLen, o1] = readVarint(buf, off); off = o1;
+      if (payloadLen === null || payloadLen <= 0n || payloadLen > BigInt(pageSize)) continue;
+      const [rowid, o2] = readVarint(buf, off); off = o2;
+      // record header
+      const recStart = off;
+      const [hdrLen, o3] = readVarint(buf, off); off = o3;
+      if (hdrLen === null || hdrLen <= 0n) continue;
+      const hdrEnd = recStart + Number(hdrLen);
+      const serials = [];
+      while (off < hdrEnd) {
+        const [st, oN] = readVarint(buf, off); off = oN;
+        if (st === null) break;
+        serials.push(st);
+      }
+      let vOff = hdrEnd;
+      const cols = [];
+      for (const st of serials) {
+        const [val, vN] = readValue(buf, vOff, st);
+        cols.push(val); vOff = vN;
+      }
+      if (cols.length >= minCols) out.push({ rowid: rowid === null ? null : rowid.toString(), cols });
+    } catch (_e) { /* skip malformed cell */ }
+  }
+  return out.length ? out : null;
+}
+
+/**
+ * Scan an in-memory dump buffer for table-leaf pages and return all salvaged
+ * records (deduped). Engine-agnostic — works on any decrypted-page dump.
+ *
+ * @param {Buffer} buf
+ * @param {{pageSize?: number, minCols?: number, unaligned?: boolean, stride?: number}} [opts]
+ *   - pageSize: SQLite page size (default 4096)
+ *   - minCols:  drop records with fewer columns (default 3)
+ *   - unaligned: scan at a finer stride (512) to catch pages not 4096-aligned
+ *     in a malloc'd page cache; ~8x slower, recovers pages the aligned scan
+ *     misses. The strengthened header validation rejects the extra false
+ *     positives.
+ *   - stride: explicit scan stride (overrides the unaligned default)
+ * @returns {{records: Array<{rowid: string|null, cols: any[]}>, pages: number}}
+ */
+function salvageBuffer(buf, opts = {}) {
+  if (!Buffer.isBuffer(buf)) {
+    throw new TypeError("salvageBuffer: buf must be a Buffer");
+  }
+  const pageSize = Number.isFinite(opts.pageSize) && opts.pageSize > 0 ? opts.pageSize : 4096;
+  const minCols = Number.isFinite(opts.minCols) && opts.minCols >= 0 ? opts.minCols : 3;
+  const unaligned = !!opts.unaligned;
+  const stride = Number.isFinite(opts.stride) && opts.stride > 0
+    ? opts.stride
+    : (unaligned ? 512 : pageSize);
+
+  let pages = 0;
+  const records = [];
+  const seen = new Set(); // dedup overlapping finds
+  for (let base = 0; base + 8 <= buf.length; base += stride) {
+    if (buf[base] !== 0x0d) continue; // cheap pre-filter before full parse
+    const recs = parseLeafPage(buf, base, pageSize, minCols);
+    if (!recs) continue;
+    pages++;
+    for (const r of recs) {
+      const key = r.rowid + " " + JSON.stringify(r.cols);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      records.push(r);
+    }
+  }
+  return { records, pages };
+}
+
+/** Read a dump file and salvage records from it. See {@link salvageBuffer}. */
+function salvageFile(filePath, opts = {}) {
+  const buf = fs.readFileSync(filePath);
+  return salvageBuffer(buf, opts);
+}
+
+module.exports = {
+  readVarint,
+  serialTypeSize,
+  readValue,
+  parseLeafPage,
+  salvageBuffer,
+  salvageFile,
+};