@chainlesschain/personal-data-hub 0.2.0 → 0.2.1

package/__tests__/adapters/wechat-md5-key-provider.test.js

@@ -0,0 +1,101 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const {
+  WeChatKeyProvider,
+  WeChatMD5KeyProvider,
+} = require("../../lib/adapters/wechat");
+
+describe("WeChatKeyProvider — base contract", () => {
+  it("getKey throws on bare base instance (subclass must override)", async () => {
+    const base = new WeChatKeyProvider();
+    await expect(base.getKey()).rejects.toThrow(/must be overridden/);
+  });
+
+  it("name defaults to key-provider-base", () => {
+    const base = new WeChatKeyProvider();
+    expect(base.name).toBe("key-provider-base");
+  });
+});
+
+describe("WeChatMD5KeyProvider — construction validation", () => {
+  it("throws if opts missing", () => {
+    expect(() => new WeChatMD5KeyProvider()).toThrow(/wechatDataPath/);
+  });
+
+  it("throws if wechatDataPath missing", () => {
+    expect(() => new WeChatMD5KeyProvider({ uin: "1" })).toThrow(/wechatDataPath/);
+  });
+
+  it("name returns md5", () => {
+    const p = new WeChatMD5KeyProvider({ wechatDataPath: "/tmp/wx" });
+    expect(p.name).toBe("md5");
+  });
+});
+
+describe("WeChatMD5KeyProvider — extractor DI happy path", () => {
+  it("getKey returns hex when extractor yields key", async () => {
+    const extractor = (opts) => {
+      expect(opts.wechatDataPath).toBe("/tmp/wx");
+      return {
+        uin: "100200300",
+        imei: "350123456789012",
+        key: "abcdef1",
+        source: "test",
+        warnings: [],
+      };
+    };
+    const p = new WeChatMD5KeyProvider({
+      wechatDataPath: "/tmp/wx",
+      extractor,
+    });
+    const key = await p.getKey();
+    expect(key).toBe("abcdef1");
+    expect(p.getLastResult().uin).toBe("100200300");
+    expect(p.getLastResult().imei).toBe("350123456789012");
+  });
+
+  it("getKey passes uin/imei overrides through to extractor", async () => {
+    let passedOpts = null;
+    const extractor = (opts) => {
+      passedOpts = opts;
+      return { key: "0000000", uin: opts.uin, imei: opts.imei, warnings: [] };
+    };
+    const p = new WeChatMD5KeyProvider({
+      wechatDataPath: "/tmp/wx",
+      uin: "999",
+      imei: "deadbeef",
+      extractor,
+    });
+    await p.getKey();
+    expect(passedOpts.uin).toBe("999");
+    expect(passedOpts.imei).toBe("deadbeef");
+  });
+});
+
+describe("WeChatMD5KeyProvider — extractor failure surfaces as throw", () => {
+  it("throws with warnings when extractor returns no key", async () => {
+    const extractor = () => ({
+      uin: null,
+      imei: null,
+      key: null,
+      source: "missing",
+      warnings: ["UIN not found in shared_prefs", "IMEI not found in CompatibleInfo.cfg"],
+    });
+    const p = new WeChatMD5KeyProvider({
+      wechatDataPath: "/tmp/empty",
+      extractor,
+    });
+    await expect(p.getKey()).rejects.toThrow(/UIN not found/);
+  });
+
+  it("throws with generic reason when warnings empty", async () => {
+    const extractor = () => ({ key: null, warnings: [] });
+    const p = new WeChatMD5KeyProvider({
+      wechatDataPath: "/tmp/empty",
+      extractor,
+    });
+    await expect(p.getKey()).rejects.toThrow(/extraction returned empty/);
+  });
+});

package/__tests__/analysis-skills.test.js

@@ -250,6 +250,64 @@ describe("RelationsSkill", () => {
     expect(r.ranked[0].personId).toBe("p-mom");
     expect(r.ranked[0].totalInteractions).toBe(2);
   });
+
+  it("empty vault → ranked mode returns empty list, no crash", async () => {
+    const skill = new RelationsSkill({ vault: rig.vault });
+    const r = await skill.run({});
+    expect(r.mode).toBe("ranked");
+    expect(r.ranked).toEqual([]);
+    expect(r.citations).toEqual([]);
+    expect(r.llm_commentary).toBeNull();
+  });
+
+  it("non-local LLM gate: isLocal=false without acceptNonLocal → commentary stays null", async () => {
+    makePerson(rig.vault, "p-mom", ["妈"]);
+    makePayment(rig.vault, { id: "e1", occurredAt: ts(2026, 5, 1), counterpartyId: "p-mom", counterpartyName: "妈", amount: 100 });
+    const nonLocalLlm = {
+      isLocal: false,
+      chat: async () => ({ text: "this should never reach the caller" }),
+    };
+    const skill = new RelationsSkill({ vault: rig.vault, llm: nonLocalLlm });
+    const r = await skill.run({ personId: "p-mom" });
+    expect(r.mode).toBe("single");
+    expect(r.profile.totalInteractions).toBe(1);
+    // gate enforced by base.callLlmCommentary
+    expect(r.llm_commentary).toBeNull();
+  });
+
+  it("LLM exception swallowed → commentary null but profile data intact", async () => {
+    makePerson(rig.vault, "p-mom", ["妈"]);
+    makePayment(rig.vault, { id: "e1", occurredAt: ts(2026, 5, 1), counterpartyId: "p-mom", counterpartyName: "妈", amount: 100 });
+    const throwingLlm = {
+      isLocal: true,
+      chat: async () => { throw new Error("model timeout"); },
+    };
+    const skill = new RelationsSkill({ vault: rig.vault, llm: throwingLlm });
+    const r = await skill.run({ personId: "p-mom" });
+    expect(r.profile.totalInteractions).toBe(1); // data path unaffected
+    expect(r.llm_commentary).toBeNull();
+  });
+
+  it("merge-group expansion: vault.getMergeGroupMembers fans the personId out", async () => {
+    // Two PersonIds representing the same real-world person across sources;
+    // EntityResolver (Phase 8) would normally merge them into a group.
+    makePerson(rig.vault, "p-mom-email", ["妈"], { email: ["mom@163.com"] });
+    makePerson(rig.vault, "p-mom-alipay", ["陈XX"], { alipay: ["mom@163.com"] });
+    makePayment(rig.vault, { id: "e1", occurredAt: ts(2026, 4, 1), counterpartyId: "p-mom-email", counterpartyName: "妈", amount: 200, adapter: "email-imap" });
+    makePayment(rig.vault, { id: "e2", occurredAt: ts(2026, 5, 1), counterpartyId: "p-mom-alipay", counterpartyName: "陈XX", amount: 300, adapter: "alipay-bill" });
+
+    // Stub the resolver hook
+    rig.vault.getMergeGroupMembers = (pid) =>
+      (pid === "p-mom-email" || pid === "p-mom-alipay")
+        ? ["p-mom-email", "p-mom-alipay"]
+        : [pid];
+
+    const skill = new RelationsSkill({ vault: rig.vault });
+    const r = await skill.run({ personId: "p-mom-email" });
+    expect(r.profile.totalInteractions).toBe(2); // both events counted
+    expect(r.profile.totalSpend).toBe(500);
+    expect(Object.keys(r.profile.byAdapter).sort()).toEqual(["alipay-bill", "email-imap"]);
+  });
 });
 
 // ─── FootprintSkill ──────────────────────────────────────────────────────
@@ -301,6 +359,55 @@ describe("FootprintSkill", () => {
     expect(r.summary.totalTrips).toBe(0);
     expect(r.topPlaces).toEqual([]);
   });
+
+  it("local LLM commentary fires when trips present", async () => {
+    rig.vault.putEvent({
+      id: "trip-1", type: "event", subtype: "trip",
+      occurredAt: ts(2026, 4, 1),
+      actor: "person-self",
+      content: { title: "Hangzhou trip" },
+      ingestedAt: Date.now(),
+      source: defaultSource("travel"),
+      extra: { to: "Hangzhou" },
+    });
+    const llm = { isLocal: true, chat: async () => ({ text: "你这个月去过 1 个地方。" }) };
+    const skill = new FootprintSkill({ vault: rig.vault, llm });
+    const r = await skill.run({});
+    expect(r.llm_commentary).toBe("你这个月去过 1 个地方。");
+  });
+
+  it("non-local LLM gate → llm_commentary null", async () => {
+    rig.vault.putEvent({
+      id: "trip-1", type: "event", subtype: "trip",
+      occurredAt: ts(2026, 4, 1),
+      actor: "person-self",
+      content: { title: "Beijing" },
+      ingestedAt: Date.now(),
+      source: defaultSource("travel"),
+      extra: { to: "Beijing" },
+    });
+    const llm = { isLocal: false, chat: async () => ({ text: "should not appear" }) };
+    const skill = new FootprintSkill({ vault: rig.vault, llm });
+    const r = await skill.run({});
+    expect(r.llm_commentary).toBeNull();
+  });
+
+  it("LLM exception swallowed → commentary null but data intact", async () => {
+    rig.vault.putEvent({
+      id: "trip-1", type: "event", subtype: "trip",
+      occurredAt: ts(2026, 4, 1),
+      actor: "person-self",
+      content: { title: "Tokyo" },
+      ingestedAt: Date.now(),
+      source: defaultSource("travel"),
+      extra: { to: "Tokyo" },
+    });
+    const llm = { isLocal: true, chat: async () => { throw new Error("net down"); } };
+    const skill = new FootprintSkill({ vault: rig.vault, llm });
+    const r = await skill.run({});
+    expect(r.summary.totalTrips).toBe(1);
+    expect(r.llm_commentary).toBeNull();
+  });
 });
 
 // ─── InterestsSkill ──────────────────────────────────────────────────────
@@ -349,6 +456,46 @@ describe("InterestsSkill", () => {
     expect(r.llmInterests).toHaveLength(1);
     expect(r.llmInterests[0].category).toBe("摄影");
   });
+
+  it("empty vault → topTopics + topItems empty, no crash", async () => {
+    const skill = new InterestsSkill({ vault: rig.vault });
+    const r = await skill.run({});
+    expect(r.topTopics).toEqual([]);
+    expect(r.topItems).toEqual([]);
+    expect(r.llmInterests).toBeNull();
+  });
+
+  it("non-local LLM gate → llmInterests null even with topics present", async () => {
+    rig.vault.putTopic({
+      id: "topic-b", type: "topic", name: "Cooking",
+      derivedFromEvents: ["e-1"],
+      ingestedAt: Date.now(), source: defaultSource("test"),
+    });
+    const llm = {
+      isLocal: false,
+      chat: async () => ({ text: '[{"category":"烹饪","evidenceCount":1,"examples":["Cooking"]}]' }),
+    };
+    const skill = new InterestsSkill({ vault: rig.vault, llm });
+    const r = await skill.run({});
+    expect(r.topTopics[0].name).toBe("Cooking");
+    expect(r.llmInterests).toBeNull();
+  });
+
+  it("LLM clustering exception swallowed → llmInterests null but data intact", async () => {
+    rig.vault.putTopic({
+      id: "topic-c", type: "topic", name: "Travel",
+      derivedFromEvents: ["e-1", "e-2"],
+      ingestedAt: Date.now(), source: defaultSource("test"),
+    });
+    const llm = {
+      isLocal: true,
+      chat: async () => { throw new Error("vllm 500"); },
+    };
+    const skill = new InterestsSkill({ vault: rig.vault, llm });
+    const r = await skill.run({});
+    expect(r.topTopics[0].name).toBe("Travel");
+    expect(r.llmInterests).toBeNull();
+  });
 });
 
 // ─── TimelineSkill ──────────────────────────────────────────────────────

package/__tests__/analysis.test.js

@@ -1,6 +1,6 @@
 "use strict";
 
-import { describe, it, expect, afterEach } from "vitest";
+import { describe, it, expect, afterEach, vi } from "vitest";
 
 const fs = require("node:fs");
 const os = require("node:os");
@@ -287,6 +287,241 @@ describe("AnalysisEngine RAG retriever", () => {
   });
 });
 
+// ─── TOTALS block — authoritative counts beat FACTS sample length ─────
+//
+// Bug 2026-05-21: even after _gatherFacts pulled persons + items into the
+// prompt, the LLM still said "32 contacts" because FACTS is capped at 80
+// items and the LLM was counting the array. Real vault had ~500 contacts.
+// Fix: stick vault.stats() totals at the head of the user message so the
+// model has an authoritative ground-truth number to quote.
+
+describe("AnalysisEngine emits TOTALS preamble", () => {
+  it("includes vault.stats() totals in the prompt", async () => {
+    const fakeVault = {
+      queryEvents: () => [],
+      queryPersons: () => [],
+      queryItems: () => [],
+      stats: () => ({ events: 12, persons: 512, places: 3, items: 89, topics: 0 }),
+      getEvent: () => null,
+      audit: () => {},
+    };
+    const chatCalls = [];
+    const llm = {
+      isLocal: true,
+      chat: async (msgs) => {
+        chatCalls.push(msgs);
+        return { text: "ok", usage: {} };
+      },
+    };
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    await engine.ask("几个联系人");
+    const userMsg = chatCalls[0][1].content;
+    expect(userMsg).toContain("TOTALS");
+    expect(userMsg).toContain('"persons": 512');
+    expect(userMsg).toContain('"items": 89');
+    // System prompt tells LLM to trust TOTALS for counts.
+    expect(chatCalls[0][0].content).toMatch(/TOTALS.*authoritative/);
+  });
+
+  it("intent=count for '几个联系人' and '几个 app' and '多少个 X'", () => {
+    const { parseQuery } = require("../lib/query-parser");
+    expect(parseQuery("几个联系人").intent).toBe("count");
+    expect(parseQuery("几个 app").intent).toBe("count");
+    expect(parseQuery("我有多少个联系人？").intent).toBe("count");
+    expect(parseQuery("how many contacts do I have").intent).toBe("count");
+    expect(parseQuery("列出我的联系人").intent).toBe("list");
+  });
+
+  it("legacy vault without stats() falls back gracefully — no TOTALS block", async () => {
+    const legacyVault = {
+      queryEvents: () => [],
+      // no stats()
+      getEvent: () => null,
+      audit: () => {},
+    };
+    const chatCalls = [];
+    const llm = {
+      isLocal: true,
+      chat: async (msgs) => {
+        chatCalls.push(msgs);
+        return { text: "ok", usage: {} };
+      },
+    };
+    const engine = new AnalysisEngine({ vault: legacyVault, llm });
+    await engine.ask("test");
+    const userMsg = chatCalls[0][1].content;
+    expect(userMsg).not.toContain("TOTALS");
+  });
+});
+
+// ─── Cache bypass — PDH ask must always go to LLM, never cached ───────
+//
+// Bug 2026-05-21: desktop ResponseCache (7-day TTL) served a stale
+// hallucinated answer ("32 contacts") even after _gatherFacts fix put real
+// persons in the prompt — same sha256(messages) hit from an earlier session.
+// AnalysisEngine.ask must pass skipCache:true so LLMManager bypasses cache.
+
+describe("AnalysisEngine.ask cache bypass", () => {
+  it("passes skipCache:true to llm.chat options", async () => {
+    freshVault();
+    seedOrders(vault);
+    const chatCalls = [];
+    const llm = {
+      isLocal: true,
+      chat: async (messages, opts) => {
+        chatCalls.push({ messages, opts });
+        return { text: "ok", usage: {} };
+      },
+    };
+    const engine = new AnalysisEngine({ vault, llm });
+    await engine.ask("test", { now: NOW });
+    expect(chatCalls).toHaveLength(1);
+    expect(chatCalls[0].opts.skipCache).toBe(true);
+  });
+
+  it("retrieveContext does NOT need skipCache (no LLM call)", async () => {
+    freshVault();
+    seedOrders(vault);
+    const llm = {
+      isLocal: true,
+      chat: () => {
+        throw new Error("must not be called");
+      },
+    };
+    const engine = new AnalysisEngine({ vault, llm });
+    // retrieveContext is Path Y — caller hosts the LLM, so cache concerns
+    // belong to the caller, not us. Don't pass skipCache here.
+    const r = await engine.retrieveContext("test");
+    expect(r.factCount).toBeGreaterThanOrEqual(0);
+  });
+});
+
+// ─── Path C follow-up — persons / items show up as facts ───────────────
+//
+// Bug 2026-05-21: "我有几个联系人" hallucinated "2" because contacts ingest
+// into persons table but _gatherFacts only queried events. Fix: pull persons
+// + items into facts within the maxFacts budget.
+
+describe("AnalysisEngine._gatherFacts includes persons and items", () => {
+  it("returns persons + items even when events are empty (contacts-only vault)", async () => {
+    freshVault();
+    // Use a fake vault that exposes queryPersons / queryItems but no event
+    // history — mimics the post-Path-C-ingest state where contacts +
+    // installed apps are the only data.
+    const fakeVault = {
+      queryEvents: () => [],
+      queryPersons: ({ limit }) => {
+        const n = Math.min(limit ?? 100, 5);
+        return Array.from({ length: n }, (_, i) => ({
+          id: "person-android-" + i,
+          type: "person",
+          subtype: "contact",
+          names: ["联系人" + i],
+          ingestedAt: Date.now(),
+          source: {
+            adapter: "system-data-android",
+            adapterVersion: "0.1.0",
+            capturedAt: Date.now(),
+            capturedBy: "api",
+          },
+        }));
+      },
+      queryItems: ({ limit }) => {
+        const n = Math.min(limit ?? 100, 3);
+        return Array.from({ length: n }, (_, i) => ({
+          id: "item-android-app-com.foo" + i,
+          type: "item",
+          subtype: "other",
+          name: "App" + i,
+          ingestedAt: Date.now(),
+          source: {
+            adapter: "system-data-android",
+            adapterVersion: "0.1.0",
+            capturedAt: Date.now(),
+            capturedBy: "api",
+          },
+        }));
+      },
+      getEvent: () => null,
+      audit: () => {},
+    };
+    const llm = new MockLLMClient({ reply: "你共有 5 个联系人" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("我有几个联系人");
+    expect(r.facts.length).toBe(8); // 0 events + 5 persons + 3 items
+    expect(r.facts.filter((f) => f.type === "person").length).toBe(5);
+    expect(r.facts.filter((f) => f.type === "item").length).toBe(3);
+  });
+
+  it("respects maxFacts budget — events get majority, persons + items split remainder", async () => {
+    const fakeVault = {
+      queryEvents: () => Array.from({ length: 60 }, (_, i) => ({
+        id: "event-" + i, type: "event", subtype: "order",
+        occurredAt: Date.now(), actor: "person-self",
+        ingestedAt: Date.now(), source: {
+          adapter: "taobao", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api",
+        },
+      })),
+      queryPersons: ({ limit }) => Array.from({ length: Math.min(limit, 100) }, (_, i) => ({
+        id: "p-" + i, type: "person", subtype: "contact",
+        names: ["P" + i], ingestedAt: Date.now(),
+        source: { adapter: "system-data-android", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+      })),
+      queryItems: ({ limit }) => Array.from({ length: Math.min(limit, 100) }, (_, i) => ({
+        id: "i-" + i, type: "item", subtype: "other", name: "Item" + i,
+        ingestedAt: Date.now(),
+        source: { adapter: "system-data-android", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+      })),
+      getEvent: () => null,
+      audit: () => {},
+    };
+    const llm = new MockLLMClient({ reply: "" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm, maxFacts: 80 });
+    const r = await engine.retrieveContext("hello");
+    // 60 events + budget for the rest. remaining = 80-60 = 20 → 10 persons + 10 items
+    expect(r.facts.filter((f) => f.type === "event").length).toBe(60);
+    expect(r.facts.filter((f) => f.type === "person").length).toBe(10);
+    expect(r.facts.filter((f) => f.type === "item").length).toBe(10);
+  });
+
+  it("gracefully degrades when vault lacks queryPersons / queryItems (legacy fork)", async () => {
+    const legacyVault = {
+      queryEvents: () => [],
+      // no queryPersons / queryItems methods
+      getEvent: () => null,
+      audit: () => {},
+    };
+    const llm = new MockLLMClient({ reply: "" });
+    const engine = new AnalysisEngine({ vault: legacyVault, llm });
+    const r = await engine.ask("hello");
+    expect(r.facts.length).toBe(0);
+    expect(r.warning).toBe("no-facts");
+  });
+
+  it("events take majority when budget < events.length (no person/item budget left)", async () => {
+    const fakeVault = {
+      queryEvents: () => Array.from({ length: 80 }, (_, i) => ({
+        id: "e" + i, type: "event", subtype: "order",
+        occurredAt: Date.now(), actor: "self",
+        ingestedAt: Date.now(),
+        source: { adapter: "taobao", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+      })),
+      queryPersons: vi.fn(() => []),
+      queryItems: vi.fn(() => []),
+      getEvent: () => null,
+      audit: () => {},
+    };
+    const llm = new MockLLMClient({ reply: "" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm, maxFacts: 80 });
+    const r = await engine.ask("hi");
+    expect(r.facts.length).toBe(80);
+    // budget exhausted → queryPersons / queryItems still called but with limit 0
+    // (current impl skips with personBudget <= 0). Verify they're NOT called.
+    expect(fakeVault.queryPersons).not.toHaveBeenCalled();
+    expect(fakeVault.queryItems).not.toHaveBeenCalled();
+  });
+});
+
 // ─── Empty / bad input ────────────────────────────────────────────────────
 
 describe("AnalysisEngine input validation", () => {
@@ -300,3 +535,96 @@ describe("AnalysisEngine input validation", () => {
     await expect(engine.ask(null)).rejects.toThrow();
   });
 });
+
+// ─── retrieveContext: prompt assembly without LLM call ───────────────────
+//
+// Path Y wiring lets a mobile front-end host the LLM call locally (e.g. the
+// Android-side Volcengine Doubao adapter) while keeping vault + retrieval on
+// the desktop. retrieveContext mirrors the front half of ask() and returns
+// the assembled messages so the caller can hand them straight to its own LLM.
+
+describe("AnalysisEngine.retrieveContext", () => {
+  it("returns parsed + facts + messages without invoking the LLM", async () => {
+    freshVault();
+    const [e1, e2, e3] = seedOrders(vault);
+
+    // LLM that would throw if called — proves retrieveContext is LLM-free.
+    const llm = {
+      isLocal: true,
+      chat: () => { throw new Error("LLM must not be called by retrieveContext"); },
+    };
+    const engine = new AnalysisEngine({ vault, llm });
+    const r = await engine.retrieveContext("上个月在淘宝总共花了多少？", { now: NOW });
+
+    expect(r.question).toBe("上个月在淘宝总共花了多少？");
+    expect(r.parsed.filters.adapter).toBe("taobao");
+    expect(r.facts.length).toBe(3);
+    expect(r.factIds).toEqual(expect.arrayContaining([e1.id, e2.id, e3.id]));
+    expect(r.factCount).toBe(3);
+    expect(r.truncated).toBe(false);
+    expect(Array.isArray(r.messages)).toBe(true);
+    expect(r.messages.length).toBeGreaterThan(0);
+    expect(r.messages[0]).toHaveProperty("role");
+    expect(r.messages[0]).toHaveProperty("content");
+    expect(r.systemPrompt).toBeTypeOf("string");
+    expect(r.retrievedAt).toBeTypeOf("number");
+    expect(r.durationMs).toBeGreaterThanOrEqual(0);
+  });
+
+  it("ignores acceptNonLocal — privacy gate does not apply (no LLM contacted)", async () => {
+    freshVault();
+    seedOrders(vault);
+    // Non-local LLM declared on the engine, but retrieveContext doesn't call it.
+    const llm = {
+      isLocal: false,
+      chat: () => { throw new Error("must not be called"); },
+    };
+    const engine = new AnalysisEngine({ vault, llm });
+    // No acceptNonLocal option needed.
+    const r = await engine.retrieveContext("test", { now: NOW });
+    expect(r.factCount).toBeGreaterThanOrEqual(0);
+  });
+
+  it("incorporates RAG retriever results into facts", async () => {
+    freshVault();
+    const orders = seedOrders(vault);
+    const ragRetriever = async () => [{ id: orders[3].id, text: "fake", metadata: {} }];
+    const llm = { isLocal: true, chat: () => { throw new Error("nope"); } };
+    const engine = new AnalysisEngine({ vault, llm, ragRetriever });
+    const r = await engine.retrieveContext("上个月在淘宝总共花了多少？", { now: NOW });
+    expect(r.facts.length).toBe(4);
+    expect(r.ragContextIds).toEqual([orders[3].id]);
+  });
+
+  it("RAG failure is captured but doesn't abort retrieval", async () => {
+    freshVault();
+    seedOrders(vault);
+    const ragRetriever = async () => { throw new Error("qdrant unreachable"); };
+    const llm = { isLocal: true, chat: () => { throw new Error("nope"); } };
+    const engine = new AnalysisEngine({ vault, llm, ragRetriever });
+    const r = await engine.retrieveContext("test", { now: NOW });
+    expect(r.factCount).toBeGreaterThanOrEqual(0);
+    const audits = vault.queryAudit({ action: "analysis.rag_failed" });
+    expect(audits.length).toBe(1);
+  });
+
+  it("writes analysis.retrieve_context audit row by default", async () => {
+    freshVault();
+    seedOrders(vault);
+    const llm = { isLocal: true, chat: () => { throw new Error("nope"); } };
+    const engine = new AnalysisEngine({ vault, llm });
+    await engine.retrieveContext("test", { now: NOW });
+    const audits = vault.queryAudit({ action: "analysis.retrieve_context" });
+    expect(audits.length).toBe(1);
+  });
+
+  it("rejects empty / non-string question", async () => {
+    freshVault();
+    const engine = new AnalysisEngine({
+      vault,
+      llm: new MockLLMClient({ reply: "" }),
+    });
+    await expect(engine.retrieveContext("")).rejects.toThrow(/non-empty/);
+    await expect(engine.retrieveContext(null)).rejects.toThrow();
+  });
+});