recallnest 2.3.0 → 2.6.0

package/src/__tests__/retrieval-eval.test.ts

@@ -0,0 +1,163 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "bun:test";
+
+import { scoreRetrievalCase, type RetrievalEvalCase } from "../eval.js";
+
+// 对齐 eval/cases.json 的真实形状：20 个 case 全部只声明 expectAny +
+// expectScopePrefixes，没有一个声明 expectAll 或 forbid。
+function makeCase(overrides: Partial<RetrievalEvalCase> = {}): RetrievalEvalCase {
+  return {
+    name: "case",
+    query: "q",
+    expectAny: ["alpha", "beta", "gamma", "delta"],
+    expectScopePrefixes: ["project:"],
+    ...overrides,
+  };
+}
+
+function hits(texts: string[], scope = "project:test") {
+  return texts.map((text) => ({ entry: { text, scope } }));
+}
+
+describe("scoreRetrievalCase", () => {
+  it("case 没声明的期望不再白送权重", () => {
+    // 这条守的就是那个漏洞：expectAll 在所有真实 case 里都没声明，
+    // 白送它的 0.3 意味着 expectAny 命中 1 个再加 scope 前缀命中，
+    // 就正好压在 0.7 及格线上——检索质量其实很差。
+    const weak = scoreRetrievalCase(makeCase(), hits(["alpha only"]));
+
+    expect(weak.matchedAny).toEqual(["alpha"]);
+    expect(weak.matchedScopes).toEqual(["project:"]);
+    // (0.4×1/4 + 0.2×1/1) / 0.6 × 0.9 + 0.1 = 0.55
+    expect(weak.score).toBeCloseTo(0.55, 5);
+    expect(weak.passed).toBe(false);
+  });
+
+  it("同样形状下 expectAny 要命中一半才刚好摸到及格线", () => {
+    const report = scoreRetrievalCase(makeCase(), hits(["alpha beta"]));
+
+    expect(report.matchedAny).toEqual(["alpha", "beta"]);
+    // (0.4×2/4 + 0.2) / 0.6 × 0.9 + 0.1 = 0.7
+    expect(report.score).toBeCloseTo(0.7, 5);
+    expect(report.passed).toBe(true);
+  });
+
+  it("声明的期望全部命中给满分", () => {
+    const report = scoreRetrievalCase(makeCase(), hits(["alpha beta gamma delta"]));
+
+    expect(report.score).toBeCloseTo(1.0, 5);
+    expect(report.passed).toBe(true);
+  });
+
+  it("多声明一个维度不会稀释满分——归一化是重分配不是膨胀", () => {
+    const withAll = scoreRetrievalCase(
+      makeCase({ expectAll: ["alpha", "beta"] }),
+      hits(["alpha beta gamma delta"]),
+    );
+
+    expect(withAll.score).toBeCloseTo(1.0, 5);
+    expect(withAll.passed).toBe(true);
+  });
+
+  it("声明了 expectAll 却全 miss 会把分数拉到及格线上", () => {
+    const report = scoreRetrievalCase(
+      makeCase({ expectAll: ["epsilon", "zeta"] }),
+      hits(["alpha beta gamma delta"]),
+    );
+
+    expect(report.matchedAll).toEqual([]);
+    // 声明总权重 0.9 里挣到 0.4 + 0 + 0.2，归一化后加非空奖励正好 0.7——
+    // 这是"仍能通过"的最弱一档：其余全中、只丢掉整个 expectAll。
+    expect(report.score).toBeCloseTo((0.6 / 0.9) * 0.9 + 0.1, 5);
+    expect(report.passed).toBe(true);
+  });
+
+  it("再滑掉一个维度就掉到线下", () => {
+    const report = scoreRetrievalCase(
+      makeCase({ expectAll: ["epsilon", "zeta"] }),
+      hits(["alpha beta gamma"]), // expectAny 4 中 3，expectAll 全 miss
+    );
+
+    expect(report.score).toBeLessThan(0.7);
+    expect(report.passed).toBe(false);
+  });
+
+  it("只声明一个维度时该维度独占全部权重", () => {
+    const single = makeCase({ expectScopePrefixes: undefined });
+
+    const full = scoreRetrievalCase(single, hits(["alpha beta gamma delta"]));
+    expect(full.score).toBeCloseTo(1.0, 5);
+
+    const half = scoreRetrievalCase(single, hits(["alpha beta"]));
+    // 4 个词命中 2 个 → 拿走整个信封的一半，再加非空奖励
+    expect(half.score).toBeCloseTo(0.5 * 0.9 + 0.1, 5);
+    expect(half.passed).toBe(false);
+  });
+
+  it("expectAll 按命中比例计分，不是全有或全无", () => {
+    const report = scoreRetrievalCase(
+      makeCase({ expectAny: ["alpha"], expectScopePrefixes: undefined, expectAll: ["beta", "epsilon"] }),
+      hits(["alpha beta"]),
+    );
+
+    expect(report.matchedAll).toEqual(["beta"]);
+    // (0.4×1 + 0.3×1/2) / 0.7 × 0.9 + 0.1
+    expect(report.score).toBeCloseTo((0.55 / 0.7) * 0.9 + 0.1, 5);
+  });
+
+  it("scope 前缀也按命中比例计分", () => {
+    const report = scoreRetrievalCase(
+      makeCase({ expectAny: undefined, expectScopePrefixes: ["project:", "hippo:"] }),
+      hits(["随便什么内容"]),
+    );
+
+    expect(report.matchedScopes).toEqual(["project:"]);
+    // 2 个前缀命中 1 个 → 0.5 × 0.9 + 0.1
+    expect(report.score).toBeCloseTo(0.55, 5);
+    expect(report.passed).toBe(false);
+  });
+
+  it("命中 forbid 既扣分又直接判 fail", () => {
+    const report = scoreRetrievalCase(
+      makeCase({ forbid: ["secret"] }),
+      hits(["alpha beta gamma delta secret"]),
+    );
+
+    expect(report.forbiddenMatches).toEqual(["secret"]);
+    expect(report.score).toBeCloseTo(0.7, 5);
+    // 分数够线，但命中禁词一律判不通过
+    expect(report.passed).toBe(false);
+  });
+
+  it("空召回拿不到非空奖励，得 0 分", () => {
+    const report = scoreRetrievalCase(makeCase(), []);
+
+    expect(report.hitCount).toBe(0);
+    expect(report.score).toBe(0);
+    expect(report.passed).toBe(false);
+  });
+
+  it("一个期望都没声明的畸形 case 拿不到及格分", () => {
+    const report = scoreRetrievalCase({ name: "empty", query: "q" }, hits(["anything at all"]));
+
+    // 只剩非空奖励 0.1；改之前这里是三个维度全额白送 = 满分 1.0
+    expect(report.score).toBeCloseTo(0.1, 5);
+    expect(report.passed).toBe(false);
+  });
+
+  it("生产 case 集：完全不相关的召回不得有任何一个 case 过线", () => {
+    // 守住评分器不再退回白送状态——不依赖 case 集当前的写法，
+    // 以后无论 eval/cases.json 怎么增删，零匹配都必须是零通过。
+    const cases = JSON.parse(
+      readFileSync(new URL("../../eval/cases.json", import.meta.url), "utf-8"),
+    ) as RetrievalEvalCase[];
+    expect(cases.length).toBeGreaterThan(0);
+
+    const irrelevant = [{ entry: { text: "完全无关的内容", scope: "unrelated/scope" } }];
+    const leaked = cases
+      .map((c) => scoreRetrievalCase(c, irrelevant))
+      .filter((r) => r.passed)
+      .map((r) => r.name);
+    expect(leaked).toEqual([]);
+  });
+});

package/src/__tests__/retrieval-trace.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, it } from "bun:test";
+import { TraceCollector } from "../retrieval-trace.js";
+import { createRetriever } from "../retriever.js";
+
+describe("TraceCollector", () => {
+  it("accumulates stages correctly", () => {
+    const trace = new TraceCollector();
+    trace.startStage("vector_search", 0);
+    trace.endStage(20, [0.3, 0.9]);
+
+    trace.startStage("min_score_filter", 20);
+    trace.endStage(15, [0.35, 0.9]);
+
+    const result = trace.finalize("test query", "hybrid");
+    expect(result.query).toBe("test query");
+    expect(result.mode).toBe("hybrid");
+    expect(result.stages).toHaveLength(2);
+    expect(result.finalCount).toBe(15);
+    expect(result.totalMs).toBeGreaterThanOrEqual(0);
+  });
+
+  it("computes droppedCount as input - output", () => {
+    const trace = new TraceCollector();
+    trace.startStage("hard_min_score", 20);
+    trace.endStage(12);
+
+    const result = trace.finalize("q", "vector");
+    expect(result.stages[0].droppedCount).toBe(8);
+  });
+
+  it("computes scoreRange from surviving scores", () => {
+    const trace = new TraceCollector();
+    trace.startStage("rerank", 10);
+    trace.endStage(8, [0.2, 0.5, 0.8, 0.3, 0.6, 0.7, 0.4, 0.9]);
+
+    const stage = trace.finalize("q", "hybrid").stages[0];
+    expect(stage.scoreRange).not.toBeNull();
+    expect(stage.scoreRange![0]).toBeCloseTo(0.2);
+    expect(stage.scoreRange![1]).toBeCloseTo(0.9);
+  });
+
+  it("returns null scoreRange when no scores provided", () => {
+    const trace = new TraceCollector();
+    trace.startStage("noise_filter", 5);
+    trace.endStage(3);
+
+    expect(trace.finalize("q", "hybrid").stages[0].scoreRange).toBeNull();
+  });
+
+  it("summarize() produces readable multi-line output", () => {
+    const trace = new TraceCollector();
+    trace.startStage("vector_search", 0);
+    trace.endStage(20, [0.31, 0.89]);
+    trace.startStage("min_score_filter", 20);
+    trace.endStage(18, [0.35, 0.89]);
+
+    const summary = trace.summarize("auth middleware", "hybrid");
+    expect(summary).toContain('[retrieve] query="auth middleware" mode=hybrid');
+    expect(summary).toContain("vector_search: 0 → 20");
+    expect(summary).toContain("min_score_filter: 20 → 18 (2 dropped)");
+    expect(summary).toContain("final: 18 results");
+  });
+});
+
+describe("retriever with trace", () => {
+  it("populates trace stages without changing retrieval behavior", async () => {
+    const trace = new TraceCollector();
+
+    const retriever = createRetriever(
+      {
+        hasFtsSupport: false,
+        async vectorSearch() {
+          return [
+            {
+              entry: {
+                id: "m1",
+                text: "test memory",
+                vector: [1, 0, 0],
+                category: "entities",
+                scope: "project:test",
+                importance: 0.8,
+                timestamp: Date.now(),
+                metadata: "{}",
+              },
+              score: 0.8,
+            },
+          ];
+        },
+      } as any,
+      {
+        async embedQuery() { return [1, 0, 0]; },
+        async embedPassage() { return [1, 0, 0]; },
+      } as any,
+      {
+        mode: "vector",
+        rerank: "none",
+        filterNoise: false,
+        hardMinScore: 0,
+        minScore: 0,
+        recencyWeight: 0,
+        timeDecayHalfLifeDays: 0,
+        lengthNormAnchor: 0,
+      },
+    );
+
+    const results = await retriever.retrieve({
+      query: "authentication middleware config",
+      limit: 5,
+      trace,
+    });
+
+    // Results unchanged
+    expect(results).toHaveLength(1);
+    expect(results[0].entry.id).toBe("m1");
+
+    // Trace populated
+    const traceResult = trace.finalize("test", "vector");
+    expect(traceResult.stages.length).toBeGreaterThan(0);
+    expect(traceResult.stages[0].name).toBe("vector_search");
+    expect(traceResult.finalCount).toBe(1);
+  });
+
+  it("works identically without trace (no overhead)", async () => {
+    const retriever = createRetriever(
+      {
+        hasFtsSupport: false,
+        async vectorSearch() {
+          return [
+            {
+              entry: {
+                id: "m1",
+                text: "test memory",
+                vector: [1, 0, 0],
+                category: "entities",
+                scope: "project:test",
+                importance: 0.8,
+                timestamp: Date.now(),
+                metadata: "{}",
+              },
+              score: 0.8,
+            },
+          ];
+        },
+      } as any,
+      {
+        async embedQuery() { return [1, 0, 0]; },
+        async embedPassage() { return [1, 0, 0]; },
+      } as any,
+      {
+        mode: "vector",
+        rerank: "none",
+        filterNoise: false,
+        hardMinScore: 0,
+        minScore: 0,
+        recencyWeight: 0,
+        timeDecayHalfLifeDays: 0,
+        lengthNormAnchor: 0,
+      },
+    );
+
+    // No trace passed — should work exactly as before
+    const results = await retriever.retrieve({
+      query: "authentication middleware config",
+      limit: 5,
+    });
+
+    expect(results).toHaveLength(1);
+    expect(results[0].entry.id).toBe("m1");
+  });
+
+  it("trace captures hard_min_score drops", async () => {
+    const trace = new TraceCollector();
+
+    const retriever = createRetriever(
+      {
+        hasFtsSupport: false,
+        async vectorSearch() {
+          return [
+            {
+              entry: { id: "high", text: "good", vector: [1, 0, 0], category: "entities", scope: "p:t", importance: 0.8, timestamp: Date.now(), metadata: "{}" },
+              score: 0.9,
+            },
+            {
+              entry: { id: "low", text: "weak", vector: [0, 1, 0], category: "entities", scope: "p:t", importance: 0.5, timestamp: Date.now(), metadata: "{}" },
+              score: 0.2,
+            },
+          ];
+        },
+      } as any,
+      {
+        async embedQuery() { return [1, 0, 0]; },
+        async embedPassage() { return [1, 0, 0]; },
+      } as any,
+      {
+        mode: "vector",
+        rerank: "none",
+        filterNoise: false,
+        hardMinScore: 0.35,
+        minScore: 0,
+        recencyWeight: 0,
+        timeDecayHalfLifeDays: 0,
+        lengthNormAnchor: 0,
+      },
+    );
+
+    await retriever.retrieve({ query: "authentication middleware config", limit: 5, trace });
+
+    const result = trace.finalize("test", "vector");
+    const hardStage = result.stages.find(s => s.name === "hard_min_score");
+    expect(hardStage).toBeDefined();
+    expect(hardStage!.droppedCount).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/retriever-boundary-weight.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from "bun:test";
+
+import { createRetriever } from "../retriever.js";
+
+function buildEntry(id: string, scoreText: string, scope: string, metadata: Record<string, unknown>) {
+  return {
+    entry: {
+      id,
+      text: scoreText,
+      vector: [1, 0, 0],
+      category: "preferences",
+      scope,
+      importance: 0.8,
+      timestamp: Date.parse("2026-03-16T00:00:00.000Z"),
+      metadata: JSON.stringify(metadata),
+    },
+    score: 0.8,
+  };
+}
+
+describe("retriever provenance weighting", () => {
+  it("prefers durable structured memories over evidence when scores are close", async () => {
+    const retriever = createRetriever({
+      hasFtsSupport: false,
+      async vectorSearch() {
+        return [
+          {
+            ...buildEntry("evidence-1", "Transcript hint", "cc:session1", {
+              source: "cc",
+              boundary: {
+                layer: "evidence",
+                authority: "transcript-ingest",
+                conflictPolicy: "append-only",
+                originalCategory: "preferences",
+              },
+            }),
+            score: 0.8,
+          },
+          {
+            ...buildEntry("durable-1", "Curated durable preference", "memory:agent", {
+              source: "agent",
+              boundary: {
+                layer: "durable",
+                authority: "structured-memory",
+                conflictPolicy: "latest-wins",
+                originalCategory: "preferences",
+              },
+            }),
+            score: 0.79,
+          },
+        ];
+      },
+    } as any, {
+      async embedQuery() {
+        return [1, 0, 0];
+      },
+      async embedPassage() {
+        return [1, 0, 0];
+      },
+    } as any, {
+      mode: "vector",
+      rerank: "none",
+      filterNoise: false,
+      hardMinScore: 0,
+      minScore: 0,
+      recencyWeight: 0,
+      timeDecayHalfLifeDays: 0,
+    });
+
+    const results = await retriever.retrieve({
+      query: "user reply style preference",
+      limit: 5,
+      category: "preferences",
+    });
+
+    expect(results[0]?.entry.id).toBe("durable-1");
+    expect(results[1]?.entry.id).toBe("evidence-1");
+  });
+
+  it("does not override clearly stronger relevance with provenance weighting", async () => {
+    const retriever = createRetriever({
+      hasFtsSupport: false,
+      async vectorSearch() {
+        return [
+          {
+            ...buildEntry("evidence-strong", "Very strong transcript evidence", "cc:session1", {
+              source: "cc",
+              boundary: {
+                layer: "evidence",
+                authority: "transcript-ingest",
+                conflictPolicy: "append-only",
+                originalCategory: "preferences",
+              },
+            }),
+            score: 0.95,
+          },
+          {
+            ...buildEntry("durable-weaker", "Weaker durable preference", "memory:agent", {
+              source: "agent",
+              boundary: {
+                layer: "durable",
+                authority: "structured-memory",
+                conflictPolicy: "latest-wins",
+                originalCategory: "preferences",
+              },
+            }),
+            score: 0.7,
+          },
+        ];
+      },
+    } as any, {
+      async embedQuery() {
+        return [1, 0, 0];
+      },
+      async embedPassage() {
+        return [1, 0, 0];
+      },
+    } as any, {
+      mode: "vector",
+      rerank: "none",
+      filterNoise: false,
+      hardMinScore: 0,
+      minScore: 0,
+      recencyWeight: 0,
+      timeDecayHalfLifeDays: 0,
+    });
+
+    const results = await retriever.retrieve({
+      query: "user reply style preference",
+      limit: 5,
+      category: "preferences",
+    });
+
+    expect(results[0]?.entry.id).toBe("evidence-strong");
+  });
+});

package/src/__tests__/retriever-lazy-init-dispatch.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "bun:test";
+
+import { createRetriever } from "../retriever.js";
+
+/**
+ * 回归：retrieve() 在分派前必须等 store 完成惰性初始化。
+ *
+ * 真实 MemoryStore 的 hasFtsSupport 在 ensureInitialized() 跑完前恒为 false
+ * （ftsIndexCreated 初值 false，建索引发生在 doInitialize 里）。retriever.ts 的
+ * 分派条件是 `mode === "vector" || !this.store.hasFtsSupport`，若不先 await
+ * store.ready()，hybrid 模式的**首次**检索会读到初始化前的 false 并静默落回
+ * vector 路径——同一实例第二次才正常。
+ *
+ * 该缺陷自 c10607a（2026-03-03 初始版本）就在，长期未暴露：生产 mode 一直是
+ * "vector"，第一个条件短路；而 eval 每 case 新建组件，每个 case 都停在"首次"，
+ * 于是 eval 从未测到过 hybrid 路径。
+ *
+ * 下面的 fake store 用 getter + ready() 精确复现这个时序：不修复则 bm25Search
+ * 不会被调用。
+ */
+function buildResult(id: string, text: string) {
+  return {
+    entry: {
+      id,
+      text,
+      vector: [1, 0, 0],
+      category: "preferences",
+      scope: "memory:test",
+      importance: 0.8,
+      timestamp: Date.parse("2026-08-07T00:00:00.000Z"),
+      metadata: JSON.stringify({}),
+    },
+    score: 0.8,
+  };
+}
+
+const fakeEmbedder = {
+  async embedQuery() {
+    return [1, 0, 0];
+  },
+  async embedPassage() {
+    return [1, 0, 0];
+  },
+} as any;
+
+function buildLazyStore() {
+  const calls = { bm25: 0, vector: 0, ready: 0 };
+  let initialized = false;
+
+  const store = {
+    // 复现真实时序：初始化完成前恒 false
+    get hasFtsSupport() {
+      return initialized;
+    },
+    async ready() {
+      calls.ready += 1;
+      initialized = true;
+    },
+    async vectorSearch() {
+      calls.vector += 1;
+      return [buildResult("vec-1", "vector hit")];
+    },
+    async bm25Search() {
+      calls.bm25 += 1;
+      return [buildResult("bm25-1", "bm25 hit")];
+    },
+  };
+
+  return { store, calls };
+}
+
+const LOOSE_CONFIG = {
+  rerank: "none" as const,
+  filterNoise: false,
+  hardMinScore: 0,
+  minScore: 0,
+  recencyWeight: 0,
+  timeDecayHalfLifeDays: 0,
+};
+
+describe("retrieve() 分派与 store 惰性初始化的时序", () => {
+  it("hybrid 模式的首次检索不因惰性初始化落回 vector 路径", async () => {
+    const { store, calls } = buildLazyStore();
+    const retriever = createRetriever(store as any, fakeEmbedder, {
+      ...LOOSE_CONFIG,
+      mode: "hybrid",
+    });
+
+    await retriever.retrieve({ query: "双机契约 同步", limit: 5 });
+
+    // 修复前：hasFtsSupport 读到初始化前的 false → 落回 vectorOnly → bm25 为 0。
+    expect(calls.ready).toBeGreaterThan(0);
+    expect(calls.bm25).toBeGreaterThan(0);
+  });
+
+  it("vector 模式不受影响——短路在第一个条件，不走 BM25", async () => {
+    const { store, calls } = buildLazyStore();
+    const retriever = createRetriever(store as any, fakeEmbedder, {
+      ...LOOSE_CONFIG,
+      mode: "vector",
+    });
+
+    await retriever.retrieve({ query: "双机契约 同步", limit: 5 });
+
+    // 这条守的是"修复不得改变生产行为"：生产 mode 就是 vector。
+    expect(calls.bm25).toBe(0);
+    expect(calls.vector).toBeGreaterThan(0);
+  });
+
+  it("琐碎 query 走 skip 分支时不触发初始化", async () => {
+    const { store, calls } = buildLazyStore();
+    const retriever = createRetriever(store as any, fakeEmbedder, {
+      ...LOOSE_CONFIG,
+      mode: "hybrid",
+    });
+
+    // shouldSkipRetrieval 在分派之前提前 return，await ready() 不该被执行到。
+    await retriever.retrieve({ query: "ok", limit: 5 });
+
+    expect(calls.ready).toBe(0);
+    expect(calls.vector).toBe(0);
+  });
+});