@chainlesschain/personal-data-hub 0.3.6 → 0.3.8

package/__tests__/adapters/social-xiaohongshu-adb-sign-provider-injection.test.js

@@ -0,0 +1,351 @@
+"use strict";
+
+/**
+ * Phase 6b — verify signProvider injection in XhsApiClient + collector.
+ *
+ * Tests both paths:
+ *  - Bridge path (signedHeaders returns non-empty) → uses bridge headers
+ *  - Fallback path (NullSignProvider OR bridge returns {}) → in-process md5
+ *
+ * Uses a fake fetch + fake signProvider to verify wiring without spawning
+ * Electron WebContentsView.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+
+const {
+  XhsApiClient,
+} = require("../../lib/adapters/social-xiaohongshu-adb/api-client");
+const {
+  collect,
+} = require("../../lib/adapters/social-xiaohongshu-adb/collector");
+const { NULL_SIGN_PROVIDER } = require("../../lib/sign-providers");
+
+function makeFakeFetch(responses) {
+  const calls = [];
+  const fakeFetch = async (urlStr, opts) => {
+    calls.push({ url: urlStr, opts });
+    for (const [pattern, payload] of responses) {
+      if (urlStr.includes(pattern)) {
+        const resolved =
+          typeof payload === "function" ? await payload(urlStr, opts) : payload;
+        return {
+          ok: resolved.status == null || resolved.status === 200,
+          status: resolved.status || 200,
+          text: async () => resolved.body,
+        };
+      }
+    }
+    throw new Error("fake fetch: no response for " + urlStr);
+  };
+  return { fakeFetch, calls };
+}
+
+const HAPPY_RESPONSES = [
+  [
+    "/user/me",
+    {
+      body: JSON.stringify({
+        code: 0,
+        data: { user_id: "5e8c8f7e", nickname: "Alice" },
+      }),
+    },
+  ],
+  [
+    "user_posted",
+    {
+      body: JSON.stringify({
+        code: 0,
+        data: { notes: [{ note_id: "N1", title: "n", time: 1 }] },
+      }),
+    },
+  ],
+  [
+    "note/like/page",
+    {
+      body: JSON.stringify({
+        code: 0,
+        data: { notes: [{ note_id: "L1", title: "l" }] },
+      }),
+    },
+  ],
+  [
+    "user/follow/list",
+    {
+      body: JSON.stringify({
+        code: 0,
+        data: { users: [{ user_id: "U1", nickname: "x" }] },
+      }),
+    },
+  ],
+];
+
+// ─── XhsApiClient direct injection ──────────────────────────────────────
+
+describe("XhsApiClient — signProvider injection", () => {
+  it("defaults to NULL_SIGN_PROVIDER when no opts.signProvider", () => {
+    const client = new XhsApiClient({ fetch: () => {} });
+    expect(client.signProvider).toBe(NULL_SIGN_PROVIDER);
+  });
+
+  it("uses opts.signProvider verbatim when provided", () => {
+    const fakeProvider = { signedHeaders: vi.fn(async () => ({})) };
+    const client = new XhsApiClient({
+      fetch: () => {},
+      signProvider: fakeProvider,
+    });
+    expect(client.signProvider).toBe(fakeProvider);
+  });
+
+  it("falls back to in-process md5 when provider returns {}", async () => {
+    const { fakeFetch, calls } = makeFakeFetch(HAPPY_RESPONSES);
+    const fakeProvider = { signedHeaders: vi.fn(async () => ({})) };
+    const client = new XhsApiClient({
+      fetch: fakeFetch,
+      signProvider: fakeProvider,
+    });
+    await client.fetchNotes("a1=fp; web_session=s", "fp", "5e8c8f7e");
+    const notesCall = calls.find((c) => c.url.includes("user_posted"));
+    // Fallback used → in-process X-S/X-T headers should be set
+    expect(notesCall.opts.headers["X-S"]).toMatch(/^XYW_/);
+    expect(notesCall.opts.headers["X-T"]).toMatch(/^\d+$/);
+    expect(client._bridgeHits).toBe(0);
+    expect(client._fallbackHits).toBe(1);
+  });
+
+  it("uses bridge headers when provider returns non-empty", async () => {
+    const { fakeFetch, calls } = makeFakeFetch(HAPPY_RESPONSES);
+    const fakeProvider = {
+      signedHeaders: vi.fn(async () => ({
+        "X-s": "XYW_bridge_value",
+        "X-t": "1716383021000",
+        "X-s-common": "common_value",
+      })),
+    };
+    const client = new XhsApiClient({
+      fetch: fakeFetch,
+      signProvider: fakeProvider,
+    });
+    await client.fetchNotes("a1=fp; web_session=s", "fp", "5e8c8f7e");
+    const notesCall = calls.find((c) => c.url.includes("user_posted"));
+    expect(notesCall.opts.headers["X-s"]).toBe("XYW_bridge_value");
+    expect(notesCall.opts.headers["X-t"]).toBe("1716383021000");
+    expect(notesCall.opts.headers["X-s-common"]).toBe("common_value");
+    // Bridge headers used — no fallback X-S/X-T injected
+    expect(notesCall.opts.headers["X-S"]).toBeUndefined();
+    expect(client._bridgeHits).toBe(1);
+    expect(client._fallbackHits).toBe(0);
+  });
+
+  it("does NOT call signedHeaders for /user/me (no X-S required)", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    const fakeProvider = { signedHeaders: vi.fn(async () => ({})) };
+    const client = new XhsApiClient({
+      fetch: fakeFetch,
+      signProvider: fakeProvider,
+    });
+    await client.fetchMe("a1=fp; web_session=s");
+    expect(fakeProvider.signedHeaders).not.toHaveBeenCalled();
+  });
+
+  it("calls signedHeaders for fetchNotes / fetchLiked / fetchFollows", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    const fakeProvider = { signedHeaders: vi.fn(async () => ({})) };
+    const client = new XhsApiClient({
+      fetch: fakeFetch,
+      signProvider: fakeProvider,
+    });
+    await client.fetchNotes("a1=fp; web_session=s", "fp", "5e8c8f7e");
+    await client.fetchLiked("a1=fp; web_session=s", "fp");
+    await client.fetchFollows("a1=fp; web_session=s", "fp", "5e8c8f7e");
+    expect(fakeProvider.signedHeaders).toHaveBeenCalledTimes(3);
+  });
+
+  it("forwards `<path>|` as purpose to signedHeaders", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    const fakeProvider = { signedHeaders: vi.fn(async () => ({})) };
+    const client = new XhsApiClient({
+      fetch: fakeFetch,
+      signProvider: fakeProvider,
+    });
+    await client.fetchNotes("a1=fp; web_session=s", "fp", "5e8c8f7e");
+    const [, purpose] = fakeProvider.signedHeaders.mock.calls[0];
+    expect(purpose).toMatch(/^\/api\/sns\/web\/v2\/user_posted.*\|$/);
+  });
+});
+
+// ─── collector lifecycle ────────────────────────────────────────────────
+
+describe("collector — signProvider lifecycle", () => {
+  it("warms up bridge before X-S endpoints", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    const apiClient = new XhsApiClient({ fetch: fakeFetch });
+    const warmedUp = [];
+    const fakeProvider = {
+      warmUp: vi.fn(async (cookie) => warmedUp.push(cookie)),
+      signedHeaders: vi.fn(async () => ({})),
+      shutdown: vi.fn(async () => {}),
+    };
+    const bridge = {
+      invoke: vi.fn(async () => ({
+        cookie: "a1=fp; web_session=s",
+        a1: "fp",
+        diagnostic: {},
+      })),
+    };
+    await collect(bridge, {
+      apiClient,
+      signProvider: fakeProvider,
+      stagingDir: require("node:os").tmpdir(),
+    });
+    expect(fakeProvider.warmUp).toHaveBeenCalledOnce();
+    expect(warmedUp[0]).toBe("a1=fp; web_session=s");
+  });
+
+  it("shuts down bridge in finally — happy path", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    const apiClient = new XhsApiClient({ fetch: fakeFetch });
+    const fakeProvider = {
+      warmUp: vi.fn(async () => {}),
+      signedHeaders: vi.fn(async () => ({})),
+      shutdown: vi.fn(async () => {}),
+    };
+    const bridge = {
+      invoke: vi.fn(async () => ({
+        cookie: "a1=fp; web_session=s",
+        a1: "fp",
+        diagnostic: {},
+      })),
+    };
+    await collect(bridge, {
+      apiClient,
+      signProvider: fakeProvider,
+      stagingDir: require("node:os").tmpdir(),
+    });
+    expect(fakeProvider.shutdown).toHaveBeenCalledOnce();
+  });
+
+  it("shuts down bridge in finally — even on fetchMe failure", async () => {
+    const { fakeFetch } = makeFakeFetch([
+      ["/user/me", { body: JSON.stringify({ code: 0, data: {} }) }],
+    ]);
+    const apiClient = new XhsApiClient({ fetch: fakeFetch });
+    const fakeProvider = {
+      warmUp: vi.fn(async () => {}),
+      signedHeaders: vi.fn(async () => ({})),
+      shutdown: vi.fn(async () => {}),
+    };
+    const bridge = {
+      invoke: vi.fn(async () => ({
+        cookie: "a1=fp; web_session=s",
+        a1: "fp",
+        diagnostic: {},
+      })),
+    };
+    const result = await collect(bridge, {
+      apiClient,
+      signProvider: fakeProvider,
+      stagingDir: require("node:os").tmpdir(),
+    });
+    expect(result.meFetchFailed).toBe(true);
+    expect(fakeProvider.shutdown).toHaveBeenCalledOnce();
+  });
+
+  it("tolerates warmUp throw (falls back to in-process md5)", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    const fakeProvider = {
+      warmUp: vi.fn(async () => {
+        throw new Error("xhs.com 403 — anti-bot blocked");
+      }),
+      signedHeaders: vi.fn(async () => ({})),
+      shutdown: vi.fn(async () => {}),
+    };
+    // Inject same provider into the apiClient too — real wiring path
+    // creates them together inside collector.
+    const apiClient = new XhsApiClient({
+      fetch: fakeFetch,
+      signProvider: fakeProvider,
+    });
+    const bridge = {
+      invoke: vi.fn(async () => ({
+        cookie: "a1=fp; web_session=s",
+        a1: "fp",
+        diagnostic: {},
+      })),
+    };
+    const result = await collect(bridge, {
+      apiClient,
+      signProvider: fakeProvider,
+      stagingDir: require("node:os").tmpdir(),
+    });
+    // Sync proceeded — fallback md5 used instead of bridge for all 3
+    // X-S endpoints (bridge.signedHeaders returns {} so client falls
+    // back). Note lastErrorCode gets cleared by successful subsequent
+    // fetchMe so we check _fallbackHits instead.
+    expect(result.meFetchFailed).toBe(false);
+    expect(apiClient._fallbackHits).toBeGreaterThanOrEqual(3);
+    expect(apiClient._bridgeHits).toBe(0);
+    // shutdown still runs in finally
+    expect(fakeProvider.shutdown).toHaveBeenCalledOnce();
+  });
+
+  it("reports signProvider diagnostic in collect result", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    // Subclass to control constructor.name (vitest mocks can't override it
+    // on plain object literals — constructor.name is read-only on Object).
+    class XhsSignBridge {
+      constructor() {
+        this.warmUp = vi.fn(async () => {});
+        this.signedHeaders = vi.fn(async () => ({
+          "X-s": "bridge",
+          "X-t": "1",
+          "X-s-common": "c",
+        }));
+        this.shutdown = vi.fn(async () => {});
+      }
+    }
+    const fakeProvider = new XhsSignBridge();
+    const apiClient = new XhsApiClient({
+      fetch: fakeFetch,
+      signProvider: fakeProvider,
+    });
+    const bridge = {
+      invoke: vi.fn(async () => ({
+        cookie: "a1=fp; web_session=s",
+        a1: "fp",
+        diagnostic: {},
+      })),
+    };
+    const result = await collect(bridge, {
+      apiClient,
+      signProvider: fakeProvider,
+      stagingDir: require("node:os").tmpdir(),
+    });
+    expect(result.signProviderUsed).toBe("XhsSignBridge");
+    expect(result.signProviderHits).toBe(3); // 3 X-S endpoints all hit bridge
+    expect(result.signProviderFallbacks).toBe(0);
+  });
+
+  it("undefined signProvider → no warmUp/shutdown, fallback md5 used", async () => {
+    const { fakeFetch } = makeFakeFetch(HAPPY_RESPONSES);
+    // Pre-construct apiClient with fakeFetch but no signProvider — client
+    // defaults to NULL_SIGN_PROVIDER which returns {} from signedHeaders.
+    const apiClient = new XhsApiClient({ fetch: fakeFetch });
+    const bridge = {
+      invoke: vi.fn(async () => ({
+        cookie: "a1=fp; web_session=s",
+        a1: "fp",
+        diagnostic: {},
+      })),
+    };
+    const result = await collect(bridge, {
+      apiClient,
+      stagingDir: require("node:os").tmpdir(),
+    });
+    // No bridge → in-process fallback throughout
+    expect(result.signProviderUsed).toBe("none");
+    expect(result.signProviderHits).toBe(0);
+    // 3 X-S endpoints called fallback md5 each
+    expect(result.signProviderFallbacks).toBeGreaterThanOrEqual(3);
+  });
+});

package/__tests__/analysis.test.js

@@ -403,11 +403,16 @@ describe("AnalysisEngine.ask cache bypass", () => {
 // + 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 () => {
+  it("contact question routes via entityFocus=persons — persons only, no items competition", 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.
+    // 2026-05-27 fix: "我有几个联系人" now matches parseEntityFocus → "persons",
+    // which intentionally skips the items table to give the full prompt
+    // budget to contacts. Pre-fix this test asserted 5 persons + 3 items
+    // (8 facts) because _gatherFacts always pulled both tables; post-fix
+    // items are deliberately excluded — the user asked about contacts, not
+    // apps. Items still surface for generic "what's in my vault" questions
+    // (entityFocus=null) and for explicit "我装了哪些 app" (entityFocus=
+    // "items"). Verified at __tests__:_gatherFacts entityFocus routing.
     const fakeVault = {
       queryEvents: () => [],
       queryPersons: ({ limit }) => {
@@ -448,9 +453,8 @@ describe("AnalysisEngine._gatherFacts includes persons and items", () => {
     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);
+    expect(r.facts.filter((f) => f.type === "item").length).toBe(0);
   });
 
   it("respects maxFacts budget — events get majority, persons + items split remainder", async () => {
@@ -498,7 +502,11 @@ describe("AnalysisEngine._gatherFacts includes persons and items", () => {
     expect(r.warning).toBe("no-facts");
   });
 
-  it("events take majority when budget < events.length (no person/item budget left)", async () => {
+  it("events overflow + empty side tables → events refill the reserved slots", async () => {
+    // 2026-05-27 fix: when events would monopolize effMaxFacts the engine
+    // reserves slots for persons + items; if BOTH side tables return 0 rows
+    // the reserve is refilled with events so a contact-less vault still
+    // sees the full event budget.
     const fakeVault = {
       queryEvents: () => Array.from({ length: 80 }, (_, i) => ({
         id: "e" + i, type: "event", subtype: "order",
@@ -515,10 +523,225 @@ describe("AnalysisEngine._gatherFacts includes persons and items", () => {
     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();
+    expect(r.facts.filter((f) => f.type === "event").length).toBe(80);
+    // Side queries WERE called (different from pre-fix); they just returned [].
+    expect(fakeVault.queryPersons).toHaveBeenCalledWith({ limit: 16 });
+    expect(fakeVault.queryItems).toHaveBeenCalledWith({ limit: 8 });
+  });
+
+  it("Android small-model budget — events overflow cap, persons survive", async () => {
+    // Regression: Android local path (effMaxFacts=20, effMaxQueryLimit=50).
+    // Vault returns 50 events; pre-fix _gatherFacts shipped 50 events,
+    // buildPrompt sliced to first 20 events, persons = 0 → "几个联系人"
+    // hallucinated zero. Now events cap at 14 (20*0.7), persons get 3,
+    // items get 3 → contact rows reach the LLM.
+    const fakeVault = {
+      queryEvents: () => Array.from({ length: 50 }, (_, i) => ({
+        id: "e" + i, type: "event", subtype: "message",
+        occurredAt: Date.now(), actor: "self",
+        ingestedAt: Date.now(),
+        source: { adapter: "wechat", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+      })),
+      queryPersons: ({ limit }) => Array.from({ length: limit }, (_, i) => ({
+        id: "p" + i, type: "person", subtype: "contact",
+        names: ["联系人" + i], ingestedAt: Date.now(),
+        source: { adapter: "system-data-android", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+      })),
+      queryItems: ({ limit }) => Array.from({ length: limit }, (_, 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: () => {},
+    };
+    const llm = new MockLLMClient({ reply: "" });
+    const engine = new AnalysisEngine({
+      vault: fakeVault, llm,
+      maxFacts: 20, maxQueryLimit: 50,
+    });
+    const r = await engine.ask("hi"); // generic question — default path
+    // 20 * 0.2 = 4 persons, 20 * 0.1 = 2 items, remainder 14 for events.
+    expect(r.facts.filter((f) => f.type === "event").length).toBe(14);
+    expect(r.facts.filter((f) => f.type === "person").length).toBe(4);
+    expect(r.facts.filter((f) => f.type === "item").length).toBe(2);
+  });
+});
+
+// ─── entityFocus routing — persons / items table priority ────────────────
+//
+// 2026-05-27 fix: when the question is explicitly about contacts ("我有
+// 哪些联系人", "妈手机号"), _gatherFacts must NOT compete persons against
+// the events pool. Pre-fix Android small-model budgets (20 facts / 50 row
+// cap) had events drown out the contact slice → user saw "没数据" even
+// when the vault held hundreds of contacts.
+
+describe("AnalysisEngine._gatherFacts entityFocus routing", () => {
+  it("entityFocus=persons skips events broad scan, prioritizes persons", async () => {
+    const fakeVault = {
+      queryEvents: vi.fn(() => Array.from({ length: 50 }, (_, i) => ({
+        id: "e" + i, type: "event", subtype: "message",
+        occurredAt: Date.now(), actor: "self",
+        ingestedAt: Date.now(),
+        source: { adapter: "wechat", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+      }))),
+      queryPersons: vi.fn(({ limit }) => Array.from({ length: limit }, (_, i) => ({
+        id: "p" + i, type: "person", subtype: "contact",
+        names: ["联系人" + i], ingestedAt: Date.now(),
+        source: { adapter: "system-data-android", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+      }))),
+      queryItems: vi.fn(() => []),
+      getEvent: () => null,
+      audit: () => {},
+    };
+    const llm = new MockLLMClient({ reply: "" });
+    const engine = new AnalysisEngine({
+      vault: fakeVault, llm,
+      maxFacts: 20, maxQueryLimit: 50,
+    });
+    const r = await engine.ask("我有哪些联系人");
+    // 95% goes to persons (19), 5% headroom = 1 event slot.
+    expect(r.facts.filter((f) => f.type === "person").length).toBe(19);
+    expect(r.facts.filter((f) => f.type === "event").length).toBeLessThanOrEqual(1);
+    expect(fakeVault.queryPersons).toHaveBeenCalledWith({ limit: 19 });
+  });
+
+  it("entityFocus=persons falls through to default path when persons table is empty", async () => {
+    const fakeVault = {
+      queryEvents: () => Array.from({ length: 5 }, (_, i) => ({
+        id: "e" + i, type: "event", subtype: "message",
+        occurredAt: Date.now(), actor: "self",
+        ingestedAt: Date.now(),
+        source: { adapter: "wechat", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+      })),
+      queryPersons: () => [], // empty contacts table
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+    };
+    const llm = new MockLLMClient({ reply: "" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm });
+    const r = await engine.ask("我有哪些联系人");
+    // Fell through to default → 5 events surfaced (no cap since 5 < 80).
+    expect(r.facts.filter((f) => f.type === "event").length).toBe(5);
+  });
+
+  it("entityFocus=persons with name candidate → searchPersons short-circuit", async () => {
+    // 2026-05-27 S3 治本 — "妈手机号" must hit searchPersons LIKE search
+    // even when vault holds 500 contacts. Pre-S3 _gatherFacts dumped the
+    // first N by ingest_at; the target person rarely landed in the slice.
+    const fakeVault = {
+      queryEvents: () => [],
+      queryPersons: vi.fn(() => [
+        { id: "p-other", type: "person", subtype: "contact", names: ["张三"], ingestedAt: 0,
+          source: { adapter: "system-data-android", adapterVersion: "0", capturedAt: 0, capturedBy: "api" } },
+      ]),
+      searchPersons: vi.fn(({ q, limit }) => {
+        if (q === "妈") {
+          return [{
+            id: "p-mom", type: "person", subtype: "contact", names: ["妈妈"],
+            identifiers: { phone: ["13800138000"] }, ingestedAt: 0,
+            source: { adapter: "system-data-android", adapterVersion: "0", capturedAt: 0, capturedBy: "api" },
+          }];
+        }
+        return [];
+      }),
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+    };
+    const llm = new MockLLMClient({ reply: "妈手机号是 13800138000" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm, maxFacts: 20 });
+    const r = await engine.ask("妈手机号是多少");
+    expect(fakeVault.searchPersons).toHaveBeenCalledWith({ q: "妈", limit: 19 });
+    expect(fakeVault.queryPersons).not.toHaveBeenCalled(); // search hit → skip fallback
+    expect(r.facts.filter((f) => f.type === "person").length).toBe(1);
+    expect(r.facts.find((f) => f.id === "p-mom")).toBeDefined();
+  });
+
+  it("entityFocus=persons with name candidate but 0 search hits → falls back to queryPersons", async () => {
+    const fakeVault = {
+      queryEvents: () => [],
+      queryPersons: vi.fn(({ limit }) => Array.from({ length: limit }, (_, i) => ({
+        id: "p" + i, type: "person", subtype: "contact", names: ["P" + i], ingestedAt: 0,
+        source: { adapter: "system-data-android", adapterVersion: "0", capturedAt: 0, capturedBy: "api" },
+      }))),
+      searchPersons: vi.fn(() => []), // 0 hits
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+    };
+    const llm = new MockLLMClient({ reply: "" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm, maxFacts: 20 });
+    await engine.ask("张三的电话号码");
+    expect(fakeVault.searchPersons).toHaveBeenCalled();
+    expect(fakeVault.queryPersons).toHaveBeenCalledWith({ limit: 19 });
+  });
+
+  it("entityFocus=persons without name candidate (pure list) skips searchPersons", async () => {
+    const fakeVault = {
+      queryEvents: () => [],
+      queryPersons: vi.fn(({ limit }) => Array.from({ length: limit }, (_, i) => ({
+        id: "p" + i, type: "person", subtype: "contact", names: ["P" + i], ingestedAt: 0,
+        source: { adapter: "system-data-android", adapterVersion: "0", capturedAt: 0, capturedBy: "api" },
+      }))),
+      searchPersons: vi.fn(() => []),
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+    };
+    const llm = new MockLLMClient({ reply: "" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm, maxFacts: 20 });
+    await engine.ask("我有哪些联系人");
+    // Pure list — no name in question → skip searchPersons, go straight to queryPersons.
+    expect(fakeVault.searchPersons).not.toHaveBeenCalled();
+    expect(fakeVault.queryPersons).toHaveBeenCalledWith({ limit: 19 });
+  });
+
+  it("entityFocus=persons tolerates vault without searchPersons (legacy)", async () => {
+    const fakeVault = {
+      queryEvents: () => [],
+      queryPersons: vi.fn(({ limit }) => Array.from({ length: Math.min(limit, 3) }, (_, i) => ({
+        id: "p" + i, type: "person", subtype: "contact", names: ["P" + i], ingestedAt: 0,
+        source: { adapter: "system-data-android", adapterVersion: "0", capturedAt: 0, capturedBy: "api" },
+      }))),
+      // No searchPersons method
+      queryItems: () => [],
+      getEvent: () => null,
+      audit: () => {},
+    };
+    const llm = new MockLLMClient({ reply: "" });
+    const engine = new AnalysisEngine({ vault: fakeVault, llm, maxFacts: 20 });
+    const r = await engine.ask("妈手机号");
+    expect(fakeVault.queryPersons).toHaveBeenCalled();
+    expect(r.facts.filter((f) => f.type === "person").length).toBe(3);
+  });
+
+  it("entityFocus=items prioritizes items table over events", async () => {
+    const fakeVault = {
+      queryEvents: () => Array.from({ length: 100 }, (_, i) => ({
+        id: "e" + i, type: "event", subtype: "browse",
+        occurredAt: Date.now(), actor: "self",
+        ingestedAt: Date.now(),
+        source: { adapter: "browser-history", adapterVersion: "0", capturedAt: Date.now(), capturedBy: "api" },
+      })),
+      queryPersons: () => [],
+      queryItems: vi.fn(({ limit }) => Array.from({ length: limit }, (_, 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: () => {},
+    };
+    const llm = new MockLLMClient({ reply: "" });
+    const engine = new AnalysisEngine({
+      vault: fakeVault, llm,
+      maxFacts: 20, maxQueryLimit: 50,
+    });
+    const r = await engine.ask("我装了哪些 app");
+    expect(r.facts.filter((f) => f.type === "item").length).toBe(19);
+    expect(fakeVault.queryItems).toHaveBeenCalledWith({ limit: 19 });
   });
 });
 
@@ -682,10 +905,12 @@ describe("AnalysisEngine per-call budget overrides", () => {
     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.
+    // 2026-05-27 fix: _gatherFacts now respects effMaxFacts upstream
+    // (events would have overflowed → reservation branch; persons/items
+    // returned [] → refill back to events.slice(0,10)). buildPrompt sees
+    // exactly 10 facts, nothing to truncate.
     expect(r.factCount).toBe(10);
-    expect(r.truncated).toBe(40); // 50 gathered - 10 kept = 40 truncated
+    expect(r.truncated).toBe(0);
   });
 
   it("retrieveContext() honors options.maxFacts and options.maxQueryLimit", async () => {