@chainlesschain/personal-data-hub 0.1.0 → 0.2.1

package/lib/vault.js

@@ -37,6 +37,13 @@ const DEFAULT_CIPHER_PAGE_SIZE = 4096;
 
 // ─── Helpers ─────────────────────────────────────────────────────────────
 
+function newGroupId() {
+  // Lightweight uuid v4-ish for merge_groups.id. Doesn't need crypto
+  // strength — uniqueness within one user's vault is enough.
+  const r = () => Math.random().toString(16).slice(2, 10);
+  return `mg-${r()}${r()}-${Date.now().toString(36)}`;
+}
+
 function loadDriver() {
   // Lazy require so consumers that only need schemas don't pay for the
   // native binding load. Errors surface here with a precise message.
@@ -598,6 +605,83 @@ class LocalVault {
       .map((row) => this._rowToEvent(row));
   }
 
+  /**
+   * queryPersons — list person entities (contacts, family, colleagues...).
+   * Phase 14.x Path C — needed so AnalysisEngine can answer questions about
+   * "how many contacts" / "did I call mom last week" without missing the
+   * persons-table half of the world.
+   *
+   * @param {object} q
+   * @param {string} [q.subtype]   e.g. "contact" / "family" / "colleague"
+   * @param {string} [q.adapter]   source_adapter filter
+   * @param {number} [q.limit=100]
+   * @param {number} [q.offset=0]
+   */
+  queryPersons(q = {}) {
+    const where = [];
+    const params = {};
+    if (q.subtype) {
+      where.push("subtype = @subtype");
+      params.subtype = q.subtype;
+    }
+    if (q.adapter) {
+      where.push("source_adapter = @adapter");
+      params.adapter = q.adapter;
+    }
+    const limit = Number.isInteger(q.limit) && q.limit > 0 ? Math.min(q.limit, 10000) : 100;
+    const offset = Number.isInteger(q.offset) && q.offset >= 0 ? q.offset : 0;
+    params.limit = limit;
+    params.offset = offset;
+    const sql =
+      "SELECT * FROM persons" +
+      (where.length ? " WHERE " + where.join(" AND ") : "") +
+      " ORDER BY ingested_at DESC LIMIT @limit OFFSET @offset";
+    return this._requireOpen()
+      .prepare(sql)
+      .all(params)
+      .map((row) => this._rowToPerson(row));
+  }
+
+  /**
+   * queryItems — list item entities (installed apps, purchases, media...).
+   * Pairs with queryPersons for AnalysisEngine fact gathering.
+   *
+   * @param {object} q
+   * @param {string} [q.subtype]
+   * @param {string} [q.adapter]
+   * @param {string} [q.category]
+   * @param {number} [q.limit=100]
+   * @param {number} [q.offset=0]
+   */
+  queryItems(q = {}) {
+    const where = [];
+    const params = {};
+    if (q.subtype) {
+      where.push("subtype = @subtype");
+      params.subtype = q.subtype;
+    }
+    if (q.adapter) {
+      where.push("source_adapter = @adapter");
+      params.adapter = q.adapter;
+    }
+    if (q.category) {
+      where.push("category = @category");
+      params.category = q.category;
+    }
+    const limit = Number.isInteger(q.limit) && q.limit > 0 ? Math.min(q.limit, 10000) : 100;
+    const offset = Number.isInteger(q.offset) && q.offset >= 0 ? q.offset : 0;
+    params.limit = limit;
+    params.offset = offset;
+    const sql =
+      "SELECT * FROM items" +
+      (where.length ? " WHERE " + where.join(" AND ") : "") +
+      " ORDER BY ingested_at DESC LIMIT @limit OFFSET @offset";
+    return this._requireOpen()
+      .prepare(sql)
+      .all(params)
+      .map((row) => this._rowToItem(row));
+  }
+
   countEvents(q = {}) {
     const where = [];
     const params = {};
@@ -716,6 +800,9 @@ class LocalVault {
   stats() {
     const db = this._requireOpen();
     const count = (tbl) => db.prepare(`SELECT COUNT(*) as n FROM ${tbl}`).get().n;
+    const safeCount = (tbl) => {
+      try { return count(tbl); } catch (_e) { return 0; }
+    };
     return {
       schemaVersion: getSchemaVersion(db),
       events: count("events"),
@@ -726,9 +813,265 @@ class LocalVault {
       rawEvents: count("raw_events"),
       auditLog: count("audit_log"),
       watermarks: count("sync_watermarks"),
+      // Phase 8 — EntityResolver tables (safeCount because v1 vaults
+      // don't have these yet until migrate).
+      mergeGroups: safeCount("merge_groups"),
+      mergeMembers: safeCount("merge_members"),
+      resolveQueue: safeCount("resolve_queue"),
+      reviewQueue: safeCount("review_queue"),
+      resolveDecisions: safeCount("resolve_decisions"),
     };
   }
 
+  // ─── Phase 8 EntityResolver helpers ───────────────────────────────────
+
+  /**
+   * Insert a new pending row into resolve_queue. Idempotent — already-
+   * pending rows for the same person are not duplicated. Returns the
+   * row id (existing or newly inserted).
+   */
+  enqueueResolve(personId) {
+    if (typeof personId !== "string" || personId.length === 0) {
+      throw new Error("enqueueResolve: personId required");
+    }
+    const db = this._requireOpen();
+    const existing = db.prepare(
+      "SELECT id FROM resolve_queue WHERE person_id = ? AND status IN ('pending','in-progress')"
+    ).get(personId);
+    if (existing) return existing.id;
+    const info = db.prepare(
+      "INSERT INTO resolve_queue (person_id, enqueued_at, status) VALUES (?, ?, 'pending')"
+    ).run(personId, Date.now());
+    return info.lastInsertRowid;
+  }
+
+  /**
+   * Pull up to `limit` pending rows + atomically mark them in-progress.
+   * Returns [{id, person_id, attempts}, ...].
+   */
+  claimResolveBatch(limit = 50) {
+    const db = this._requireOpen();
+    const tx = db.transaction(() => {
+      const rows = db.prepare(
+        "SELECT id, person_id, attempts FROM resolve_queue WHERE status = 'pending' ORDER BY enqueued_at LIMIT ?"
+      ).all(limit);
+      if (rows.length === 0) return [];
+      const stmt = db.prepare(
+        "UPDATE resolve_queue SET status = 'in-progress', attempts = attempts + 1 WHERE id = ?"
+      );
+      for (const r of rows) stmt.run(r.id);
+      return rows;
+    });
+    return tx();
+  }
+
+  /**
+   * Mark a resolve_queue row as done (success path).
+   */
+  completeResolve(queueId) {
+    const db = this._requireOpen();
+    db.prepare("UPDATE resolve_queue SET status = 'done' WHERE id = ?").run(queueId);
+  }
+
+  /**
+   * Mark a resolve_queue row as errored (retry-eligible if attempts < 3).
+   */
+  errorResolve(queueId, errMsg) {
+    const db = this._requireOpen();
+    // If attempts < 3, leave status 'pending' for retry; else 'error'
+    db.prepare(
+      `UPDATE resolve_queue
+         SET status = CASE WHEN attempts >= 3 THEN 'error' ELSE 'pending' END,
+             last_error = ?
+       WHERE id = ?`
+    ).run(errMsg || "unknown", queueId);
+  }
+
+  /**
+   * Record a resolve_decisions row. Lex-orders the two ids so each pair
+   * is stored only once. Returns inserted-or-updated row.
+   */
+  recordResolveDecision({ aId, bId, verdict, confidence, decidedBy, reason }) {
+    const db = this._requireOpen();
+    const [lo, hi] = aId < bId ? [aId, bId] : [bId, aId];
+    db.prepare(
+      `INSERT INTO resolve_decisions
+         (a_person_id, b_person_id, verdict, confidence, decided_at, decided_by, reason)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(a_person_id, b_person_id) DO UPDATE SET
+         verdict = excluded.verdict,
+         confidence = excluded.confidence,
+         decided_at = excluded.decided_at,
+         decided_by = excluded.decided_by,
+         reason = excluded.reason`
+    ).run(lo, hi, verdict, confidence, Date.now(), decidedBy || "rule", reason || null);
+  }
+
+  getResolveDecision(aId, bId) {
+    const db = this._requireOpen();
+    const [lo, hi] = aId < bId ? [aId, bId] : [bId, aId];
+    return db.prepare(
+      "SELECT * FROM resolve_decisions WHERE a_person_id = ? AND b_person_id = ?"
+    ).get(lo, hi);
+  }
+
+  /**
+   * Merge a pair into a merge_group. If either side already belongs to a
+   * group, the other side joins it (and the two groups merge if both
+   * already existed). Returns the resulting group_id.
+   */
+  mergePair({ aId, bId, joinedBy = "rule" }) {
+    const db = this._requireOpen();
+    const tx = db.transaction(() => {
+      const aGroup = db.prepare("SELECT group_id FROM merge_members WHERE person_id = ?").get(aId);
+      const bGroup = db.prepare("SELECT group_id FROM merge_members WHERE person_id = ?").get(bId);
+      const now = Date.now();
+
+      if (aGroup && bGroup && aGroup.group_id === bGroup.group_id) {
+        return aGroup.group_id; // already same group
+      }
+      if (aGroup && bGroup) {
+        // Merge two existing groups → keep aGroup, move bGroup members in
+        db.prepare(
+          "UPDATE merge_members SET group_id = ? WHERE group_id = ?"
+        ).run(aGroup.group_id, bGroup.group_id);
+        db.prepare("DELETE FROM merge_groups WHERE id = ?").run(bGroup.group_id);
+        db.prepare(
+          "UPDATE merge_groups SET member_count = (SELECT COUNT(*) FROM merge_members WHERE group_id = ?), last_updated = ? WHERE id = ?"
+        ).run(aGroup.group_id, now, aGroup.group_id);
+        return aGroup.group_id;
+      }
+      if (aGroup) {
+        // Add b to a's group
+        db.prepare(
+          "INSERT INTO merge_members (group_id, person_id, joined_at, joined_by) VALUES (?, ?, ?, ?)"
+        ).run(aGroup.group_id, bId, now, joinedBy);
+        db.prepare(
+          "UPDATE merge_groups SET member_count = member_count + 1, last_updated = ? WHERE id = ?"
+        ).run(now, aGroup.group_id);
+        return aGroup.group_id;
+      }
+      if (bGroup) {
+        db.prepare(
+          "INSERT INTO merge_members (group_id, person_id, joined_at, joined_by) VALUES (?, ?, ?, ?)"
+        ).run(bGroup.group_id, aId, now, joinedBy);
+        db.prepare(
+          "UPDATE merge_groups SET member_count = member_count + 1, last_updated = ? WHERE id = ?"
+        ).run(now, bGroup.group_id);
+        return bGroup.group_id;
+      }
+      // Neither in any group — create new
+      const groupId = newGroupId();
+      db.prepare(
+        "INSERT INTO merge_groups (id, primary_id, member_count, created_at, last_updated) VALUES (?, ?, 2, ?, ?)"
+      ).run(groupId, aId, now, now);
+      const ins = db.prepare(
+        "INSERT INTO merge_members (group_id, person_id, joined_at, joined_by) VALUES (?, ?, ?, ?)"
+      );
+      ins.run(groupId, aId, now, joinedBy);
+      ins.run(groupId, bId, now, joinedBy);
+      return groupId;
+    });
+    return tx();
+  }
+
+  /**
+   * Remove a person from its merge group (unmerge). If only one member
+   * remains, the group is deleted entirely.
+   */
+  unmergePerson(personId) {
+    const db = this._requireOpen();
+    const tx = db.transaction(() => {
+      const row = db.prepare(
+        "SELECT group_id FROM merge_members WHERE person_id = ?"
+      ).get(personId);
+      if (!row) return { ok: false, reason: "not in any group" };
+      const groupId = row.group_id;
+      db.prepare("DELETE FROM merge_members WHERE person_id = ?").run(personId);
+      const remaining = db.prepare(
+        "SELECT COUNT(*) as n FROM merge_members WHERE group_id = ?"
+      ).get(groupId).n;
+      if (remaining < 2) {
+        // Group of 1 or 0 — delete the group + remaining member row
+        db.prepare("DELETE FROM merge_members WHERE group_id = ?").run(groupId);
+        db.prepare("DELETE FROM merge_groups WHERE id = ?").run(groupId);
+      } else {
+        db.prepare(
+          "UPDATE merge_groups SET member_count = ?, last_updated = ? WHERE id = ?"
+        ).run(remaining, Date.now(), groupId);
+      }
+      return { ok: true, groupId, remaining };
+    });
+    return tx();
+  }
+
+  /**
+   * Get all person ids in the same merge group as the given person.
+   * Returns [personId, ...] including the input (whether or not it's in
+   * a group — a "group of 1" is just `[personId]`).
+   */
+  getMergeGroupMembers(personId) {
+    const db = this._requireOpen();
+    const groupRow = db.prepare(
+      "SELECT group_id FROM merge_members WHERE person_id = ?"
+    ).get(personId);
+    if (!groupRow) return [personId];
+    return db.prepare(
+      "SELECT person_id FROM merge_members WHERE group_id = ? ORDER BY joined_at"
+    ).all(groupRow.group_id).map((r) => r.person_id);
+  }
+
+  /**
+   * Insert a row into review_queue when the LLM stage returns "maybe".
+   * UI lists these for user one-click decisions.
+   */
+  enqueueReview({ aId, bId, embedSim, llmVerdict, llmReason, llmConfidence }) {
+    const db = this._requireOpen();
+    const [lo, hi] = aId < bId ? [aId, bId] : [bId, aId];
+    const info = db.prepare(
+      `INSERT INTO review_queue
+         (a_person_id, b_person_id, embed_sim, llm_verdict, llm_reason, llm_confidence, enqueued_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`
+    ).run(lo, hi, embedSim || null, llmVerdict || null, llmReason || null, llmConfidence || null, Date.now());
+    return info.lastInsertRowid;
+  }
+
+  /**
+   * List pending review rows (oldest first).
+   */
+  listReviewQueue({ limit = 50 } = {}) {
+    const db = this._requireOpen();
+    return db.prepare(
+      "SELECT * FROM review_queue WHERE reviewed_at IS NULL ORDER BY enqueued_at ASC LIMIT ?"
+    ).all(Math.min(limit, 1000));
+  }
+
+  /**
+   * Mark a review row as decided by the user.
+   */
+  recordReviewDecision({ reviewId, decision }) {
+    if (!["same", "different", "skip"].includes(decision)) {
+      throw new Error(`invalid review decision: ${decision}`);
+    }
+    const db = this._requireOpen();
+    const row = db.prepare("SELECT * FROM review_queue WHERE id = ?").get(reviewId);
+    if (!row) throw new Error(`review row ${reviewId} not found`);
+    db.prepare(
+      "UPDATE review_queue SET reviewed_at = ?, user_decision = ? WHERE id = ?"
+    ).run(Date.now(), decision, reviewId);
+    return row;
+  }
+
+  resolveQueueStats() {
+    const db = this._requireOpen();
+    const rows = db.prepare(
+      "SELECT status, COUNT(*) as n FROM resolve_queue GROUP BY status"
+    ).all();
+    const out = { pending: 0, "in-progress": 0, done: 0, error: 0 };
+    for (const r of rows) out[r.status] = r.n;
+    return out;
+  }
+
   // ─── Key rotation ──────────────────────────────────────────────────────
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chainlesschain/personal-data-hub",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Personal Data Hub — UnifiedSchema + validators + KG ingest helpers for the data-back-to-the-individual middleware",
   "type": "commonjs",
   "main": "lib/index.js",
@@ -26,7 +26,38 @@
     "./bridges/cc-llm-adapter": "./lib/bridges/cc-llm-adapter.js",
     "./bridges/cc-kg-sink": "./lib/bridges/cc-kg-sink.js",
     "./bridges/cc-rag-sink": "./lib/bridges/cc-rag-sink.js",
-    "./adapters/email-imap": "./lib/adapters/email-imap/index.js"
+    "./adapters/email-imap": "./lib/adapters/email-imap/index.js",
+    "./adapters/alipay-bill": "./lib/adapters/alipay-bill/index.js",
+    "./adapters/system-data": "./lib/adapters/system-data/index.js",
+    "./adapters/system-data-android": "./lib/adapters/system-data-android/index.js",
+    "./entity-resolver": "./lib/entity-resolver/index.js",
+    "./analysis-skills": "./lib/analysis-skills/index.js",
+    "./mobile-extractor": "./lib/mobile-extractor/index.js",
+    "./adapters/wechat": "./lib/adapters/wechat/index.js",
+    "./adapters/ai-chat-history": "./lib/adapters/ai-chat-history/index.js",
+    "./adapters/ai-chat-history/cookie-capture-spec": "./lib/adapters/ai-chat-history/cookie-capture-spec.js",
+    "./adapters/ai-chat-history/wizard-controller": "./lib/adapters/ai-chat-history/wizard-controller.js",
+    "./adapters/ai-chat-history/health-checker": "./lib/adapters/ai-chat-history/health-checker.js",
+    "./lib/adapters/ai-chat-history/cookie-capture-spec": "./lib/adapters/ai-chat-history/cookie-capture-spec.js",
+    "./lib/adapters/ai-chat-history/wizard-controller": "./lib/adapters/ai-chat-history/wizard-controller.js",
+    "./lib/adapters/ai-chat-history/health-checker": "./lib/adapters/ai-chat-history/health-checker.js",
+    "./adapters/travel-base": "./lib/adapters/travel-base/index.js",
+    "./adapters/travel-12306": "./lib/adapters/travel-12306/index.js",
+    "./adapters/travel-ctrip": "./lib/adapters/travel-ctrip/index.js",
+    "./adapters/travel-amap": "./lib/adapters/travel-amap/index.js",
+    "./adapters/travel-baidu-map": "./lib/adapters/travel-baidu-map/index.js",
+    "./adapters/shopping-base": "./lib/adapters/shopping-base/index.js",
+    "./adapters/shopping-taobao": "./lib/adapters/shopping-taobao/index.js",
+    "./adapters/shopping-jd": "./lib/adapters/shopping-jd/index.js",
+    "./adapters/shopping-meituan": "./lib/adapters/shopping-meituan/index.js",
+    "./adapters/social-bilibili": "./lib/adapters/social-bilibili/index.js",
+    "./adapters/social-weibo": "./lib/adapters/social-weibo/index.js",
+    "./adapters/social-douyin": "./lib/adapters/social-douyin/index.js",
+    "./adapters/social-xiaohongshu": "./lib/adapters/social-xiaohongshu/index.js",
+    "./adapters/messaging-qq": "./lib/adapters/messaging-qq/index.js",
+    "./adapters/messaging-telegram": "./lib/adapters/messaging-telegram/index.js",
+    "./adapters/messaging-whatsapp": "./lib/adapters/messaging-whatsapp/index.js",
+    "./sidecar": "./lib/sidecar/index.js"
   },
   "scripts": {
     "test": "vitest run",
@@ -55,7 +86,9 @@
     "mailparser": "^3.7.1"
   },
   "optionalDependencies": {
-    "imapflow": "^1.0.183"
+    "imapflow": "^1.0.183",
+    "adm-zip": "^0.5.16",
+    "iconv-lite": "^0.6.3"
   },
   "devDependencies": {
     "vitest": "^4.1.5"

package/scripts/_make-fixture-all.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * Build a complete fixture directory with all 4 system-data sources:
+ *
+ *   <out>/
+ *     contacts2.db          (raw_contacts + data + mimetypes)
+ *     mmssms.db             (sms)
+ *     wifi/
+ *       WifiConfigStore.xml
+ *
+ * Usage:
+ *   node scripts/_make-fixture-all.js ./fixtures
+ */
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const Database = require("better-sqlite3-multiple-ciphers");
+
+const outDir = path.resolve(process.argv[2] || "./fixtures");
+fs.mkdirSync(path.join(outDir, "wifi"), { recursive: true });
+
+// ── contacts2.db ──────────────────────────────────────────────────────────
+const contactsPath = path.join(outDir, "contacts2.db");
+if (fs.existsSync(contactsPath)) fs.unlinkSync(contactsPath);
+const contacts = new Database(contactsPath);
+contacts.exec(`
+  CREATE TABLE raw_contacts (
+    _id INTEGER PRIMARY KEY, display_name TEXT, starred INTEGER DEFAULT 0, deleted INTEGER DEFAULT 0
+  );
+  CREATE TABLE mimetypes (_id INTEGER PRIMARY KEY, mimetype TEXT NOT NULL UNIQUE);
+  CREATE TABLE data (
+    _id INTEGER PRIMARY KEY, raw_contact_id INTEGER NOT NULL, mimetype_id INTEGER NOT NULL, data1 TEXT
+  );
+  CREATE TABLE calls (
+    _id INTEGER PRIMARY KEY, number TEXT, type INTEGER, duration INTEGER, date INTEGER, name TEXT, is_read INTEGER DEFAULT 1
+  );
+`);
+const MT = { phone: 5, email: 1, org: 4, note: 10, photo: 14 };
+const mi = contacts.prepare("INSERT INTO mimetypes (_id, mimetype) VALUES (?, ?)");
+mi.run(MT.phone, "vnd.android.cursor.item/phone_v2");
+mi.run(MT.email, "vnd.android.cursor.item/email_v2");
+mi.run(MT.org, "vnd.android.cursor.item/organization");
+mi.run(MT.note, "vnd.android.cursor.item/note");
+mi.run(MT.photo, "vnd.android.cursor.item/photo");
+const ci = contacts.prepare(
+  "INSERT INTO raw_contacts (_id, display_name, starred, deleted) VALUES (?, ?, ?, 0)",
+);
+ci.run(1, "妈妈", 1);
+ci.run(2, "张三", 0);
+ci.run(3, "李四 Manager", 0);
+ci.run(5, "工商银行客服", 0);
+const di = contacts.prepare(
+  "INSERT INTO data (raw_contact_id, mimetype_id, data1) VALUES (?, ?, ?)",
+);
+di.run(1, MT.phone, "13800001111");
+di.run(1, MT.phone, "13900002222");
+di.run(1, MT.email, "mom@example.com");
+di.run(1, MT.note, "亲妈，过年回家");
+di.run(2, MT.phone, "13711112222");
+di.run(3, MT.phone, "13822223333");
+di.run(3, MT.email, "lisi@corp.example.com");
+di.run(3, MT.org, "Example Corp");
+di.run(5, MT.phone, "95588");
+// Calls table inside contacts2.db (pre-Android-11 location)
+const li = contacts.prepare(
+  "INSERT INTO calls (_id, number, type, duration, date, name, is_read) VALUES (?, ?, ?, ?, ?, ?, ?)",
+);
+li.run(1, "13800001111", 1, 120, 1737000000000, "妈妈", 1);
+li.run(2, "13800001111", 2, 45, 1737010000000, "妈妈", 1);
+li.run(3, "13999998888", 3, 0, 1737020000000, "", 0);
+li.run(4, "10086", 1, 8, 1737030000000, "中国移动", 1);
+contacts.close();
+console.log("wrote:", contactsPath);
+
+// ── mmssms.db ─────────────────────────────────────────────────────────────
+const smsPath = path.join(outDir, "mmssms.db");
+if (fs.existsSync(smsPath)) fs.unlinkSync(smsPath);
+const sms = new Database(smsPath);
+sms.exec(`
+  CREATE TABLE sms (
+    _id INTEGER PRIMARY KEY, thread_id INTEGER, address TEXT, body TEXT,
+    type INTEGER, date INTEGER, read INTEGER
+  );
+`);
+const si = sms.prepare(
+  "INSERT INTO sms (_id, thread_id, address, body, type, date, read) VALUES (?, ?, ?, ?, ?, ?, ?)",
+);
+si.run(1, 100, "13800001111", "妈妈我到家了", 2, 1737000000000, 1);
+si.run(2, 100, "13800001111", "好的，注意安全", 1, 1737000010000, 1);
+si.run(3, 200, "10086", "【中国移动】您的话费余额为 ¥36.50", 1, 1737000020000, 1);
+si.run(4, 300, "95588", "【工商银行】您的验证码为 123456，3 分钟内有效", 1, 1737000030000, 0);
+sms.close();
+console.log("wrote:", smsPath);
+
+// ── wifi/WifiConfigStore.xml ──────────────────────────────────────────────
+const wifiXml = path.join(outDir, "wifi", "WifiConfigStore.xml");
+fs.writeFileSync(
+  wifiXml,
+  `<?xml version='1.0' encoding='UTF-8'?>
+<WifiConfigStoreData>
+  <NetworkList>
+    <Network>
+      <WifiConfiguration>
+        <string name="SSID">"Home_5G"</string>
+        <string name="PreSharedKey">"secret"</string>
+        <string name="KeyMgmt">WPA-PSK</string>
+        <boolean name="HiddenSSID">false</boolean>
+      </WifiConfiguration>
+    </Network>
+    <Network>
+      <WifiConfiguration>
+        <string name="SSID">"Starbucks Free"</string>
+        <string name="KeyMgmt">NONE</string>
+        <boolean name="HiddenSSID">false</boolean>
+      </WifiConfiguration>
+    </Network>
+  </NetworkList>
+</WifiConfigStoreData>
+`,
+  "utf-8",
+);
+console.log("wrote:", wifiXml);
+
+console.log("\nAll fixtures ready under:", outDir);

package/scripts/_make-fixture-contacts.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Build a synthetic Android contacts2.db at the given path.
+ *
+ * Only used by the smoke runner / docs walkthrough — production code never
+ * relies on this. Mirrors the fixture from
+ * packages/personal-data-hub-bridge/tests/test_parsers_system_contacts.py.
+ *
+ * Usage:
+ *   node scripts/_make-fixture-contacts.js ./fixtures/contacts2.db
+ */
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const Database = require("better-sqlite3-multiple-ciphers");
+
+const target = path.resolve(process.argv[2] || "./fixtures/contacts2.db");
+fs.mkdirSync(path.dirname(target), { recursive: true });
+if (fs.existsSync(target)) fs.unlinkSync(target);
+
+const db = new Database(target);
+try {
+  db.exec(`
+    CREATE TABLE raw_contacts (
+      _id INTEGER PRIMARY KEY,
+      display_name TEXT,
+      starred INTEGER DEFAULT 0,
+      deleted INTEGER DEFAULT 0
+    );
+    CREATE TABLE mimetypes (
+      _id INTEGER PRIMARY KEY,
+      mimetype TEXT NOT NULL UNIQUE
+    );
+    CREATE TABLE data (
+      _id INTEGER PRIMARY KEY,
+      raw_contact_id INTEGER NOT NULL,
+      mimetype_id INTEGER NOT NULL,
+      data1 TEXT
+    );
+  `);
+
+  const MT = {
+    phone: 5,
+    email: 1,
+    org: 4,
+    note: 10,
+    photo: 14,
+  };
+  const insertMime = db.prepare(
+    "INSERT INTO mimetypes (_id, mimetype) VALUES (?, ?)",
+  );
+  insertMime.run(MT.phone, "vnd.android.cursor.item/phone_v2");
+  insertMime.run(MT.email, "vnd.android.cursor.item/email_v2");
+  insertMime.run(MT.org, "vnd.android.cursor.item/organization");
+  insertMime.run(MT.note, "vnd.android.cursor.item/note");
+  insertMime.run(MT.photo, "vnd.android.cursor.item/photo");
+
+  const insertC = db.prepare(
+    "INSERT INTO raw_contacts (_id, display_name, starred, deleted) VALUES (?, ?, ?, 0)",
+  );
+  insertC.run(1, "妈妈", 1);
+  insertC.run(2, "张三", 0);
+  insertC.run(3, "李四 Manager", 0);
+  insertC.run(4, "", 0); // nameless — skipped by parser
+  insertC.run(5, "工商银行客服", 0);
+
+  const insertD = db.prepare(
+    "INSERT INTO data (raw_contact_id, mimetype_id, data1) VALUES (?, ?, ?)",
+  );
+  insertD.run(1, MT.phone, "13800001111");
+  insertD.run(1, MT.phone, "13900002222");
+  insertD.run(1, MT.email, "mom@example.com");
+  insertD.run(1, MT.note, "亲妈，过年回家");
+  insertD.run(2, MT.phone, "13711112222");
+  insertD.run(3, MT.phone, "13822223333");
+  insertD.run(3, MT.email, "lisi@corp.example.com");
+  insertD.run(3, MT.org, "Example Corp");
+  insertD.run(5, MT.phone, "95588");
+} finally {
+  db.close();
+}
+console.log("fixture written:", target);