@chainlesschain/personal-data-hub 0.1.0 → 0.2.0

package/lib/adapters/wechat/key-extractor.js

@@ -0,0 +1,158 @@
+/**
+ * Phase 12 v0.5 — WeChat legacy key extractor (frida-INDEPENDENT).
+ *
+ * Ports sjqz/parsers/wechat_decrypt.py legacy path to Node:
+ *
+ *   key = MD5(IMEI + UIN)[:7].lower()
+ *
+ * Works for WeChat versions < 8.0.X where the IMEI-derived key path is
+ * still active. WeChat 8.0+ requires Frida hook on `sqlite3_key` —
+ * that's Phase 12.6 (frida-dependent) and ships when device + Frida are
+ * available.
+ *
+ * Inputs:
+ *   - wechatDataPath: directory mirroring /data/data/com.tencent.mm/
+ *     after `adb pull` (or PC WeChat Files directory)
+ *   - Optional explicit overrides (imei, uin, manualKey) for testing or
+ *     when CompatibleInfo.cfg parsing fails
+ *
+ * Outputs:
+ *   {
+ *     uin: "1234567890",
+ *     imei: "1234567890abcdef",
+ *     key: "5d41402",         // 7-char hex MD5 prefix
+ *     source: "auth-xml+compatible-cfg" | "manual" | "...",
+ *     warnings: [...]
+ *   }
+ */
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+/**
+ * Extract UIN from shared_prefs/auth_info_key_prefs.xml or
+ * system_config_prefs.xml. UIN may be negative; can also be in
+ * `default_uin` or `_auth_uin` keys depending on WeChat version.
+ */
+function extractUinFromPrefs(wechatDataPath) {
+  const candidates = [
+    path.join(wechatDataPath, "shared_prefs", "auth_info_key_prefs.xml"),
+    path.join(wechatDataPath, "shared_prefs", "system_config_prefs.xml"),
+  ];
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    try {
+      const content = fs.readFileSync(p, "utf-8");
+      const patterns = [
+        /<int name="[^"]*_auth_uin[^"]*"\s+value="(-?\d+)"/,
+        /<int name="default_uin"\s+value="(-?\d+)"/,
+        /<int name="[^"]*uin[^"]*"\s+value="(-?\d+)"/,
+      ];
+      for (const re of patterns) {
+        const m = re.exec(content);
+        if (m) return { uin: m[1], from: path.basename(p) };
+      }
+    } catch (_e) {
+      // Try next candidate
+    }
+  }
+  return { uin: null, from: null };
+}
+
+/**
+ * Extract IMEI / device serial from CompatibleInfo.cfg. The file is a
+ * Java HashMap serialization; we use string-search for 15-digit IMEI
+ * patterns + GUIDs as fallback (matches sjqz approach).
+ */
+function extractImeiFromCompatibleInfo(wechatDataPath) {
+  const cfgPath = path.join(wechatDataPath, "MicroMsg", "CompatibleInfo.cfg");
+  if (!fs.existsSync(cfgPath)) return { imei: null, from: null };
+  try {
+    const buf = fs.readFileSync(cfgPath);
+    const text = buf.toString("binary"); // 8-bit safe — we don't care about decoding
+    // 15-digit IMEI
+    const imeiMatch = /\D(\d{15})\D/.exec(text);
+    if (imeiMatch) return { imei: imeiMatch[1], from: "CompatibleInfo.cfg (15-digit)" };
+    // Fallback: 14-digit + check digit pattern
+    const imei14 = /\D(\d{14})\D/.exec(text);
+    if (imei14) return { imei: imei14[1], from: "CompatibleInfo.cfg (14-digit)" };
+    // Fallback: GUID-like
+    const guid = /([0-9a-f]{32})/i.exec(text);
+    if (guid) return { imei: guid[1], from: "CompatibleInfo.cfg (guid)" };
+  } catch (_e) {}
+  return { imei: null, from: null };
+}
+
+/**
+ * Derive the SQLCipher key.
+ *
+ * @param {string} imei
+ * @param {string|number} uin
+ * @returns {string} 7-char hex prefix of MD5(IMEI+UIN), lowercase
+ */
+function deriveLegacyKey(imei, uin) {
+  if (typeof imei !== "string" || imei.length === 0) {
+    throw new Error("deriveLegacyKey: imei required");
+  }
+  if (uin == null) throw new Error("deriveLegacyKey: uin required");
+  const raw = String(imei) + String(uin);
+  return crypto.createHash("md5").update(raw, "utf-8").digest("hex").slice(0, 7).toLowerCase();
+}
+
+/**
+ * Top-level: extract key from a pulled WeChat data directory.
+ *
+ * @param {object} opts
+ * @param {string} opts.wechatDataPath   directory like the pulled
+ *                                       /data/data/com.tencent.mm/ tree
+ * @param {string} [opts.uin]            override (skip auth XML parse)
+ * @param {string} [opts.imei]           override (skip CompatibleInfo)
+ * @returns {object}  { uin, imei, key, source, warnings }
+ */
+function extractWeChatKey(opts = {}) {
+  if (!opts.wechatDataPath || typeof opts.wechatDataPath !== "string") {
+    throw new Error("extractWeChatKey: opts.wechatDataPath required");
+  }
+  const warnings = [];
+
+  let uin = opts.uin || null;
+  let uinSource = "manual";
+  if (!uin) {
+    const r = extractUinFromPrefs(opts.wechatDataPath);
+    uin = r.uin;
+    uinSource = r.from || "missing";
+    if (!uin) warnings.push("UIN not found in shared_prefs — adapter unusable without manual override");
+  }
+
+  let imei = opts.imei || null;
+  let imeiSource = "manual";
+  if (!imei) {
+    const r = extractImeiFromCompatibleInfo(opts.wechatDataPath);
+    imei = r.imei;
+    imeiSource = r.from || "missing";
+    if (!imei) warnings.push("IMEI not found in CompatibleInfo.cfg — adapter unusable without manual override");
+  }
+
+  if (!uin || !imei) {
+    return { uin, imei, key: null, source: `uin:${uinSource} | imei:${imeiSource}`, warnings };
+  }
+
+  const key = deriveLegacyKey(imei, uin);
+  return {
+    uin,
+    imei,
+    key,
+    source: `uin:${uinSource} | imei:${imeiSource}`,
+    warnings,
+  };
+}
+
+module.exports = {
+  extractWeChatKey,
+  deriveLegacyKey,
+  extractUinFromPrefs,
+  extractImeiFromCompatibleInfo,
+};

package/lib/adapters/wechat/normalize.js

@@ -0,0 +1,220 @@
+/**
+ * Phase 12 v0.5 — WeChat row → UnifiedSchema mapping.
+ *
+ * Per `Adapter_WeChat_SQLCipher.md` §7. Pure function (DB row in → batch
+ * out); orchestrated by WechatAdapter.normalize() during ingest.
+ */
+
+"use strict";
+
+const { newId } = require("../../ids");
+const { parseContent, isGroupTalker } = require("./content-parser");
+
+const NAME = "wechat";
+const VERSION = "0.5.0"; // Phase 12 v0.5 — frida-indep slice
+
+/**
+ * Map a single message row to a NormalizedBatch.
+ *
+ * @param {object} row    raw WeChat message row
+ * @param {object} ctx    { contactByUsername, chatroomByName, accountUin }
+ * @returns {NormalizedBatch}
+ */
+function normalizeMessage(row, ctx = {}) {
+  if (!row || typeof row !== "object") {
+    throw new Error("normalizeMessage: row required");
+  }
+  const parsed = parseContent(row);
+  const isGroup = isGroupTalker(row.talker);
+  const now = Date.now();
+  const occurredAt = Number.isFinite(Number(row.createTime)) ? Number(row.createTime) : now;
+  const isSend = Number(row.isSend) === 1;
+
+  const accountUin = ctx.accountUin || "wechat-self";
+  const selfId = `person-wechat-${accountUin}`;
+  const peerWxid = row.talker;
+  const peerId = peerWxid ? wxidToPersonId(peerWxid) : null;
+
+  // Group senders use the prefix in parsed.structured.senderWxid; in
+  // 1-on-1 chats actor = talker (inbound) or self (outbound).
+  let actorId;
+  if (isGroup) {
+    const senderWxid = parsed.structured && parsed.structured.senderWxid;
+    actorId = senderWxid ? wxidToPersonId(senderWxid) : (isSend ? selfId : peerId);
+  } else {
+    actorId = isSend ? selfId : peerId;
+  }
+
+  const participants = [];
+  if (peerId) participants.push(peerId);
+  participants.push(selfId);
+
+  const eventId = newId();
+  const source = {
+    adapter: NAME,
+    adapterVersion: VERSION,
+    originalId: String(row.msgSvrId || row.msgId || `wechat-msg-${eventId}`),
+    capturedAt: occurredAt,
+    capturedBy: "sqlite",
+  };
+
+  // Subtype mapping per UnifiedSchema EVENT_SUBTYPES
+  let subtype = "message";
+  if (parsed.kind === "voipcall") subtype = "call";
+  else if (parsed.kind === "system") subtype = "interaction";
+  else if (parsed.kind === "redpacket") subtype = "redenvelope";
+  else if (parsed.kind === "image" || parsed.kind === "video" || parsed.kind === "emoji" || parsed.kind === "voice") {
+    subtype = "media";
+  }
+  else subtype = "message";
+
+  const event = {
+    id: eventId,
+    type: "event",
+    subtype,
+    occurredAt,
+    actor: actorId || selfId,
+    participants: dedup(participants).filter(Boolean),
+    content: {
+      title: parsed.text.slice(0, 80) || "(无内容)",
+      text: parsed.text,
+    },
+    ingestedAt: now,
+    source,
+    extra: {
+      wechatType: Number(row.type),
+      isSend,
+      talker: row.talker,
+      ...(isGroup ? { isGroup: true, chatroom: row.talker } : {}),
+      ...parsed.structured,
+    },
+  };
+
+  // Persons — talker / sender; merge-group keys via wxid
+  const persons = [];
+  if (peerId && peerId !== selfId) {
+    persons.push({
+      id: peerId,
+      type: "person",
+      subtype: isGroup ? "unknown" : "contact",
+      names: [contactDisplayName(ctx.contactByUsername, row.talker)],
+      identifiers: { wechatId: row.talker },
+      ingestedAt: now,
+      source,
+      extra: { fromAdapter: NAME, wxid: row.talker },
+    });
+  }
+  // For group messages, also add the sender as a person if known
+  if (isGroup && parsed.structured && parsed.structured.senderWxid) {
+    const senderId = wxidToPersonId(parsed.structured.senderWxid);
+    if (senderId !== selfId && !persons.some((p) => p.id === senderId)) {
+      persons.push({
+        id: senderId,
+        type: "person",
+        subtype: "contact",
+        names: [contactDisplayName(ctx.contactByUsername, parsed.structured.senderWxid)],
+        identifiers: { wechatId: parsed.structured.senderWxid },
+        ingestedAt: now,
+        source,
+        extra: { fromAdapter: NAME, wxid: parsed.structured.senderWxid },
+      });
+    }
+  }
+
+  // Topic — every group chat is a Topic (per design doc OQ-4 = C)
+  const topics = [];
+  if (isGroup) {
+    const chatroomName = (ctx.chatroomByName && ctx.chatroomByName[row.talker])
+      || row.talker.replace("@chatroom", "");
+    topics.push({
+      id: `topic-wechat-group-${row.talker}`,
+      type: "topic",
+      name: chatroomName,
+      derivedFromEvents: [event.id],
+      ingestedAt: now,
+      source,
+      extra: { wxid: row.talker, fromAdapter: NAME },
+    });
+    if (!event.extra.topicId) event.extra.topicId = topics[0].id;
+  }
+
+  return { events: [event], persons, places: [], items: [], topics };
+}
+
+/**
+ * Map a contact row to a Person entity. Used for backfill — adapter
+ * yields RawContact records via sync(); normalize() turns them into
+ * persons.
+ */
+function normalizeContact(row, ctx = {}) {
+  if (!row || !row.username) return { events: [], persons: [], places: [], items: [], topics: [] };
+  const now = Date.now();
+  const source = {
+    adapter: NAME,
+    adapterVersion: VERSION,
+    originalId: `wechat-contact-${row.username}`,
+    capturedAt: now,
+    capturedBy: "sqlite",
+  };
+  const names = [row.conRemark, row.nickname, row.alias, row.username]
+    .filter((n) => typeof n === "string" && n.length > 0);
+  const subtype = guessContactSubtype(row);
+  const person = {
+    id: wxidToPersonId(row.username),
+    type: "person",
+    subtype,
+    names: dedup(names),
+    identifiers: { wechatId: row.username },
+    ingestedAt: now,
+    source,
+    extra: { fromAdapter: NAME, wxid: row.username, wechatType: row.type },
+  };
+  return { events: [], persons: [person], places: [], items: [], topics: [] };
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────
+
+function wxidToPersonId(wxid) {
+  if (!wxid) return null;
+  // Stable id keyed off wxid (Phase 8 EntityResolver R1 will dedup
+  // across adapters via the `wechatId` identifier).
+  return `person-wechat-${wxid}`;
+}
+
+function dedup(arr) {
+  const seen = new Set();
+  const out = [];
+  for (const x of arr) {
+    if (x == null || seen.has(x)) continue;
+    seen.add(x);
+    out.push(x);
+  }
+  return out;
+}
+
+function contactDisplayName(byUsername, wxid) {
+  if (byUsername && byUsername[wxid]) {
+    const c = byUsername[wxid];
+    return c.conRemark || c.nickname || c.alias || wxid;
+  }
+  return wxid;
+}
+
+function guessContactSubtype(row) {
+  // rcontact.type bits: official accounts / group / regular contact /
+  // black list. Detailed mapping in WeChat reverse-eng community —
+  // for v0.5 we keep it simple: anything that's not the user's self is
+  // "contact". Phase 12.6 will refine with full bit mapping.
+  if (typeof row.username === "string" && row.username.endsWith("@chatroom")) {
+    return "unknown"; // chat group, not a Person
+  }
+  return "contact";
+}
+
+module.exports = {
+  normalizeMessage,
+  normalizeContact,
+  wxidToPersonId,
+  NAME,
+  VERSION,
+};

package/lib/adapters/wechat/wechat-adapter.js

@@ -0,0 +1,205 @@
+/**
+ * Phase 12 v0.5 — WechatAdapter (frida-INDEPENDENT slice).
+ *
+ * Per `Adapter_WeChat_SQLCipher.md` §17.2 buildable-now scope. This is
+ * the 60% of Phase 12 that can land without rooted device + Frida:
+ * everything from "DB file is decrypted at this path on disk" forward.
+ *
+ * Flow:
+ *   1. UI / CLI workflow drives the on-device pull via AndroidExtractor
+ *      (Phase 7.5) — copies EnMicroMsg.db to a local cache.
+ *   2. keyProvider returns the key (legacy: KeyExtractor MD5(IMEI+UIN)
+ *      computes it; Phase 12.6 hot path: Frida hook fetches it).
+ *   3. WechatAdapter.sync() opens the DB via WeChatDBReader, iterates
+ *      message + contact tables, yields raw events.
+ *   4. normalize() turns each row into UnifiedSchema entities.
+ *
+ * Watermark: max msgSvrId per scope. Adapter sync({sinceWatermark}) is
+ * a high-water filter rather than per-talker — Phase 12.6 adds the
+ * per-talker variant.
+ */
+
+"use strict";
+
+const fs = require("node:fs");
+
+const { CAPTURED_BY } = require("../../constants");
+const { WeChatDBReader } = require("./db-reader");
+const { normalizeMessage, normalizeContact, NAME, VERSION } = require("./normalize");
+
+class WechatAdapter {
+  constructor(opts = {}) {
+    if (!opts || typeof opts !== "object") {
+      throw new Error("WechatAdapter: opts required");
+    }
+    if (!opts.account || typeof opts.account !== "object") {
+      throw new Error("WechatAdapter: opts.account required");
+    }
+    if (!opts.account.uin) {
+      throw new Error("WechatAdapter: opts.account.uin required (WeChat user identifier)");
+    }
+    this.account = opts.account;
+    // dbPath: local path to the (already-pulled) decrypted-source
+    // EnMicroMsg.db. Test seam.
+    this._dbPath = opts.dbPath || null;
+    // keyProvider: { getKey(): Promise<string> }. v0.5 default is
+    // a synthetic provider for tests; production wires this to either
+    // KeyExtractor (legacy) or Frida bridge (Phase 12.6).
+    this._keyProvider = opts.keyProvider || null;
+    // DI seam for tests — swap the DB reader
+    this._dbReaderFactory = typeof opts.dbReaderFactory === "function"
+      ? opts.dbReaderFactory
+      : null;
+
+    this.name = NAME;
+    this.version = VERSION;
+    this.capabilities = [
+      "sync:sqlite",
+      "auth:keystore",
+      "decrypt:sqlcipher-v1",
+      "parse:wechat-message",
+    ];
+    this.extractMode = "device-pull"; // Phase 7.5 contract field
+    this.rateLimits = {};
+    this.dataDisclosure = {
+      fields: [
+        "wechat:messages (text + group + 1-on-1 chats from EnMicroMsg.db)",
+        "wechat:contacts (rcontact: nickname / alias / 备注名)",
+        "wechat:chatrooms (group display names + member lists)",
+      ],
+      sensitivity: "high",
+      legalGate: true, // first-use 法律 gate per design doc OQ-7
+    };
+  }
+
+  async authenticate() {
+    // No server auth; sanity check the on-disk state.
+    if (!this._dbPath || !fs.existsSync(this._dbPath)) {
+      return { ok: false, reason: "DB_NOT_PULLED", error: `DB path missing: ${this._dbPath}` };
+    }
+    if (!this._keyProvider || typeof this._keyProvider.getKey !== "function") {
+      return { ok: false, reason: "NO_KEY_PROVIDER", error: "keyProvider required" };
+    }
+    try {
+      const key = await this._keyProvider.getKey();
+      if (!key) return { ok: false, reason: "EMPTY_KEY", error: "keyProvider returned empty key" };
+      return { ok: true, account: this.account.uin };
+    } catch (err) {
+      return { ok: false, reason: "KEY_PROVIDER_THREW", error: err && err.message ? err.message : String(err) };
+    }
+  }
+
+  async healthCheck() {
+    const r = await this.authenticate();
+    if (r.ok) return { ok: true, lastChecked: Date.now() };
+    return { ok: false, reason: r.reason, error: r.error };
+  }
+
+  /**
+   * Iterate WeChat data → RawEvent stream. Each row becomes one raw
+   * event with `payload.kind = "message"` or `"contact"`.
+   *
+   * @param {object} opts
+   * @param {string|number} [opts.sinceWatermark]  max msgSvrId watermark
+   * @param {number} [opts.maxPerType=10_000]
+   * @param {Function} [opts.onProgress]
+   */
+  async *sync(opts = {}) {
+    const onProgress = typeof opts.onProgress === "function" ? opts.onProgress : null;
+    const emit = (phase, payload = {}) => {
+      if (!onProgress) return;
+      try { onProgress({ phase, adapter: NAME, ...payload }); } catch (_e) {}
+    };
+
+    if (!this._dbPath || !fs.existsSync(this._dbPath)) {
+      // No DB pulled yet — registry-safe idle no-op
+      emit("idle", { reason: "no DB at " + this._dbPath });
+      return;
+    }
+    const maxPerType = Number.isFinite(opts.maxPerType) ? opts.maxPerType : 10_000;
+    const sinceMsgSvrId = parseWatermark(opts.sinceWatermark);
+
+    emit("opening", { dbPath: this._dbPath });
+    const Reader = this._dbReaderFactory || ((readerOpts) => new WeChatDBReader(readerOpts));
+    const reader = Reader({ dbPath: this._dbPath, keyProvider: this._keyProvider });
+
+    try {
+      const openInfo = await reader.open();
+      emit("opened", { profile: openInfo.profile, tables: openInfo.tables });
+
+      if (!reader.isEnMicroMsg()) {
+        emit("error", { phase: "verify", message: "not an EnMicroMsg.db (missing message/rcontact)" });
+        return;
+      }
+
+      // Contacts first — gives normalize() context for message senders
+      const contacts = reader.fetchContacts({ limit: 10_000 });
+      emit("contacts-loaded", { count: contacts.length });
+      const contactByUsername = {};
+      for (const c of contacts) contactByUsername[c.username] = c;
+      for (const c of contacts) {
+        yield this._rowToRaw("contact", c, { contactByUsername });
+      }
+
+      // Chatrooms — produce Topics
+      const chatrooms = reader.fetchChatrooms({ limit: 5000 });
+      const chatroomByName = {};
+      for (const cr of chatrooms) chatroomByName[cr.chatroomname] = cr.displayname || cr.chatroomname;
+      emit("chatrooms-loaded", { count: chatrooms.length });
+
+      // Messages
+      const messages = reader.fetchMessages({ sinceMsgSvrId, limit: maxPerType });
+      emit("messages-loaded", { count: messages.length, since: sinceMsgSvrId });
+      let count = 0;
+      let maxSvr = sinceMsgSvrId;
+      for (const m of messages) {
+        count += 1;
+        if (Number(m.msgSvrId) > maxSvr) maxSvr = Number(m.msgSvrId);
+        emit("processing", { current: count, total: messages.length, msgSvrId: m.msgSvrId });
+        yield this._rowToRaw("message", m, { contactByUsername, chatroomByName });
+      }
+      emit("done", { messagesYielded: count, newWatermark: maxSvr });
+    } finally {
+      try { reader.close(); } catch (_e) {}
+    }
+  }
+
+  normalize(raw) {
+    if (!raw || !raw.payload) {
+      throw new Error("WechatAdapter.normalize: raw.payload missing");
+    }
+    const ctx = {
+      accountUin: this.account.uin,
+      contactByUsername: raw.payload.contactByUsername || {},
+      chatroomByName: raw.payload.chatroomByName || {},
+    };
+    if (raw.payload.kind === "contact") {
+      return normalizeContact(raw.payload.row, ctx);
+    }
+    return normalizeMessage(raw.payload.row, ctx);
+  }
+
+  _rowToRaw(kind, row, ctxExtras = {}) {
+    const originalId = kind === "message"
+      ? String(row.msgSvrId || row.msgId)
+      : `contact-${row.username}`;
+    return {
+      adapter: NAME,
+      originalId,
+      capturedAt: Date.now(),
+      payload: {
+        kind,
+        row,
+        ...ctxExtras,
+      },
+    };
+  }
+}
+
+function parseWatermark(wm) {
+  if (wm == null) return 0;
+  const n = parseInt(String(wm), 10);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+module.exports = { WechatAdapter, NAME, VERSION };

package/lib/analysis-skills/base.js

@@ -0,0 +1,113 @@
+/**
+ * Phase 11 — Analysis skills base.
+ *
+ * Each skill = a focused analysis function over the vault. Inputs are
+ * a small typed options bag (time range + dimension + filters); output
+ * is `{ summary, breakdown, llm_commentary?, citations }`.
+ *
+ * Skills are pure logic on vault data + optional LLM commentary. They
+ * compose with cross-source merge groups (Phase 8 EntityResolver) so
+ * "上个月给我妈花了多少" returns combined Email + Alipay + WeChat
+ * spending tied to the same merged Person.
+ *
+ * Skills share these conventions:
+ *   - `vault` injected at construction
+ *   - `llm` optional; when null, skill returns pure-data result (no
+ *     commentary); when provided, llm.chat() generates a 1-2 sentence
+ *     prose commentary on the breakdown.
+ *   - `timeWindow` is `{ since, until }` ms epoch pair; absent = all-time
+ *   - results always carry `citations` = list of event ids that
+ *     contributed to the answer (lets UI deep-link back per Phase 5.6
+ *     citation flow)
+ *
+ * Privacy invariant: every skill that calls llm passes
+ * `acceptNonLocal: false` to the wrapper; non-local LLMs need explicit
+ * opt-in from the caller (same gate as AnalysisEngine).
+ */
+
+"use strict";
+
+class AnalysisSkill {
+  constructor(opts) {
+    if (!opts || typeof opts !== "object") {
+      throw new Error("AnalysisSkill: opts required");
+    }
+    if (!opts.vault) {
+      throw new Error("AnalysisSkill: opts.vault required");
+    }
+    this.vault = opts.vault;
+    this.llm = opts.llm || null; // optional
+    this.name = opts.name || "unnamed";
+  }
+
+  async run(_options = {}) {
+    throw new Error(`AnalysisSkill.run() not implemented for ${this.name}`);
+  }
+
+  // ─── helpers shared by skills ───────────────────────────────────────
+
+  /**
+   * Normalize a time window. Accepts:
+   *   - { since, until }      ms epoch
+   *   - { sinceDays }         relative (now - N days)
+   *   - { sinceMonths }       relative
+   * Returns `{ since, until }` ms or `{ since: null, until: null }` for
+   * all-time.
+   */
+  resolveTimeWindow(options = {}) {
+    const now = Date.now();
+    if (typeof options.since === "number" && options.since > 0) {
+      return {
+        since: options.since,
+        until: typeof options.until === "number" ? options.until : now,
+      };
+    }
+    if (typeof options.sinceDays === "number" && options.sinceDays > 0) {
+      return {
+        since: now - options.sinceDays * 24 * 3600_000,
+        until: now,
+      };
+    }
+    if (typeof options.sinceMonths === "number" && options.sinceMonths > 0) {
+      return {
+        since: now - options.sinceMonths * 30 * 24 * 3600_000,
+        until: now,
+      };
+    }
+    return { since: null, until: null };
+  }
+
+  /**
+   * Expand a personId to "all Person ids in its merge group". If
+   * EntityResolver hasn't merged anyone, returns just `[personId]`.
+   * Phase 8 closure utility.
+   */
+  expandToMergeGroup(personId) {
+    if (!personId) return [];
+    try {
+      if (typeof this.vault.getMergeGroupMembers === "function") {
+        return this.vault.getMergeGroupMembers(personId);
+      }
+    } catch (_e) {}
+    return [personId];
+  }
+
+  /**
+   * Wrap llm.chat() with the privacy gate. Returns the response text or
+   * null when LLM is unavailable / non-local without opt-in.
+   */
+  async callLlmCommentary(messages, opts = {}) {
+    if (!this.llm || typeof this.llm.chat !== "function") return null;
+    if (this.llm.isLocal === false && !opts.acceptNonLocal) {
+      return null;
+    }
+    try {
+      const r = await this.llm.chat(messages, { temperature: 0.2, ...opts });
+      return (r && r.text) || null;
+    } catch (_e) {
+      return null;
+    }
+  }
+}
+
+module.exports = { AnalysisSkill };