@modusensus/dsh-mneme 0.4.4 → 0.4.6

package/test/llm-audit.test.js

@@ -0,0 +1,279 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createDreamScheduler } from "../src/dream.js";
+import { createSummarizer } from "../src/summarize.js";
+import { createApi } from "../src/api.js";
+import { createSettings } from "../src/settings.js";
+import { mockCtx } from "./helpers/dream-mock.js";
+
+// Bug8: LLM audit trail. Every background LLM call (autoDream consolidation +
+// summary, autoSummarize compression) records tokens/time/status into
+// llm_audit_logs. Failures are captured as status='error' and never block the
+// calling feature. Read back through the API (/llm-audit + /llm-audit/stats).
+// Gating: runDream treats llmAudit.enabled === false as off; summarize treats
+// llmAudit.enabled !== false as on.
+
+function dreamSetup(over = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  return {
+    store,
+    service,
+    config: { dreamProvider: "deepseek", dreamModel: "deepseek-chat", llmAudit: { enabled: true }, ...over }
+  };
+}
+
+test("autoDream writes llm_audit_logs rows for consolidation and summary", async () => {
+  const { store, service, config } = dreamSetup();
+  service.saveWithDedupe({ type: "project", title: "旧1", content: "第一段内容" });
+  service.saveWithDedupe({ type: "project", title: "旧2", content: "第二段内容" });
+  const ctx = mockCtx({
+    onConsolidation: (listText) => {
+      const ids = [...listText.matchAll(/id=([^\s|]+)\s*\|\s*type=\w+\s*\|\s*importance=\d+/g)].map((m) => m[1]);
+      return JSON.stringify(ids.map((id) => ({ action: "keep", ids: [id] })));
+    }
+  });
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0 });
+  const result = await dream.runDream(ctx, service, config);
+  assert.equal(result.ok, true);
+
+  const rows = service.listLlmAudits();
+  assert.equal(rows.length, 2, "one consolidation + one summary audit row");
+  const consolidate = rows.find((r) => r.operation_type === "dream_consolidate");
+  const summarize = rows.find((r) => r.operation_type === "dream_summarize");
+  assert.ok(consolidate, "dream_consolidate row present");
+  assert.ok(summarize, "dream_summarize row present");
+  assert.equal(consolidate.trigger_source, "autoDream");
+  assert.equal(summarize.trigger_source, "autoDream");
+  assert.equal(consolidate.status, "success");
+  assert.equal(summarize.status, "success");
+  // mockCtx resolves the route from agentDefaultModel (mock:stress-model), not
+  // the config fallback — assert the actually-used route.
+  assert.equal(consolidate.model_id, "mock:stress-model");
+  assert.equal(summarize.model_id, "mock:stress-model");
+  assert.ok(Array.isArray(consolidate.related_memory_ids) && consolidate.related_memory_ids.length === 2,
+    "consolidation audit records the snapshot ids");
+  assert.ok(consolidate.total_tokens >= 0 && summarize.total_tokens >= 0);
+  assert.ok(typeof consolidate.duration_ms === "number" && consolidate.duration_ms >= 0);
+  store.close();
+});
+
+test("autoDream LLM failure is audited as status=error and never blocks the run", async () => {
+  const { store, service, config } = dreamSetup();
+  service.saveWithDedupe({ type: "project", title: "主题", content: "内容" });
+  // Consolidation stream finishes with kind "error" → streamText returns
+  // undefined → the run fails safe; runAuditedLlm must still leave an
+  // error audit row before the failure propagates.
+  const ctx = {
+    logger: { warn: () => {} },
+    llm: {
+      async *stream() {
+        yield { type: "text-delta", index: 0, text: "" };
+        yield { type: "finish", reason: { kind: "error" } };
+      }
+    }
+  };
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0 });
+  const result = await dream.runDream(ctx, service, config);
+  assert.equal(result.ok, false, "aborted/errored stream fails the run");
+  const rows = service.listLlmAudits();
+  assert.equal(rows.length, 1, "failed consolidation still audited");
+  assert.equal(rows[0].operation_type, "dream_consolidate");
+  assert.equal(rows[0].status, "error");
+  assert.ok(rows[0].error_message, "error message recorded");
+  // the audit write did not block the failure path
+  assert.equal(result.error, "llm failed");
+  store.close();
+});
+
+test("autoDream throwing LLM is audited as status=error", async () => {
+  const { store, service, config } = dreamSetup();
+  service.saveWithDedupe({ type: "project", title: "主题", content: "内容" });
+  const ctx = {
+    logger: { warn: () => {} },
+    llm: {
+      async *stream() {
+        throw new Error("network down");
+      }
+    }
+  };
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0 });
+  const result = await dream.runDream(ctx, service, config);
+  assert.equal(result.ok, false);
+  const rows = service.listLlmAudits();
+  assert.equal(rows.length, 1, "throwing call still audited");
+  assert.equal(rows[0].status, "error");
+  assert.match(rows[0].error_message, /network down/);
+  store.close();
+});
+
+test("autoDream audit is skipped when llmAudit.enabled === false", async () => {
+  const { store, service, config } = dreamSetup({ llmAudit: { enabled: false } });
+  service.saveWithDedupe({ type: "project", title: "主题", content: "内容" });
+  const ctx = mockCtx();
+  const dream = createDreamScheduler({ thresholdCount: 1, thresholdChars: 0, delayMs: 0 });
+  await dream.runDream(ctx, service, config);
+  assert.equal(service.listLlmAudits().length, 0, "no audit rows when disabled");
+  store.close();
+});
+
+test("autoSummarize writes an llm_audit_logs row (trigger_source autoSummarize)", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const events = [];
+  const ctx = {
+    on(name, fn) {
+      events.push({ name, fn });
+      return () => {};
+    },
+    logger: { warn: () => {} },
+    llm: {
+      async *stream() {
+        yield { type: "text-delta", index: 0, text: JSON.stringify([
+          { type: "decision", title: "选型", content: "确定用 node:sqlite", importance: 4 }
+        ]) };
+        yield { type: "finish", reason: { kind: "stop" } };
+      }
+    }
+  };
+  const config = {
+    autoSummarize: true,
+    summarizeProvider: "deepseek",
+    summarizeModel: "deepseek-chat",
+    llmAudit: { enabled: true }
+  };
+  createSummarizer(ctx, service, config);
+  const handler = events.find((e) => e.name === "session/event").fn;
+  const session = {
+    id: "s1",
+    requestHeader: () => ({ config: {} }),
+    events: [
+      { type: "user/message", data: { source: { kind: "user" }, content: [{ type: "text", text: "帮我选型" }] } },
+      { seq: 2, type: "turn/end" }
+    ]
+  };
+  await handler(session, { seq: 2, type: "turn/end" });
+  const rows = service.listLlmAudits();
+  assert.equal(rows.length, 1, "one autoSummarize audit row");
+  assert.equal(rows[0].trigger_source, "autoSummarize");
+  assert.equal(rows[0].operation_type, "summarize_compress");
+  assert.equal(rows[0].model_id, "deepseek:deepseek-chat");
+  assert.equal(rows[0].status, "success");
+  store.close();
+});
+
+// --- API surface ------------------------------------------------------------
+
+class FakeRes extends EventEmitter {
+  constructor() { super(); this.statusCode = 200; this.body = ""; }
+  writeHead(code, headers) { this.statusCode = code; this.headers = headers; return this; }
+  end(text) { this.body = text ?? ""; this.emit("end"); return this; }
+}
+
+function req(path) {
+  const r = new EventEmitter();
+  r.url = path;
+  r.method = "GET";
+  r.headers = {};
+  return r;
+}
+
+function apiSetup() {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const settings = createSettings(store.db);
+  const routes = [];
+  const ctx = {
+    webServer: {
+      register(route) {
+        routes.push(route);
+        return () => {};
+      }
+    }
+  };
+  createApi(ctx, service, settings, { add: () => {}, remove: () => false, list: () => [] });
+  return { store, service, routes };
+}
+
+test("GET /api/dsh-mneme/semantic/llm-audit paginates and filters by source", async () => {
+  const { store, service, routes } = apiSetup();
+  for (let i = 0; i < 3; i++) {
+    service.saveLlmAudit({
+      trigger_source: "autoDream",
+      operation_type: "dream_consolidate",
+      model_id: "deepseek:deepseek-chat",
+      input_tokens: 10, output_tokens: 5, status: "success"
+    });
+  }
+  service.saveLlmAudit({
+    trigger_source: "autoSummarize",
+    operation_type: "summarize_compress",
+    model_id: "deepseek:deepseek-chat",
+    input_tokens: 3, output_tokens: 1, status: "success"
+  });
+  const route = routes.find((r) => r.path === "/api/dsh-mneme/semantic/llm-audit");
+
+  // full page
+  let res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/semantic/llm-audit?page=1&pageSize=2"), res);
+  let data = JSON.parse(res.body);
+  assert.equal(res.statusCode, 200);
+  assert.equal(data.total, 4);
+  assert.equal(data.page, 1);
+  assert.equal(data.pageSize, 2);
+  assert.equal(data.items.length, 2);
+
+  // second page
+  res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/semantic/llm-audit?page=2&pageSize=2"), res);
+  data = JSON.parse(res.body);
+  assert.equal(data.items.length, 2, "page 2 has the remaining rows");
+  assert.equal(data.total, 4);
+
+  // source filter
+  res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/semantic/llm-audit?source=autoSummarize"), res);
+  data = JSON.parse(res.body);
+  assert.equal(data.total, 1);
+  assert.equal(data.items[0].trigger_source, "autoSummarize");
+  store.close();
+});
+
+test("GET /api/dsh-mneme/semantic/llm-audit/stats aggregates by source and status", async () => {
+  const { store, service, routes } = apiSetup();
+  service.saveLlmAudit({
+    timestamp: new Date().toISOString(),
+    trigger_source: "autoDream", operation_type: "dream_consolidate",
+    model_id: "m", input_tokens: 100, output_tokens: 40, duration_ms: 25, status: "success"
+  });
+  service.saveLlmAudit({
+    timestamp: new Date().toISOString(),
+    trigger_source: "autoDream", operation_type: "dream_summarize",
+    model_id: "m", input_tokens: 30, output_tokens: 10, duration_ms: 8, status: "success"
+  });
+  service.saveLlmAudit({
+    timestamp: new Date().toISOString(),
+    trigger_source: "autoSummarize", operation_type: "summarize_compress",
+    model_id: "m", input_tokens: 5, output_tokens: 2, duration_ms: 4, status: "error"
+  });
+  const route = routes.find((r) => r.path === "/api/dsh-mneme/semantic/llm-audit/stats");
+  const res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/semantic/llm-audit/stats?days=7"), res);
+  const stats = JSON.parse(res.body);
+  assert.equal(res.statusCode, 200);
+  assert.equal(stats.days, 7);
+  assert.equal(stats.total_calls, 3);
+  assert.equal(stats.input_tokens, 135);
+  assert.equal(stats.output_tokens, 52);
+  assert.equal(stats.total_tokens, 187);
+  assert.equal(stats.total_duration_ms, 37);
+  const bySource = stats.by_source.find((s) => s.source === "autoDream");
+  assert.equal(bySource.c, 2);
+  assert.equal(bySource.total_tokens, 180);
+  const errStatus = stats.by_status.find((s) => s.status === "error");
+  assert.equal(errStatus.c, 1);
+  store.close();
+});

package/test/mirror-edit-digest.test.js

@@ -75,7 +75,9 @@ test("digest 匹配：saveWithDedupe 同标题 merge 后新值落地、无伪冲
     assert.equal(result.action, "merged");
     assert.equal(store.count(), 1, "同标题合并不新增条目");
     const m = service.getById(result.memory.id);
-    assert.equal(m.content, "新内容", "合并后新值必须落地");
+    // Bug5: 同标题合并不是覆盖，而是追加（旧内容 + --- 分隔 + 新内容）
+    assert.ok(m.content.includes("旧内容"), "合并后旧内容保留在追加正文");
+    assert.ok(m.content.includes("新内容"), "合并后新值必须落地");
     assert.ok(!m.content.includes(CONFLICT_MARKER), "不得出现伪冲突 marker");
     const file = readFileSync(mirrorFile(dir, "preference"), "utf8");
     assert.match(file, /新内容/, "镜像已重渲染为新值");

package/test/quality-filter.test.js

@@ -0,0 +1,118 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import {
+  evaluateMemoryQuality,
+  META_MEMORY_RE,
+  textSimilarity,
+  dedupRatio
+} from "../src/quality-filter.js";
+
+// Bug7: rule-based memory quality filter. Gated on
+// config.memoryQualityFilter.enabled === true — raw configs (`{}`) keep the
+// legacy behavior. Score bands:
+//   >= 60       stored normally
+//   30 .. < 60  quality_score persisted, injection ranked by importance × score/100
+//   < 30        archived + tagged low_quality (explicit search still recalls it)
+
+function setup(over = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: { memoryQualityFilter: { enabled: true }, ...over } });
+  return { store, service };
+}
+
+test("evaluateMemoryQuality: meta-memory scores below 60 (degraded, not archived)", () => {
+  const { score, tags } = evaluateMemoryQuality({
+    type: "history",
+    title: "对话总结",
+    content: "总结一下刚才的对话，需要记住以下要点"
+  });
+  assert.ok(score >= 30 && score < 60, `meta memory should be degraded (30..60), got ${score}`);
+  assert.ok(tags.includes("meta"), "tagged meta");
+});
+
+test("evaluateMemoryQuality: short content is archived (< 30)", () => {
+  const { score, tags } = evaluateMemoryQuality({ type: "preference", title: "语言", content: "短" });
+  assert.ok(score < 30, `short content should be archived, got ${score}`);
+  assert.ok(tags.includes("short_content"));
+  assert.ok(tags.includes("low_quality"));
+});
+
+test("evaluateMemoryQuality: near-duplicate of a recent memory is archived", () => {
+  const { score, tags } = evaluateMemoryQuality(
+    { type: "preference", title: "重复", content: "猫咪喜欢在阳台晒太阳并打盹" },
+    { recentContents: ["猫咪喜欢在阳台晒太阳并打盹"] }
+  );
+  assert.ok(score < 30, `duplicate should be archived, got ${score}`);
+  assert.ok(tags.includes("duplicate"));
+});
+
+test("saveWithDedupe: meta memory persists quality_score < 60 and is not archived", () => {
+  const { store, service } = setup();
+  const { memory } = service.saveWithDedupe({
+    type: "history",
+    title: "对话总结",
+    content: "总结一下刚才的对话，需要记住以下要点"
+  });
+  const got = store.getById(memory.id);
+  assert.ok(got.quality_score !== undefined && got.quality_score < 60,
+    `meta memory should store quality_score < 60, got ${got.quality_score}`);
+  assert.equal(got.archived, false, "degraded memory stays un-archived");
+});
+
+test("saveWithDedupe: short text is archived + tagged low_quality", () => {
+  const { store, service } = setup();
+  const { memory } = service.saveWithDedupe({
+    type: "preference",
+    title: "语言",
+    content: "短"
+  });
+  const got = store.getById(memory.id);
+  assert.equal(got.archived, true, "short text archived");
+  assert.ok(got.tags.includes("low_quality"), "tagged low_quality");
+  assert.ok(got.quality_score < 30, `score below archive threshold, got ${got.quality_score}`);
+});
+
+test("saveWithDedupe: near-duplicate content is archived", () => {
+  const { store, service } = setup();
+  service.saveWithDedupe({ type: "preference", title: "习惯一", content: "猫咪喜欢在阳台晒太阳并打盹" });
+  const { memory: dup } = service.saveWithDedupe({ type: "preference", title: "习惯二", content: "猫咪喜欢在阳台晒太阳并打盹" });
+  const got = store.getById(dup.id);
+  assert.equal(got.archived, true, "near-duplicate archived");
+  assert.ok(got.tags.includes("low_quality"));
+});
+
+test("saveWithDedupe: filter disabled (raw config) skips scoring entirely", () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const { memory } = service.saveWithDedupe({ type: "preference", title: "语言", content: "短" });
+  const got = store.getById(memory.id);
+  assert.equal(got.archived, false, "nothing archived when filter off");
+  assert.equal(got.quality_score, undefined, "no quality_score when filter off");
+  assert.ok(!got.tags.includes("low_quality"));
+});
+
+test("injectCandidates: degraded memory ranks below a healthy preference", () => {
+  const { service } = setup();
+  // Healthy preference: score 100 → weight 1.0 → 3 * 1.0 = 3.0.
+  service.saveWithDedupe({ type: "preference", title: "健康偏好", content: "用户平时习惯用中文交流", importance: 3 });
+  // Degraded (meta-memory) preference: score ~55 → weight 0.55 → 5 * 0.55 = 2.75.
+  service.saveWithDedupe({ type: "preference", title: "元记忆偏好", content: "总结一下刚才的对话内容吧", importance: 5 });
+  const candidates = service.injectCandidates({ maxItems: 5, threshold: 3 });
+  const titles = candidates.map((c) => c.title);
+  assert.ok(titles.includes("健康偏好"), "healthy preference present");
+  assert.ok(titles.includes("元记忆偏好"), "degraded preference present");
+  assert.ok(titles.indexOf("健康偏好") < titles.indexOf("元记忆偏好"),
+    "degraded memory is demoted below the healthy one");
+});
+
+test("exported helpers behave (meta regex, similarity, dedup ratio)", () => {
+  assert.ok(META_MEMORY_RE.test("总结一下刚才的对话"));
+  assert.ok(META_MEMORY_RE.test("作为AI助手，我需要记住"));
+  assert.ok(!META_MEMORY_RE.test("用户喜欢喝咖啡"));
+  assert.equal(textSimilarity("猫咪喜欢晒太阳", "猫咪喜欢晒太阳"), 1);
+  assert.ok(textSimilarity("猫咪喜欢晒太阳", "完全不同的内容") < 0.3);
+  assert.ok(dedupRatio("哈哈哈哈哈哈") < 0.3, "repetitive filler has low dedup ratio");
+  assert.ok(dedupRatio("一句信息量足够的话") > 0.3);
+});

package/test/recall-evals.test.js

@@ -0,0 +1,235 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { DatabaseSync } from "node:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { Config } from "../src/config.js";
+
+// Mock embedder: every query maps to the fixed vector [1,0,0], so vector recall
+// surfaces any row embedded at [1,0,0] and excludes orthogonal ones.
+const embedder = {
+  embedSingle: async () => [1, 0, 0],
+  embed: async () => [1, 0, 0],
+  schedule: () => {},
+  modelHash: "eval#mock",
+  dimension: 3
+};
+
+function setup(config = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config });
+  return { store, service };
+}
+
+function saveMemory(service, title, content) {
+  return service.saveWithDedupe({ type: "preference", title, content, importance: 5 }).memory;
+}
+
+// ---------------------------------------------------------------- schema / config
+
+test("config: evalPersistTestResults defaults to false (opt-in)", () => {
+  assert.equal(Config({}).evalPersistTestResults, false, "off by default");
+  assert.equal(Config({ evalPersistTestResults: true }).evalPersistTestResults, true, "explicit opt-in");
+});
+
+test("schema: recall_evals table exists with the expected columns", () => {
+  const store = createStore(":memory:");
+  const cols = store.db.prepare("PRAGMA table_info(recall_evals)").all().map((c) => c.name);
+  for (const col of ["id", "recall_run_id", "query", "expected_ids", "actual_ids", "metrics", "eval_type", "created_at"]) {
+    assert.ok(cols.includes(col), `column ${col} present`);
+  }
+  // FK clause is declared against recall_runs.
+  const fks = store.db.prepare("PRAGMA foreign_key_list(recall_evals)").all();
+  assert.ok(fks.some((fk) => fk.table === "recall_runs" && fk.from === "recall_run_id"), "FK to recall_runs(id) declared");
+  store.close();
+});
+
+test("legacy DB without recall_evals is upgraded idempotently on open", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-recall-evals-"));
+  const dbPath = join(dir, "memory.db");
+  try {
+    const old = new DatabaseSync(dbPath);
+    old.exec(`
+      CREATE TABLE recall_runs (
+        id TEXT PRIMARY KEY, query TEXT NOT NULL, mode TEXT NOT NULL,
+        top_k INTEGER, threshold REAL, candidates TEXT NOT NULL, created_at TEXT NOT NULL
+      );
+      INSERT INTO recall_runs (id, query, mode, candidates, created_at) VALUES ('r1', '旧', 'keyword', '[]', 't');
+    `);
+    old.close();
+    const store = createStore(dbPath);
+    const cols = store.db.prepare("PRAGMA table_info(recall_evals)").all().map((c) => c.name);
+    assert.ok(cols.includes("id"), "recall_evals created on a legacy DB");
+    assert.equal(store.getRecallRun("r1").query, "旧", "legacy recall_runs row preserved");
+    store.close();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------- switch-off / switch-on
+
+test("switch off: evaluateRetrieval computes metrics but writes nothing", async () => {
+  const { store, service } = setup({}); // evalPersistTestResults defaults false
+  const m = saveMemory(service, "量子计算入门", "叠加态");
+  const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", topK: 10 });
+  assert.ok(res.metrics.precision >= 0 && res.metrics.precision <= 1, "metrics computed");
+  assert.deepEqual(res.actualIds, [m.id], "retrieval ran and returned the memory");
+  assert.equal(res.persisted, false, "no persistence when switch is off");
+  assert.deepEqual(store.listRecallEvals(), [], "recall_evals stays empty");
+  store.close();
+});
+
+test("switch on: evaluateRetrieval persists a recall_evals snapshot", async () => {
+  const { store, service } = setup({ evalPersistTestResults: true });
+  const m = saveMemory(service, "量子计算入门", "叠加态");
+  const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", topK: 10, evalType: "regression" });
+  assert.equal(res.persisted, true, "snapshot persisted");
+  const evals = store.listRecallEvals();
+  assert.equal(evals.length, 1, "one eval row");
+  const row = evals[0];
+  assert.equal(row.query, "量子");
+  assert.deepEqual(row.expected_ids, [m.id], "expected ids round-trip");
+  assert.deepEqual(row.actual_ids, [m.id], "actual ids round-trip");
+  assert.equal(row.eval_type, "regression");
+  assert.ok(row.metrics && typeof row.metrics.precision === "number", "metrics JSON round-trips");
+  assert.ok(typeof row.created_at === "string" && row.created_at.length > 0, "timestamp captured");
+  // Idempotent on id: the same logical eval id replays without duplicates.
+  store.saveRecallEval({ id: "ev-x", query: "q", expected_ids: [], actual_ids: [], metrics: {}, eval_type: "manual" });
+  store.saveRecallEval({ id: "ev-x", query: "q2", expected_ids: [], actual_ids: [], metrics: {}, eval_type: "manual" });
+  assert.equal(store.listRecallEvals().filter((e) => e.id === "ev-x").length, 1, "replay overwrites, no duplicate");
+  store.close();
+});
+
+test("persist override: call-level persist:true writes even with the switch off", async () => {
+  const { store, service } = setup({}); // switch off
+  const m = saveMemory(service, "量子计算入门", "叠加态");
+  const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", persist: true });
+  assert.equal(res.persisted, true, "explicit persist override honored");
+  assert.equal(store.listRecallEvals().length, 1);
+  store.close();
+});
+
+test("persist override: call-level persist:false suppresses even with the switch on", async () => {
+  const { store, service } = setup({ evalPersistTestResults: true });
+  saveMemory(service, "量子计算入门", "叠加态");
+  const res = await service.evaluateRetrieval("量子", [], { mode: "keyword", persist: false });
+  assert.equal(res.persisted, false, "explicit opt-out honored");
+  assert.deepEqual(store.listRecallEvals(), [], "nothing written");
+  store.close();
+});
+
+// ---------------------------------------------------------------- metrics correctness
+
+test("metrics: computeRetrievalMetrics is exact for known inputs", () => {
+  const { service } = setup();
+  // a,b,c retrieved; a,x expected → 1 relevant at rank 1.
+  assert.deepEqual(
+    service.computeRetrievalMetrics(["a", "b", "c"], ["a", "x"]),
+    { precision: 0.3333, recall: 0.5, mrr: 1, hit_count: 1 }
+  );
+  // relevant at rank 3 → mrr 1/3.
+  assert.deepEqual(
+    service.computeRetrievalMetrics(["x", "y", "a"], ["a", "b"]),
+    { precision: 0.3333, recall: 0.5, mrr: 0.3333, hit_count: 1 }
+  );
+  // empty retrieval → zero metrics, no divide-by-zero.
+  assert.deepEqual(
+    service.computeRetrievalMetrics([], ["a", "b"]),
+    { precision: 0, recall: 0, mrr: 0, hit_count: 0 }
+  );
+  // everything relevant, nothing missed → perfect scores.
+  assert.deepEqual(
+    service.computeRetrievalMetrics(["a", "b"], ["a", "b"]),
+    { precision: 1, recall: 1, mrr: 1, hit_count: 2 }
+  );
+  // extra noise harms precision but not recall.
+  assert.deepEqual(
+    service.computeRetrievalMetrics(["a", "b", "c", "d"], ["a"]),
+    { precision: 0.25, recall: 1, mrr: 1, hit_count: 1 }
+  );
+});
+
+test("metrics: integration — partial hit scores precision/recall/mrr from real recall", async () => {
+  const { store, service } = setup({ evalPersistTestResults: true });
+  const hit = saveMemory(service, "量子计算入门", "叠加态");
+  saveMemory(service, "量子纠缠", "贝尔态");
+  saveMemory(service, "猫咪饲养", "喂食");
+  const res = await service.evaluateRetrieval("量子", [hit.id], { mode: "keyword", topK: 10 });
+  // Two literal 量子 hits retrieved, one relevant → precision 1/2, recall 1/1.
+  // Title-tied, equal-importance rows order by updated_at DESC, so the later
+  // saved 量子纠缠 ranks first and the relevant row is at rank 2 → mrr 1/2.
+  assert.equal(res.metrics.hit_count, 1);
+  assert.equal(res.metrics.precision, 0.5);
+  assert.equal(res.metrics.recall, 1);
+  assert.equal(res.metrics.mrr, 0.5);
+  const row = store.listRecallEvals()[0];
+  assert.equal(row.metrics.precision, 0.5, "persisted metrics match");
+  store.close();
+});
+
+// ---------------------------------------------------------------- FK linkage
+
+test("FK: recordRecall=true links the eval to the recall_runs audit row", async () => {
+  const { store, service } = setup({ evalPersistTestResults: true });
+  const m = saveMemory(service, "量子计算入门", "叠加态");
+  const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", topK: 5, recordRecall: true });
+  assert.ok(res.recallRunId, "a recall run was recorded for the same scene");
+  assert.equal(store.listRecallRuns().length, 1, "exactly one recall_runs row");
+  const run = store.getRecallRun(res.recallRunId);
+  assert.equal(run.query, "量子");
+  const evals = store.listRecallEvals();
+  assert.equal(evals.length, 1);
+  assert.equal(evals[0].recall_run_id, res.recallRunId, "eval links to the recorded run");
+  store.close();
+});
+
+test("FK: explicit recallRunId is preserved — recordRecall never clobbers it (regression)", async () => {
+  const { store, service } = setup({ evalPersistTestResults: true });
+  const m = saveMemory(service, "量子计算入门", "叠加态");
+  // Pre-existing audit run the evaluator wants to link against.
+  const run = store.saveRecallRun({
+    query: "量子", mode: "keyword", topK: 5, candidates: [], created_at: new Date().toISOString()
+  });
+  // recordRecall=true alongside an explicit recallRunId: the explicit link wins,
+  // and NO extra recall_runs row is minted.
+  const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword", recordRecall: true, recallRunId: run.id });
+  assert.equal(res.recallRunId, run.id, "explicit recallRunId preserved");
+  assert.equal(store.listRecallRuns().length, 1, "no duplicate recall_runs row minted");
+  const evals = store.listRecallEvals();
+  assert.equal(evals[0].recall_run_id, run.id, "eval links to the pre-existing run");
+  store.close();
+});
+
+test("FK: recordRecall=false leaves recall_run_id null and writes no recall_runs row", async () => {
+  const { store, service } = setup({ evalPersistTestResults: true });
+  const m = saveMemory(service, "量子计算入门", "叠加态");
+  const res = await service.evaluateRetrieval("量子", [m.id], { mode: "keyword" });
+  assert.equal(res.recallRunId, null, "no run recorded by default");
+  assert.deepEqual(store.listRecallRuns(), [], "recall_runs untouched by evals");
+  const row = store.listRecallEvals()[0];
+  assert.ok(!row.recall_run_id, "eval row has no recall_run_id");
+  store.close();
+});
+
+// ---------------------------------------------------------------- production isolation
+
+test("production search never writes recall_evals, even with the switch on", async () => {
+  const { store, service } = setup({ evalPersistTestResults: true });
+  // Mimic src/index.js wiring: the recall recorder persists to recall_runs.
+  service.setRecallRecorder((recall) => {
+    store.saveRecallRun({
+      query: recall.query, mode: recall.mode, topK: recall.topK, threshold: recall.threshold ?? null,
+      candidates: recall.candidates ?? [], created_at: recall.createdAt
+    });
+  });
+  saveMemory(service, "量子计算入门", "叠加态");
+  const rows = await service.searchMemories("量子", { mode: "keyword", recordRecall: true });
+  assert.ok(rows.length >= 1, "search returned results");
+  assert.equal(store.listRecallRuns().length, 1, "production audit lands in recall_runs");
+  assert.deepEqual(store.listRecallEvals(), [], "recall_evals stays untouched by production search");
+  store.close();
+});