recallnest 2.6.1 → 3.0.0

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", {

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

@@ -0,0 +1,256 @@
+import { describe, expect, it, beforeEach } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  applyUtilityToMeta,
+  computeMemoryUtility,
+  formatMemoryUtility,
+  JOIN_WEIGHT,
+  linkMemoryToObservations,
+  OUTCOME_REWARD,
+  readUtility,
+  summarizeMemoryOutcomes,
+  UTILITY_FIELD,
+} from "../memory-utility.js";
+import { buildWorkflowObservationRecord } from "../workflow-observation-engine.js";
+import { WorkflowObservationStore } from "../workflow-observation-store.js";
+import {
+  PROCESS_READER_ID,
+  RECALLED_IDS_CAP,
+  recallLedgerSize,
+  recentRecallHits,
+  recordRecallHits,
+  resetRecallLedger,
+} from "../recall-ledger.js";
+import { AccessTracker } from "../access-tracker.js";
+import { isDecayExempt, resolveTier } from "../decay-engine.js";
+
+const MEM_A = "aaaaaaaa-0000-4000-8000-000000000001";
+const MEM_B = "bbbbbbbb-0000-4000-8000-000000000002";
+
+function obs(overrides: Record<string, unknown>) {
+  return buildWorkflowObservationRecord({
+    workflowId: "resume_context",
+    summary: "test observation",
+    ...overrides,
+  });
+}
+
+describe("recall ledger (P0 join key)", () => {
+  beforeEach(() => resetRecallLedger());
+
+  it("records hits and returns them newest-first within the window", () => {
+    const t0 = 1_000_000;
+    recordRecallHits([MEM_A], t0);
+    recordRecallHits([MEM_B], t0 + 1000);
+    expect(recentRecallHits(60_000, 10, t0 + 2000)).toEqual([MEM_B, MEM_A]);
+  });
+
+  it("drops hits older than the window", () => {
+    const t0 = 1_000_000;
+    recordRecallHits([MEM_A], t0);
+    recordRecallHits([MEM_B], t0 + 60 * 60_000);
+    expect(recentRecallHits(30 * 60_000, 10, t0 + 60 * 60_000)).toEqual([MEM_B]);
+  });
+
+  it("caps the returned list", () => {
+    const ids = Array.from({ length: RECALLED_IDS_CAP + 20 }, (_, i) => `id-${i}`);
+    recordRecallHits(ids, 5_000);
+    expect(recentRecallHits(60_000, RECALLED_IDS_CAP, 5_000).length).toBe(RECALLED_IDS_CAP);
+  });
+
+  it("gives every AccessTracker the same process-level reader id", () => {
+    // 回归防线：readerId 曾是 per-instance 随机的，而 components 按 profile 缓存 —— 同一个
+    // 会话开两个 profile 就伪造出两个 reader，join 直接失效。
+    const fakeStore = {} as never;
+    expect(new AccessTracker(fakeStore).readerId).toBe(PROCESS_READER_ID);
+    expect(new AccessTracker(fakeStore).readerId).toBe(new AccessTracker(fakeStore).readerId);
+    expect(new AccessTracker(fakeStore, undefined, "r-explicit").readerId).toBe("r-explicit");
+  });
+
+  it("records into the ledger before the novelty/cooldown gate", () => {
+    // 高相似度 + 严格 novelty 闸：强化会被挡下，但 agent 确实看到了这条 —— 账本必须记。
+    const fakeStore = {} as never;
+    const tracker = new AccessTracker(fakeStore, {
+      flushIntervalMs: 5000,
+      reinforcementFactor: 0.5,
+      maxMultiplier: 3,
+      accessFreshnessHalfLifeDays: 30,
+      noveltyThreshold: 0.9,
+      cooldownMs: 0,
+    });
+    tracker.recordAccess([MEM_A], [0.99]);
+    expect(tracker.pendingCount).toBe(0);
+    expect(recentRecallHits()).toContain(MEM_A);
+    tracker.destroy();
+  });
+});
+
+describe("memory ↔ observation join", () => {
+  it("joins exactly when the observation names the memory", () => {
+    const links = linkMemoryToObservations(MEM_A, "{}", [
+      obs({ recalledIds: [MEM_A, MEM_B], outcome: "success" }),
+      obs({ recalledIds: [MEM_B], outcome: "failure" }),
+    ]);
+    expect(links.length).toBe(1);
+    expect(links[0].join).toBe("exact");
+  });
+
+  it("falls back to session join through readerId ∩ metadata.readerIds", () => {
+    const meta = JSON.stringify({ readerIds: ["r-1234abcd"] });
+    const links = linkMemoryToObservations(MEM_A, meta, [
+      obs({ readerId: "r-1234abcd", outcome: "corrected" }),
+      obs({ readerId: "r-otherxx", outcome: "failure" }),
+    ]);
+    expect(links.length).toBe(1);
+    expect(links[0].join).toBe("session");
+    expect(links[0].outcome).toBe("corrected");
+  });
+
+  it("prefers exact over session for the same observation", () => {
+    const meta = JSON.stringify({ readerIds: ["r-1234abcd"] });
+    const links = linkMemoryToObservations(MEM_A, meta, [
+      obs({ readerId: "r-1234abcd", recalledIds: [MEM_A], outcome: "success" }),
+    ]);
+    expect(links.length).toBe(1);
+    expect(links[0].join).toBe("exact");
+  });
+
+  it("returns nothing when neither key is present (the pre-P0 state)", () => {
+    expect(linkMemoryToObservations(MEM_A, "{}", [obs({ outcome: "success" })])).toEqual([]);
+  });
+});
+
+describe("utility computation", () => {
+  const now = Date.parse("2026-08-23T00:00:00.000Z");
+  const at = (daysAgo: number) => new Date(now - daysAgo * 86_400_000).toISOString();
+
+  it("answers 「这条 memory 参与过的任务成功率是多少」", () => {
+    const summary = summarizeMemoryOutcomes(MEM_A, [
+      { observationId: "o1", workflowId: "w", outcome: "success", recordedAt: at(1), join: "exact", summary: "" },
+      { observationId: "o2", workflowId: "w", outcome: "success", recordedAt: at(2), join: "exact", summary: "" },
+      { observationId: "o3", workflowId: "w", outcome: "failure", recordedAt: at(3), join: "exact", summary: "" },
+    ], now);
+    expect(summary.total).toBe(3);
+    expect(summary.successRate).toBeCloseTo(2 / 3, 5);
+    expect(summary.exactSuccessRate).toBeCloseTo(2 / 3, 5);
+  });
+
+  it("goes negative when the tasks mostly failed — importance could never hold this", () => {
+    const summary = summarizeMemoryOutcomes(MEM_A, [
+      { observationId: "o1", workflowId: "w", outcome: "failure", recordedAt: at(0), join: "exact", summary: "" },
+      { observationId: "o2", workflowId: "w", outcome: "failure", recordedAt: at(1), join: "exact", summary: "" },
+      { observationId: "o3", workflowId: "w", outcome: "missed", recordedAt: at(2), join: "exact", summary: "" },
+    ], now);
+    expect(summary.utility).not.toBeNull();
+    expect(summary.utility!).toBeLessThan(0);
+  });
+
+  it("weights session joins below exact ones", () => {
+    const exact = summarizeMemoryOutcomes(MEM_A, [
+      { observationId: "o1", workflowId: "w", outcome: "success", recordedAt: at(0), join: "exact", summary: "" },
+    ], now);
+    const session = summarizeMemoryOutcomes(MEM_A, [
+      { observationId: "o1", workflowId: "w", outcome: "success", recordedAt: at(0), join: "session", summary: "" },
+    ], now);
+    expect(exact.effectiveSamples).toBeCloseTo(JOIN_WEIGHT.exact, 5);
+    expect(session.effectiveSamples).toBeCloseTo(JOIN_WEIGHT.session, 5);
+    // 同一个 outcome，加权平均的值一样，可信度不同 —— 差别落在 effectiveSamples 上。
+    expect(exact.utility).toBeCloseTo(OUTCOME_REWARD.success, 5);
+  });
+
+  it("decays old outcomes by the 30-day half-life", () => {
+    const fresh = summarizeMemoryOutcomes(MEM_A, [
+      { observationId: "o1", workflowId: "w", outcome: "success", recordedAt: at(0), join: "exact", summary: "" },
+    ], now);
+    const old = summarizeMemoryOutcomes(MEM_A, [
+      { observationId: "o1", workflowId: "w", outcome: "success", recordedAt: at(30), join: "exact", summary: "" },
+    ], now);
+    expect(old.effectiveSamples).toBeCloseTo(fresh.effectiveSamples * 0.5, 3);
+  });
+
+  it("ignores session-join noise once exact samples exist", () => {
+    // 2026-08-23 落地当天的实测：同一会话跑多个任务时，readerId join 会把无关任务的
+    // 成败摊到每条被读过的记忆上——那次 5 条记忆的会话级成功率全是 44%（常数，零信息），
+    // 精确成功率却是 100%/33%/0%。所以有精确样本时不掺会话级。
+    const links = [
+      { observationId: "e1", workflowId: "w", outcome: "success" as const, recordedAt: at(0), join: "exact" as const, summary: "" },
+      { observationId: "e2", workflowId: "w", outcome: "success" as const, recordedAt: at(0), join: "exact" as const, summary: "" },
+      { observationId: "s1", workflowId: "w", outcome: "failure" as const, recordedAt: at(0), join: "session" as const, summary: "" },
+      { observationId: "s2", workflowId: "w", outcome: "failure" as const, recordedAt: at(0), join: "session" as const, summary: "" },
+    ];
+    const preferred = summarizeMemoryOutcomes(MEM_A, links, now);
+    expect(preferred.utilityBasis).toBe("exact");
+    expect(preferred.utility).toBeCloseTo(OUTCOME_REWARD.success, 5);
+
+    const mixed = summarizeMemoryOutcomes(MEM_A, links, now, { preferExact: false });
+    expect(mixed.utility!).toBeLessThan(preferred.utility!);
+  });
+
+  it("falls back to session join when nothing named this memory", () => {
+    const links = Array.from({ length: 4 }, (_, i) => ({
+      observationId: `s${i}`, workflowId: "w", outcome: "success" as const,
+      recordedAt: at(0), join: "session" as const, summary: "",
+    }));
+    const summary = summarizeMemoryOutcomes(MEM_A, links, now);
+    expect(summary.utilityBasis).toBe("session");
+    expect(summary.utility).toBeCloseTo(OUTCOME_REWARD.success, 5);
+  });
+
+  it("returns null (not 0) when there is no evidence", () => {
+    const summary = summarizeMemoryOutcomes(MEM_A, [], now);
+    expect(summary.utility).toBeNull();
+    expect(summary.successRate).toBeNull();
+    expect(summary.utilityBasis).toBe("none");
+  });
+});
+
+describe("utility metadata write-back", () => {
+  it("writes utility without touching importance-derived behaviour", () => {
+    const summary = summarizeMemoryOutcomes(MEM_A, [
+      { observationId: "o1", workflowId: "w", outcome: "failure", recordedAt: new Date().toISOString(), join: "exact", summary: "" },
+    ]);
+    const before = { tier: "peripheral", accessCount: 2 };
+    const after = applyUtilityToMeta(before, summary);
+    expect(after[UTILITY_FIELD]).toBeLessThan(0);
+    // 硬约束：utility 不进 tier、不进 decay 豁免。
+    expect(resolveTier(JSON.stringify(after), 0.7)).toBe(resolveTier(JSON.stringify(before), 0.7));
+    expect(isDecayExempt(JSON.stringify(after), 0.7, "cases"))
+      .toBe(isDecayExempt(JSON.stringify(before), 0.7, "cases"));
+    expect((after as Record<string, unknown>).importance).toBeUndefined();
+  });
+
+  it("clears utility instead of writing 0 when the evidence is gone", () => {
+    const meta = { utility: -0.5, utilitySamples: 1, utilityUpdatedAt: 1 };
+    const cleared = applyUtilityToMeta(meta, summarizeMemoryOutcomes(MEM_A, []));
+    expect(UTILITY_FIELD in cleared).toBe(false);
+    expect(readUtility(JSON.stringify(cleared))).toBeNull();
+  });
+});
+
+describe("end-to-end through the observation store", () => {
+  it("round-trips join keys and answers the success-rate query", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "recallnest-utility-obs-"));
+    const store = new WorkflowObservationStore(dir);
+    await store.save(obs({ recalledIds: [MEM_A], outcome: "success", readerId: "r-sess0001" }));
+    await store.save(obs({ recalledIds: [MEM_A], outcome: "failure", readerId: "r-sess0001", workflowId: "checkpoint_session" }));
+    await store.save(obs({ recalledIds: [MEM_B], outcome: "success", readerId: "r-sess0001" }));
+
+    const records = await store.listRecent({ limit: 100 });
+    const summary = computeMemoryUtility({ id: MEM_A, metadata: "{}" }, records);
+    expect(summary.total).toBe(2);
+    expect(summary.successRate).toBeCloseTo(0.5, 5);
+    expect(formatMemoryUtility(summary, { showLinks: 2 })).toContain("成功率");
+  });
+
+  it("still parses observations written before the join-key fields existed", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "recallnest-utility-legacy-"));
+    const store = new WorkflowObservationStore(dir);
+    const legacy = obs({ outcome: "success" });
+    expect((legacy as Record<string, unknown>).recalledIds).toBeUndefined();
+    await store.save(legacy);
+    expect((await store.listRecent({ limit: 10 })).length).toBe(1);
+  });
+});