recallnest 2.5.4 → 2.6.0

package/src/__tests__/recall-gate.test.ts

@@ -0,0 +1,266 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { runAutoRecall } from "../auto-recall.js";
+import {
+  RECALL_GATE_SHADOW_FILE,
+  classifyRecallGate,
+  resolveRecallGateMode,
+  type RecallGateDecision,
+} from "../recall-gate.js";
+import type { RetrievalContext, RetrievalResult } from "../retriever.js";
+
+const savedGateEnv = process.env.RECALLNEST_RECALL_GATE;
+const savedDataDirEnv = process.env.RECALLNEST_DATA_DIR;
+const cleanupPaths: string[] = [];
+
+afterEach(() => {
+  if (savedGateEnv === undefined) delete process.env.RECALLNEST_RECALL_GATE;
+  else process.env.RECALLNEST_RECALL_GATE = savedGateEnv;
+  if (savedDataDirEnv === undefined) delete process.env.RECALLNEST_DATA_DIR;
+  else process.env.RECALLNEST_DATA_DIR = savedDataDirEnv;
+  while (cleanupPaths.length > 0) {
+    const target = cleanupPaths.pop();
+    if (target) rmSync(target, { recursive: true, force: true });
+  }
+});
+
+function tempDataDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "recallnest-gate-"));
+  cleanupPaths.push(dir);
+  process.env.RECALLNEST_DATA_DIR = dir;
+  return dir;
+}
+
+function expectDecision(message: string, decision: RecallGateDecision, ruleId?: string) {
+  const verdict = classifyRecallGate(message);
+  expect(`${message} → ${verdict.decision}`).toBe(`${message} → ${decision}`);
+  if (ruleId) expect(verdict.ruleId).toBe(ruleId);
+}
+
+describe("classifyRecallGate — verdict matrix", () => {
+  it("force cues win over every short-text rule", () => {
+    expectDecision("可以按上次方案做", "full-recall", "force:memory-cue-zh");
+    expectDecision("记得我说过什么吗", "full-recall");
+    expectDecision("我的偏好是什么", "full-recall");
+    expectDecision("do you remember my setup?", "full-recall", "force:memory-cue-en");
+    expectDecision("what did we discussed last time", "full-recall");
+    // Force cue inside an otherwise long message still labels full-recall.
+    const long = `${"背景介绍。".repeat(20)}上次的结论是什么?`;
+    expectDecision(long, "full-recall");
+  });
+
+  it("whole-message acks skip; acks with real content pass", () => {
+    expectDecision("好的", "skip-all", "skip:ack");
+    expectDecision("好的吧。", "skip-all");
+    expectDecision("嗯嗯", "skip-all");
+    expectDecision("OK", "skip-all");
+    expectDecision("Thanks!", "skip-all");
+    expectDecision("好的 谢谢", "skip-all");
+    expectDecision("收到了哈", "skip-all");
+    expectDecision("好的,先跑测试再说", "pass");
+    expectDecision("可以先做项1", "pass");
+  });
+
+  it("continuity nudges are resume-only; nudge + content passes", () => {
+    expectDecision("继续", "resume-only", "resume:continuity");
+    expectDecision("继续吧", "resume-only");
+    expectDecision("接着来", "resume-only");
+    expectDecision("下一步", "resume-only");
+    expectDecision("开始", "resume-only");
+    expectDecision("开始吧", "resume-only");
+    expectDecision("continue", "resume-only");
+    expectDecision("接着改 auto-recall 的闸", "pass");
+    // "继续讨论上次的方案" carries a force cue → full-recall, not resume-only.
+    expectDecision("继续讨论上次的方案", "full-recall");
+  });
+
+  it("bare CLI invocations skip; CLI words inside prose pass", () => {
+    expectDecision("git push", "skip-all", "skip:cli");
+    expectDecision("npm test", "skip-all");
+    expectDecision("bun test src/__tests__/recall-gate.test.ts", "skip-all");
+    expectDecision("git", "skip-all");
+    expectDecision("git 为什么失败", "pass");
+    expectDecision("why does npm test hang?", "pass");
+    expectDecision("测试之前讨论的方案", "full-recall"); // force cue, not cli
+  });
+
+  it("slash commands and heartbeats skip", () => {
+    expectDecision("/compact", "skip-all", "skip:slash");
+    expectDecision("/goal 写个爬虫", "skip-all");
+    expectDecision("HEARTBEAT_OK", "skip-all", "skip:heartbeat");
+  });
+
+  it("pure emoji skips; bare digits/#/* are NOT emoji", () => {
+    expectDecision("👍", "skip-all", "skip:emoji");
+    expectDecision("👍👍 🎉", "skip-all");
+    expectDecision("🇸🇬", "skip-all");
+    expectDecision("42", "pass");
+    expectDecision("#1", "pass");
+    expectDecision("*", "pass");
+  });
+
+  it("greetings skip as whole messages only", () => {
+    expectDecision("你好", "skip-all", "skip:greeting");
+    expectDecision("早", "skip-all");
+    expectDecision("hello", "skip-all");
+    expectDecision("在吗", "skip-all");
+    expectDecision("你好,帮我查一下部署状态", "pass");
+  });
+
+  it("long messages without force cues always pass", () => {
+    const long = "这条消息足够长,描述了一个具体的问题背景和期望的处理方式,值得走完整的检索管线来补上下文。".repeat(2);
+    expect(long.length).toBeGreaterThan(80);
+    expectDecision(long, "pass", "pass:long");
+  });
+
+  it("empty input degrades to skip:empty", () => {
+    expectDecision("   ", "skip-all", "skip:empty");
+  });
+});
+
+describe("resolveRecallGateMode", () => {
+  it("defaults to observe; parses enforce/off; junk falls back to observe", () => {
+    expect(resolveRecallGateMode({})).toBe("observe");
+    expect(resolveRecallGateMode({ RECALLNEST_RECALL_GATE: "enforce" })).toBe("enforce");
+    expect(resolveRecallGateMode({ RECALLNEST_RECALL_GATE: "OFF" })).toBe("off");
+    expect(resolveRecallGateMode({ RECALLNEST_RECALL_GATE: "banana" })).toBe("observe");
+  });
+});
+
+// --- integration through runAutoRecall ---
+
+function buildResult(id: string, text: string): RetrievalResult {
+  return {
+    entry: {
+      id,
+      text,
+      vector: [],
+      category: "events",
+      scope: "project:gate",
+      importance: 0.8,
+      timestamp: Date.parse("2026-07-01T00:00:00.000Z"),
+      metadata: "{}",
+    },
+    score: 0.9,
+    sources: { fused: { score: 0.9 } },
+  };
+}
+
+function makeDeps() {
+  const calls: RetrievalContext[] = [];
+  return {
+    calls,
+    deps: {
+      retriever: {
+        async retrieve(context: RetrievalContext): Promise<RetrievalResult[]> {
+          calls.push(context);
+          if (!context.category) return [buildResult("hit-1", "focused hit")];
+          return [];
+        },
+      },
+      checkpointStore: { async getLatest() { return null; } },
+      listPins: () => [],
+    },
+  };
+}
+
+describe("runAutoRecall × recall gate", () => {
+  it("observe mode leaves behavior unchanged and appends a shadow entry", async () => {
+    const dir = tempDataDir();
+    const { deps, calls } = makeDeps();
+
+    const response = await runAutoRecall(deps, {
+      message: "好的",
+      scope: "project:gate",
+      operation: "test:gate-observe",
+      env: { RECALLNEST_RECALL_GATE: "observe" } as NodeJS.ProcessEnv,
+    });
+
+    // Unchanged behavior: full resume+search pipeline still ran.
+    expect(response.mode).toBe("resume+search");
+    expect(calls.length).toBeGreaterThan(0);
+    expect(response.results.length).toBe(1);
+
+    const shadowPath = join(dir, RECALL_GATE_SHADOW_FILE);
+    expect(existsSync(shadowPath)).toBe(true);
+    const entry = JSON.parse(readFileSync(shadowPath, "utf8").trim().split("\n")[0] ?? "{}");
+    expect(entry.decision).toBe("skip-all");
+    expect(entry.ruleId).toBe("skip:ack");
+    expect(entry.mode).toBe("observe");
+    expect(entry.msgLen).toBe(2);
+    expect(entry.source).toBe("test:gate-observe");
+    expect(JSON.stringify(entry)).not.toContain("好的"); // never log message text
+  });
+
+  it("enforce + skip-all short-circuits before any retriever call", async () => {
+    tempDataDir();
+    const { deps, calls } = makeDeps();
+
+    const response = await runAutoRecall(deps, {
+      message: "👍",
+      scope: "project:gate",
+      operation: "test:gate-enforce-skip",
+      env: { RECALLNEST_RECALL_GATE: "enforce" } as NodeJS.ProcessEnv,
+    });
+
+    expect(response.mode).toBe("resume-only");
+    expect(response.results.length).toBe(0);
+    expect(response.searchSkippedReason).toContain("skip-all");
+    expect(response.searchSkippedReason).toContain("skip:emoji");
+    expect(calls.length).toBe(0); // neither compose nor focused search hit the retriever
+  });
+
+  it("enforce + resume-only keeps resume context but skips the focused search", async () => {
+    tempDataDir();
+    const { deps, calls } = makeDeps();
+
+    const response = await runAutoRecall(deps, {
+      message: "继续",
+      scope: "project:gate",
+      operation: "test:gate-enforce-resume",
+      env: { RECALLNEST_RECALL_GATE: "enforce" } as NodeJS.ProcessEnv,
+    });
+
+    expect(response.mode).toBe("resume-only");
+    expect(response.results.length).toBe(0);
+    expect(response.searchSkippedReason).toContain("resume-only");
+    // Resume composition ran (retriever called with categories), but no
+    // focused search (which would be the category-less call).
+    const focusedCalls = calls.filter((c) => !c.category);
+    expect(focusedCalls.length).toBe(0);
+    expect(calls.length).toBeGreaterThan(0);
+  });
+
+  it("enforce mode leaves normal content untouched", async () => {
+    tempDataDir();
+    const { deps } = makeDeps();
+
+    const response = await runAutoRecall(deps, {
+      message: "帮我看看 retriever 的打分逻辑有没有问题",
+      scope: "project:gate",
+      operation: "test:gate-enforce-pass",
+      env: { RECALLNEST_RECALL_GATE: "enforce" } as NodeJS.ProcessEnv,
+    });
+
+    expect(response.mode).toBe("resume+search");
+    expect(response.results.length).toBe(1);
+  });
+
+  it("off mode computes nothing and writes no shadow log", async () => {
+    const dir = tempDataDir();
+    const { deps } = makeDeps();
+
+    const response = await runAutoRecall(deps, {
+      message: "好的",
+      scope: "project:gate",
+      operation: "test:gate-off",
+      env: { RECALLNEST_RECALL_GATE: "off" } as NodeJS.ProcessEnv,
+    });
+
+    expect(response.mode).toBe("resume+search");
+    expect(existsSync(join(dir, RECALL_GATE_SHADOW_FILE))).toBe(false);
+  });
+});

package/src/__tests__/resolve-db-path.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "bun:test";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { readdirSync, readFileSync } from "node:fs";
+
+import { resolveDbPath, resolveDataDir, type LocalMemoryConfig } from "../runtime-config.js";
+
+const REPO_ROOT = resolve(import.meta.dir, "../..");
+
+function cfg(dbPath: string): LocalMemoryConfig {
+  return {
+    dbPath,
+    embedding: { provider: "jina", apiKey: "x", model: "m" },
+    sources: {},
+  };
+}
+
+/**
+ * Regression guard for the 2026-07-19 audit finding: maintenance scripts each
+ * resolved the database on their own — some hardcoded "./data/lancedb", others
+ * read `config.database?.path`, a key that does not exist in LocalMemoryConfig
+ * and therefore always fell through to the hardcoded default. A health check or
+ * cleanup could then report on an empty directory while the server used a
+ * different database entirely.
+ */
+describe("resolveDbPath", () => {
+  it("resolves a relative dbPath against the repo root, not process.cwd()", () => {
+    expect(resolveDbPath(cfg("./data/lancedb"))).toBe(resolve(REPO_ROOT, "data/lancedb"));
+    expect(resolveDbPath(cfg("data/lancedb"))).toBe(resolve(REPO_ROOT, "data/lancedb"));
+  });
+
+  it("expands a leading ~/ to the home directory", () => {
+    expect(resolveDbPath(cfg("~/.recallnest/data/lancedb"))).toBe(
+      resolve(homedir(), ".recallnest/data/lancedb")
+    );
+  });
+
+  it("keeps an absolute dbPath unchanged", () => {
+    expect(resolveDbPath(cfg("/tmp/rn-abs/lancedb"))).toBe("/tmp/rn-abs/lancedb");
+  });
+
+  it("always returns an absolute path", () => {
+    for (const p of ["./data/lancedb", "data/lancedb", "~/x/lancedb", "/tmp/y"]) {
+      expect(resolveDbPath(cfg(p)).startsWith("/")).toBe(true);
+    }
+  });
+
+  it("puts the sidecar data dir directly beside the database", () => {
+    expect(resolveDataDir(cfg("~/.recallnest/data/lancedb"))).toBe(
+      resolve(homedir(), ".recallnest/data")
+    );
+    expect(resolveDataDir(cfg("./data/lancedb"))).toBe(resolve(REPO_ROOT, "data"));
+  });
+});
+
+describe("scripts resolve the database through runtime-config", () => {
+  it("no script hardcodes a lancedb path", () => {
+    const dir = resolve(REPO_ROOT, "scripts");
+    const offenders: string[] = [];
+
+    // Two shapes of the same mistake. The second was missed by the first
+    // revision of this guard: health-check.ts built its path with
+    // path.join(dir, "..", "data", "lancedb"), so no single string literal
+    // ever contained "data/lancedb".
+    const LITERAL_PATH = /["'`][^"'`]*data\/lancedb[^"'`]*["'`]/;
+    const JOINED_PATH = /\b(join|resolve)\s*\([^)]*["'`][^"'`]*lancedb[^"'`]*["'`]/i;
+
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith(".ts")) continue;
+      const src = readFileSync(resolve(dir, name), "utf-8");
+      for (const [i, line] of src.split("\n").entries()) {
+        const code = line.split("//")[0];
+        if (/^\s*\*/.test(line)) continue; // block-comment body
+        if (/@lancedb\/lancedb/.test(code)) continue; // the package import itself
+        if (LITERAL_PATH.test(code) || JOINED_PATH.test(code)) {
+          offenders.push(`${name}:${i + 1}`);
+        }
+      }
+    }
+
+    expect(offenders).toEqual([]);
+  });
+
+  it("no src file re-implements dbPath resolution instead of calling resolveDbPath", () => {
+    // cli.ts once duplicated the resolve() expression for its destructive
+    // "clear index" path, and doctor.ts resolved against process.cwd() — so the
+    // health check could report on a different directory than the server used.
+    const dir = resolve(REPO_ROOT, "src");
+    const offenders: string[] = [];
+
+    const walk = (d: string): void => {
+      for (const entry of readdirSync(d, { withFileTypes: true })) {
+        if (entry.name === "__tests__" || entry.name === "node_modules") continue;
+        const full = resolve(d, entry.name);
+        if (entry.isDirectory()) {
+          walk(full);
+          continue;
+        }
+        if (!entry.name.endsWith(".ts") || entry.name === "runtime-config.ts") continue;
+        const src = readFileSync(full, "utf-8");
+        for (const [i, line] of src.split("\n").entries()) {
+          if (/expandHome\(\s*\w+\.dbPath\s*\)/.test(line)) {
+            offenders.push(`${entry.name}:${i + 1}`);
+          }
+        }
+      }
+    };
+    walk(dir);
+
+    expect(offenders).toEqual([]);
+  });
+
+  it("no script reads the non-existent config.database key", () => {
+    const dir = resolve(REPO_ROOT, "scripts");
+    const offenders: string[] = [];
+
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith(".ts")) continue;
+      const src = readFileSync(resolve(dir, name), "utf-8");
+      for (const [i, line] of src.split("\n").entries()) {
+        // Skip comments — documenting the retired key must not fail the guard.
+        if (/^\s*(\/\/|\*|\/\*)/.test(line)) continue;
+        const code = line.split("//")[0];
+        if (/config\.database\b/.test(code)) offenders.push(`${name}:${i + 1}`);
+      }
+    }
+
+    expect(offenders).toEqual([]);
+  });
+});

package/src/__tests__/resolve-tier.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "bun:test";
+
+import { isDecayExempt, resolveTier } from "../decay-engine.js";
+
+/**
+ * importance 是 MemoryEntry 的列字段，metadata 里没有它——顶层住着的是
+ * accessCount / lastAccessedAt / tier（access-tracker 写的）。所以 heuristic
+ * 分支必须由调用方把 entry.importance 传进来。
+ * 2026-07 实测：全库 115688 行里 3214 行走这个分支，其中 metadata 顶层有
+ * importance 的是 0 行——也就是这些条目当时全部被压成了 peripheral。
+ */
+function meta(extra: Record<string, unknown> = {}): string {
+  return JSON.stringify({ source: "cc", evolution: { status: "active" }, ...extra });
+}
+
+describe("resolveTier", () => {
+  it("拿到 entry.importance 时，高 importance 条目升到对应档位", () => {
+    // 真实样本形状：importance 0.9 的 patterns，此前一直被判 peripheral
+    expect(resolveTier(meta(), 0.9)).toBe("working");
+    expect(resolveTier(meta(), 0.96)).toBe("core");
+    expect(resolveTier(meta(), 0.5)).toBe("peripheral");
+  });
+
+  it("不传 entry.importance 时退回 0——这正是修复前的行为", () => {
+    // 保持向后兼容：老调用方不传就还是老结果，不会炸
+    expect(resolveTier(meta(), undefined)).toBe("peripheral");
+    expect(resolveTier(meta())).toBe("peripheral");
+  });
+
+  it("显式 tier 优先，entry.importance 不能覆盖它", () => {
+    // access-tracker 算过一次就会把 tier 写进顶层，那是权威值
+    expect(resolveTier(meta({ tier: "peripheral" }), 0.99)).toBe("peripheral");
+    expect(resolveTier(meta({ tier: "core" }), 0.1)).toBe("core");
+  });
+
+  it("metadata 顶层真有 importance 时以它为准", () => {
+    // 顺序：meta.importance > entryImportance > 0
+    expect(resolveTier(meta({ importance: 0.85 }), 0.1)).toBe("working");
+  });
+
+  it("accessCount 仍走 metadata 顶层——那是 access-tracker 实际写入的位置", () => {
+    expect(resolveTier(meta({ accessCount: 10 }), 0.1)).toBe("core");
+    expect(resolveTier(meta({ accessCount: 3 }), 0.1)).toBe("working");
+  });
+
+  it("没有 metadata 或解析失败时给 peripheral", () => {
+    expect(resolveTier(undefined, 0.99)).toBe("peripheral");
+    expect(resolveTier("{ 坏掉的 json", 0.99)).toBe("peripheral");
+  });
+});
+
+describe("isDecayExempt", () => {
+  it("core + 高 importance 免衰减——importance 来自入参而非 metadata", () => {
+    // 修复前：resolveTierFromMeta 读不到 importance，tier 恒为 peripheral，
+    // 于是这条规则对没有显式 tier 的条目从来没生效过。
+    const noExplicitTier = JSON.stringify({ source: "cc", lastAccessedAt: 0 });
+    expect(isDecayExempt(noExplicitTier, 0.96)).toBe(true);
+  });
+
+  it("importance 不够高时不豁免", () => {
+    const noExplicitTier = JSON.stringify({ source: "cc", lastAccessedAt: 0 });
+    expect(isDecayExempt(noExplicitTier, 0.9)).toBe(false);
+  });
+});

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([]);
+  });
+});