@modusensus/dsh-mneme 0.2.6 → 0.2.8

package/test/policy-epoch.test.js

@@ -0,0 +1,259 @@
+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 { Config } from "../src/config.js";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createDreamScheduler, parseReceipt } from "../src/dream.js";
+
+// ---------------------------------------------------------------- helpers
+
+function openMemory() {
+  return createStore(":memory:");
+}
+
+// Minimal valid dream_runs row for store-level tests.
+function run(id, policyEpoch, createdAt) {
+  const r = {
+    id,
+    created_at: createdAt,
+    status: "ok",
+    snapshot_hash: `hash-${id}`,
+    input_count: 1,
+    decisions: [{ action: "keep", ids: ["x"] }],
+    outcome: { byId: { x: "keep" } },
+    applied: 0,
+    summary_stored: false,
+    receipt: `dsh-mneme:run:${id}:ok:${`hash-${id}`.slice(0, 12)}:1:0:0`
+  };
+  if (policyEpoch !== undefined) r.policy_epoch = policyEpoch;
+  return r;
+}
+
+/**
+ * Minimal DSH-like ctx whose LLM distinguishes the two dream calls by the user
+ * prompt shape: consolidation prompts start with "id=…", summary prompts with
+ * "- title: content". Mirrors audit.test.js.
+ */
+function mockCtx({ onConsolidation, summaryText = "记忆库总览：用户偏好中文。" } = {}) {
+  return {
+    logger: { warn: () => {} },
+    agentDefaultModel: { currentSelection: () => ({ provider: "mock", model: "mock-model" }) },
+    llm: {
+      async *stream(options) {
+        const userText = options.messages.find((m) => m.role === "user")?.content?.[0]?.text ?? "";
+        if (userText.startsWith("id=")) {
+          yield { type: "block-start", index: 0, blockType: "text" };
+          yield { type: "text-delta", index: 0, text: onConsolidation ? onConsolidation(userText) : "[]" };
+          yield { type: "block-end", index: 0, block: { type: "text" } };
+          yield { type: "finish", reason: { kind: "stop" } };
+          return;
+        }
+        if (typeof summaryText === "string") {
+          yield { type: "text-delta", index: 0, text: summaryText };
+          yield { type: "finish", reason: { kind: "stop" } };
+        } else {
+          throw summaryText instanceof Error ? summaryText : new Error(String(summaryText));
+        }
+      }
+    }
+  };
+}
+
+// ---------------------------------------------------------------- config
+
+test("policyEpoch defaults to 0 when config omits it", () => {
+  const cfg = Config({});
+  assert.equal(cfg.policyEpoch, 0);
+});
+
+test("policyEpoch accepts in-range integers including both boundaries", () => {
+  assert.equal(Config({ policyEpoch: 42 }).policyEpoch, 42, "mid-range accepted");
+  assert.equal(Config({ policyEpoch: 0 }).policyEpoch, 0, "min boundary accepted");
+  assert.equal(Config({ policyEpoch: 1000000 }).policyEpoch, 1000000, "max boundary accepted");
+});
+
+test("policyEpoch rejects out-of-range / non-integer / wrong-type values", () => {
+  assert.throws(() => Config({ policyEpoch: -1 }), /expected number >= 0/, "below min rejected");
+  assert.throws(() => Config({ policyEpoch: 1000001 }), /expected number <= 1000000/, "above max rejected");
+  assert.throws(() => Config({ policyEpoch: 1.5 }), /expected number multiple of 1/, "non-integer rejected");
+  assert.throws(() => Config({ policyEpoch: "5" }), /expected number/, "string type rejected");
+});
+
+// ---------------------------------------------------------------- store
+
+test("saveDreamRun stores policy_epoch and getDreamRun reads it back", () => {
+  const store = openMemory();
+  const saved = store.saveDreamRun(run("r-epoch-7", 7));
+  assert.equal(saved.policy_epoch, 7, "write path returns epoch");
+  assert.equal(store.getDreamRun("r-epoch-7").policy_epoch, 7, "read path returns epoch");
+  store.close();
+});
+
+test("saveDreamRun without policy_epoch defaults to 0", () => {
+  const store = openMemory();
+  const saved = store.saveDreamRun(run("r-no-epoch"));
+  assert.equal(saved.policy_epoch, 0);
+  assert.equal(store.getDreamRun("r-no-epoch").policy_epoch, 0);
+  store.close();
+});
+
+test("saveDreamRun falls back to 0 for non-integer policy_epoch", () => {
+  const store = openMemory();
+  for (const bad of [1.5, undefined, "7", null]) {
+    store.saveDreamRun(run(`r-bad-${String(bad)}`, bad));
+    assert.equal(store.getDreamRun(`r-bad-${String(bad)}`).policy_epoch, 0, `policy_epoch=${String(bad)} coerced to 0`);
+  }
+  store.close();
+});
+
+test("migration: legacy dream_runs without policy_epoch column gets it backfilled to 0", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-epoch-migrate-"));
+  const dbPath = join(dir, "legacy.db");
+  try {
+    // Legacy dream_runs DDL (pre-policy_epoch) + one existing row.
+    const legacy = new DatabaseSync(dbPath);
+    legacy.exec(`CREATE TABLE dream_runs (
+      id TEXT PRIMARY KEY, created_at TEXT NOT NULL, status TEXT NOT NULL, error TEXT,
+      provider TEXT, model TEXT, snapshot_hash TEXT NOT NULL, input_count INTEGER NOT NULL,
+      input TEXT, decisions TEXT, outcome TEXT, applied INTEGER NOT NULL DEFAULT 0,
+      summary_stored INTEGER NOT NULL DEFAULT 0, receipt TEXT NOT NULL
+    );`);
+    legacy.exec(`CREATE INDEX idx_dream_runs_created ON dream_runs(created_at);`);
+    legacy.prepare(
+      `INSERT INTO dream_runs (id, created_at, status, snapshot_hash, input_count, receipt)
+       VALUES (?, ?, ?, ?, ?, ?)`
+    ).run("legacy-run", "2026-08-01T00:00:00.000Z", "ok", "h", 1, "dsh-mneme:run:legacy-run:ok:h:1:0:0");
+    legacy.close();
+
+    const store = createStore(dbPath);
+    const cols = store.db.prepare("PRAGMA table_info(dream_runs)").all().map((c) => c.name);
+    assert.ok(cols.includes("policy_epoch"), "policy_epoch column added");
+    assert.equal(store.getDreamRun("legacy-run").policy_epoch, 0, "existing row backfilled to default 0");
+    store.close();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("migration is idempotent: reopening a migrated store does not error or lose data", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-epoch-idem-"));
+  const dbPath = join(dir, "epoch.db");
+  try {
+    const s1 = createStore(dbPath);
+    s1.saveDreamRun(run("r1", 5));
+    s1.close();
+    // Reopen over the already-migrated schema — must not re-ALTER or throw.
+    const s2 = createStore(dbPath);
+    assert.equal(s2.getDreamRun("r1").policy_epoch, 5, "data intact across reopen");
+    const cols = s2.db.prepare("PRAGMA table_info(dream_runs)").all().map((c) => c.name);
+    assert.equal(cols.filter((c) => c === "policy_epoch").length, 1, "column not duplicated");
+    s2.close();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("getLatestPolicyEpoch returns the newest run's epoch by created_at", () => {
+  const store = openMemory();
+  store.saveDreamRun(run("epoch-1", 1, "2026-08-01T00:00:00.000Z"));
+  assert.equal(store.getLatestPolicyEpoch(), 1, "only row wins");
+  store.saveDreamRun(run("epoch-2", 2, "2026-08-02T00:00:00.000Z"));
+  assert.equal(store.getLatestPolicyEpoch(), 2, "newer row wins");
+  store.saveDreamRun(run("epoch-5", 5, "2026-08-03T00:00:00.000Z"));
+  assert.equal(store.getLatestPolicyEpoch(), 5, "newest row wins over mixed epochs");
+  store.close();
+});
+
+test("getLatestPolicyEpoch returns 0 on an empty store", () => {
+  const store = openMemory();
+  assert.equal(store.getLatestPolicyEpoch(), 0);
+  store.close();
+});
+
+// ---------------------------------------------------------------- dream
+
+function dreamSetup() {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const dream = createDreamScheduler({ onRun: () => Promise.resolve({ ok: true, skipped: true }) });
+  return { store, service, dream };
+}
+
+test("runDream writes audit row with policy_epoch when config.policyEpoch=5", async () => {
+  const { store, service, dream } = dreamSetup();
+  const a = service.saveWithDedupe({ type: "project", title: "旧1", content: "内容A" });
+  const b = service.saveWithDedupe({ type: "project", title: "旧2", content: "内容B" });
+  const ctx = mockCtx({
+    onConsolidation: () => JSON.stringify([
+      { action: "merge", ids: [a.memory.id, b.memory.id], title: "合并", content: "合并内容", importance: 4, keepSource: a.memory.id }
+    ])
+  });
+  const result = await dream.runDream(ctx, service, { policyEpoch: 5 });
+  assert.equal(result.ok, true);
+  const run = store.getDreamRun(result.runId);
+  assert.equal(run.policy_epoch, 5, "audit row carries configured epoch");
+  store.close();
+});
+
+test("runDream writes audit row with policy_epoch 0 when config omits it", async () => {
+  const { store, service, dream } = dreamSetup();
+  const a = service.saveWithDedupe({ type: "project", title: "旧1", content: "内容A" });
+  const b = service.saveWithDedupe({ type: "project", title: "旧2", content: "内容B" });
+  const ctx = mockCtx({
+    onConsolidation: () => JSON.stringify([
+      { action: "merge", ids: [a.memory.id, b.memory.id], title: "合并", content: "合并内容", importance: 4, keepSource: a.memory.id }
+    ])
+  });
+  const result = await dream.runDream(ctx, service, {});
+  assert.equal(result.ok, true);
+  const run = store.getDreamRun(result.runId);
+  assert.equal(run.policy_epoch, 0, "default epoch written when config omits policyEpoch");
+  store.close();
+});
+
+test("compat: receipt stays 8 segments with an epoch in use", async () => {
+  const { store, service, dream } = dreamSetup();
+  const a = service.saveWithDedupe({ type: "project", title: "旧1", content: "内容A" });
+  const b = service.saveWithDedupe({ type: "project", title: "旧2", content: "内容B" });
+  const ctx = mockCtx({
+    onConsolidation: () => JSON.stringify([
+      { action: "merge", ids: [a.memory.id, b.memory.id], title: "合并", content: "合并内容", importance: 4, keepSource: a.memory.id }
+    ])
+  });
+  const result = await dream.runDream(ctx, service, { policyEpoch: 5 });
+  const run = store.getDreamRun(result.runId);
+  assert.equal(run.receipt.split(":").length, 8, "receipt format unchanged (8 segments)");
+  const parsed = parseReceipt(run.receipt);
+  assert.deepEqual(parsed, {
+    runId: run.id,
+    status: "ok",
+    snapshotHash: run.snapshot_hash.slice(0, 12),
+    inputCount: 2,
+    applied: 1,
+    summaryStored: true
+  }, "receipt round-trips with an epoch in use");
+  store.close();
+});
+
+// ---------------------------------------------------------------- semantic
+
+test("semantic: runs from different epochs stay distinguishable and the newer epoch wins", () => {
+  const store = openMemory();
+  // epoch 1 = old ruling-rule version (historical evidence after upgrade)
+  store.saveDreamRun(run("v1-run", 1, "2026-08-01T00:00:00.000Z"));
+  // epoch 2 = new ruling-rule version
+  store.saveDreamRun(run("v2-run", 2, "2026-08-02T00:00:00.000Z"));
+  assert.equal(store.getDreamRun("v1-run").policy_epoch, 1, "old run keeps its epoch (historical evidence)");
+  assert.equal(store.getDreamRun("v2-run").policy_epoch, 2, "new run keeps its epoch");
+  assert.notEqual(
+    store.getDreamRun("v1-run").policy_epoch,
+    store.getDreamRun("v2-run").policy_epoch,
+    "epochs are distinguishable per run"
+  );
+  assert.equal(store.getLatestPolicyEpoch(), 2, "effective rule version reflects the upgrade");
+  store.close();
+});

package/test/recall-layer.test.js

@@ -0,0 +1,314 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createVectorIndex } from "../src/vector-index.js";
+
+// Mock embedder: every query maps to the fixed vector [1,0,0], so vector recall
+// surfaces any row embedded at [1,0,0] (cosine 1) and excludes orthogonal ones
+// (cosine 0) once the search passes a threshold > 0.
+const embedder = {
+  embedSingle: async () => [1, 0, 0],
+  embed: async () => [1, 0, 0],
+  modelHash: "recall#mock",
+  dimension: 3
+};
+
+// Real store + service wired with the mock embedder and a vector index over the
+// same store (the service's vector path prefers vectorIndex when set).
+function setup() {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const vectorIndex = createVectorIndex({ store });
+  service.setEmbedder(embedder);
+  service.setVectorIndex(vectorIndex);
+  return { store, service, vectorIndex };
+}
+
+function saveMemory(service, vectorIndex, { title, content, embedding }) {
+  const mem = service.saveWithDedupe({ type: "preference", title, content, importance: 5 });
+  if (embedding) vectorIndex.saveEmbedding(mem.memory.id, embedding);
+  return mem.memory;
+}
+
+test("recordRecall=true invokes the recorder once with the full recall scene", async () => {
+  const { service } = setup();
+  const seen = [];
+  service.setRecallRecorder((r) => seen.push(r));
+  saveMemory(service, null, { title: "量子计算", content: "入门" });
+  const rows = await service.searchMemories("量子", { mode: "keyword", topK: 5, threshold: 0.4, recordRecall: true });
+
+  assert.equal(seen.length, 1, "recorder called exactly once");
+  const rec = seen[0];
+  assert.equal(rec.query, "量子");
+  assert.equal(rec.mode, "keyword");
+  assert.equal(rec.topK, 5);
+  assert.equal(rec.threshold, 0.4);
+  assert.ok(typeof rec.createdAt === "string" && rec.createdAt.length > 0, "createdAt is an ISO string");
+  assert.equal(rec.candidates.length, rows.length, "candidates mirror the returned rows");
+});
+
+test("recorded candidates carry id/title/content/score/source and match the return value", async () => {
+  const { service } = setup();
+  const seen = [];
+  service.setRecallRecorder((r) => seen.push(r));
+  const a = saveMemory(service, null, { title: "量子计算入门", content: "叠加态" });
+  const b = saveMemory(service, null, { title: "量子纠缠", content: "贝尔态" });
+  const rows = await service.searchMemories("量子", { mode: "keyword", topK: 5, recordRecall: true });
+
+  const cands = seen[0].candidates;
+  assert.deepEqual(cands.map((c) => c.id), rows.map((r) => r.id), "candidate ids equal returned ids");
+  for (const c of cands) {
+    assert.ok(typeof c.id === "string" && c.id, "id present");
+    assert.ok("title" in c && "content" in c, "title/content present");
+    assert.equal(typeof c.score, "number", "score is numeric");
+    assert.equal(c.source, "keyword", "keyword-mode candidates are marked 'keyword'");
+  }
+  // Exact candidate rows must deep-equal the returned memory rows.
+  const byId = new Map(rows.map((r) => [r.id, r]));
+  for (const c of cands) {
+    const row = byId.get(c.id);
+    assert.equal(c.title, row.title);
+    assert.equal(c.content, row.content);
+    assert.equal(c.score, row.score);
+  }
+  assert.ok(cands.some((c) => c.id === a.id), "first memory recorded");
+  assert.ok(cands.some((c) => c.id === b.id), "second memory recorded");
+});
+
+test("recordRecall defaults to off — recorder is not called", async () => {
+  const { service } = setup();
+  let calls = 0;
+  service.setRecallRecorder(() => calls++);
+  saveMemory(service, null, { title: "量子计算", content: "入门" });
+  await service.searchMemories("量子", { mode: "keyword" });
+  await service.searchMemories("量子", { mode: "keyword", recordRecall: false });
+  assert.equal(calls, 0, "no recorder call when recordRecall is unset or false");
+});
+
+test("recordRecall=true with no recorder installed is safe and returns normally", async () => {
+  const { service } = setup();
+  saveMemory(service, null, { title: "量子计算", content: "入门" });
+  const rows = await service.searchMemories("量子", { mode: "keyword", recordRecall: true });
+  assert.ok(Array.isArray(rows) && rows.length === 1, "search still returns results");
+});
+
+test("a throwing recorder never breaks the search", async () => {
+  const { service } = setup();
+  service.setRecallRecorder(() => { throw new Error("recorder exploded"); });
+  saveMemory(service, null, { title: "量子计算", content: "入门" });
+  const rows = await service.searchMemories("量子", { mode: "keyword", recordRecall: true });
+  assert.equal(rows.length, 1, "search unaffected by recorder failure");
+});
+
+test("an empty result set still records a run with an empty candidate list", async () => {
+  const { service } = setup();
+  const seen = [];
+  service.setRecallRecorder((r) => seen.push(r));
+  const rows = await service.searchMemories("不存在的记忆xyz", { mode: "keyword", recordRecall: true });
+  assert.deepEqual(rows, [], "no matches");
+  assert.equal(seen.length, 1, "receipt emitted even for empty recall");
+  assert.deepEqual(seen[0].candidates, [], "candidates empty");
+});
+
+test("an empty query short-circuits before the recorder", async () => {
+  const { service } = setup();
+  const seen = [];
+  service.setRecallRecorder((r) => seen.push(r));
+  const rows = await service.searchMemories("   ", { mode: "keyword", recordRecall: true });
+  assert.deepEqual(rows, [], "blank query returns nothing");
+  assert.equal(seen.length, 0, "no receipt for blank query");
+});
+
+test("consecutive recordRecall=true searches emit one receipt each", async () => {
+  const { service } = setup();
+  const seen = [];
+  service.setRecallRecorder((r) => seen.push(r));
+  saveMemory(service, null, { title: "量子计算", content: "入门" });
+  await service.searchMemories("量子", { mode: "keyword", recordRecall: true });
+  await service.searchMemories("量子", { mode: "keyword", recordRecall: true });
+  await service.searchMemories("量子", { mode: "keyword", recordRecall: true });
+  assert.equal(seen.length, 3, "no misses, no duplicates");
+});
+
+test("reinstalling a recorder replaces the previous one", async () => {
+  const { service } = setup();
+  const first = [];
+  const second = [];
+  service.setRecallRecorder((r) => first.push(r));
+  service.setRecallRecorder((r) => second.push(r));
+  saveMemory(service, null, { title: "量子计算", content: "入门" });
+  await service.searchMemories("量子", { mode: "keyword", recordRecall: true });
+  assert.equal(first.length, 0, "old recorder dropped");
+  assert.equal(second.length, 1, "new recorder receives the receipt");
+});
+
+test("vector mode marks candidates with source 'vector' (mock embedder)", async () => {
+  const { service, vectorIndex } = setup();
+  const seen = [];
+  service.setRecallRecorder((r) => seen.push(r));
+  saveMemory(service, vectorIndex, { title: "猫", content: "喜欢猫", embedding: [1, 0, 0] });
+  const rows = await service.searchMemories("猫", { mode: "vector", threshold: 0.5, useRerank: false, recordRecall: true });
+  assert.ok(rows.length >= 1, "vector recall hits the embedded row");
+  const cands = seen[0].candidates;
+  for (const c of cands) assert.equal(c.source, "vector", "vector-mode candidate source");
+  assert.ok(cands.every((c) => typeof c.score === "number"), "vector scores numeric");
+});
+
+test("keyword mode marks candidates with source 'keyword' even when an embedder is installed", async () => {
+  const { service, vectorIndex } = setup();
+  const seen = [];
+  service.setRecallRecorder((r) => seen.push(r));
+  saveMemory(service, vectorIndex, { title: "量子计算", content: "入门", embedding: [1, 0, 0] });
+  const rows = await service.searchMemories("量子", { mode: "keyword", useRerank: false, recordRecall: true });
+  assert.ok(rows.length >= 1, "keyword recall hits the literal match");
+  for (const c of seen[0].candidates) assert.equal(c.source, "keyword");
+});
+
+test("hybrid mode marks vector-only / keyword-only / both candidates correctly", async () => {
+  const { service, vectorIndex } = setup();
+  const seen = [];
+  service.setRecallRecorder((r) => seen.push(r));
+  // vector-only: no literal match, embedded exactly at the query vector.
+  const vec = saveMemory(service, vectorIndex, { title: "猫", content: "喜欢猫", embedding: [1, 0, 0] });
+  // keyword-only: literal match, embedding far from [1,0,0] -> excluded by threshold.
+  const kw = saveMemory(service, vectorIndex, { title: "量子计算", content: "入门", embedding: [0, 1, 0] });
+  // both: literal match AND embedded at [1,0,0].
+  const both = saveMemory(service, vectorIndex, { title: "量子计算笔记", content: "量子实践", embedding: [1, 0, 0] });
+
+  await service.searchMemories("量子", { mode: "hybrid", threshold: 0.5, useRerank: false, topK: 10, recordRecall: true });
+  const cands = seen[0].candidates;
+  const byId = new Map(cands.map((c) => [c.id, c]));
+  assert.equal(byId.get(vec.id).source, "vector", "vector-only hit marked 'vector'");
+  assert.equal(byId.get(kw.id).source, "keyword", "keyword-only hit marked 'keyword'");
+  // Shared memory: vector leads the blend, so the merged row keeps the vector mark.
+  assert.equal(byId.get(both.id).source, "vector", "both-path hit marked 'vector'");
+  assert.equal(cands.length, 3, "all three rows in the receipt");
+});
+
+test("rerank overwrites the candidate source to 'rerank'", async () => {
+  const { service } = setup();
+  const seen = [];
+  service.setRecallRecorder((r) => seen.push(r));
+  service.setReranker({
+    rerank: async (q, cands) => cands.map((c, i) => ({ id: c.id, score: i }))
+  });
+  saveMemory(service, null, { title: "量子计算", content: "入门" });
+  await service.searchMemories("量子", { mode: "keyword", recordRecall: true });
+  assert.equal(seen[0].candidates[0].source, "rerank", "reranked candidates are marked 'rerank'");
+});
+
+test("store: saveRecallRun round-trips through getRecallRun with candidates intact", async () => {
+  const store = createStore(":memory:");
+  const cands = [
+    { id: "a", title: "量子计算", content: "入门\n第二行", score: 0.9, source: "vector" },
+    { id: "b", title: "猫", content: "喜欢猫 \"quoted\"", score: null, source: "keyword" }
+  ];
+  const saved = store.saveRecallRun({
+    id: "run-1", query: "量子", mode: "hybrid", topK: 5, threshold: 0.4,
+    candidates: cands, created_at: "2026-08-16T01:00:00.000Z"
+  });
+  assert.equal(saved.id, "run-1", "save returns the persisted run");
+  const got = store.getRecallRun("run-1");
+  assert.equal(got.query, "量子");
+  assert.equal(got.mode, "hybrid");
+  assert.equal(got.topK, 5);
+  assert.equal(got.threshold, 0.4);
+  assert.equal(got.created_at, "2026-08-16T01:00:00.000Z");
+  assert.deepEqual(got.candidates, cands, "candidates JSON survives round-trip");
+});
+
+test("store: getRecallRun returns undefined for a missing id", async () => {
+  const store = createStore(":memory:");
+  assert.equal(store.getRecallRun("nope"), undefined);
+});
+
+test("store: saveRecallRun is idempotent on the run id (replay overwrites)", async () => {
+  const store = createStore(":memory:");
+  store.saveRecallRun({ id: "r", query: "量子", mode: "keyword", topK: 5, candidates: [{ id: "a" }] });
+  store.saveRecallRun({ id: "r", query: "量子", mode: "keyword", topK: 10, candidates: [{ id: "a" }, { id: "b" }] });
+  const runs = store.listRecallRuns();
+  assert.equal(runs.length, 1, "one row for a replayed id");
+  assert.equal(runs[0].topK, 10, "replay overwrites the previous values");
+  assert.equal(runs[0].candidates.length, 2);
+});
+
+test("store: saveRecallRun without an id assigns a unique id per run", async () => {
+  const store = createStore(":memory:");
+  const a = store.saveRecallRun({ query: "q1", mode: "keyword", topK: 5, candidates: [] });
+  const b = store.saveRecallRun({ query: "q2", mode: "keyword", topK: 5, candidates: [] });
+  assert.ok(a.id && b.id && a.id !== b.id, "distinct generated ids");
+  assert.equal(store.listRecallRuns().length, 2, "both persisted, none overwritten");
+});
+
+test("store: listRecallRuns orders by created_at descending", async () => {
+  const store = createStore(":memory:");
+  store.saveRecallRun({ id: "old", query: "旧查询", mode: "keyword", topK: 5, candidates: [], created_at: "2026-08-16T01:00:00.000Z" });
+  store.saveRecallRun({ id: "new", query: "新查询", mode: "vector", topK: 5, candidates: [], created_at: "2026-08-16T03:00:00.000Z" });
+  store.saveRecallRun({ id: "mid", query: "中间", mode: "hybrid", topK: 5, candidates: [], created_at: "2026-08-16T02:00:00.000Z" });
+  const runs = store.listRecallRuns();
+  assert.deepEqual(runs.map((r) => r.id), ["new", "mid", "old"], "newest first");
+});
+
+test("store: listRecallRuns filters by query substring", async () => {
+  const store = createStore(":memory:");
+  store.saveRecallRun({ id: "1", query: "量子计算", mode: "keyword", topK: 5, candidates: [] });
+  store.saveRecallRun({ id: "2", query: "猫咪饲养", mode: "keyword", topK: 5, candidates: [] });
+  store.saveRecallRun({ id: "3", query: "量子纠缠", mode: "keyword", topK: 5, candidates: [] });
+  const runs = store.listRecallRuns({ query: "量子" });
+  assert.deepEqual(runs.map((r) => r.id), ["3", "1"], "only matching queries, newest first");
+});
+
+test("store: listRecallRuns honors limit/offset paging", async () => {
+  const store = createStore(":memory:");
+  for (let i = 0; i < 5; i++) {
+    store.saveRecallRun({ id: `r${i}`, query: `查询${i}`, mode: "keyword", topK: 5, candidates: [], created_at: `2026-08-16T0${i + 1}:00:00.000Z` });
+  }
+  const page = store.listRecallRuns({ limit: 2, offset: 1 });
+  assert.equal(page.length, 2, "page size honored");
+  assert.deepEqual(page.map((r) => r.id), ["r3", "r2"], "ordered desc, offset applied");
+  assert.deepEqual(store.listRecallRuns({ limit: 100, offset: 100 }), [], "offset past the end is empty");
+});
+
+test("e2e: index.js wiring — recordRecall search lands a row listRecallRuns can read back", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  // Simulate src/index.js: the recorder persists each receipt 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
+    });
+  });
+  service.saveWithDedupe({ type: "preference", title: "量子计算入门", content: "叠加态" });
+
+  const rows = await service.searchMemories("量子", { mode: "keyword", topK: 3, recordRecall: true });
+  const runs = store.listRecallRuns();
+  assert.equal(runs.length, 1, "exactly one recall run persisted");
+  const run = runs[0];
+  assert.equal(run.query, "量子");
+  assert.equal(run.mode, "keyword");
+  assert.equal(run.topK, 3);
+  assert.equal(run.threshold, null);
+  assert.deepEqual(run.candidates.map((c) => c.id), rows.map((r) => r.id), "candidates match the response");
+  assert.ok(run.created_at, "timestamp captured");
+  // The receipt is available immediately after the awaited search returns.
+  assert.equal(store.getRecallRun(run.id).query, "量子", "row readable right away");
+});
+
+test("e2e: without recordRecall the recall_runs table gains no rows", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  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
+  }));
+  service.saveWithDedupe({ type: "preference", title: "量子计算入门", content: "叠加态" });
+  await service.searchMemories("量子", { mode: "keyword" });
+  await service.searchMemories("量子", { mode: "keyword", recordRecall: false });
+  assert.deepEqual(store.listRecallRuns(), [], "no rows without recordRecall=true");
+});