@chainlesschain/personal-data-hub 0.1.0 → 0.2.1

package/lib/entity-resolver/rule-stage.js

@@ -0,0 +1,208 @@
+/**
+ * Phase 8.2 — EntityResolver rule stage.
+ *
+ * Per docs/design/Personal_Data_Hub_EntityResolver.md §4.1 — the synchronous
+ * fast-path. Returns "same" | "different" | "uncertain" by looking only at
+ * identifier overlap + naming + source provenance. No external calls, no
+ * Ollama, < 5ms p99 even for thousands of candidates.
+ *
+ * The intent is to cleanly handle the cases where we KNOW the answer:
+ *   - same identifier (email/phone/wechatId/did) → same
+ *   - completely disjoint fingerprint → different
+ *   - same adapter, same name, different originalId → same (adapter
+ *     produced two rows for one person — rare but happens with
+ *     un-normalized export channels)
+ *
+ * Anything else falls through to `uncertain` and gets sent to the
+ * async embedding+LLM pipeline.
+ */
+
+"use strict";
+
+/**
+ * Identifier keys we treat as "if they overlap, they're definitively
+ * the same person". These should be globally-unique-per-person values.
+ * Keep this list conservative — adding `name` here would catch false
+ * positives (different people sharing common Chinese names).
+ */
+const STRONG_IDENTIFIER_KEYS = [
+  "email",
+  "phone",
+  "wechatId",
+  "alipayUid",
+  "did",
+  "idHash",      // SHA-256 of national ID number (Phase 9+ contribution)
+];
+
+/**
+ * Run the rule stage on a (pending, candidate) pair.
+ *
+ * @param {object} a   Person row
+ * @param {object} b   Person row
+ * @returns {{ verdict: "same"|"different"|"uncertain", reason: string }}
+ */
+function ruleStage(a, b) {
+  if (!a || !b || typeof a !== "object" || typeof b !== "object") {
+    return { verdict: "different", reason: "invalid input" };
+  }
+  if (a.id === b.id) {
+    // Same Person row — vacuously "same" but caller should never pair a
+    // person with itself. Surface clearly.
+    return { verdict: "same", reason: "identical id" };
+  }
+
+  // R1. Strong identifier overlap → same
+  const sharedKey = findSharedIdentifier(a.identifiers || {}, b.identifiers || {});
+  if (sharedKey) {
+    return { verdict: "same", reason: `identifier match: ${sharedKey.key}=${sharedKey.value}` };
+  }
+
+  // R3. Same adapter, different originalId, sharing a name → same
+  // (catches adapter-internal duplicates where an export contains the
+  // same person under two surface forms — rare but documented in design.)
+  // GUARD: if BOTH sides have a strong identifier of the SAME key but
+  // with DIFFERENT values, they're definitively different people sharing
+  // a common name (homonym-trap). Don't R3-merge.
+  if (a.source && b.source
+      && a.source.adapter === b.source.adapter
+      && a.source.originalId !== b.source.originalId
+      && sharesAnyName(a.names, b.names)
+      && !hasConflictingIdentifier(a.identifiers || {}, b.identifiers || {})
+  ) {
+    return {
+      verdict: "same",
+      reason: `same-adapter (${a.source.adapter}) internal dup: shared name`,
+    };
+  }
+
+  // R2. Zero overlap on any field → different
+  const overlap = countFieldOverlap(a, b);
+  if (overlap === 0) {
+    return { verdict: "different", reason: "no field overlap" };
+  }
+
+  // R4. Otherwise uncertain — send to async pipeline
+  return { verdict: "uncertain", reason: `overlap=${overlap}` };
+}
+
+/**
+ * Find a strong identifier shared between two identifier maps. Each
+ * identifier value can be a string OR an array of strings (per UnifiedSchema).
+ *
+ * @returns {{key: string, value: string} | null}
+ */
+function findSharedIdentifier(idsA, idsB) {
+  for (const key of STRONG_IDENTIFIER_KEYS) {
+    const av = toArray(idsA[key]);
+    const bv = toArray(idsB[key]);
+    if (av.length === 0 || bv.length === 0) continue;
+    // Normalize before compare — emails / phones often have surface variance
+    const aNorm = av.map((v) => normalizeIdValue(key, v));
+    const bNorm = bv.map((v) => normalizeIdValue(key, v));
+    for (const v of aNorm) {
+      if (v && bNorm.includes(v)) return { key, value: v };
+    }
+  }
+  return null;
+}
+
+function toArray(v) {
+  if (Array.isArray(v)) return v.filter((x) => typeof x === "string" && x.length > 0);
+  if (typeof v === "string" && v.length > 0) return [v];
+  return [];
+}
+
+/**
+ * Returns true iff both sides have at least one strong identifier of
+ * the SAME key but with DIFFERENT (normalized) values. This is the
+ * "homonym-trap guard" for R3: if Alice@a.com and Alice@b.com share
+ * the name "Alice" but have different emails, they're DIFFERENT people.
+ */
+function hasConflictingIdentifier(idsA, idsB) {
+  for (const key of STRONG_IDENTIFIER_KEYS) {
+    const av = toArray(idsA[key]).map((v) => normalizeIdValue(key, v));
+    const bv = toArray(idsB[key]).map((v) => normalizeIdValue(key, v));
+    if (av.length === 0 || bv.length === 0) continue;
+    // Both have this identifier — overlap means SAME (handled by R1 above);
+    // no overlap on the same key = conflict
+    const overlap = av.some((v) => bv.includes(v));
+    if (!overlap) return true;
+  }
+  return false;
+}
+
+/**
+ * Light normalization to avoid trivial misses:
+ *   - email: lowercase + trim
+ *   - phone: digits only (strips + - spaces parens)
+ *   - others: trim only
+ */
+function normalizeIdValue(key, v) {
+  if (typeof v !== "string") return "";
+  const trimmed = v.trim();
+  if (key === "email") return trimmed.toLowerCase();
+  if (key === "phone") {
+    let digits = trimmed.replace(/[^0-9]/g, "");
+    // Strip common country-code prefixes so "+86 138-0000 1111" and
+    // "13800001111" collapse to the same value.
+    if (digits.length === 13 && digits.startsWith("86")) digits = digits.slice(2);
+    if (digits.length === 12 && digits.startsWith("1")) digits = digits.slice(1); // US +1 leading
+    return digits;
+  }
+  return trimmed;
+}
+
+/**
+ * Whether any name in A is also a name (or substring) in B. We use
+ * substring match because adapters often label the same person differently
+ * ("陈XX" in Alipay vs "陈" in WeChat nickname).
+ */
+function sharesAnyName(namesA, namesB) {
+  const a = (namesA || []).filter((n) => typeof n === "string" && n.length > 0);
+  const b = (namesB || []).filter((n) => typeof n === "string" && n.length > 0);
+  if (a.length === 0 || b.length === 0) return false;
+  // Exact match
+  for (const x of a) {
+    if (b.includes(x)) return true;
+  }
+  return false;
+}
+
+/**
+ * Count the number of fields (name, identifier value, location, etc.)
+ * that show ANY commonality between A and B. The threshold for R2 is
+ * "0 overlap → different"; we don't try to weight overlaps here, just
+ * detect total disjointedness.
+ */
+function countFieldOverlap(a, b) {
+  let n = 0;
+
+  // Name overlap
+  if (sharesAnyName(a.names, b.names)) n += 1;
+
+  // Identifier overlap (counted per-key)
+  const aIds = a.identifiers || {};
+  const bIds = b.identifiers || {};
+  for (const key of Object.keys(aIds)) {
+    if (!bIds[key]) continue;
+    const av = toArray(aIds[key]);
+    const bv = toArray(bIds[key]);
+    if (av.some((v) => bv.includes(v))) n += 1;
+  }
+
+  // Same primary source adapter — usually means same data origin
+  if (a.source && b.source && a.source.adapter === b.source.adapter) {
+    n += 1;
+  }
+
+  return n;
+}
+
+module.exports = {
+  ruleStage,
+  findSharedIdentifier,
+  countFieldOverlap,
+  sharesAnyName,
+  normalizeIdValue,
+  STRONG_IDENTIFIER_KEYS,
+};

package/lib/entity-resolver/worker.js

@@ -0,0 +1,149 @@
+/**
+ * Phase 8.5 — Async resolve_queue worker.
+ *
+ * Long-running idle loop that polls the resolve_queue, calls
+ * `EntityResolver.drain(batch)`, sleeps when empty, exits cleanly on
+ * stop(). Designed to run alongside the hub process (desktop main /
+ * cc serve / Workflow runner).
+ *
+ * Lifecycle:
+ *   const w = new EntityResolverWorker({ resolver, intervalMs: 30_000 });
+ *   w.start();   // returns immediately; loop runs async
+ *   ...
+ *   await w.stop(); // waits for current batch to finish, then exits
+ *
+ * The worker is dumb to where it runs — caller decides cadence (idle
+ * scheduler in Electron main, cron in cc serve, etc.).
+ */
+
+"use strict";
+
+class EntityResolverWorker {
+  constructor(opts = {}) {
+    if (!opts || typeof opts !== "object") {
+      throw new Error("EntityResolverWorker: opts required");
+    }
+    if (!opts.resolver) {
+      throw new Error("EntityResolverWorker: opts.resolver required");
+    }
+    this._resolver = opts.resolver;
+    this._batchSize = Number.isFinite(opts.batchSize) ? opts.batchSize : 20;
+    // Sleep when the queue is empty (poll cadence). 30s default is
+    // enough to keep latency low on user-initiated sync while not
+    // pegging CPU in steady state.
+    this._idleIntervalMs = Number.isFinite(opts.idleIntervalMs) ? opts.idleIntervalMs : 30_000;
+    // Between non-empty batches: small breather so cooperative scheduling
+    // works with other adapter syncs.
+    this._batchSpacingMs = Number.isFinite(opts.batchSpacingMs) ? opts.batchSpacingMs : 50;
+    // Optional progress callback for UI + audit
+    this._onProgress = typeof opts.onProgress === "function" ? opts.onProgress : null;
+    this._logger = opts.logger || null;
+
+    this._running = false;
+    this._loopPromise = null;
+    this._stopRequested = false;
+    this._stats = {
+      startedAt: 0,
+      batchesProcessed: 0,
+      itemsProcessed: 0,
+      same: 0,
+      different: 0,
+      review: 0,
+      error: 0,
+      lastBatchAt: 0,
+    };
+  }
+
+  isRunning() {
+    return this._running;
+  }
+
+  stats() {
+    return { ...this._stats };
+  }
+
+  start() {
+    if (this._running) return;
+    this._running = true;
+    this._stopRequested = false;
+    this._stats.startedAt = Date.now();
+    this._loopPromise = this._loop().finally(() => {
+      this._running = false;
+    });
+  }
+
+  async stop() {
+    this._stopRequested = true;
+    if (this._loopPromise) {
+      try { await this._loopPromise; } catch (_e) {}
+    }
+    this._running = false;
+  }
+
+  /**
+   * Run one batch synchronously (caller drives, no loop). Returns the
+   * drain output. Useful for tests + on-demand "process N now" buttons.
+   */
+  async tick() {
+    return await this._processBatch();
+  }
+
+  async _loop() {
+    while (!this._stopRequested) {
+      let batchResult;
+      try {
+        batchResult = await this._processBatch();
+      } catch (err) {
+        this._log("worker batch threw — sleeping then retrying", err && err.message);
+        batchResult = null;
+      }
+      if (this._stopRequested) break;
+      const empty = !batchResult || batchResult.processed === 0;
+      const delay = empty ? this._idleIntervalMs : this._batchSpacingMs;
+      await this._sleep(delay);
+    }
+  }
+
+  async _processBatch() {
+    const result = await this._resolver.drain({ limit: this._batchSize });
+    this._stats.batchesProcessed += 1;
+    this._stats.itemsProcessed += result.processed;
+    this._stats.same += result.same;
+    this._stats.different += result.different;
+    this._stats.review += result.review;
+    this._stats.error += result.error;
+    this._stats.lastBatchAt = Date.now();
+    this._emitProgress({ batch: result, totals: { ...this._stats } });
+    return result;
+  }
+
+  _emitProgress(payload) {
+    if (!this._onProgress) return;
+    try {
+      this._onProgress(payload);
+    } catch (_e) {
+      // listener errors don't break the loop
+    }
+  }
+
+  async _sleep(ms) {
+    if (ms <= 0) return;
+    // Interruptable sleep — checks _stopRequested every 100ms so stop()
+    // can land within a sane bound.
+    const step = 100;
+    let remaining = ms;
+    while (remaining > 0 && !this._stopRequested) {
+      const next = Math.min(step, remaining);
+      await new Promise((resolve) => setTimeout(resolve, next));
+      remaining -= next;
+    }
+  }
+
+  _log(...args) {
+    if (this._logger && typeof this._logger.info === "function") {
+      this._logger.info("[EntityResolverWorker]", ...args);
+    }
+  }
+}
+
+module.exports = { EntityResolverWorker };

package/lib/index.js

@@ -32,6 +32,30 @@ const { MockLLMClient, OllamaClient } = require("./llm-client");
 const { AnalysisEngine, DEFAULT_MAX_FACTS, DEFAULT_MAX_QUERY_LIMIT } = require("./analysis");
 const bridges = require("./bridges");
 const emailImapAdapter = require("./adapters/email-imap");
+const alipayBillAdapter = require("./adapters/alipay-bill");
+const wechatAdapter = require("./adapters/wechat");
+const travelBase = require("./adapters/travel-base");
+const { Train12306Adapter } = require("./adapters/travel-12306");
+const { CtripAdapter } = require("./adapters/travel-ctrip");
+const { AmapAdapter } = require("./adapters/travel-amap");
+const { BaiduMapAdapter } = require("./adapters/travel-baidu-map");
+const shoppingBase = require("./adapters/shopping-base");
+const { TaobaoAdapter } = require("./adapters/shopping-taobao");
+const { JdAdapter } = require("./adapters/shopping-jd");
+const { MeituanAdapter } = require("./adapters/shopping-meituan");
+const { BilibiliAdapter } = require("./adapters/social-bilibili");
+const { WeiboAdapter } = require("./adapters/social-weibo");
+const { DouyinAdapter } = require("./adapters/social-douyin");
+const { XiaohongshuAdapter } = require("./adapters/social-xiaohongshu");
+const { ToutiaoAdapter } = require("./adapters/social-toutiao");
+const { KuaishouAdapter } = require("./adapters/social-kuaishou");
+const { QQAdapter } = require("./adapters/messaging-qq");
+const { TelegramAdapter } = require("./adapters/messaging-telegram");
+const { WhatsAppAdapter } = require("./adapters/messaging-whatsapp");
+const entityResolver = require("./entity-resolver");
+const analysisSkills = require("./analysis-skills");
+const mobileExtractor = require("./mobile-extractor");
+const systemDataAndroid = require("./adapters/system-data-android");
 
 module.exports = {
   // Constants / enums
@@ -138,4 +162,111 @@ module.exports = {
   ImapConnectionFailedError: emailImapAdapter.ImapConnectionFailedError,
   ImapMailboxNotFoundError: emailImapAdapter.ImapMailboxNotFoundError,
   parseRawEmail: emailImapAdapter.parseRawEmail,
+  // Phase 5.3 — email classifier
+  EMAIL_CATEGORIES: emailImapAdapter.EMAIL_CATEGORIES,
+  EMAIL_LAYER1_RULES: emailImapAdapter.EMAIL_LAYER1_RULES,
+  classifyEmail: emailImapAdapter.classifyEmail,
+  classifyEmailLayer1: emailImapAdapter.classifyEmailLayer1,
+  classifyEmailLayer2: emailImapAdapter.classifyEmailLayer2,
+  // Phase 5.4 — 6 template extractors + dispatcher
+  extractEmailFields: emailImapAdapter.extractEmailFields,
+  EMAIL_CATEGORY_EXTRACTORS: emailImapAdapter.EMAIL_CATEGORY_EXTRACTORS,
+  extractEmailBill: emailImapAdapter.extractBill,
+  extractEmailOrder: emailImapAdapter.extractOrder,
+  extractEmailTravel: emailImapAdapter.extractTravel,
+  extractEmailGovernment: emailImapAdapter.extractGovernment,
+  extractEmailRegister: emailImapAdapter.extractRegister,
+  extractEmailOther: emailImapAdapter.extractOther,
+  // Phase 5.5 — PDF decryption + transactions
+  extractPdfText: emailImapAdapter.extractPdfText,
+  pdfPasswordsFromHints: emailImapAdapter.pdfPasswordsFromHints,
+  extractEmailTransactions: emailImapAdapter.extractTransactions,
+
+  // Phase 8 — EntityResolver
+  EntityResolver: entityResolver.EntityResolver,
+  entityResolverRuleStage: entityResolver.entityResolverRuleStage,
+  entityResolverSharedIdentifier: entityResolver.entityResolverSharedIdentifier,
+  ENTITY_RESOLVER_STRONG_IDENTIFIER_KEYS: entityResolver.ENTITY_RESOLVER_STRONG_IDENTIFIER_KEYS,
+  EntityResolverEmbeddingStage: entityResolver.EntityResolverEmbeddingStage,
+  entityResolverCosineSimilarity: entityResolver.entityResolverCosineSimilarity,
+  EntityResolverLLMStage: entityResolver.EntityResolverLLMStage,
+  ENTITY_RESOLVER_LLM_SYSTEM_PROMPT: entityResolver.ENTITY_RESOLVER_LLM_SYSTEM_PROMPT,
+  parseEntityResolverLLMResponse: entityResolver.parseEntityResolverLLMResponse,
+  EntityResolverWorker: entityResolver.EntityResolverWorker,
+
+  // Phase 11 — 5 内置 analysis skills
+  AnalysisSkill: analysisSkills.AnalysisSkill,
+  SpendingSkill: analysisSkills.SpendingSkill,
+  RelationsSkill: analysisSkills.RelationsSkill,
+  FootprintSkill: analysisSkills.FootprintSkill,
+  InterestsSkill: analysisSkills.InterestsSkill,
+  TimelineSkill: analysisSkills.TimelineSkill,
+  ANALYSIS_SKILL_NAMES: analysisSkills.ANALYSIS_SKILL_NAMES,
+  runAnalysisSkill: analysisSkills.runAnalysisSkill,
+
+  // Phase 7.5 — Mobile extraction layer (借 sjqz architecture)
+  AndroidExtractor: mobileExtractor.AndroidExtractor,
+  iOSBackupReader: mobileExtractor.iOSBackupReader,
+
+  // Phase 12 v0.5 — WeChat (frida-independent slice)
+  WechatAdapter: wechatAdapter.WechatAdapter,
+  WECHAT_NAME: wechatAdapter.WECHAT_NAME,
+  WECHAT_VERSION: wechatAdapter.WECHAT_VERSION,
+  parseWeChatContent: wechatAdapter.parseWeChatContent,
+  extractWeChatKey: wechatAdapter.extractWeChatKey,
+  deriveWeChatLegacyKey: wechatAdapter.deriveWeChatLegacyKey,
+  WeChatDBReader: wechatAdapter.WeChatDBReader,
+  normalizeWeChatMessage: wechatAdapter.normalizeWeChatMessage,
+  normalizeWeChatContact: wechatAdapter.normalizeWeChatContact,
+  wxidToWeChatPersonId: wechatAdapter.wxidToWeChatPersonId,
+  WECHAT_PRAGMA_PROFILES: wechatAdapter.WECHAT_PRAGMA_PROFILES,
+
+  // Phase 9 — Travel four-pack
+  normalizeTravelRecord: travelBase.normalizeTravelRecord,
+  parseChineseDateTime: travelBase.parseChineseDateTime,
+  Train12306Adapter,
+  CtripAdapter,
+  AmapAdapter,
+  BaiduMapAdapter,
+
+  // Phase 7 — Shopping three-pack
+  normalizeOrderRecord: shoppingBase.normalizeOrderRecord,
+  CookieAuth: shoppingBase.CookieAuth,
+  TaobaoAdapter,
+  JdAdapter,
+  MeituanAdapter,
+
+  // Phase 13+ — long-tail social + messaging (借 sjqz parsers)
+  BilibiliAdapter,
+  WeiboAdapter,
+  DouyinAdapter,
+  XiaohongshuAdapter,
+  ToutiaoAdapter,
+  KuaishouAdapter,
+  QQAdapter,
+  TelegramAdapter,
+  WhatsAppAdapter,
+
+  // Plan A v0.1 — Android on-device system-data adapter (no Python sidecar,
+  // UI-pushed snapshot via ContentResolver + PackageManager).
+  SystemDataAndroidAdapter: systemDataAndroid.SystemDataAndroidAdapter,
+  SYSTEM_DATA_ANDROID_NAME: systemDataAndroid.SYSTEM_DATA_ANDROID_NAME,
+  SYSTEM_DATA_ANDROID_VERSION: systemDataAndroid.SYSTEM_DATA_ANDROID_VERSION,
+  SYSTEM_DATA_ANDROID_SNAPSHOT_SCHEMA_VERSION:
+    systemDataAndroid.SNAPSHOT_SCHEMA_VERSION,
+  // Path C — staging + ingest helper shared by IPC / WS / mobile-route layers
+  ingestSystemDataAndroidSnapshot:
+    systemDataAndroid.ingestSystemDataAndroidSnapshot,
+
+  // Phase 6 — AlipayBillAdapter (CSV import)
+  AlipayBillAdapter: alipayBillAdapter.AlipayBillAdapter,
+  ALIPAY_BILL_NAME: alipayBillAdapter.ALIPAY_BILL_NAME,
+  ALIPAY_BILL_VERSION: alipayBillAdapter.ALIPAY_BILL_VERSION,
+  parseAlipayCsv: alipayBillAdapter.parseAlipayCsv,
+  parseAlipayCsvBuffer: alipayBillAdapter.parseAlipayCsvBuffer,
+  extractAlipayCsvFromZip: alipayBillAdapter.extractAlipayCsvFromZip,
+  classifyAlipayCounterparty: alipayBillAdapter.classifyAlipayCounterparty,
+  alipayCounterpartyToPersonId: alipayBillAdapter.alipayCounterpartyToPersonId,
+  ALIPAY_KNOWN_MERCHANTS: alipayBillAdapter.ALIPAY_KNOWN_MERCHANTS,
+  mapAlipayTypeToSubtype: alipayBillAdapter.mapAlipayTypeToSubtype,
 };

package/lib/migrations.js

@@ -179,6 +179,72 @@ const INITIAL_DDL = [
   `CREATE INDEX IF NOT EXISTS idx_raw_captured ON raw_events(captured_at)`,
 ];
 
+// Phase 8 DDL — EntityResolver tables (5 new tables).
+// Per docs/design/Personal_Data_Hub_EntityResolver.md §5.1.
+const PHASE_8_DDL = [
+  // mergeGroups: identifies clusters of Person rows that are the "same"
+  // real-world entity. Multiple Person ids in the same group_id ↔ same
+  // person. primary_id is the canonical (oldest) row for display.
+  `CREATE TABLE IF NOT EXISTS merge_groups (
+    id              TEXT PRIMARY KEY,
+    primary_id      TEXT NOT NULL,
+    member_count    INTEGER NOT NULL DEFAULT 1,
+    created_at      INTEGER NOT NULL,
+    last_updated    INTEGER NOT NULL,
+    reviewed_by_user INTEGER NOT NULL DEFAULT 0
+  )`,
+  `CREATE TABLE IF NOT EXISTS merge_members (
+    group_id        TEXT NOT NULL,
+    person_id       TEXT NOT NULL,
+    joined_at       INTEGER NOT NULL,
+    joined_by       TEXT NOT NULL,
+    PRIMARY KEY (group_id, person_id),
+    FOREIGN KEY (group_id) REFERENCES merge_groups(id) ON DELETE CASCADE
+  )`,
+  `CREATE INDEX IF NOT EXISTS idx_merge_members_person ON merge_members(person_id)`,
+
+  // resolve_decisions: every yes/no verdict the pipeline (or user) has
+  // emitted for a pair. Lexicographic ordering on the two ids prevents
+  // both (A,B) and (B,A) ever existing.
+  `CREATE TABLE IF NOT EXISTS resolve_decisions (
+    a_person_id     TEXT NOT NULL,
+    b_person_id     TEXT NOT NULL,
+    verdict         TEXT NOT NULL,
+    confidence      REAL NOT NULL,
+    decided_at      INTEGER NOT NULL,
+    decided_by      TEXT NOT NULL,
+    reason          TEXT,
+    PRIMARY KEY (a_person_id, b_person_id)
+  )`,
+
+  // resolve_queue: backlog of Person rows pending pipeline processing.
+  // Adapter ingest hook enqueues; async worker drains.
+  `CREATE TABLE IF NOT EXISTS resolve_queue (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    person_id       TEXT NOT NULL,
+    enqueued_at     INTEGER NOT NULL,
+    status          TEXT NOT NULL DEFAULT 'pending',
+    attempts        INTEGER NOT NULL DEFAULT 0,
+    last_error      TEXT
+  )`,
+  `CREATE INDEX IF NOT EXISTS idx_resolve_queue_status ON resolve_queue(status, enqueued_at)`,
+
+  // review_queue: pairs the pipeline can't decide; user reviews via UI.
+  `CREATE TABLE IF NOT EXISTS review_queue (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    a_person_id     TEXT NOT NULL,
+    b_person_id     TEXT NOT NULL,
+    embed_sim       REAL,
+    llm_verdict     TEXT,
+    llm_reason      TEXT,
+    llm_confidence  REAL,
+    enqueued_at     INTEGER NOT NULL,
+    reviewed_at     INTEGER,
+    user_decision   TEXT
+  )`,
+  `CREATE INDEX IF NOT EXISTS idx_review_queue_pending ON review_queue(reviewed_at, enqueued_at)`,
+];
+
 const MIGRATIONS = [
   {
     version: 1,
@@ -187,6 +253,13 @@ const MIGRATIONS = [
       for (const sql of INITIAL_DDL) db.exec(sql);
     },
   },
+  {
+    version: 2,
+    description: "Phase 8 EntityResolver — merge_groups + merge_members + resolve_decisions + resolve_queue + review_queue",
+    up(db) {
+      for (const sql of PHASE_8_DDL) db.exec(sql);
+    },
+  },
 ];
 
 const TARGET_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;