@chainlesschain/personal-data-hub 0.3.6 → 0.3.8

package/lib/adapters/social-xiaohongshu-adb/collector.js

@@ -36,7 +36,12 @@ async function collect(bridge, opts = {}) {
     );
   }
   const now = opts.now || Date.now;
-  const client = opts.apiClient || new XhsApiClient({ now });
+  // Phase 6b: signProvider opt — desktop wiring injects XhsSignBridge for
+  // ~100% X-S hit rate; cli wiring leaves undefined → client falls back
+  // to in-process best-effort md5 (~60% GET / <30% POST).
+  const signProvider = opts.signProvider || undefined;
+  const client =
+    opts.apiClient || new XhsApiClient({ now, signProvider });
   const limits = opts.limits || {};
 
   const cookieResult = await bridge.invoke("xhs.cookies");
@@ -54,67 +59,108 @@ async function collect(bridge, opts = {}) {
   }
   const { cookie, a1, diagnostic: cookieDiagnostic } = cookieResult;
 
-  // fetchMe — no X-S required
-  const me = await client.fetchMe(cookie);
-  if (!me) {
-    // Cookie expired or web_session missing — write empty snapshot
-    // (build requires userId, use sentinel "0" + emit 0 events).
+  // Phase 6b: warm up the sign bridge with the captured cookie BEFORE
+  // calling any X-S endpoint. warmUp is idempotent (no-op when already
+  // warm). NullSignProvider.warmUp doesn't exist (only on the abstract
+  // base + ElectronWebSignBridge), so we feature-detect.
+  if (signProvider && typeof signProvider.warmUp === "function") {
+    try {
+      await signProvider.warmUp(cookie);
+    } catch (e) {
+      // Bridge warm-up failed (timeout / xhs.com 403 / IPC error).
+      // Fall through — api-client will use in-process fallback. Surface
+      // the reason via lastErrorMessage so UI can hint "Electron bridge
+      // unavailable, command-line precision degraded".
+      client._setLastError(
+        -98,
+        `signProvider warm-up failed: ${e && e.message ? e.message : String(e)}`,
+      );
+    }
+  }
+
+  try {
+    // fetchMe — no X-S required
+    const me = await client.fetchMe(cookie);
+    if (!me) {
+      // Cookie expired or web_session missing — write empty snapshot
+      // (build requires userId, use sentinel "0" + emit 0 events).
+      const snapshot = buildSnapshot({
+        userId: "unknown-user",
+        nickname: opts.displayName,
+        snapshottedAt: now(),
+      });
+      const snapshotPath = writeSnapshotJson(snapshot, { dir: opts.stagingDir });
+      return {
+        snapshotPath,
+        userId: null,
+        nickname: null,
+        eventCounts: { note: 0, liked: 0, follow: 0, total: 0 },
+        lastErrorCode: client.lastErrorCode,
+        lastErrorMessage: client.lastErrorMessage,
+        cookieDiagnostic: cookieDiagnostic || null,
+        meFetchFailed: true,
+        signProviderUsed: signProvider
+          ? signProvider.constructor.name
+          : "none",
+        signProviderHits: client._bridgeHits,
+        signProviderFallbacks: client._fallbackHits,
+      };
+    }
+
+    // Parallel 3 endpoints — partial failure tolerated; bridge-signed
+    // requests should hit ~100% while fallback hits ~60% GET / <30% POST.
+    const [notes, liked, follows] = await Promise.all([
+      client.fetchNotes(cookie, a1, me.userId, {
+        limit: Number.isInteger(limits.note) ? limits.note : undefined,
+      }),
+      client.fetchLiked(cookie, a1, {
+        limit: Number.isInteger(limits.liked) ? limits.liked : undefined,
+      }),
+      client.fetchFollows(cookie, a1, me.userId, {
+        limit: Number.isInteger(limits.follow) ? limits.follow : undefined,
+      }),
+    ]);
+
     const snapshot = buildSnapshot({
-      userId: "unknown-user",
-      nickname: opts.displayName,
+      userId: me.userId,
+      nickname: opts.displayName || me.nickname,
+      notes,
+      liked,
+      follows,
       snapshottedAt: now(),
     });
     const snapshotPath = writeSnapshotJson(snapshot, { dir: opts.stagingDir });
+
     return {
       snapshotPath,
-      userId: null,
-      nickname: null,
-      eventCounts: { note: 0, liked: 0, follow: 0, total: 0 },
+      userId: me.userId,
+      nickname: me.nickname,
+      eventCounts: {
+        note: notes.length,
+        liked: liked.length,
+        follow: follows.length,
+        total: snapshot.events.length,
+      },
       lastErrorCode: client.lastErrorCode,
       lastErrorMessage: client.lastErrorMessage,
       cookieDiagnostic: cookieDiagnostic || null,
-      meFetchFailed: true,
+      meFetchFailed: false,
+      signProviderUsed: signProvider ? signProvider.constructor.name : "none",
+      signProviderHits: client._bridgeHits,
+      signProviderFallbacks: client._fallbackHits,
     };
+  } finally {
+    // Always release the WebContentsView heap (~30-50MB) — even on
+    // throw. shutdown is idempotent so collectAndSync's outer cleanup
+    // calling it again is safe.
+    if (signProvider && typeof signProvider.shutdown === "function") {
+      try {
+        await signProvider.shutdown();
+      } catch (_e) {
+        // Best-effort — shutdown errors don't block sync result.
+      }
+    }
   }
-
-  // Parallel 3 endpoints — partial failure tolerated (~60% X-S hit rate)
-  const [notes, liked, follows] = await Promise.all([
-    client.fetchNotes(cookie, a1, me.userId, {
-      limit: Number.isInteger(limits.note) ? limits.note : undefined,
-    }),
-    client.fetchLiked(cookie, a1, {
-      limit: Number.isInteger(limits.liked) ? limits.liked : undefined,
-    }),
-    client.fetchFollows(cookie, a1, me.userId, {
-      limit: Number.isInteger(limits.follow) ? limits.follow : undefined,
-    }),
-  ]);
-
-  const snapshot = buildSnapshot({
-    userId: me.userId,
-    nickname: opts.displayName || me.nickname,
-    notes,
-    liked,
-    follows,
-    snapshottedAt: now(),
-  });
-  const snapshotPath = writeSnapshotJson(snapshot, { dir: opts.stagingDir });
-
-  return {
-    snapshotPath,
-    userId: me.userId,
-    nickname: me.nickname,
-    eventCounts: {
-      note: notes.length,
-      liked: liked.length,
-      follow: follows.length,
-      total: snapshot.events.length,
-    },
-    lastErrorCode: client.lastErrorCode,
-    lastErrorMessage: client.lastErrorMessage,
-    cookieDiagnostic: cookieDiagnostic || null,
-    meFetchFailed: false,
-  };
 }
 
 async function collectAndSync(bridge, registry, opts = {}) {
@@ -147,6 +193,11 @@ async function collectAndSync(bridge, registry, opts = {}) {
       lastErrorMessage: collectResult.lastErrorMessage,
       cookieDiagnostic: collectResult.cookieDiagnostic,
       meFetchFailed: collectResult.meFetchFailed,
+      // Phase 6b diagnostic — UI can highlight when bridge upgraded
+      // X-S signing from ~60% best-effort to ~100% bridge.
+      signProviderUsed: collectResult.signProviderUsed,
+      signProviderHits: collectResult.signProviderHits,
+      signProviderFallbacks: collectResult.signProviderFallbacks,
       cleanupFailed,
     },
   };

package/lib/analysis.js

@@ -21,7 +21,7 @@
 
 "use strict";
 
-const { parseQuery, extractEntityTerm } = require("./query-parser");
+const { parseQuery, extractEntityTerm, extractPersonNameCandidate } = require("./query-parser");
 const {
   buildPrompt,
   parseCitations,
@@ -61,6 +61,27 @@ const SUM_AMOUNT_SUBTYPES = ["order", "payment", "transfer", "income"];
 // 12) doesn't starve any single subtype.
 const SUM_AMOUNT_MIN_PER_SUBTYPE = 20;
 
+// entityFocus="persons" routing — explicit contact queries ("我有哪些联系人",
+// "妈手机号"). When the user names the target table the engine MUST NOT
+// compete persons against the events pool: small-model Android budgets
+// (20 facts / 50 row cap) get drained by a few hundred Bilibili
+// notifications and the contact slice ends up empty. parseEntityFocus
+// surfaces the signal; we honor it by going persons-first.
+//
+// Keep a TINY events headroom (5%) so questions like "我最近跟妈打过电话吗"
+// still surface 通话 event rows alongside the contact entry.
+const PERSONS_FOCUS_EVENT_HEADROOM_RATIO = 0.05;
+
+// Default-path budget split when no entityFocus signal. Pre-fix events
+// got the entire effMaxFacts pool first and persons/items shared only the
+// remainder; on a busy vault that meant 0 contacts in the prompt. Cap
+// events at 70%, reserve 20% for persons and 10% for items so a generic
+// "what's going on" question still sees the full data shape.
+const DEFAULT_EVENT_BUDGET_RATIO = 0.7;
+const DEFAULT_PERSON_BUDGET_RATIO = 0.2;
+// Items take whatever remains; intent=count/list questions about contacts
+// already short-circuit via entityFocus before reaching this branch.
+
 class AnalysisEngine {
   /**
    * @param {object} opts
@@ -426,6 +447,88 @@ class AnalysisEngine {
       // 0 results → fall through to default broader path below.
     }
 
+    // entityFocus=persons routing — "我有哪些联系人", "妈手机号", "通讯录里
+    // 有多少人". Skip the events broad scan and put the entire fact budget
+    // on the persons table (with a 5% events headroom for adjacent rows
+    // like 通话/短信). Adapter / time window are NOT applied to persons:
+    // contacts are current-state snapshots, not time-stamped events.
+    //
+    // 0 hits → fall through to the default path. A user might say "联系人"
+    // colloquially when they mean "people I've messaged" — the default
+    // events+persons mix is the right safety net.
+    if (parsed.entityFocus === "persons") {
+      const personLimit = effMaxFacts > 1 ? effMaxFacts - 1 : effMaxFacts;
+      let persons = [];
+      // Name-search short-circuit — when the question carries a probable
+      // person-name candidate ("妈手机号", "张三的电话"), try LIKE-search
+      // against names / identifiers / notes / relation. Hits go straight
+      // to FACTS so the LLM sees the target contact even when the vault
+      // holds hundreds of others. Falls back to ingest-ordered queryPersons
+      // when 0 hits or no name candidate.
+      const nameCandidate = extractPersonNameCandidate(parsed.raw);
+      if (nameCandidate && typeof this.vault.searchPersons === "function") {
+        try {
+          persons = this.vault.searchPersons({ q: nameCandidate, limit: personLimit });
+        } catch (_e) { /* tolerate — try ingest-ordered fallback */ }
+      }
+      if (persons.length === 0) {
+        try {
+          persons = this.vault.queryPersons({ limit: personLimit });
+        } catch (_e) {
+          // legacy vault — fall through
+        }
+      }
+      if (persons.length > 0) {
+        const eventHeadroom = Math.max(
+          0,
+          Math.floor(effMaxFacts * PERSONS_FOCUS_EVENT_HEADROOM_RATIO)
+        );
+        let events = [];
+        if (eventHeadroom > 0) {
+          const eq = { limit: eventHeadroom };
+          if (parsed.filters && parsed.filters.adapter) eq.adapter = parsed.filters.adapter;
+          if (parsed.timeWindow) {
+            if (Number.isFinite(parsed.timeWindow.since)) eq.since = parsed.timeWindow.since;
+            if (Number.isFinite(parsed.timeWindow.until)) eq.until = parsed.timeWindow.until;
+          }
+          try {
+            events = this.vault.queryEvents(eq);
+          } catch (_e) { /* tolerate */ }
+        }
+        // persons-first ordering so the LLM reads the contact rows before
+        // the (sparse) event tail.
+        const combined = [...persons, ...events].slice(0, effMaxFacts);
+        return combined;
+      }
+      // 0 persons → fall through.
+    }
+
+    // entityFocus=items routing — "我装了哪些 app", "有哪些游戏". Mirror
+    // persons branch: skip events, query items table directly, keep a
+    // tiny events headroom for adjacent rows.
+    if (parsed.entityFocus === "items") {
+      const itemLimit = effMaxFacts > 1 ? effMaxFacts - 1 : effMaxFacts;
+      let items = [];
+      try {
+        items = this.vault.queryItems({ limit: itemLimit });
+      } catch (_e) { /* legacy */ }
+      if (items.length > 0) {
+        const eventHeadroom = Math.max(
+          0,
+          Math.floor(effMaxFacts * PERSONS_FOCUS_EVENT_HEADROOM_RATIO)
+        );
+        let events = [];
+        if (eventHeadroom > 0) {
+          const eq = { limit: eventHeadroom };
+          if (parsed.filters && parsed.filters.adapter) eq.adapter = parsed.filters.adapter;
+          try {
+            events = this.vault.queryEvents(eq);
+          } catch (_e) { /* tolerate */ }
+        }
+        return [...items, ...events].slice(0, effMaxFacts);
+      }
+    }
+
     // intent=sum-amount routing — "总共花了多少" / "在淘宝花了多少钱"
     // only needs events from amount-bearing subtypes (order/payment/
     // transfer/income). Pulling messages / visits / browses wastes
@@ -551,22 +654,40 @@ class AnalysisEngine {
     //  - installed apps land in `items`, not `events`
     //  - places (visited locations) live in `places`
     // Without these the LLM gets 0 facts for "我有几个联系人" style questions
-    // and hallucinates a count. We pull a bounded slice of each entity type
-    // and append; prompt-builder.summarizeFact already handles `person` /
-    // `place` / fallback `item` shapes, so this is additive with no schema
-    // change to the LLM-facing prompt.
+    // and hallucinates a count.
+    //
+    // Sizing — two regimes:
+    //  (a) Events fit (events.length < effMaxFacts): legacy behavior —
+    //      events first, split the remainder evenly between persons + items.
+    //  (b) Events would monopolize (events.length >= effMaxFacts): reserve
+    //      DEFAULT_PERSON_BUDGET_RATIO (20%) + 10% for persons + items so a
+    //      busy event timeline doesn't shove every contact out of the prompt.
+    //      If persons + items tables BOTH return 0 rows, refill the reserve
+    //      with events — no point starving the LLM of facts when the side
+    //      tables are empty (small vaults / pre-Path-C ingest state).
     //
-    // Sizing: keep events as the majority (existing behavior is unchanged for
-    // event-heavy queries like 消费 / 通话); split the remaining 1/2 budget
-    // between persons + items. Time window + adapter filters don't apply to
-    // these tables (persons aren't time-stamped events) — they're current-
-    // state snapshots that should always be visible. Adapter filter is also
-    // skipped because users asking "我有几个联系人" don't say "from
-    // system-data-android".
-    const remaining = Math.max(0, effMaxFacts - events.length);
-    const sideBudget = Math.floor(remaining / 2);
-    const personBudget = sideBudget > 0 ? sideBudget : 0;
-    const itemBudget = remaining - personBudget;
+    // Time window + adapter filters don't apply to persons/items: they're
+    // current-state snapshots, not time-stamped events. A user asking
+    // "上个月联系人变化" is rare enough to leave for a future intent.
+    let cappedEvents = events;
+    let personBudget;
+    let itemBudget;
+    if (events.length >= effMaxFacts) {
+      const personReserve = Math.max(1, Math.floor(effMaxFacts * DEFAULT_PERSON_BUDGET_RATIO));
+      const itemReserve = Math.max(
+        1,
+        Math.floor(effMaxFacts * (1 - DEFAULT_EVENT_BUDGET_RATIO - DEFAULT_PERSON_BUDGET_RATIO))
+      );
+      const eventCap = Math.max(1, effMaxFacts - personReserve - itemReserve);
+      cappedEvents = events.slice(0, eventCap);
+      personBudget = personReserve;
+      itemBudget = itemReserve;
+    } else {
+      const remaining = effMaxFacts - events.length;
+      const sideBudget = Math.floor(remaining / 2);
+      personBudget = sideBudget > 0 ? sideBudget : 0;
+      itemBudget = remaining - personBudget;
+    }
 
     let persons = [];
     if (personBudget > 0) {
@@ -585,7 +706,20 @@ class AnalysisEngine {
       }
     }
 
-    return [...events, ...persons, ...items];
+    // Refill backfill — when events overflowed (reservation branch) but
+    // persons + items both returned 0 rows, give the reserved slots back
+    // to events. Small vaults / pre-Path-C state would otherwise see fewer
+    // facts than the budget allowed.
+    if (
+      events.length >= effMaxFacts &&
+      persons.length === 0 &&
+      items.length === 0 &&
+      cappedEvents.length < effMaxFacts
+    ) {
+      cappedEvents = events.slice(0, effMaxFacts);
+    }
+
+    return [...cappedEvents, ...persons, ...items];
   }
 
   /**
@@ -630,4 +764,7 @@ module.exports = {
   LIST_INTENT_FTS_LIMIT,
   SUM_AMOUNT_SUBTYPES,
   SUM_AMOUNT_MIN_PER_SUBTYPE,
+  PERSONS_FOCUS_EVENT_HEADROOM_RATIO,
+  DEFAULT_EVENT_BUDGET_RATIO,
+  DEFAULT_PERSON_BUDGET_RATIO,
 };

package/lib/query-parser.js

@@ -219,6 +219,42 @@ function parseIntent(text) {
   return "list";
 }
 
+// ─── Entity-focus detection (persons / items routing) ────────────────────
+//
+// 2026-05-27 — Bug: user asked "我有哪些联系人" / "我妈手机号" several times;
+// vault held real contacts but the LLM kept replying "没数据" because the
+// default _gatherFacts pulled 200 row-cap of events first and the persons
+// slice got squeezed out of the small-model 20-fact budget. parseIntent
+// already catches "几个 X" as count, but that doesn't tell the engine WHICH
+// table the user means. parseEntityFocus is the missing signal: when the
+// question is explicitly about contacts/apps, the engine prioritizes that
+// table instead of competing with events.
+//
+// Returns null when no focus signal — engine falls back to the existing
+// events-majority + persons/items remainder behavior.
+//
+// Memory: pdh_analysis_engine_intent_routing.md.
+
+const PERSON_FOCUS_PATTERNS = [
+  /(联系人|通讯录|电话簿|通信录|好友列表|朋友列表)/,
+  /(手机号|电话号|号码是|的电话|的手机)/,
+  /(谁是|是谁|是什么人)/,
+  /\b(contact|contacts|phonebook|address\s*book|phone\s*number)\b/i,
+];
+
+const ITEM_FOCUS_PATTERNS = [
+  /(装了|安装了|装过|下了什么|下载了什么|有哪些(app|应用|软件|游戏))/i,
+  /(我的(app|应用|软件)|哪些(app|应用|软件|游戏))/i,
+  /\b(installed\s+apps?|my\s+apps?|installed\s+packages?)\b/i,
+];
+
+function parseEntityFocus(text) {
+  if (typeof text !== "string" || text.length === 0) return null;
+  if (PERSON_FOCUS_PATTERNS.some((re) => re.test(text))) return "persons";
+  if (ITEM_FOCUS_PATTERNS.some((re) => re.test(text))) return "items";
+  return null;
+}
+
 // ─── Entity-name extraction (FTS5 fulltext routing) ────────────────────
 //
 // Pull a probable entity-name candidate out of the raw question so
@@ -291,6 +327,56 @@ function extractEntityTerm(text) {
   return candidates[0];
 }
 
+// ─── Person-name extraction (entityFocus=persons routing) ────────────────
+//
+// Specialized extractor for the persons branch in AnalysisEngine. Differs
+// from extractEntityTerm in two ways:
+//
+//  1. Strips person-FOCUS framing words first (联系人/手机号/电话/etc.) —
+//     they're question scaffolding, not the target name. extractEntityTerm
+//     left "妈手机号" intact because it doesn't know that phrase is framing.
+//
+//  2. Allows single-character names from a relation-word whitelist
+//     (妈/爸/姐/弟/...) — extractEntityTerm filtered every 1-char Chinese to
+//     suppress verb false positives, but that also dropped "妈" / "爸" which
+//     are the dominant contact-name shorthands on a personal phonebook.
+//
+// Multi-char candidates always win over single-char fallback so "张三的
+// 手机号" returns "张三" not "三".
+
+const PERSON_FRAMING_STOP_PATTERNS = [
+  /(联系人|通讯录|电话簿|通信录|好友列表|朋友列表)/g,
+  /(手机号|电话号|号码是|的电话|的手机|号码|电话)/g,
+  /(谁是|是谁|是什么人|是哪位)/g,
+  /\b(contact|contacts|phonebook|address\s*book|phone\s*number)\b/gi,
+];
+
+// Whitelisted single-character Chinese relation words. Single-char tokens
+// outside this set are dropped to keep verb / particle false-positives from
+// leaking through. Extend cautiously — every new char widens the LIKE
+// surface area and could match unrelated rows.
+const PERSON_RELATION_SINGLE_CHARS_RE =
+  /^[妈爸姐妹哥弟爹娘爷奶姥舅姑叔伯婶嫂嫁公婆]$/;
+
+function extractPersonNameCandidate(text) {
+  if (typeof text !== "string" || text.length === 0) return null;
+  let s = text;
+  for (const re of PERSON_FRAMING_STOP_PATTERNS) {
+    s = s.replace(re, " ");
+  }
+  for (const re of ENTITY_STOP_PATTERNS) {
+    s = s.replace(re, " ");
+  }
+  const all = s.split(/\s+/).filter((t) => t.length >= 1 && t.length <= 10);
+  if (all.length === 0) return null;
+  const multi = all
+    .filter((t) => t.length >= 2)
+    .sort((a, b) => b.length - a.length);
+  if (multi.length > 0) return multi[0];
+  const single = all.find((t) => t.length === 1 && PERSON_RELATION_SINGLE_CHARS_RE.test(t));
+  return single || null;
+}
+
 // ─── Full parser ─────────────────────────────────────────────────────────
 
 /**
@@ -314,6 +400,7 @@ function parseQuery(question, opts = {}) {
     timeWindow: parseTimeWindow(raw, now),
     filters: parseFilters(raw),
     intent: parseIntent(raw),
+    entityFocus: parseEntityFocus(raw),
   };
 }
 
@@ -322,9 +409,15 @@ module.exports = {
   parseTimeWindow,
   parseFilters,
   parseIntent,
+  parseEntityFocus,
   extractEntityTerm,
+  extractPersonNameCandidate,
   // exposed for tests
   SUBTYPE_KEYWORDS,
   ADAPTER_KEYWORDS,
+  PERSON_FOCUS_PATTERNS,
+  ITEM_FOCUS_PATTERNS,
   ENTITY_STOP_PATTERNS,
+  PERSON_FRAMING_STOP_PATTERNS,
+  PERSON_RELATION_SINGLE_CHARS_RE,
 };

package/lib/vault.js

@@ -865,6 +865,70 @@ class LocalVault {
       .map((row) => this._rowToPerson(row));
   }
 
+  /**
+   * searchPersons — LIKE-based name/identifier/notes search.
+   *
+   * 2026-05-27 — AnalysisEngine entityFocus="persons" path uses this when the
+   * question carries a probable person-name candidate ("妈手机号", "张三的电话").
+   * Pre-fix the engine dumped the first N contacts by ingest_at and let the
+   * LLM scan — but on small-model (Qwen 0.5B/1.5B, 20-fact budget) and large
+   * contact tables (100+), the target person rarely landed in the slice.
+   * Searching by LIKE %term% against the JSON-serialized `names` column +
+   * `identifiers` (phone numbers) + `notes` + `relation` gives the LLM the
+   * matching contact directly, eliminating that miss.
+   *
+   * No FTS5 schema migration: contact tables are small (typically <2000
+   * rows on Android), full LIKE scan stays sub-millisecond. Sticking with
+   * LIKE also avoids partial-index drift trap #25.
+   *
+   * @param {object} q
+   * @param {string} q.q          term to match. Falls back to queryPersons when empty.
+   * @param {string} [q.subtype]
+   * @param {string} [q.adapter]
+   * @param {number} [q.limit=100]
+   * @param {number} [q.offset=0]
+   */
+  searchPersons(q = {}) {
+    const term = typeof q.q === "string" ? q.q.trim() : "";
+    if (term.length === 0) {
+      return this.queryPersons(q);
+    }
+    const where = [];
+    const params = {};
+    // LIKE-escape % and _ in the user input so a name with literal % won't
+    // wildcard. SQLite LIKE ESCAPE clause handles this.
+    const escaped = term.replace(/([\\%_])/g, "\\$1");
+    params.qPat = "%" + escaped + "%";
+    where.push(
+      "(" +
+        "names LIKE @qPat ESCAPE '\\' OR " +
+        "identifiers LIKE @qPat ESCAPE '\\' OR " +
+        "notes LIKE @qPat ESCAPE '\\' OR " +
+        "relation LIKE @qPat ESCAPE '\\'" +
+        ")"
+    );
+    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 " + where.join(" AND ") +
+      " ORDER BY (confidence IS NULL) ASC, confidence DESC, 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chainlesschain/personal-data-hub",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Personal Data Hub — UnifiedSchema + validators + KG ingest helpers for the data-back-to-the-individual middleware",
   "type": "commonjs",
   "main": "lib/index.js",
@@ -61,6 +61,10 @@
     "./adapters/social-douyin-adb": "./lib/adapters/social-douyin-adb/index.js",
     "./adapters/social-xiaohongshu": "./lib/adapters/social-xiaohongshu/index.js",
     "./adapters/social-xiaohongshu-adb": "./lib/adapters/social-xiaohongshu-adb/index.js",
+    "./adapters/social-toutiao": "./lib/adapters/social-toutiao/index.js",
+    "./adapters/social-toutiao-adb": "./lib/adapters/social-toutiao-adb/index.js",
+    "./adapters/social-kuaishou": "./lib/adapters/social-kuaishou/index.js",
+    "./adapters/social-kuaishou-adb": "./lib/adapters/social-kuaishou-adb/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",