@chainlesschain/personal-data-hub 0.2.4 → 0.3.0

package/__tests__/analysis.test.js

@@ -561,7 +561,9 @@ describe("AnalysisEngine.retrieveContext", () => {
     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);
+    // `truncated` is the count of dropped facts (Number), not a boolean.
+    // 3 gathered, all kept (no maxFacts cap) → 0 dropped.
+    expect(r.truncated).toBe(0);
     expect(Array.isArray(r.messages)).toBe(true);
     expect(r.messages.length).toBeGreaterThan(0);
     expect(r.messages[0]).toHaveProperty("role");
@@ -628,3 +630,840 @@ describe("AnalysisEngine.retrieveContext", () => {
     await expect(engine.retrieveContext(null)).rejects.toThrow();
   });
 });
+
+// ─── Per-call budget overrides (small-model callers) ─────────────────────
+//
+// On-device Qwen2.5-1.5B has an effective instruction-following window of
+// 2-4K tokens, much tighter than the 80-fact / 200-row default sized for
+// desktop 7B+ models. Android passes `maxFacts=20 maxQueryLimit=50` per
+// call to keep the prompt ~1.5K tokens. Construction stays untouched so
+// the desktop default path is unaffected.
+describe("AnalysisEngine per-call budget overrides", () => {
+  it("ask() honors options.maxFacts and options.maxQueryLimit", async () => {
+    const queryEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => {
+        queryEventsCalls.push(q);
+        // Return exactly q.limit rows so we can detect the cap.
+        return Array.from({ length: q.limit }, (_, 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: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 30, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    // Default constructor (maxFacts=80, maxQueryLimit=200) — overridden per call.
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    await engine.ask("hi", { maxFacts: 10, maxQueryLimit: 50 });
+    // queryEvents.limit must reflect the per-call override, not the default 200.
+    expect(queryEventsCalls).toHaveLength(1);
+    expect(queryEventsCalls[0].limit).toBe(50);
+  });
+
+  it("ask() retrieveContext-level maxFacts bounds factCount via buildPrompt", async () => {
+    const fakeVault = {
+      queryEvents: (q) => Array.from({ length: q.limit }, (_, 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: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 200, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = { isLocal: true, chat: () => { throw new Error("nope"); } };
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.retrieveContext("hi", { maxFacts: 10, maxQueryLimit: 50 });
+    // _gatherFacts returns 50 events, but buildPrompt caps factCount to maxFacts=10.
+    // `truncated` is a count of dropped facts, not a boolean.
+    expect(r.factCount).toBe(10);
+    expect(r.truncated).toBe(40); // 50 gathered - 10 kept = 40 truncated
+  });
+
+  it("retrieveContext() honors options.maxFacts and options.maxQueryLimit", async () => {
+    const queryEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => {
+        queryEventsCalls.push(q);
+        return [];
+      },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 0, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = { isLocal: true, chat: () => { throw new Error("nope"); } };
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    await engine.retrieveContext("hi", { maxFacts: 15, maxQueryLimit: 40 });
+    expect(queryEventsCalls).toHaveLength(1);
+    expect(queryEventsCalls[0].limit).toBe(40);
+  });
+
+  it("ignores non-positive / non-integer overrides → falls back to constructor defaults", async () => {
+    const queryEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => { queryEventsCalls.push(q); return []; },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 0, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = { isLocal: true, chat: () => { throw new Error("nope"); } };
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    await engine.retrieveContext("hi", { maxFacts: 0, maxQueryLimit: -5 });
+    // Both bogus → fall back to ctor defaults (maxQueryLimit=200)
+    expect(queryEventsCalls[0].limit).toBe(200);
+  });
+});
+
+// ─── intent=latest routing — newest-few path ─────────────────────────────
+//
+// 2026-05-24 follow-up — _gatherFacts now routes intent=latest WITHOUT a
+// time window to a hard-capped queryEvents({ limit: 3 }) and skips
+// persons/items entirely. Frees prompt budget for the LLM to actually read
+// row content instead of skimming 200 rows. Memory:
+// pdh_analysis_engine_intent_routing.md.
+//
+// Guards covered:
+//   (a) intent=latest + no timeWindow → ≤3 events, persons/items NOT touched
+//   (b) intent=latest + timeWindow ("最近 30 天") → fall through (list semantics)
+//   (c) intent=latest + 0 results → fall back to default (persons+items pulled)
+//   (d) intent=latest + adapter filter → respects filter on the narrow path
+//   (e) parseQuery sanity: "最近的订单" → intent=latest, timeWindow=null
+
+describe("AnalysisEngine._gatherFacts intent=latest routing", () => {
+  it("(a) latest without timeWindow → ≤3 events, persons/items NOT queried", async () => {
+    const queryEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => {
+        queryEventsCalls.push(q);
+        return Array.from({ length: 10 }, (_, i) => ({
+          id: "e-" + i, type: "event", subtype: "order",
+          occurredAt: Date.now() - i * 1000, actor: "self",
+          ingestedAt: Date.now(),
+          source: { adapter: "taobao", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+        })).slice(0, q.limit);
+      },
+      queryPersons: vi.fn(() => []),
+      queryItems: vi.fn(() => []),
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 10, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("最近的订单");
+
+    expect(r.parsed.intent).toBe("latest");
+    expect(r.parsed.timeWindow).toBeNull();
+    expect(queryEventsCalls).toHaveLength(1);
+    expect(queryEventsCalls[0].limit).toBe(3);
+    expect(r.facts).toHaveLength(3);
+    expect(r.facts.every((f) => f.type === "event")).toBe(true);
+    expect(fakeVault.queryPersons).not.toHaveBeenCalled();
+    expect(fakeVault.queryItems).not.toHaveBeenCalled();
+  });
+
+  it("(b) latest WITH timeWindow ('最近 30 天') → falls through to default broader path", async () => {
+    const queryEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => {
+        queryEventsCalls.push(q);
+        return [];
+      },
+      queryPersons: vi.fn(() => []),
+      queryItems: vi.fn(() => []),
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 0, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("最近 30 天的消费", { now: NOW });
+
+    expect(r.parsed.intent).toBe("latest");
+    expect(r.parsed.timeWindow).not.toBeNull();
+    // Default path: limit=200 (DEFAULT_MAX_QUERY_LIMIT), NOT 3.
+    expect(queryEventsCalls).toHaveLength(1);
+    expect(queryEventsCalls[0].limit).toBe(200);
+    // Default path also tries persons + items (budget remaining after 0 events).
+    expect(fakeVault.queryPersons).toHaveBeenCalled();
+    expect(fakeVault.queryItems).toHaveBeenCalled();
+  });
+
+  it("(c) latest with 0 results → fallback pulls persons + items via default path", async () => {
+    const queryEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => {
+        queryEventsCalls.push(q);
+        return []; // both narrow + default calls return 0 events
+      },
+      queryPersons: ({ limit }) => Array.from({ length: Math.min(limit, 2) }, (_, 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, 2) }, (_, i) => ({
+        id: "i-" + i, type: "item", subtype: "other", name: "I" + i,
+        ingestedAt: Date.now(),
+        source: { adapter: "system-data-android", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+      })),
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 0, persons: 2, places: 0, items: 2, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("最近的订单");
+
+    // Narrow path (limit=3) called first, returned 0 → fall through to default
+    // (limit=200) — so we expect 2 queryEvents calls total.
+    expect(queryEventsCalls).toHaveLength(2);
+    expect(queryEventsCalls[0].limit).toBe(3);
+    expect(queryEventsCalls[1].limit).toBe(200);
+    // Default path pulled persons + items; user gets a useful answer instead of "no-facts".
+    expect(r.facts.filter((f) => f.type === "person").length).toBe(2);
+    expect(r.facts.filter((f) => f.type === "item").length).toBe(2);
+  });
+
+  it("(d) latest passes adapter filter to the narrow queryEvents call", async () => {
+    const queryEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => {
+        queryEventsCalls.push(q);
+        return Array.from({ length: 3 }, (_, i) => ({
+          id: "e-" + i, type: "event", subtype: "order",
+          occurredAt: Date.now() - i * 1000, actor: "self",
+          ingestedAt: Date.now(),
+          source: { adapter: "taobao", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+        }));
+      },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 3, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    await engine.ask("最近在淘宝买的");
+
+    expect(queryEventsCalls).toHaveLength(1);
+    expect(queryEventsCalls[0].adapter).toBe("taobao");
+    expect(queryEventsCalls[0].limit).toBe(3);
+  });
+
+  it("(e) parseQuery sanity: '最近的订单' → intent=latest, timeWindow=null", () => {
+    const { parseQuery } = require("../lib/query-parser");
+    const q = parseQuery("最近的订单");
+    expect(q.intent).toBe("latest");
+    expect(q.timeWindow).toBeNull();
+    // Sanity: 最近 N 天 still produces both (list-with-window semantics on
+    // the engine side, but parser still tags intent=latest because "最近"
+    // matches. Engine's heuristic handles the disambiguation.)
+    const q2 = parseQuery("最近 30 天");
+    expect(q2.intent).toBe("latest");
+    expect(q2.timeWindow).not.toBeNull();
+  });
+
+  it("(f) latest narrow path respects per-call maxFacts cap (Android small-model 20 budget)", async () => {
+    // If caller passes maxFacts=2 (tighter than LATEST_INTENT_FACT_LIMIT=3),
+    // honor the tighter cap — small-model callers know their budget best.
+    const queryEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => {
+        queryEventsCalls.push(q);
+        return Array.from({ length: q.limit }, (_, i) => ({
+          id: "e-" + i, type: "event", subtype: "order",
+          occurredAt: Date.now() - i * 1000, actor: "self",
+          ingestedAt: Date.now(),
+          source: { adapter: "taobao", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+        }));
+      },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 2, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    await engine.ask("最近消息", { maxFacts: 2 });
+    expect(queryEventsCalls[0].limit).toBe(2);
+  });
+});
+
+// ─── intent=list + entity-name FTS5 augmentation ────────────────────────
+//
+// 2026-05-24 follow-up — when the parser pulls a probable entity name out
+// of the question (extractEntityTerm), _gatherFacts appends FTS5 hits to
+// the FACTS pool via vault.searchEvents. Strictly additive: wrong term →
+// 0 rows wasted, never lost events. FTS unavailable / errors → main path
+// (queryEvents + persons + items) unaffected. Memory:
+// pdh_analysis_engine_intent_routing.md.
+
+describe("AnalysisEngine._gatherFacts intent=list + entity-name FTS augmentation", () => {
+  // Shared event row factory.
+  const mkEvent = (id, adapter = "wechat") => ({
+    id, type: "event", subtype: "message",
+    occurredAt: Date.now(), actor: "self",
+    ingestedAt: Date.now(),
+    source: { adapter, adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+  });
+
+  it("(a) entity extracted → searchEvents called with q + adapter + timeWindow passthrough", async () => {
+    const queryEventsCalls = [];
+    const searchEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (qq) => {
+        queryEventsCalls.push(qq);
+        return [mkEvent("e-1", "wechat"), mkEvent("e-2", "wechat")];
+      },
+      searchEvents: (qq) => {
+        searchEventsCalls.push(qq);
+        return { rows: [mkEvent("fts-1", "wechat"), mkEvent("fts-2", "wechat")], nextCursor: null, mode: "fts5", shortQuery: false };
+      },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 4, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("提到王老板的微信消息");
+
+    expect(r.parsed.intent).toBe("list");
+    expect(searchEventsCalls).toHaveLength(1);
+    expect(searchEventsCalls[0].q).toBe("王老板");
+    expect(searchEventsCalls[0].adapter).toBe("wechat"); // parsed.filters.adapter passthrough
+    expect(searchEventsCalls[0].limit).toBe(10); // LIST_INTENT_FTS_LIMIT cap
+    // facts: 2 events + 2 FTS hits = 4 unique
+    expect(r.facts.filter((f) => f.type === "event")).toHaveLength(4);
+    expect(r.facts.map((f) => f.id)).toEqual(expect.arrayContaining(["e-1", "e-2", "fts-1", "fts-2"]));
+  });
+
+  it("(b) no extractable entity → searchEvents NOT called", async () => {
+    const searchEventsCalls = [];
+    const fakeVault = {
+      queryEvents: () => [mkEvent("e-1")],
+      searchEvents: (qq) => { searchEventsCalls.push(qq); return { rows: [], mode: "fts5", shortQuery: false }; },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 1, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    // "在淘宝买了什么" — extractEntityTerm strips everything → null
+    await engine.ask("在淘宝买了什么");
+    expect(searchEventsCalls).toHaveLength(0);
+  });
+
+  it("(c) vault without searchEvents method → graceful skip, main path runs", async () => {
+    const fakeVault = {
+      queryEvents: () => [mkEvent("e-1")],
+      // no searchEvents — legacy vault fork
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 1, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("提到王老板的消息");
+    // Engine doesn't blow up; main path returns the 1 event.
+    expect(r.facts).toHaveLength(1);
+  });
+
+  it("(d) FTS hits with overlapping ids are deduped (no double-count)", async () => {
+    const fakeVault = {
+      queryEvents: () => [mkEvent("e-1"), mkEvent("e-2")],
+      searchEvents: () => ({
+        rows: [mkEvent("e-1"), mkEvent("fts-3")], // e-1 overlaps with main query
+        nextCursor: null, mode: "fts5", shortQuery: false,
+      }),
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 3, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("提到王老板的消息");
+    // e-1, e-2, fts-3 — NOT 4 entries (e-1 dedup'd)
+    expect(r.facts.filter((f) => f.type === "event")).toHaveLength(3);
+    const ids = r.facts.map((f) => f.id);
+    expect(new Set(ids).size).toBe(ids.length); // no duplicates
+  });
+
+  it("(e) intent=count / latest / sum-amount do NOT trigger FTS augmentation", async () => {
+    const searchEventsCalls = [];
+    const fakeVault = {
+      queryEvents: () => [mkEvent("e-1")],
+      searchEvents: (qq) => { searchEventsCalls.push(qq); return { rows: [], mode: "fts5", shortQuery: false }; },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 1, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    // intent=count
+    await engine.ask("提到王老板的几个消息");
+    // intent=latest is short-circuited in narrow path; with extracted entity
+    // "王老板" wouldn't be hit because narrow returns 1 event and bails. Still
+    // verify the augmentation branch doesn't fire post-narrow.
+    await engine.ask("最近提到王老板的消息");
+    // intent=sum-amount
+    await engine.ask("总共花了多少在王老板这？");
+    expect(searchEventsCalls).toHaveLength(0);
+  });
+
+  it("(f) searchEvents throwing does not block — main events still returned", async () => {
+    const fakeVault = {
+      queryEvents: () => [mkEvent("e-1"), mkEvent("e-2")],
+      searchEvents: () => { throw new Error("FTS5 module missing"); },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 2, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("提到王老板的消息");
+    expect(r.facts).toHaveLength(2); // main path's events survive
+  });
+
+  it("(g) FTS limit respects headroom — small maxFacts shrinks the FTS slice", async () => {
+    const searchEventsCalls = [];
+    const fakeVault = {
+      queryEvents: () => [mkEvent("e-1"), mkEvent("e-2"), mkEvent("e-3")],
+      searchEvents: (qq) => {
+        searchEventsCalls.push(qq);
+        return { rows: [mkEvent("fts-" + qq.limit)], mode: "fts5", shortQuery: false };
+      },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 4, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm, maxFacts: 5 });
+    await engine.ask("提到王老板的消息");
+    // maxFacts=5, events=3 → headroom=2, FTS limit = min(2, 10) = 2
+    expect(searchEventsCalls[0].limit).toBe(2);
+  });
+
+  it("(h) when events already fill maxFacts, FTS skipped entirely", async () => {
+    const searchEventsCalls = [];
+    const fakeVault = {
+      queryEvents: () => Array.from({ length: 10 }, (_, i) => mkEvent("e-" + i)),
+      searchEvents: (qq) => { searchEventsCalls.push(qq); return { rows: [], mode: "fts5", shortQuery: false }; },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 10, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm, maxFacts: 10 });
+    await engine.ask("提到王老板的消息");
+    expect(searchEventsCalls).toHaveLength(0); // headroom = 0
+  });
+
+  it("(i) FTS hit budget consumes persons/items remainder — not additive on top", async () => {
+    // FTS hits push events.length up → remaining budget for persons/items shrinks.
+    // Validates the FTS augment happens BEFORE persons/items calc.
+    const queryPersonsCalls = [];
+    const queryItemsCalls = [];
+    const fakeVault = {
+      queryEvents: () => [mkEvent("e-1"), mkEvent("e-2")], // 2 events
+      searchEvents: () => ({ rows: [mkEvent("fts-1"), mkEvent("fts-2")], mode: "fts5", shortQuery: false }),
+      queryPersons: ({ limit }) => { queryPersonsCalls.push(limit); return []; },
+      queryItems: ({ limit }) => { queryItemsCalls.push(limit); return []; },
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 4, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm, maxFacts: 10 });
+    await engine.ask("提到王老板的消息");
+    // 2 events + 2 FTS = 4 in events array → remaining = 10-4 = 6
+    // sideBudget = 3 → personBudget=3, itemBudget=3
+    expect(queryPersonsCalls[0]).toBe(3);
+    expect(queryItemsCalls[0]).toBe(3);
+  });
+});
+
+// ─── intent=sum-amount routing — subtype-narrowed amount slice ──────────
+//
+// 2026-05-24 follow-up — "总共花了多少" / "在淘宝花了多少钱" only needs
+// events from amount-bearing subtypes (order/payment/transfer/income).
+// Pulling messages / visits / browses wastes prompt budget on rows the
+// LLM can't sum. We split the budget across the 4 subtypes (min 20 each),
+// union+dedup+sort by occurredAt DESC, skip persons/items entirely.
+// 0 hits → fall through to default (defensive: empty-vault graceful).
+// Memory: pdh_analysis_engine_intent_routing.md.
+
+describe("AnalysisEngine._gatherFacts intent=sum-amount routing", () => {
+  const mkEvent = (id, subtype, adapter = "taobao", occurredAt = Date.now()) => ({
+    id, type: "event", subtype, occurredAt, actor: "self",
+    content: { amount: { value: 100, currency: "CNY", direction: "out" } },
+    ingestedAt: Date.now(),
+    source: { adapter, adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+  });
+
+  it("(a) hits 4 subtype queries: order/payment/transfer/income → merged + deduped + sorted DESC", async () => {
+    const queryEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => {
+        queryEventsCalls.push(q);
+        // Return one event per subtype, occurredAt staggered so we can verify sort.
+        if (q.subtype === "order") return [mkEvent("o-1", "order", "taobao", 5000)];
+        if (q.subtype === "payment") return [mkEvent("p-1", "payment", "alipay-bill", 4000)];
+        if (q.subtype === "transfer") return [mkEvent("t-1", "transfer", "wechat", 3000)];
+        if (q.subtype === "income") return [mkEvent("i-1", "income", "email-imap", 2000)];
+        return [];
+      },
+      queryPersons: vi.fn(() => []),
+      queryItems: vi.fn(() => []),
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 4, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("总共花了多少钱");
+
+    expect(r.parsed.intent).toBe("sum-amount");
+    // 4 queryEvents calls, one per subtype.
+    expect(queryEventsCalls).toHaveLength(4);
+    expect(queryEventsCalls.map((c) => c.subtype).sort()).toEqual(
+      ["income", "order", "payment", "transfer"]
+    );
+    // facts: 4 unique events, sorted DESC by occurredAt → o-1 first.
+    expect(r.facts.map((f) => f.id)).toEqual(["o-1", "p-1", "t-1", "i-1"]);
+    // persons + items skipped — sum-amount doesn't need them.
+    expect(fakeVault.queryPersons).not.toHaveBeenCalled();
+    expect(fakeVault.queryItems).not.toHaveBeenCalled();
+  });
+
+  it("(b) 0 amount events → return EMPTY (NOT fall through, prevents LLM summing unrelated rows)", async () => {
+    // Design change 2026-05-24: sum-amount narrow returning 0 used to fall
+    // through to the default broader path, which pulled persons/items.
+    // Bug: default path would also pull messages/visits/browsing — events
+    // the LLM might wrongly try to "sum" when asked total spending.
+    // Fix: return empty → warning="no-facts" → LLM uses TOTALS preamble to
+    // say "找不到相关花费记录" cleanly. Diverges from latest's fallback
+    // (which surfaces context); for sum-amount fallback actively misleads.
+    const queryEventsCalls = [];
+    const queryPersonsCalls = [];
+    const queryItemsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => { queryEventsCalls.push(q); return []; },
+      queryPersons: vi.fn(() => { queryPersonsCalls.push(true); return []; }),
+      queryItems: vi.fn(() => { queryItemsCalls.push(true); return []; }),
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 0, persons: 5, places: 0, items: 2, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "找不到相关花费记录" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("总共花了多少");
+
+    // Only the 4 narrow (subtype-keyed) calls — NO default path call.
+    expect(queryEventsCalls).toHaveLength(4);
+    expect(queryEventsCalls.map((c) => c.subtype).sort()).toEqual(
+      ["income", "order", "payment", "transfer"]
+    );
+    // persons/items NOT pulled (sum-amount skips them; no fallback to default).
+    expect(fakeVault.queryPersons).not.toHaveBeenCalled();
+    expect(fakeVault.queryItems).not.toHaveBeenCalled();
+    // Empty facts + warning fired.
+    expect(r.facts).toHaveLength(0);
+    expect(r.warning).toBe("no-facts");
+  });
+
+  it("(c) adapter filter passes through to all 4 subtype queries", async () => {
+    const queryEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => {
+        queryEventsCalls.push(q);
+        return q.subtype === "order" ? [mkEvent("o-1", "order", "taobao")] : [];
+      },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 1, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    await engine.ask("在淘宝总共花了多少钱");
+
+    expect(queryEventsCalls).toHaveLength(4);
+    for (const c of queryEventsCalls) {
+      expect(c.adapter).toBe("taobao");
+    }
+  });
+
+  it("(d) timeWindow passes through to all 4 subtype queries", async () => {
+    const queryEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => {
+        queryEventsCalls.push(q);
+        return [];
+      },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 0, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    await engine.ask("上个月总共花了多少", { now: NOW });
+
+    // Narrow path's 4 subtype calls — NO default fallback since 2026-05-24
+    // sum-amount bug fix (empty narrow no longer falls through).
+    expect(queryEventsCalls).toHaveLength(4);
+    for (const c of queryEventsCalls) {
+      expect(c.since).toBeDefined();
+      expect(c.until).toBeDefined();
+    }
+  });
+
+  it("(e) sum-amount does NOT trigger FTS augmentation (list-only branch)", async () => {
+    const searchEventsCalls = [];
+    const fakeVault = {
+      queryEvents: () => [mkEvent("o-1", "order")],
+      searchEvents: (q) => { searchEventsCalls.push(q); return { rows: [], mode: "fts5", shortQuery: false }; },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 1, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    // Question carries a potential entity name "王老板", but intent=sum-amount
+    // must NOT call searchEvents (FTS is list-only).
+    await engine.ask("总共付给王老板多少钱");
+    expect(searchEventsCalls).toHaveLength(0);
+  });
+
+  it("(f) per-subtype budget respects effMaxQueryLimit/4 with floor of 20", async () => {
+    const queryEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => { queryEventsCalls.push(q); return []; },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 0, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    // effMaxQueryLimit = 200 (constructor default) → 200/4 = 50 per subtype
+    await engine.ask("总共花了多少");
+    // First 4 calls are narrow path (subtype-keyed).
+    expect(queryEventsCalls[0].limit).toBe(50);
+
+    // Small-model budget: effMaxQueryLimit=50 → 50/4 = 12 → max(20, 12) = 20
+    queryEventsCalls.length = 0;
+    await engine.ask("总共花了多少", { maxQueryLimit: 50 });
+    expect(queryEventsCalls[0].limit).toBe(20);
+  });
+
+  it("(g) dedup: same event id surfaced under multiple subtypes appears once", async () => {
+    // Defensive — events have unique subtype, but verify dedup if vault
+    // ever returns the same event from multiple subtype queries.
+    const fakeVault = {
+      queryEvents: (q) => {
+        // Both "order" and "payment" return e-shared (impossible in real
+        // vault but proves dedup logic).
+        if (q.subtype === "order" || q.subtype === "payment") {
+          return [mkEvent("e-shared", q.subtype)];
+        }
+        return [];
+      },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 1, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("总共花了多少");
+
+    expect(r.facts).toHaveLength(1);
+    expect(r.facts[0].id).toBe("e-shared");
+  });
+
+  it("(h) result truncated to effMaxFacts (small-model 20 budget)", async () => {
+    const fakeVault = {
+      queryEvents: (q) => {
+        // Each subtype returns 50 events → 4*50 = 200 total before cap
+        return Array.from({ length: 50 }, (_, i) => mkEvent(
+          q.subtype + "-" + i, q.subtype, "taobao", Date.now() - i
+        ));
+      },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 200, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("总共花了多少", { maxFacts: 20 });
+    expect(r.facts).toHaveLength(20);
+  });
+});
+
+// ─── intent=count routing — isolated coverage ───────────────────────────
+//
+// 2026-05-24 — `intent=count` ("几个 X" / "多少个 Y") is handled by the
+// TOTALS preamble (commit 19c11920e): vault.stats() is rendered before
+// FACTS so the LLM quotes the real number instead of FACTS array length.
+// FACTS itself still goes through the default broader path (no narrow
+// routing). This block isolates the count-specific behavior into its
+// own describe so the audit gap is closed.
+
+describe("AnalysisEngine._gatherFacts intent=count routing", () => {
+  const mkEvent = (id, subtype = "order", adapter = "taobao") => ({
+    id, type: "event", subtype, occurredAt: Date.now(), actor: "self",
+    ingestedAt: Date.now(),
+    source: { adapter, adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+  });
+
+  it("(a) intent=count goes through default broader path (no narrow query)", async () => {
+    const queryEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => {
+        queryEventsCalls.push(q);
+        return [mkEvent("e-1"), mkEvent("e-2")];
+      },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 2, persons: 500, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "你有 500 个联系人" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("我有几个联系人");
+
+    expect(r.parsed.intent).toBe("count");
+    // Single default queryEvents call (limit=200, no subtype filter, no narrow).
+    expect(queryEventsCalls).toHaveLength(1);
+    expect(queryEventsCalls[0].limit).toBe(200);
+    expect(queryEventsCalls[0].subtype).toBeUndefined();
+  });
+
+  it("(b) intent=count emits TOTALS block in prompt (authoritative ground truth)", async () => {
+    const chatCalls = [];
+    const fakeVault = {
+      queryEvents: () => [],
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 12, persons: 512, places: 3, items: 89, topics: 0 }),
+    };
+    const llm = {
+      isLocal: true,
+      chat: async (msgs) => { chatCalls.push(msgs); return { text: "你有 512 个联系人", 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 instructs LLM to trust TOTALS over FACTS length.
+    expect(chatCalls[0][0].content).toMatch(/TOTALS.*authoritative/i);
+  });
+
+  it("(c) intent=count does NOT trigger FTS augmentation (even with entity name)", async () => {
+    const searchEventsCalls = [];
+    const fakeVault = {
+      queryEvents: () => [],
+      searchEvents: (q) => { searchEventsCalls.push(q); return { rows: [], mode: "fts5", shortQuery: false }; },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 0, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    // Question carries an entity name "王老板" but intent=count must not call FTS
+    // (FTS is list-only; count uses TOTALS path).
+    await engine.ask("提到王老板的几个消息");
+    expect(searchEventsCalls).toHaveLength(0);
+  });
+
+  it("(d) intent=count does NOT trigger sum-amount narrow (separate routing)", async () => {
+    const queryEventsCalls = [];
+    const fakeVault = {
+      queryEvents: (q) => { queryEventsCalls.push(q); return []; },
+      queryPersons: () => [],
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 0, persons: 0, places: 0, items: 0, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    await engine.ask("几个订单");
+    // Single default call — NOT 4 subtype calls (those are sum-amount only).
+    expect(queryEventsCalls).toHaveLength(1);
+    expect(queryEventsCalls[0].subtype).toBeUndefined();
+  });
+
+  it("(e) intent=count pulls persons + items in FACTS (default path behavior)", async () => {
+    const fakeVault = {
+      queryEvents: () => [],
+      queryPersons: ({ limit }) => Array.from({ length: Math.min(limit, 5) }, (_, 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, 3) }, (_, i) => ({
+        id: "i-" + i, type: "item", subtype: "other", name: "App" + i,
+        ingestedAt: Date.now(),
+        source: { adapter: "system-data-android", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+      })),
+      getEvent: () => null,
+      audit: () => {},
+      stats: () => ({ events: 0, persons: 5, places: 0, items: 3, topics: 0 }),
+    };
+    const llm = new MockLLMClient({ reply: "ok" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("我有几个 app");
+
+    expect(r.parsed.intent).toBe("count");
+    expect(r.facts.filter((f) => f.type === "person").length).toBe(5);
+    expect(r.facts.filter((f) => f.type === "item").length).toBe(3);
+  });
+});