@chainlesschain/personal-data-hub 0.1.0 → 0.2.0

package/lib/sidecar/supervisor.js

@@ -0,0 +1,359 @@
+/**
+ * SidecarSupervisor — manages the forensics-bridge Python sidecar lifecycle.
+ *
+ * Protocol: docs/design/Personal_Data_Hub_Python_Sidecar.md §3 (JSON-lines).
+ * Counterpart: packages/personal-data-hub-bridge/forensics_bridge/ipc_server.py.
+ *
+ * Responsibilities:
+ *   - Spawn / health-check / restart the sidecar subprocess
+ *   - Frame stdin/stdout as JSON-lines (one envelope per line)
+ *   - Correlate request id → pending promise; route progress/chunk callbacks
+ *   - Forward stderr logs as events for hub audit logging
+ *
+ * Non-goals (this layer):
+ *   - Persisting credentials (caller passes them per-invoke)
+ *   - Audit logging (caller subscribes to "log" events)
+ *   - Schema validation of params (Python side enforces)
+ */
+
+"use strict";
+
+const { spawn } = require("node:child_process");
+const { EventEmitter } = require("node:events");
+const crypto = require("node:crypto");
+const readline = require("node:readline");
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_HEALTHCHECK_INTERVAL_MS = 30_000;
+const STOP_GRACE_MS = 5_000;
+
+class SidecarTimeoutError extends Error {
+  constructor(method, timeoutMs) {
+    super(`sidecar method '${method}' timed out after ${timeoutMs}ms`);
+    this.name = "SidecarTimeoutError";
+    this.code = "TIMEOUT";
+    this.retryable = true;
+  }
+}
+
+class SidecarMethodError extends Error {
+  constructor({ code, msg, retryable }) {
+    super(msg || code);
+    this.name = "SidecarMethodError";
+    this.code = code;
+    this.retryable = Boolean(retryable);
+  }
+}
+
+class SidecarNotRunningError extends Error {
+  constructor(method) {
+    super(`sidecar is not running; cannot invoke '${method}'`);
+    this.name = "SidecarNotRunningError";
+    this.code = "SIDECAR_NOT_RUNNING";
+    this.retryable = true;
+  }
+}
+
+class SidecarSupervisor extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string|string[]} opts.command - Executable (string) or [exec, ...args] for spawn.
+   * @param {string[]} [opts.args] - Extra args appended after `command`.
+   * @param {string} [opts.cwd] - Working directory for the child.
+   * @param {object} [opts.env] - Env vars merged over process.env.
+   * @param {number} [opts.healthCheckIntervalMs] - 0 to disable.
+   * @param {number} [opts.defaultTimeoutMs] - Per-invoke default.
+   */
+  constructor(opts) {
+    super();
+    if (!opts || !opts.command) {
+      throw new Error("SidecarSupervisor requires opts.command");
+    }
+    const [first, ...rest] = Array.isArray(opts.command)
+      ? opts.command
+      : [opts.command];
+    this._exec = first;
+    this._args = [...rest, ...(opts.args || [])];
+    this._cwd = opts.cwd;
+    this._env = opts.env;
+    this._healthCheckIntervalMs =
+      opts.healthCheckIntervalMs ?? DEFAULT_HEALTHCHECK_INTERVAL_MS;
+    this._defaultTimeoutMs = opts.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+    this._proc = null;
+    this._stdoutReader = null;
+    this._stderrReader = null;
+    this._pending = new Map(); // id → { resolve, reject, timer, onProgress, onChunk, method }
+    this._healthTimer = null;
+    this._stopping = false;
+  }
+
+  /**
+   * Spawn the sidecar and verify it responds to sidecar.ping.
+   * Idempotent — calling start() twice returns the same ready promise.
+   */
+  async start({ readyTimeoutMs = 5_000 } = {}) {
+    if (this._proc && !this._proc.killed) {
+      return; // already running
+    }
+
+    const env = {
+      ...process.env,
+      ...(this._env || {}),
+      PYTHONIOENCODING: "utf-8",
+      PYTHONUNBUFFERED: "1",
+    };
+
+    this._proc = spawn(this._exec, this._args, {
+      cwd: this._cwd,
+      env,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+    });
+
+    this._stopping = false;
+    this._wireStreams();
+
+    this._proc.on("error", (err) => {
+      this.emit("error", err);
+      this._failAllPending(err);
+    });
+
+    this._proc.on("exit", (code, signal) => {
+      this.emit("exit", { code, signal });
+      const reason = new Error(
+        `sidecar exited (code=${code} signal=${signal})`,
+      );
+      this._failAllPending(reason);
+      this._teardown();
+    });
+
+    await this.invoke("sidecar.ping", {}, { timeoutMs: readyTimeoutMs });
+    this._scheduleHealthCheck();
+  }
+
+  /**
+   * Invoke a sidecar method.
+   *
+   * @param {string} method
+   * @param {object} params
+   * @param {object} [opts]
+   * @param {number} [opts.timeoutMs]
+   * @param {(data: object) => void} [opts.onProgress] - invoked on progress envelopes
+   * @param {(data: object) => void} [opts.onChunk]    - invoked on chunk envelopes
+   * @returns {Promise<object>} resolves with the final `result.data`
+   */
+  invoke(method, params = {}, opts = {}) {
+    if (!this._proc || this._proc.killed || this._stopping) {
+      return Promise.reject(new SidecarNotRunningError(method));
+    }
+    const timeoutMs = opts.timeoutMs ?? this._defaultTimeoutMs;
+    const id =
+      typeof crypto.randomUUID === "function"
+        ? crypto.randomUUID()
+        : `req-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(id);
+        // Best-effort cancel on the sidecar side; don't await the response.
+        this._writeLine({
+          id: `cancel-${id}`,
+          method: "request.cancel",
+          params: { id },
+        }).catch(() => {});
+        reject(new SidecarTimeoutError(method, timeoutMs));
+      }, timeoutMs);
+      // Allow the process to exit even if a sidecar invocation timer is pending.
+      if (typeof timer.unref === "function") timer.unref();
+
+      this._pending.set(id, {
+        resolve,
+        reject,
+        timer,
+        onProgress: opts.onProgress,
+        onChunk: opts.onChunk,
+        method,
+      });
+
+      const envelope = { id, method, params, timeout_ms: timeoutMs };
+      this._writeLine(envelope).catch((err) => {
+        clearTimeout(timer);
+        this._pending.delete(id);
+        reject(err);
+      });
+    });
+  }
+
+  /**
+   * Stop the sidecar: SIGTERM → wait grace → SIGKILL.
+   * Pending invocations reject with SidecarNotRunningError.
+   */
+  async stop({ graceMs = STOP_GRACE_MS } = {}) {
+    if (!this._proc || this._proc.killed) {
+      this._teardown();
+      return;
+    }
+    this._stopping = true;
+    if (this._healthTimer) {
+      clearInterval(this._healthTimer);
+      this._healthTimer = null;
+    }
+    const proc = this._proc;
+    const exited = new Promise((res) => proc.once("exit", res));
+    try {
+      proc.stdin?.end();
+    } catch (_err) {
+      /* already closed */
+    }
+    proc.kill("SIGTERM");
+    const killed = await Promise.race([
+      exited.then(() => true),
+      new Promise((res) => {
+        const t = setTimeout(() => res(false), graceMs);
+        if (typeof t.unref === "function") t.unref();
+      }),
+    ]);
+    if (!killed) {
+      proc.kill("SIGKILL");
+      await exited;
+    }
+    this._teardown();
+  }
+
+  isRunning() {
+    return Boolean(this._proc) && !this._proc.killed && !this._stopping;
+  }
+
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+
+  _wireStreams() {
+    this._stdoutReader = readline.createInterface({
+      input: this._proc.stdout,
+      crlfDelay: Infinity,
+    });
+    this._stdoutReader.on("line", (line) => {
+      if (!line) return;
+      let envelope;
+      try {
+        envelope = JSON.parse(line);
+      } catch (err) {
+        this.emit("error", new Error(`invalid envelope from sidecar: ${line}`));
+        return;
+      }
+      this._handleEnvelope(envelope);
+    });
+
+    this._stderrReader = readline.createInterface({
+      input: this._proc.stderr,
+      crlfDelay: Infinity,
+    });
+    this._stderrReader.on("line", (line) => {
+      if (!line) return;
+      // Sidecar logs pino-style JSON; pass through for hub audit.
+      this.emit("log", line);
+    });
+  }
+
+  _handleEnvelope(env) {
+    // Envelopes with no id (e.g. INVALID_JSON parse failures) surface as events.
+    if (env.id === null || env.id === undefined) {
+      this.emit("orphan", env);
+      return;
+    }
+    const pending = this._pending.get(env.id);
+    if (!pending) {
+      this.emit("orphan", env);
+      return;
+    }
+
+    if (env.type === "progress") {
+      try {
+        pending.onProgress?.(env.data);
+      } catch (err) {
+        this.emit("error", err);
+      }
+      return;
+    }
+    if (env.type === "chunk") {
+      try {
+        pending.onChunk?.(env.data);
+      } catch (err) {
+        this.emit("error", err);
+      }
+      return;
+    }
+    // Terminal frames remove the pending entry.
+    clearTimeout(pending.timer);
+    this._pending.delete(env.id);
+
+    if (env.type === "result") {
+      pending.resolve(env.data);
+    } else if (env.type === "error") {
+      pending.reject(new SidecarMethodError(env.error || { code: "UNKNOWN" }));
+    } else {
+      pending.reject(
+        new SidecarMethodError({
+          code: "UNKNOWN_ENVELOPE_TYPE",
+          msg: `unexpected envelope type: ${env.type}`,
+        }),
+      );
+    }
+  }
+
+  _writeLine(envelope) {
+    return new Promise((resolve, reject) => {
+      if (!this._proc || !this._proc.stdin || this._proc.stdin.destroyed) {
+        reject(new SidecarNotRunningError(envelope.method || "<unknown>"));
+        return;
+      }
+      const line = JSON.stringify(envelope) + "\n";
+      this._proc.stdin.write(line, "utf8", (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+
+  _scheduleHealthCheck() {
+    if (!this._healthCheckIntervalMs) return;
+    if (this._healthTimer) clearInterval(this._healthTimer);
+    this._healthTimer = setInterval(() => {
+      this.invoke("sidecar.ping", {}, { timeoutMs: 3_000 }).catch((err) => {
+        this.emit("healthCheckFailed", err);
+      });
+    }, this._healthCheckIntervalMs);
+    if (typeof this._healthTimer.unref === "function") {
+      this._healthTimer.unref();
+    }
+  }
+
+  _failAllPending(err) {
+    for (const [, pending] of this._pending) {
+      clearTimeout(pending.timer);
+      pending.reject(err);
+    }
+    this._pending.clear();
+  }
+
+  _teardown() {
+    if (this._healthTimer) {
+      clearInterval(this._healthTimer);
+      this._healthTimer = null;
+    }
+    this._stdoutReader?.close();
+    this._stderrReader?.close();
+    this._stdoutReader = null;
+    this._stderrReader = null;
+    this._proc = null;
+  }
+}
+
+module.exports = {
+  SidecarSupervisor,
+  SidecarTimeoutError,
+  SidecarMethodError,
+  SidecarNotRunningError,
+};

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.
@@ -716,6 +723,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 +736,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.0",
   "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,31 @@
     "./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",
+    "./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/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 +79,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"