recallnest 2.6.1 → 3.0.1

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

@@ -1,163 +0,0 @@
-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

@@ -1,213 +0,0 @@
-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

@@ -1,136 +0,0 @@
-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

@@ -1,123 +0,0 @@
-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);
-  });
-});