recallnest 3.0.0 → 4.0.0

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__/retrieve-audit-revision.test.ts

@@ -1,255 +0,0 @@
-/**
- * Retrieve-audit revision/provenance coverage.
- *
- * `3fc1875` connected the retrieve audit (setAuditLogger had zero callers, so the
- * `?.` call was a permanent no-op). What it records is `query="…" hits=N` — enough to
- * prove a retrieval happened, not enough to answer the question an audit log is for:
- * when an agent acted on recalled memory, *which revision did it read*?
- *
- * That gap is not cosmetic. `archiveBeliefVersion` rewrites a belief in place: the
- * canonical id stays, `evolution.version` goes up, and the old text survives as a
- * separate `superseded` row. So "memory abc1234 was retrieved" is ambiguous across every
- * belief change, and a stale answer is indistinguishable from a current one after the
- * fact.
- *
- * These tests pin the extra fields on the existing audit row. They deliberately do not
- * introduce a second audit path — the assertions run against the same `AuditLogger`
- * interface the store/update/delete operations already use.
- */
-
-import { describe, expect, it } from "bun:test";
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { AUDIT_RETRIEVED_CAP, createAuditLogger, type AuditEntry } from "../audit-log.js";
-import { createRetriever } from "../retriever.js";
-
-function recordingLogger(): { entries: AuditEntry[]; logger: any } {
-  const entries: AuditEntry[] = [];
-  return {
-    entries,
-    logger: {
-      log(entry: Omit<AuditEntry, "timestamp">) {
-        entries.push({ timestamp: new Date().toISOString(), ...entry });
-      },
-      getRecent: () => entries,
-      exportAll: () => entries,
-      count: () => entries.length,
-    },
-  };
-}
-
-interface FakeRow {
-  id: string;
-  text: string;
-  metadata?: Record<string, unknown>;
-  score?: number;
-}
-
-function buildRetriever(rows: FakeRow[]) {
-  const results = rows.map((row) => ({
-    entry: {
-      id: row.id,
-      text: row.text,
-      vector: [1, 0, 0],
-      category: "cases",
-      scope: "memory",
-      importance: 0.8,
-      timestamp: Date.parse("2026-08-01T00:00:00.000Z"),
-      ...(row.metadata ? { metadata: JSON.stringify(row.metadata) } : {}),
-    },
-    score: row.score ?? 0.9,
-  }));
-
-  return createRetriever(
-    {
-      hasFtsSupport: false,
-      async vectorSearch() {
-        return results;
-      },
-    } 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,
-    },
-  );
-}
-
-describe("retrieve audit records revision and provenance", () => {
-  it("records the served revision, lifecycle status, and boundary of each hit", async () => {
-    const { entries, logger } = recordingLogger();
-    const retriever = buildRetriever([
-      {
-        id: "aaaaaaaa-1111-2222-3333-444444444444",
-        text: "Alice uses Bun, not npm",
-        metadata: {
-          evolution: { status: "active", version: 3 },
-          boundary: {
-            layer: "durable",
-            authority: "structured-memory",
-            conflictPolicy: "latest-wins",
-          },
-        },
-      },
-    ]);
-    retriever.setAuditLogger(logger);
-
-    await retriever.retrieve({ query: "which runtime does recallnest use", scopeFilter: ["memory"], limit: 5 });
-
-    const row = entries.find((e) => e.operation === "retrieve");
-    expect(row).toBeDefined();
-    expect(row?.retrieved).toEqual([
-      { id: "aaaaaaaa", rev: 3, st: "active", ly: "durable", au: "structured-memory" },
-    ]);
-    // The pre-existing details string is untouched — this extends the row, not replaces it.
-    expect(row?.details).toContain('query="which runtime does recallnest use"');
-    expect(row?.details).toContain("hits=1");
-  });
-
-  it("distinguishes a superseded revision from the live one", async () => {
-    const { entries, logger } = recordingLogger();
-    // Both rows are reachable by design: belief history is archive-first, so a query can
-    // legitimately surface the old text. Without `rev`/`st` the audit row cannot tell
-    // afterwards whether the agent read the current belief or the retired one.
-    const retriever = buildRetriever([
-      {
-        id: "cccccccc-0000-0000-0000-000000000000",
-        text: "Deploys go through the mini",
-        metadata: {
-          evolution: { status: "active", version: 2 },
-          boundary: { layer: "durable", authority: "structured-memory", conflictPolicy: "latest-wins" },
-        },
-      },
-      {
-        id: "hhhhhhhh-0000-0000-0000-000000000000",
-        text: "Deploys go through the MacBook",
-        metadata: {
-          evolution: { status: "superseded", version: 1, supersededBy: "cccccccc-0000-0000-0000-000000000000" },
-          boundary: { layer: "durable", authority: "structured-memory", conflictPolicy: "latest-wins" },
-        },
-        score: 0.85,
-      },
-    ]);
-    retriever.setAuditLogger(logger);
-
-    await retriever.retrieve({
-      query: "where do deploys run",
-      scopeFilter: ["memory"],
-      limit: 5,
-      // Superseded rows are excluded by default; this is the path that can serve one.
-      includeArchived: true,
-    });
-
-    const row = entries.find((e) => e.operation === "retrieve");
-    const served = row?.retrieved ?? [];
-    const byId = new Map(served.map((r) => [r.id, r]));
-
-    expect(byId.get("cccccccc")).toMatchObject({ rev: 2, st: "active" });
-    expect(byId.get("hhhhhhhh")).toMatchObject({ rev: 1, st: "superseded" });
-  });
-
-  it("defaults a memory with no evolution block to revision 1 / active", async () => {
-    const { entries, logger } = recordingLogger();
-    // Pre-versioning rows exist in the live database; they must not break the audit row.
-    const retriever = buildRetriever([
-      { id: "eeeeeeee-0000-0000-0000-000000000000", text: "legacy entry with no metadata" },
-    ]);
-    retriever.setAuditLogger(logger);
-
-    await retriever.retrieve({ query: "legacy", scopeFilter: ["memory"], limit: 5 });
-
-    const row = entries.find((e) => e.operation === "retrieve");
-    expect(row?.retrieved).toEqual([{ id: "eeeeeeee", rev: 1, st: "active" }]);
-    // No boundary metadata means no layer/authority claim — absent, not guessed.
-    expect(row?.retrieved?.[0]).not.toHaveProperty("ly");
-    expect(row?.retrieved?.[0]).not.toHaveProperty("au");
-  });
-
-  it("caps the list and says so, rather than silently reporting a short one", async () => {
-    const { entries, logger } = recordingLogger();
-    const overCap = AUDIT_RETRIEVED_CAP + 4;
-    const retriever = buildRetriever(
-      Array.from({ length: overCap }, (_, i) => ({
-        id: `${String(i).padStart(8, "0")}-0000-0000-0000-000000000000`,
-        text: `candidate ${i}`,
-        metadata: { evolution: { status: "active", version: 1 } },
-        score: 0.9 - i * 0.001,
-      })),
-    );
-    retriever.setAuditLogger(logger);
-
-    await retriever.retrieve({ query: "many candidate rows for one query", scopeFilter: ["memory"], limit: overCap });
-
-    const row = entries.find((e) => e.operation === "retrieve");
-    expect(row?.retrieved).toHaveLength(AUDIT_RETRIEVED_CAP);
-    // audit.jsonl has no rotation, so the list is bounded — but truncation must be legible.
-    expect(row?.retrievedTotal).toBe(overCap);
-    expect(row?.details).toContain(`hits=${overCap}`);
-  });
-
-  it("round-trips the new fields through the real file logger", async () => {
-    // The unit tests above assert against an in-memory logger. This one proves the fields
-    // survive the actual JSONL path — serialization, append, and parse-back — so a shape
-    // that only works in tests cannot pass. Uses a temp dir, never the production log.
-    const dir = mkdtempSync(join(tmpdir(), "recallnest-audit-"));
-    const logPath = join(dir, "audit.jsonl");
-
-    try {
-      const retriever = buildRetriever([
-        {
-          id: "ffffffff-0000-0000-0000-000000000000",
-          text: "Release verification runs on the mini",
-          metadata: {
-            evolution: { status: "active", version: 5 },
-            boundary: { layer: "evidence", authority: "distillation", conflictPolicy: "append-only" },
-          },
-        },
-      ]);
-      retriever.setAuditLogger(createAuditLogger(logPath));
-
-      await retriever.retrieve({
-        query: "where does release verification run",
-        scopeFilter: ["memory"],
-        limit: 5,
-      });
-
-      const lines = readFileSync(logPath, "utf-8").trim().split("\n").filter(Boolean);
-      const row = lines.map((l) => JSON.parse(l) as AuditEntry).find((e) => e.operation === "retrieve");
-
-      expect(row?.retrieved).toEqual([
-        { id: "ffffffff", rev: 5, st: "active", ly: "evidence", au: "distillation" },
-      ]);
-      expect(typeof row?.timestamp).toBe("string");
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  it("omits both fields when nothing was served", async () => {
-    const { entries, logger } = recordingLogger();
-    const retriever = buildRetriever([]);
-    retriever.setAuditLogger(logger);
-
-    await retriever.retrieve({ query: "a question with no stored answer", scopeFilter: ["memory"], limit: 5 });
-
-    const row = entries.find((e) => e.operation === "retrieve");
-    expect(row).toBeDefined();
-    expect(row).not.toHaveProperty("retrieved");
-    // retrievedTotal exists to flag truncation; with an empty list there is none to flag.
-    expect(row).not.toHaveProperty("retrievedTotal");
-  });
-});