recallnest 2.6.0 → 3.0.0

package/src/__tests__/dream-write-batching.test.ts

@@ -0,0 +1,211 @@
+/**
+ * 2026-08-14 dream 写爆库根治的写入层回归：
+ * - store.patchMetadataBatch：真 LanceDB 实例上的批量读改写语义（锁内最新行起底、
+ *   按序应用、scope 过滤、单条失败跳过）
+ * - activity-counter.pruneWriteCounts：transcript 计数清扫（含未达标条目）
+ * - auto-gc 批量归档：maxArchivePerRun 命中时不弃单（flush 后再停）
+ */
+import { afterAll, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { MemoryStore, type MemoryEntry } from "../store.js";
+import { incrementWriteCount, getWriteCount, pruneWriteCounts, listScopesAboveThreshold } from "../activity-counter.js";
+import { isTranscriptScope } from "../memory-boundaries.js";
+import { maybeRunGc, resetGcTimestamp } from "../auto-gc.js";
+
+const tmpDirs: string[] = [];
+afterAll(() => {
+  for (const d of tmpDirs) rmSync(d, { recursive: true, force: true });
+});
+
+function makeIsolatedStore(): { store: MemoryStore; statsPath: string } {
+  const dir = mkdtempSync(join(tmpdir(), "rn-batch-"));
+  tmpDirs.push(dir);
+  return { store: new MemoryStore({ dbPath: join(dir, "lancedb"), vectorDim: 3 }), statsPath: join(dir, "activity-stats.json") };
+}
+
+describe("store.patchMetadataBatch（真 LanceDB）", () => {
+  it("一次调用批量写 N 行，最终态各自生效", async () => {
+    const { store } = makeIsolatedStore();
+    const scope = "project:batch";
+    const a = await store.store({ text: "row a", vector: [1, 0, 0], category: "events", scope, importance: 0.5, metadata: "{}" });
+    const b = await store.store({ text: "row b", vector: [0, 1, 0], category: "events", scope, importance: 0.5, metadata: "{}" });
+
+    const written = await store.patchMetadataBatch([
+      { id: a.id, patchFn: meta => ({ ...meta, marker: "A" }) },
+      { id: b.id, patchFn: meta => ({ ...meta, marker: "B" }) },
+    ], [scope]);
+
+    expect(written).toBe(2);
+    expect(JSON.parse((await store.getById(a.id))!.metadata!).marker).toBe("A");
+    expect(JSON.parse((await store.getById(b.id))!.metadata!).marker).toBe("B");
+  });
+
+  it("patchFn 以库中最新行起底：批量写不吞前一次独立 update 写入的键", async () => {
+    const { store } = makeIsolatedStore();
+    const scope = "project:fresh";
+    const a = await store.store({ text: "row", vector: [1, 0, 0], category: "events", scope, importance: 0.5, metadata: "{}" });
+    // 先经独立通道写入一个键（模拟 3a 已提交的 version_group）
+    await store.update(a.id, { metadata: JSON.stringify({ version_group: "vg-keep" }) }, [scope]);
+    // 批量 patch 只声明自己的键 —— 旧"预物化整串"接口在这里会把 version_group 抹掉
+    await store.patchMetadataBatch([
+      { id: a.id, patchFn: meta => ({ ...meta, consolidatedInto: "x" }) },
+    ], [scope]);
+    const final = JSON.parse((await store.getById(a.id))!.metadata!);
+    expect(final.version_group).toBe("vg-keep");
+    expect(final.consolidatedInto).toBe("x");
+  });
+
+  it("同批 patchFn 按数组序执行（闭包可传递决策）", async () => {
+    const { store } = makeIsolatedStore();
+    const scope = "project:seq";
+    const a = await store.store({ text: "first", vector: [1, 0, 0], category: "events", scope, importance: 0.5, metadata: "{}" });
+    const b = await store.store({ text: "second", vector: [0, 1, 0], category: "events", scope, importance: 0.5, metadata: "{}" });
+    let decided: string | null = null;
+    await store.patchMetadataBatch([
+      { id: a.id, patchFn: meta => { decided = "from-first"; return { ...meta, tag: "lead" }; } },
+      { id: b.id, patchFn: meta => ({ ...meta, tag: decided }) },
+    ], [scope]);
+    expect(JSON.parse((await store.getById(b.id))!.metadata!).tag).toBe("from-first");
+  });
+
+  it("scope 过滤拒绝越权行、不存在的 id 跳过、空数组返回 0", async () => {
+    const { store } = makeIsolatedStore();
+    const a = await store.store({ text: "in scope", vector: [1, 0, 0], category: "events", scope: "project:x", importance: 0.5, metadata: "{}" });
+    const written = await store.patchMetadataBatch([
+      { id: a.id, patchFn: meta => ({ ...meta, touched: true }) },
+      { id: "00000000-0000-4000-8000-000000000000", patchFn: meta => meta },
+    ], ["project:other"]); // a 不在此 scope
+    expect(written).toBe(0);
+    expect(JSON.parse((await store.getById(a.id))!.metadata!).touched).toBeUndefined();
+    expect(await store.patchMetadataBatch([], ["project:x"])).toBe(0);
+  });
+
+  it("单条 patchFn 抛错跳过该条，其余照写", async () => {
+    const { store } = makeIsolatedStore();
+    const scope = "project:err";
+    const a = await store.store({ text: "bad", vector: [1, 0, 0], category: "events", scope, importance: 0.5, metadata: "{}" });
+    const b = await store.store({ text: "good", vector: [0, 1, 0], category: "events", scope, importance: 0.5, metadata: "{}" });
+    const written = await store.patchMetadataBatch([
+      { id: a.id, patchFn: () => { throw new Error("boom"); } },
+      { id: b.id, patchFn: meta => ({ ...meta, ok: true }) },
+    ], [scope]);
+    expect(written).toBe(1);
+    expect(JSON.parse((await store.getById(b.id))!.metadata!).ok).toBe(true);
+    expect(JSON.parse((await store.getById(a.id))!.metadata!).ok).toBeUndefined();
+  });
+});
+
+describe("pruneWriteCounts（transcript 计数清扫）", () => {
+  it("清掉全部 transcript 条目（达标与未达标），durable 一律保留", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "rn-prune-"));
+    tmpDirs.push(dir);
+    const cfg = { statsPath: join(dir, "activity-stats.json") };
+    await incrementWriteCount("codex:aaaa1111", 15, cfg); // transcript 达标
+    await incrementWriteCount("kimi:bbbb2222", 3, cfg);   // transcript 未达标
+    await incrementWriteCount("project:harness", 12, cfg); // durable 达标
+    await incrementWriteCount("memory", 2, cfg);           // durable 未达标
+
+    const removed = await pruneWriteCounts(isTranscriptScope, cfg);
+
+    expect(removed.sort()).toEqual(["codex:aaaa1111", "kimi:bbbb2222"]);
+    expect(getWriteCount("codex:aaaa1111", cfg)).toBe(0);
+    expect(getWriteCount("kimi:bbbb2222", cfg)).toBe(0);
+    expect(getWriteCount("project:harness", cfg)).toBe(12);
+    expect(getWriteCount("memory", cfg)).toBe(2);
+    expect(listScopesAboveThreshold(10, cfg)).toEqual(["project:harness"]);
+  });
+});
+
+describe("auto-gc 批量归档的上限语义", () => {
+  it("maxArchivePerRun 命中时已选中的候选照常提交（flush 不弃单）", async () => {
+    resetGcTimestamp();
+    const oldTs = Date.now() - 120 * 86_400_000;
+    const activeMeta = (): string => JSON.stringify({
+      evolution: { status: "active", version: 1, accessCount: 0, lastAccessedAt: null, validFrom: oldTs, validUntil: null },
+    });
+    const rows: Array<{ id: string; text: string; importance: number; timestamp: number; metadata: string; category: string; scope: string }> = [
+      { id: "g1", text: "old1", importance: 0.1, timestamp: oldTs, metadata: activeMeta(), category: "events", scope: "project:gc" },
+      { id: "g2", text: "old2", importance: 0.1, timestamp: oldTs, metadata: activeMeta(), category: "events", scope: "project:gc" },
+      { id: "g3", text: "old3", importance: 0.1, timestamp: oldTs, metadata: activeMeta(), category: "events", scope: "project:gc" },
+    ];
+    const batchCalls: number[] = [];
+    const store = {
+      async stats() { return { totalCount: 100, scopeCounts: {}, categoryCounts: {} }; },
+      async repairSingletonVersionGroups() { return 0; },
+      async list() { return rows; },
+      async listPage(opts: { limit?: number; offset?: number } = {}) {
+        const { limit = 1000, offset = 0 } = opts;
+        return rows.slice(offset, offset + limit);
+      },
+      async update() { return null; },
+      async patchMetadataBatch(
+        patches: Array<{ id: string; patchFn: (meta: Record<string, unknown>, entry: unknown) => Record<string, unknown> }>,
+      ) {
+        batchCalls.push(patches.length);
+        for (const { id, patchFn } of patches) {
+          const row = rows.find(r => r.id === id);
+          if (!row) continue;
+          row.metadata = JSON.stringify(patchFn(JSON.parse(row.metadata) as Record<string, unknown>, row));
+        }
+        return patches.length;
+      },
+    };
+
+    const result = await maybeRunGc(
+      store as unknown as Parameters<typeof maybeRunGc>[0],
+      { minMemoryCount: 1, minHoursSinceLastGc: 0, decayScoreThreshold: 0.99, maxArchivePerRun: 2, minAgeDays: 30 },
+    );
+
+    expect(result.archivedCount).toBe(2); // 上限生效
+    const archived = rows.filter(r => (JSON.parse(r.metadata) as { evolution: { status: string } }).evolution.status === "archived");
+    expect(archived.length).toBe(2); // 且真的写进去了（break 前 flush，不弃单）
+    expect(batchCalls.reduce((a, b) => a + b, 0)).toBe(2);
+  });
+
+  it("即使低于归档数量门槛也会自愈 singleton version-group", async () => {
+    resetGcTimestamp();
+    let repairCalls = 0;
+    const store = {
+      async stats() { return { totalCount: 100, scopeCounts: {}, categoryCounts: {} }; },
+      async repairSingletonVersionGroups() { repairCalls++; return 1; },
+      async listPage() { return []; },
+      async patchMetadataBatch() { return 0; },
+    };
+
+    const result = await maybeRunGc(
+      store as unknown as Parameters<typeof maybeRunGc>[0],
+      { minMemoryCount: 1000, minHoursSinceLastGc: 0, decayScoreThreshold: 0.15, maxArchivePerRun: 100, minAgeDays: 30 },
+    );
+
+    expect(repairCalls).toBe(1);
+    expect(result.triggered).toBe(false);
+    expect(result.reason).toBe("below_memory_threshold");
+    expect(result.dissolvedVersionGroups).toBe(1);
+  });
+
+  it("单成员组自愈有独立节流，不会被每个 dream scope 重复全库扫描", async () => {
+    resetGcTimestamp();
+    let repairCalls = 0;
+    const store = {
+      async stats() { return { totalCount: 100, scopeCounts: {}, categoryCounts: {} }; },
+      async repairSingletonVersionGroups() { repairCalls++; return 0; },
+      async listPage() { return []; },
+      async patchMetadataBatch() { return 0; },
+    };
+    const config = {
+      minMemoryCount: 1000,
+      minHoursSinceLastGc: 24,
+      decayScoreThreshold: 0.15,
+      maxArchivePerRun: 100,
+      minAgeDays: 30,
+    };
+
+    await maybeRunGc(store as unknown as Parameters<typeof maybeRunGc>[0], config);
+    await maybeRunGc(store as unknown as Parameters<typeof maybeRunGc>[0], config);
+
+    expect(repairCalls).toBe(1);
+  });
+});

package/src/__tests__/env-config-invariant.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "bun:test";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Architecture guard for the invariant env-config.ts declares in its own header:
+ * it is the single source of truth for every fixed `RECALLNEST_*` env read, and
+ * consumers must call its accessors instead of touching `process.env` directly.
+ *
+ * That invariant was documented but unenforced, and it had already sprung a leak:
+ * `cli.ts` read RECALLNEST_DREAM_BUDGET_MS inline and — precisely because it
+ * bypassed the accessor layer — was the one read in the repo with no
+ * `Number.isFinite` guard, so `""` silently became a 0ms dream budget and any
+ * non-numeric value became a NaN deadline that disabled the guard entirely.
+ * Bypassing the chokepoint IS how the guard gets lost; hence a test, not a note.
+ *
+ * Baseline: 0 violations as of 2026-08-18. If this goes red, the fix is normally
+ * to add an accessor to env-config.ts — not to widen EXEMPT.
+ *
+ * Deliberately NOT matched (these are the exemptions env-config.ts's header
+ * already names, and each reads differently so the pattern never sees them):
+ *   - scope-policy.ts   → `env.RECALLNEST_*` on an injected env object
+ *   - store.ts          → RECALLNEST_NS is a local constant, not an env var
+ *   - runtime-config / embedder / llm-client → dynamic `process.env[name]`
+ *     config-template expansion, which cannot be statically consolidated
+ */
+
+// Add a file here ONLY with a reason, and only when an accessor genuinely can't
+// work (e.g. the read must happen before env-config's module-init boundary).
+const EXEMPT: ReadonlyArray<{ file: string; why: string }> = [];
+
+const DIRECT_READ = /process\.env\.RECALLNEST_[A-Z_0-9]+/g;
+
+function collectSourceFiles(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      if (entry === "__tests__" || entry === "node_modules") continue;
+      collectSourceFiles(full, out);
+      continue;
+    }
+    if (!entry.endsWith(".ts") || entry.endsWith(".test.ts") || entry === "env-config.ts") continue;
+    out.push(full);
+  }
+  return out;
+}
+
+describe("env-config is the chokepoint for RECALLNEST_* reads", () => {
+  it("no src/ module reads process.env.RECALLNEST_* directly", () => {
+    const exemptFiles = new Set(EXEMPT.map((e) => e.file));
+    const violations: string[] = [];
+
+    for (const file of collectSourceFiles("src")) {
+      if (exemptFiles.has(file)) continue;
+      const lines = readFileSync(file, "utf8").split("\n");
+      lines.forEach((line, i) => {
+        for (const hit of line.match(DIRECT_READ) ?? []) {
+          violations.push(`${file}:${i + 1}  ${hit}`);
+        }
+      });
+    }
+
+    expect(
+      violations,
+      violations.length === 0
+        ? ""
+        : `Direct RECALLNEST_* env reads bypass env-config.ts's guards:\n  ${violations.join("\n  ")}\n` +
+          `Fix: add an accessor to src/env-config.ts (with its parsing + fallback) and call it here.`,
+    ).toEqual([]);
+  });
+
+  it("guard actually detects a violation (so a green run means something)", () => {
+    const synthetic = 'const x = Number(process.env.RECALLNEST_SOMETHING_NEW ?? 1);';
+    expect(synthetic.match(DIRECT_READ)).toHaveLength(1);
+    // And it must not fire on the exempted read styles:
+    expect('env.RECALLNEST_SESSION_ID'.match(DIRECT_READ)).toBeNull();
+    expect('process.env[envVar]'.match(DIRECT_READ)).toBeNull();
+    expect('const RECALLNEST_NS = "recallnest:v1";'.match(DIRECT_READ)).toBeNull();
+  });
+});

package/src/__tests__/env-config.test.ts

@@ -21,6 +21,8 @@ const KEYS = [
   "RECALLNEST_RECALL_MODE",
   "RECALLNEST_UI_PORT",
   "RECALLNEST_API_PORT",
+  "RECALLNEST_DREAM_BUDGET_MS",
+  "RECALLNEST_SYNTHESIS_MODEL",
 ];
 
 const saved: Record<string, string | undefined> = {};
@@ -149,3 +151,61 @@ describe("env-config accessors are lazy (read at call time, never frozen)", () =
     expect(envConfig.emotionScoring()).toBe(false);
   });
 });
+
+describe("env-config dreamBudgetMs — the two silent failure modes it exists to stop", () => {
+  const FALLBACK = 2 * 60 * 60 * 1000;
+
+  it("falls back when unset", () => {
+    delete process.env.RECALLNEST_DREAM_BUDGET_MS;
+    expect(envConfig.dreamBudgetMs(FALLBACK)).toBe(FALLBACK);
+  });
+
+  it('empty string does NOT become 0 (old `?? default` let "" through → Number("") === 0 → every scope skipped)', () => {
+    process.env.RECALLNEST_DREAM_BUDGET_MS = "";
+    expect(envConfig.dreamBudgetMs(FALLBACK)).toBe(FALLBACK);
+    process.env.RECALLNEST_DREAM_BUDGET_MS = "   ";
+    expect(envConfig.dreamBudgetMs(FALLBACK)).toBe(FALLBACK);
+  });
+
+  it('non-numeric does NOT become NaN (NaN deadline makes `Date.now() > deadline` permanently false → budget guard gone)', () => {
+    for (const bad of ["2h", "abc", "30min", "1_000"]) {
+      process.env.RECALLNEST_DREAM_BUDGET_MS = bad;
+      const ms = envConfig.dreamBudgetMs(FALLBACK);
+      expect(Number.isFinite(ms)).toBe(true);
+      expect(ms).toBe(FALLBACK);
+      // The regression this guards: a NaN budget silently disables the deadline.
+      expect(Date.now() > Date.now() + ms).toBe(false);
+    }
+  });
+
+  it("rejects zero and negatives (they would expire the deadline instantly)", () => {
+    for (const bad of ["0", "-1", "-60000"]) {
+      process.env.RECALLNEST_DREAM_BUDGET_MS = bad;
+      expect(envConfig.dreamBudgetMs(FALLBACK)).toBe(FALLBACK);
+    }
+  });
+
+  it("accepts a valid override", () => {
+    process.env.RECALLNEST_DREAM_BUDGET_MS = "900000";
+    expect(envConfig.dreamBudgetMs(FALLBACK)).toBe(900_000);
+  });
+});
+
+describe("env-config synthesisModel — dream 合成的模型旋钮", () => {
+  it("未设 → undefined（调用方回落到 config.llm.model，保持老行为）", () => {
+    delete process.env.RECALLNEST_SYNTHESIS_MODEL;
+    expect(envConfig.synthesisModel()).toBeUndefined();
+  });
+
+  it("空串 / 纯空白也算未设，不会把模型名设成空字符串", () => {
+    for (const blank of ["", "   ", "\t"]) {
+      process.env.RECALLNEST_SYNTHESIS_MODEL = blank;
+      expect(envConfig.synthesisModel()).toBeUndefined();
+    }
+  });
+
+  it("正常值去空白后返回", () => {
+    process.env.RECALLNEST_SYNTHESIS_MODEL = "  qwen-plus  ";
+    expect(envConfig.synthesisModel()).toBe("qwen-plus");
+  });
+});

package/src/__tests__/ingest-scope-prefix.test.ts

@@ -0,0 +1,69 @@
+/**
+ * 每个会话来源的 scope 前缀必须在 memory-boundaries 的清单里登记。
+ *
+ * 这条约束是承重的，不是整洁问题：TRANSCRIPT_SCOPE_PREFIXES 决定了会话碎片
+ * 会不会被降权到 evidence 层。漏登记一个前缀，那个端的 shell 输出就会被当成
+ * 「用户说过的话」提炼成 durable 结论——kimi 与 antigravity 就这么漏过
+ * （2026-07 进栈，直到 2026-08-01 才发现库里一直被当结论对待）。
+ *
+ * 所以加新 ingest 源时，这个测试会在你只改了 config.json / cli.ts 却忘了
+ * 登记前缀的时候变红。
+ */
+import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isTranscriptIngestSource, isTranscriptScope } from "../memory-boundaries.js";
+
+const config = JSON.parse(
+  readFileSync(join(import.meta.dir, "..", "..", "config.json"), "utf8"),
+) as { sources: Record<string, { path: string; glob: string; description?: string }> };
+
+// config 源名 → 它写进库的 scope 前缀。
+// desktop 沿用 cc 前缀是历史行为（Claude Desktop 导出的就是 CC 格式对话）。
+const SOURCE_SCOPE_PREFIX: Record<string, string | null> = {
+  cc: "cc",
+  codex: "codex",
+  gemini: "gemini",
+  kimi: "kimi",
+  desktop: "cc",
+  minis: "minis",
+  memory: null, // markdown 记忆文件，不是会话记录，不走 transcript 降权
+};
+
+describe("ingest 源的 scope 前缀登记", () => {
+  it("config.json 里每个源都在本测试的映射表里有交代", () => {
+    for (const name of Object.keys(config.sources)) {
+      expect(
+        Object.prototype.hasOwnProperty.call(SOURCE_SCOPE_PREFIX, name),
+      ).toBe(true);
+    }
+  });
+
+  it("每个会话类来源的 scope 都被判定为 transcript 证据（会被降权）", () => {
+    for (const [name, prefix] of Object.entries(SOURCE_SCOPE_PREFIX)) {
+      if (prefix === null) continue;
+      // 断言里带上源名，红的时候直接看得出是哪个源漏登记
+      expect(`${name}:${isTranscriptScope(`${prefix}:abcd1234`)}`).toBe(`${name}:true`);
+    }
+  });
+
+  it("minis 源已接线：config 有条目且前缀被降权识别", () => {
+    expect(config.sources.minis).toBeDefined();
+    expect(config.sources.minis.glob).toBe("*.jsonl");
+    expect(isTranscriptScope("minis:9f3e7a21")).toBe(true);
+  });
+
+  it("同一个前缀也必须在 source 清单里登记（两道闸，漏一道就静默失真）", () => {
+    // isTranscriptScope 看 scope、isTranscriptSource 看条目的 source 字段。
+    // 只登记前者时降权仍然生效，错误不会报出来，只会让「按来源过滤」查不准。
+    for (const [name, prefix] of Object.entries(SOURCE_SCOPE_PREFIX)) {
+      if (prefix === null) continue;
+      expect(`${name}:${isTranscriptIngestSource(prefix)}`).toBe(`${name}:true`);
+    }
+  });
+
+  it("一条反向断言：没登记过的前缀不会被误判成 transcript", () => {
+    expect(isTranscriptScope("project:recallnest")).toBe(false);
+    expect(isTranscriptScope("memory:pivot")).toBe(false);
+  });
+});

package/src/__tests__/maintenance-locks.test.ts

@@ -48,9 +48,11 @@ describe("runDream cross-process lock", () => {
         bodyRan = true;
         return { totalCount: 100, scopeCounts: {}, categoryCounts: {} };
       },
+      repairSingletonVersionGroups: async () => 0,
       list: async () => [],
       listPage: async () => [],
       update: async () => null,
+      patchMetadataBatch: async (patches: Array<{ id: string; patchFn: unknown }>) => patches.length,
       patchMetadata: async () => null,
     };
 
@@ -83,9 +85,11 @@ describe("runDream cross-process lock", () => {
     }));
     const store = {
       stats: async () => ({ totalCount: 100, scopeCounts: {}, categoryCounts: {} }),
+      repairSingletonVersionGroups: async () => 0,
       list: async () => entries,
       listPage: async () => [],
       update: async () => null,
+      patchMetadataBatch: async (patches: Array<{ id: string; patchFn: unknown }>) => patches.length,
       patchMetadata: async () => null,
       getById: async () => null,
       vectorSearch: async () => [],
@@ -123,6 +127,7 @@ describe("runDream cross-process lock", () => {
 
     const store = {
       stats: async () => ({ totalCount: 5, scopeCounts: {}, categoryCounts: {} }),
+      repairSingletonVersionGroups: async () => 0,
       // ⚠️ 2026-08-12 标注：这里 list 返回空数组，走的是 **completed_early 早退路径**，
       // 而早退路径 (dream-pipeline.ts:226) 的 resetWriteCount(scope, statsCfg) 一直是对的。
       // 本条测试因此从未覆盖「完整跑完」那条路径 —— 而 bug 恰恰在那条路径上（:301 漏传 scope）。
@@ -132,6 +137,7 @@ describe("runDream cross-process lock", () => {
       list: async () => [], // no active entries → completed_early path (still resets)
       listPage: async () => [],
       update: async () => null,
+      patchMetadataBatch: async (patches: Array<{ id: string; patchFn: unknown }>) => patches.length,
       patchMetadata: async () => null,
       getById: async () => null,
       vectorSearch: async () => [],
@@ -156,8 +162,10 @@ describe("maybeRunGc cross-process lock + throttle", () => {
   function makeStore(totalCount: number) {
     return {
       stats: async () => ({ totalCount, scopeCounts: {}, categoryCounts: {} }),
+      repairSingletonVersionGroups: async () => 0,
       listPage: async () => [] as unknown[],
       update: async () => null,
+      patchMetadataBatch: async (patches: Array<{ id: string; patchFn: unknown }>) => patches.length,
       list: async () => [],
     } as any;
   }

package/src/__tests__/memory-evolution-b2-b3-e1.test.ts

@@ -59,6 +59,7 @@ describe("B-2: Archive Strategy", () => {
       return {
         store: {
           stats: async () => ({ totalCount: data.size, scopeCounts: {}, categoryCounts: {} }),
+          repairSingletonVersionGroups: async () => 0,
           list: async () => Array.from(data.values()),
           listPage: async (opts: { limit?: number; offset?: number } = {}) => {
             const { limit = 1000, offset = 0 } = opts;
@@ -71,6 +72,22 @@ describe("B-2: Archive Strategy", () => {
             entry.metadata = patch.metadata;
             return entry;
           },
+          // 2026-08-14 auto-gc 批量归档通道：以 data 最新行起底应用 patchFn（生产语义）
+          patchMetadataBatch: async (
+            patches: Array<{ id: string; patchFn: (meta: Record<string, unknown>, entry: unknown) => Record<string, unknown> }>,
+          ) => {
+            let written = 0;
+            for (const { id, patchFn } of patches) {
+              const entry = data.get(id);
+              if (!entry) continue;
+              let meta: Record<string, unknown>;
+              try { meta = JSON.parse(entry.metadata || "{}") as Record<string, unknown>; } catch { meta = {}; }
+              entry.metadata = JSON.stringify(patchFn(meta, entry));
+              updates.push({ id, metadata: entry.metadata });
+              written++;
+            }
+            return written;
+          },
         },
         updates,
       };

package/src/__tests__/memory-output.test.ts

@@ -25,6 +25,15 @@ function buildResult(id: string, metadata: Record<string, unknown>): RetrievalRe
 }
 
 describe("memory output", () => {
+  it("renders a whole-day age next to every date so nobody has to subtract", () => {
+    const result = buildResult("abcd1234-0000-0000-0000-000000000009", { source: "agent" });
+    const search = formatSearchResults([result], { query: "concise", profile: "default" } as any);
+    expect(search).toContain("Date       Age   Retrieval Path");
+    expect(search).toMatch(/2026-03-16 \d+d\s+vector/);
+    const explain = formatExplainResults([result], { query: "concise", profile: "default" } as any);
+    expect(explain).toMatch(/2026-03-16 \(\d+d\)/);
+  });
+
   it("includes provenance in search results", () => {
     const output = formatSearchResults([
       buildResult("abcd1234-0000-0000-0000-000000000001", {