@modusensus/dsh-mneme 0.8.6 → 0.8.7

package/test/maintenance.test.js

@@ -0,0 +1,391 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { execFile, spawnSync } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createSettings } from "../src/settings.js";
+import { createMaintenance } from "../src/maintenance.js";
+import { createStandaloneApi } from "../src/api-standalone.js";
+
+// #275 存储生命周期第一批：无损回收的手动入口。
+// 这一批的验收就三条：dry-run 一个字节都不改（数字与执行出自同一处统计）；执行时只丢
+// 「可由记忆库重建的输入快照」与「检索按定义不可达的归档行向量」，行数不变、决策原文
+// 留住、活跃行向量留住；收益按 VACUUM 前后体积量，不按列字节估。
+
+const NOW = Date.parse("2026-09-24T00:00:00.000Z");
+const DAY = 86400000;
+const CLI = resolve(dirname(fileURLToPath(import.meta.url)), "..", "bin", "cli.mjs");
+// 服务跑在本进程里，所以子进程必须**异步**起：spawnSync 会堵住事件循环，服务就永远
+// 回不了应答，CLI 只会等到自己的 10s 超时（自造死锁）。
+const runCli = promisify(execFile);
+
+function fileStore() {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-reclaim-"));
+  const store = createStore(join(dir, "memory.db"));
+  return {
+    store,
+    // 闭包拿 store，不用 this：裸函数调用下 this 是 undefined，异常一旦被吞掉就会
+    // 变成「库没关就删目录」的 EPERM（清理失败还说不清原因）。
+    close() {
+      try {
+        store.close();
+      } catch { /* already closed */ }
+      rmSync(dir, { recursive: true, force: true });
+    }
+  };
+}
+
+/** 两条 run（窗口外 / 窗口内）+ 一行活跃 + 一行带向量的归档行。 */
+function seed(store) {
+  store.saveDreamRun({
+    id: "old-run",
+    created_at: new Date(NOW - 30 * DAY).toISOString(),
+    status: "ok",
+    snapshot_hash: "h-old",
+    input_count: 2,
+    input: JSON.stringify([{ id: "m1", content: "x".repeat(600) }]),
+    decisions: JSON.stringify([{ action: "keep", ids: ["m1"] }]),
+    receipt: "dsh-mneme:run:old-run:ok:h-old"
+  });
+  store.saveDreamRun({
+    id: "fresh-run",
+    created_at: new Date(NOW - 1 * DAY).toISOString(),
+    status: "ok",
+    snapshot_hash: "h-new",
+    input_count: 1,
+    input: JSON.stringify([{ id: "m2", content: "y".repeat(600) }]),
+    decisions: JSON.stringify([{ action: "keep", ids: ["m2"] }]),
+    receipt: "dsh-mneme:run:fresh-run:ok:h-new"
+  });
+  const active = store.save({ type: "project", title: "活跃", content: "活跃内容" });
+  store.setEmbedding(active.id, [0.125, 0.25, 0.5]);
+  const archived = store.save({ type: "project", title: "归档", content: "归档内容" });
+  store.setEmbedding(archived.id, [0.5, 0.25, 0.125]);
+  store.setArchived(archived.id, true);
+  // organize 的 run：同一列 `input` 存的是 apply 的重放载荷（organize.js 的 apply
+  // 直接读它重建 byIndex），不是可重建的快照——它必须活过任何窗口的回收。
+  store.saveDreamRun({
+    id: "organize-run",
+    created_at: new Date(NOW - 30 * DAY).toISOString(),
+    status: "ok",
+    snapshot_hash: "h-org",
+    input_count: 1,
+    input: JSON.stringify([{ index: 0, candidate: { type: "project", title: "整理候选", content: "候选正文" } }]),
+    decisions: JSON.stringify([{ action: "save", index: 0 }]),
+    receipt: "dsh-mneme:run:organize-run:ok:h-org",
+    run_type: "organize"
+  });
+  return { active, archived };
+}
+
+const rawRun = (store, id) =>
+  store.db.prepare("SELECT input, decisions, receipt, status FROM dream_runs WHERE id = ?").get(id);
+const rawVec = (store, id) =>
+  store.db.prepare("SELECT embedding FROM memories WHERE id = ?").get(id).embedding;
+// count() 默认不含归档行，而「一条记忆都没删」要连归档一起数
+const rawMemoryCount = (store) => store.db.prepare("SELECT count(*) AS c FROM memories").get().c;
+
+function maintenanceFor(store, config = {}) {
+  return createMaintenance({ store, config, logger: null, now: () => NOW });
+}
+
+test("dry-run：报出将清理的行数与列文本大小，一个字节都不改", () => {
+  const { store, close } = fileStore();
+  try {
+    const { archived } = seed(store);
+    const report = maintenanceFor(store).reclaim({ dryRun: true });
+
+    assert.equal(report.dryRun, true);
+    assert.equal(report.olderThanDays, 7, "默认保留窗口 7 天");
+    assert.deepEqual(report.planned, { dream_run_inputs: 1, archived_embeddings: 1 });
+    assert.deepEqual(report.cleared, { dream_run_inputs: 0, archived_embeddings: 0 });
+    assert.ok(report.column_bytes.dream_run_inputs > 600, "列文本大小要给真实数字（它是上界）");
+    assert.equal(typeof report.size.before_bytes, "number");
+    assert.equal(report.vacuum.ran, false);
+
+    assert.ok(rawRun(store, "old-run").input, "dry-run 不得置空 input");
+    assert.ok(rawVec(store, archived.id), "dry-run 不得清向量");
+    assert.equal(store.listLlmAudits().length, 0, "dry-run 不落回执");
+  } finally {
+    close();
+  }
+});
+
+test("执行：只清窗口外的输入快照，run 的骨架与决策原文留住", () => {
+  const { store, close } = fileStore();
+  try {
+    seed(store);
+    const report = maintenanceFor(store).reclaim({ dryRun: false });
+    assert.equal(report.cleared.dream_run_inputs, 1);
+
+    const old = rawRun(store, "old-run");
+    assert.equal(old.input, null, "窗口外的快照置空");
+    assert.equal(old.status, "ok", "状态是骨架，留住");
+    assert.ok(old.decisions, "LLM 决策原文不可重建，留住");
+    assert.ok(old.receipt, "receipt 留住");
+    assert.ok(rawRun(store, "fresh-run").input, "窗口内的快照不动");
+    assert.equal(rawMemoryCount(store), 2, "一条记忆都没删（本入口止体积不止条数）");
+  } finally {
+    close();
+  }
+});
+
+test("执行：清归档行向量、留活跃行向量", () => {
+  const { store, close } = fileStore();
+  try {
+    const { active, archived } = seed(store);
+    const report = maintenanceFor(store).reclaim({ dryRun: false });
+    assert.equal(report.cleared.archived_embeddings, 1);
+    assert.equal(rawVec(store, archived.id), null, "归档行向量按定义不可达，清掉");
+    assert.ok(rawVec(store, active.id), "活跃行向量不许碰");
+  } finally {
+    close();
+  }
+});
+
+test("olderThanDays=0 清掉全部快照；窗口外的行数与 dry-run 报的一致", () => {
+  const { store, close } = fileStore();
+  try {
+    seed(store);
+    const maintenance = maintenanceFor(store);
+    assert.equal(maintenance.reclaim({ dryRun: true }).planned.dream_run_inputs, 1);
+    const report = maintenance.reclaim({ dryRun: false, olderThanDays: 0 });
+    assert.equal(report.cleared.dream_run_inputs, 2, "0 天 = 全部快照");
+    assert.equal(rawRun(store, "fresh-run").input, null);
+    assert.ok(rawRun(store, "fresh-run").decisions, "决策原文仍在");
+  } finally {
+    close();
+  }
+});
+
+test("organize 的 input 是重放载荷，任何窗口都不清（清了 apply 会静默空转）", () => {
+  const { store, close } = fileStore();
+  try {
+    seed(store);
+    const maintenance = maintenanceFor(store);
+    // 窗口 0 = 清全部快照，也必须绕开 organize
+    assert.equal(maintenance.reclaim({ dryRun: true, olderThanDays: 0 }).planned.dream_run_inputs, 2);
+    const report = maintenance.reclaim({ dryRun: false, olderThanDays: 0 });
+    assert.equal(report.cleared.dream_run_inputs, 2, "只清 auto/sleep 的两个 run");
+    assert.ok(rawRun(store, "organize-run").input, "organize 的重放载荷必须留住");
+    assert.ok(rawRun(store, "organize-run").decisions, "决策也留住");
+  } finally {
+    close();
+  }
+});
+
+test("VACUUM 失败不回吞：清理照做、报告与回执都带上失败原因", () => {
+  const { store, close } = fileStore();
+  try {
+    seed(store);
+    // 模拟锁被别的进程占着（SQLITE_BUSY）——这是最常见的失败，且两个 UPDATE 早已各自提交
+    const maintenance = createMaintenance({
+      store: {
+        ...store,
+        dreamRunInputStats: (b) => store.dreamRunInputStats(b),
+        clearDreamRunInputs: (b) => store.clearDreamRunInputs(b),
+        archivedEmbeddingStats: () => store.archivedEmbeddingStats(),
+        clearArchivedEmbeddings: () => store.clearArchivedEmbeddings(),
+        storageStats: () => store.storageStats(),
+        saveLlmAudit: (e) => store.saveLlmAudit(e),
+        vacuum: () => { throw new Error("SQLITE_BUSY: database is locked"); }
+      },
+      config: {},
+      logger: null,
+      now: () => NOW
+    });
+    const report = maintenance.reclaim({ dryRun: false, vacuum: true });
+    assert.equal(report.cleared.dream_run_inputs, 1, "清理已完成");
+    assert.equal(report.vacuum.ran, false);
+    assert.match(report.vacuum.error, /SQLITE_BUSY/);
+    assert.ok(report.receipt, "清掉了东西就必须有回执，哪怕 VACUUM 没跑成");
+    assert.equal(rawRun(store, "old-run").input, null);
+    assert.equal(store.listLlmAudits({ source: "maintenance" }).length, 1);
+  } finally {
+    close();
+  }
+});
+
+test("--vacuum：体积量到真实下降、freelist 归零，库仍可读可写", () => {
+  const { store, close } = fileStore();
+  try {
+    seed(store);
+    // 撑出可回收的体积：VACUUM 的收益按前后体积量，没有真体积就量不到下降
+    store.saveDreamRun({
+      id: "bulk-run",
+      created_at: new Date(NOW - 60 * DAY).toISOString(),
+      status: "ok",
+      snapshot_hash: "h-bulk",
+      input_count: 1,
+      input: JSON.stringify([{ id: "m9", content: "z".repeat(400_000) }]),
+      decisions: "[]",
+      receipt: "dsh-mneme:run:bulk-run:ok:h-bulk"
+    });
+    const before = store.storageStats().fileBytes;
+    const report = maintenanceFor(store).reclaim({ dryRun: false, vacuum: true });
+    assert.equal(report.vacuum.requested, true);
+    assert.equal(report.vacuum.ran, true, report.vacuum.error ?? "");
+    assert.equal(report.size.freelist_pages, 0, "VACUUM 之后没有空闲页");
+    assert.ok(report.size.after_bytes < before, `体积必须真的下降：${before} → ${report.size.after_bytes}`);
+    assert.equal(rawMemoryCount(store), 2);
+    const after = store.save({ type: "project", title: "vacuum 之后", content: "写入照常" });
+    assert.ok(store.getById(after.id), "VACUUM 后库仍可用");
+  } finally {
+    close();
+  }
+});
+
+test("执行落一行回执；llmAudit 关掉时不落回执但清理照做", () => {
+  const on = fileStore();
+  try {
+    seed(on.store);
+    const report = maintenanceFor(on.store).reclaim({ dryRun: false });
+    const rows = on.store.listLlmAudits({ source: "maintenance" });
+    assert.equal(rows.length, 1, "执行留一行 receipt");
+    assert.equal(rows[0].operation_type, "storage_reclaim");
+    assert.equal(rows[0].model_id, "-", "不是模型调用，占位串避免混进花费统计");
+    assert.equal(rows[0].metadata.cleared.dream_run_inputs, 1);
+    assert.equal(rows[0].metadata.vacuum, false);
+    assert.equal(report.receipt, rows[0].id);
+  } finally {
+    on.close();
+  }
+
+  const off = fileStore();
+  try {
+    seed(off.store);
+    const report = maintenanceFor(off.store, { llmAudit: { enabled: false } }).reclaim({ dryRun: false });
+    assert.equal(off.store.listLlmAudits().length, 0, "审计关掉时不落回执");
+    assert.equal(report.cleared.dream_run_inputs, 1, "但清理照做：记不上账不等于没发生");
+  } finally {
+    off.close();
+  }
+});
+
+test("取消归档重新排队嵌入：被回收的向量能拿回来", () => {
+  const { store, close } = fileStore();
+  try {
+    const service = createService({ store, mirror: null, config: {} });
+    const scheduled = [];
+    service.setEmbedder({ ready: true, schedule: (memory) => scheduled.push(memory.id) });
+    const { archived } = seed(store);
+    store.clearArchivedEmbeddings();
+    service.setArchived(archived.id, false);
+    assert.deepEqual(scheduled, [archived.id], "还原时必须重新排队嵌入，否则回收成了单程票");
+
+    // 判据要与 store.setArchived 的归一化同口径（真值）：API/工具传 0 也会把行放回
+    // 活跃面，那条路同样得补嵌入，否则就是「还原了但没有向量」的静默降级。
+    store.setArchived(archived.id, true);
+    service.setArchived(archived.id, 0);
+    assert.deepEqual(scheduled, [archived.id, archived.id]);
+  } finally {
+    close();
+  }
+});
+
+test("HTTP 面：默认 dry-run；带 dryRun:false 但缺 confirm 只回报告不执行", async () => {
+  const { store, close } = fileStore();
+  const maintenance = maintenanceFor(store);
+  const service = createService({ store, mirror: null, config: {} });
+  const settings = createSettings(store.db);
+  const api = createStandaloneApi({ service, store, config: {}, settings, logger: null, port: 0, maintenance });
+  await api.ready;
+  const url = `http://127.0.0.1:${api.port}/maintenance/reclaim`;
+  const post = (body) =>
+    fetch(url, {
+      method: "POST",
+      headers: { authorization: `Bearer ${api.token}`, "content-type": "application/json" },
+      body: JSON.stringify(body)
+    });
+  try {
+    const { archived } = seed(store);
+
+    const dry = await post({});
+    assert.equal(dry.status, 200);
+    const dryBody = await dry.json();
+    assert.equal(dryBody.dryRun, true);
+    assert.equal(dryBody.planned.dream_run_inputs, 1);
+    assert.ok(rawVec(store, archived.id), "不带 body 的默认路径不改数据");
+
+    const refused = await post({ dryRun: false, vacuum: true });
+    assert.equal(refused.status, 400);
+    const refusedBody = await refused.json();
+    assert.equal(refusedBody.error, "confirm-required");
+    assert.equal(refusedBody.report.planned.archived_embeddings, 1, "拒绝执行时把 dry-run 报告一并回给调用方");
+    assert.equal(refusedBody.report.vacuum.requested, true, "报告必须描述将要执行的那个动作（含 vacuum）");
+    assert.ok(rawVec(store, archived.id), "缺 confirm 时一个字节都不改");
+
+    const applied = await post({ dryRun: false, confirm: true });
+    assert.equal(applied.status, 200);
+    const appliedBody = await applied.json();
+    assert.equal(appliedBody.cleared.dream_run_inputs, 1);
+    assert.equal(appliedBody.cleared.archived_embeddings, 1);
+    assert.equal(rawVec(store, archived.id), null);
+
+    const badDays = await post({ olderThanDays: -1 });
+    assert.equal(badDays.status, 400, "非法窗口给干净 400，不落进 SQL");
+    assert.equal((await badDays.json()).error, "invalid-older-than-days");
+
+    // `Number()` 会把 ""/[]/false 化成 0，而 0 在这里是「清全部快照」：最坏解释绝不
+    // 能让畸形输入静默拿到，HTTP 面只收 JSON 数字
+    for (const bogus of ["", [], false]) {
+      const bad = await post({ olderThanDays: bogus });
+      assert.equal(bad.status, 400, `畸形窗口必须拒：${JSON.stringify(bogus)}`);
+      assert.equal((await bad.json()).error, "invalid-older-than-days");
+    }
+  } finally {
+    api.server.closeIdleConnections?.();
+    api.server.close();
+    close();
+  }
+});
+
+// CLI 那一层是用户真正敲的东西（`dsh-mneme reclaim`），参数语义错一步就是「以为在
+// dry-run 却动了数据」这类事故，所以起真服务、真 spawn 它。
+
+test("CLI：reclaim 默认 dry-run 报数字，--apply --vacuum 才真收", async () => {
+  const { store, close } = fileStore();
+  const maintenance = maintenanceFor(store);
+  const service = createService({ store, mirror: null, config: {} });
+  const settings = createSettings(store.db);
+  const api = createStandaloneApi({ service, store, config: {}, settings, logger: null, port: 0, maintenance });
+  await api.ready;
+  const auth = [`--url`, `http://127.0.0.1:${api.port}`, `--token`, api.token];
+  const run = async (args) => {
+    const { stdout, stderr } = await runCli(process.execPath, [CLI, ...args], { encoding: "utf8" });
+    return { stdout, stderr };
+  };
+  try {
+    const { archived } = seed(store);
+
+    const dryRun = await run(["reclaim", ...auth]);
+    assert.match(dryRun.stdout, /dry-run，未改动任何数据/);
+    assert.match(dryRun.stdout, /将清理: dream_runs\.input 1 行 \/ 归档行向量 1 行/);
+    assert.ok(rawVec(store, archived.id), "默认路径不得动数据");
+
+    const apply = await run(["reclaim", "--apply", "--vacuum", ...auth]);
+    assert.match(apply.stdout, /已执行/);
+    assert.match(apply.stdout, /已清理: dream_runs\.input 1 行 \/ 归档行向量 1 行/);
+    assert.match(apply.stdout, /回执: llm_audit_logs #\d+/);
+    assert.equal(rawVec(store, archived.id), null);
+    assert.equal(rawRun(store, "old-run").input, null);
+
+    const asJson = await run(["reclaim", "--json", ...auth]);
+    assert.equal(JSON.parse(asJson.stdout).dryRun, true);
+  } finally {
+    api.server.closeIdleConnections?.();
+    api.server.close();
+    close();
+  }
+});
+
+test("CLI：--vacuum 单独用会被拒（dry-run 没有可回收的页），也不动数据", () => {
+  const result = spawnSync(process.execPath, [CLI, "reclaim", "--vacuum", "--token", "x"], { encoding: "utf8" });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /--vacuum 需要配 --apply/);
+});

package/test/mirror-types.test.js

@@ -0,0 +1,208 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, existsSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MIRROR_EXCLUDED_TYPES, MIRROR_READONLY_TYPES, TYPE_FILE, createMirror, parseHumanEdits, renderMirrorText } from "../src/mirror.js";
+import { createStore, TYPES } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { PACKAGE_VERSION } from "../src/version-check.js";
+
+// #278 第一批：落盘盲区。TYPE_FILE 原先只有 5 个键，pitfall / constraint /
+// rejected_solution / pattern 这些后加的 type 从不进镜像与导出——落点存在，但对
+// 一半活跃记忆是盲的，且没有任何提示。#296 第二批把 document 也收了进来（只读
+// 指针视图），排除集因此为空；两个集合的边界仍由下面的双向断言钉住。
+const FORMERLY_UNCOVERED = ["pitfall", "constraint", "rejected_solution", "pattern"];
+
+function tempDir() {
+  return mkdtempSync(join(tmpdir(), "dsh-mneme-types-"));
+}
+
+function memory(type, over = {}) {
+  return {
+    id: "m1", type, title: "标题", content: "内容", tags: ["a"], importance: 3,
+    forgotten: false, created_at: "2026-01-01T00:00:00.000Z",
+    updated_at: "2026-01-01T00:00:00.000Z", ...over
+  };
+}
+
+test("#278: every store type has a landing point except the pinned exclusions", () => {
+  const missing = [...TYPES].filter((t) => !TYPE_FILE[t] && !MIRROR_EXCLUDED_TYPES.has(t));
+  assert.deepEqual(missing, [], "新增 type 必须显式决定落不落镜像，不能留下静默盲区");
+  assert.deepEqual(Object.keys(TYPE_FILE).filter((t) => !TYPES.has(t)), [], "TYPE_FILE 不得含 store 不认识的键");
+  assert.deepEqual([...MIRROR_EXCLUDED_TYPES].filter((t) => !TYPES.has(t)), [], "排除集里的 key 必须是真 type");
+  // 双向：注释说的「TYPES \ TYPE_FILE 恰好等于排除集」要真被钉住。只查上面两条
+  // 的话，将来有人把 document 加进 TYPE_FILE 却忘了从排除集删，两边同时变假还全绿。
+  assert.deepEqual([...MIRROR_EXCLUDED_TYPES].filter((t) => TYPE_FILE[t]), [], "排除集与落盘集不得重叠");
+  for (const type of FORMERLY_UNCOVERED) {
+    assert.ok(TYPE_FILE[type], `${type} 必须有镜像文件（#278 第一批验收项）`);
+  }
+});
+
+test("#278: an entry of a formerly uncovered type survives render → parse round-trip", () => {
+  const text = renderMirrorText("pitfall", [memory("pitfall")]);
+  const [edit] = parseHumanEdits(text);
+  assert.equal(edit.id, "m1");
+  assert.equal(edit.title, "标题");
+  assert.equal(edit.content, "内容", "frontmatter 与元数据行都不得进 content");
+  assert.equal(edit.updated_at, "2026-01-01T00:00:00.000Z");
+});
+
+test("#278: file header carries type / covered / coverage / tags union", () => {
+  const text = renderMirrorText("constraint", [
+    memory("constraint", { id: "m2", tags: ["z", "a"], updated_at: "2026-02-01T00:00:00.000Z" }),
+    memory("constraint", { id: "m1", tags: ["a", "m"] })
+  ]);
+  assert.ok(text.startsWith("---\n"), "frontmatter 必须在文件最前");
+  const fm = text.slice(4, text.indexOf("\n---", 3));
+  assert.match(fm, /^type: constraint$/m);
+  // OKF §7 actor 约定：<producer>/<version>，不是裸的 producer 名
+  assert.equal(fm.match(/^generated\.by: (.+)$/m)?.[1], `dsh-mneme/${PACKAGE_VERSION}`);
+  assert.match(fm, /^generated\.at: \d{4}-\d{2}-\d{2}T/m);
+  assert.match(fm, /^covered: 2$/m);
+  assert.match(fm, /^coverage: active-only$/m);
+  assert.match(fm, /^tags: \["a", "m", "z"\]$/m);
+  // frontmatter 不是条目、也不改条目数
+  assert.equal(parseHumanEdits(text).length, 2);
+});
+
+test("#278/#296: mirror writes the formerly uncovered files, and documents land as a pointer view", () => {
+  const dir = tempDir();
+  try {
+    const mirror = createMirror(dir);
+    const rows = FORMERLY_UNCOVERED.map((type, i) => memory(type, { id: `m${i}`, content: `内容${i}` }));
+    rows.push(memory("document", {
+      id: "doc1", title: "报告", content: "第一句。第二句不该出现。", doc_path: "C:/docs/report.md"
+    }));
+    mirror.sync(rows);
+    for (const [i, type] of FORMERLY_UNCOVERED.entries()) {
+      const file = join(dir, TYPE_FILE[type]);
+      assert.ok(existsSync(file), `${TYPE_FILE[type]} 必须落盘`);
+      const [edit] = parseHumanEdits(readFileSync(file, "utf8"));
+      assert.equal(edit.id, `m${i}`);
+      assert.equal(edit.content, `内容${i}`);
+    }
+    // #296 第 4 条：document 落盘，但只给指针行——id + 标题 + 摘要首句 + 路径，
+    // 不含正文；文件头必须说清这是只读视图（不能复用「可编辑」那句）。
+    assert.ok(MIRROR_READONLY_TYPES.has("document"), "document 是只读 type");
+    assert.ok(existsSync(join(dir, "documents.md")), "document 指针行现在落盘");
+    const docs = readFileSync(join(dir, "documents.md"), "utf8");
+    assert.match(docs, /只读视图/);
+    assert.ok(docs.includes("doc1") && docs.includes("报告") && docs.includes("第一句"));
+    assert.ok(docs.includes("report.md"), "指针行必须给出 doc_path，否则「看着完整、其实找不到文件」的老问题原样回来");
+    assert.ok(!docs.includes("第二句"), "只读视图不含全文，只留摘要首句");
+    assert.equal(parseHumanEdits(docs).length, 0, "指针行不是可回填的条目");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("#296: readHumanEdits never returns the read-only type — a hand-edited view cannot reach the store", () => {
+  const dir = tempDir();
+  try {
+    const mirror = createMirror(dir);
+    mirror.sync([memory("document", { id: "doc1", doc_path: "/tmp/report.md" })]);
+    // 模拟有人在 documents.md 里手改（视图是机器所有，改动必须被忽略而不是回填）
+    const file = join(dir, TYPE_FILE.document);
+    writeFileSync(file, readFileSync(file, "utf8") + "- **ID**: `doc1`\n- **类型**: document\n被人改过的正文\n", "utf8");
+    assert.deepEqual(mirror.readHumanEdits("document"), [], "指定的只读 type 也要跳过");
+    assert.deepEqual(mirror.readHumanEdits().filter((e) => e.id === "doc1"), [], "全量扫描同样跳过它");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("#278: mirror covers every active row — no silent 500-row truncation", () => {
+  const dir = tempDir();
+  let store;
+  try {
+    store = createStore(join(dir, "memory.db"));
+    const service = createService({ store, mirror: createMirror(dir), config: {} });
+    for (let i = 0; i < 501; i++) store.save({ type: "pitfall", title: `t${i}`, content: `c${i}` });
+    // 任意一次业务写触发一次镜像同步（不是逐条 save，避免 501 次渲染）
+    service.saveWithDedupe({ type: "pattern", title: "trigger", content: "x" });
+    const text = readFileSync(join(dir, TYPE_FILE.pitfall), "utf8");
+    assert.match(text, /^covered: 501$/m, "文件头必须如实自述覆盖条数");
+    assert.equal((text.match(/^- \*\*ID\*\*: /gm) ?? []).length, 501, "超过 500 条的活跃集必须全部落盘");
+    assert.equal(parseHumanEdits(text).length, 501);
+  } finally {
+    // close 必须在 rm 之前：Windows 上库文件仍被打开时 rmSync 会 EPERM，把断言
+    // 失败覆盖成文件锁错误。
+    store?.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("#278: scope / sensitivity 只作展示字段，且永不进 content", () => {
+  const text = renderMirrorText("constraint", [memory("constraint", {
+    agent_scope: "standard",
+    workspace_scope: "D:/WorkSpace/demo",
+    sensitivity: "personal"
+  })]);
+  assert.match(text, /^- \*\*作用域\*\*: standard \/ D:\/WorkSpace\/demo$/m);
+  assert.match(text, /^- \*\*敏感度\*\*: personal$/m);
+  assert.equal(parseHumanEdits(text)[0].content, "内容", "新字段不得进 content");
+  // 没值的条目不该多出空字段行（本机 2843 条里只有 37 条带 scope 标签）
+  const bare = renderMirrorText("constraint", [memory("constraint")]);
+  assert.ok(!bare.includes("作用域") && !bare.includes("敏感度"));
+  // 值是调用方传的任意字符串：里面的换行不得伪造出第二个条目头
+  const injected = renderMirrorText("constraint", [memory("constraint", {
+    sensitivity: "x\n- **ID**: `ghost`\n- **类型**: decision"
+  })]);
+  assert.equal(parseHumanEdits(injected).length, 1, "值里的换行不得造出幽灵条目");
+  // 值本身仍在（被压成一行），关键是它不再位于行首——行首才是条目头的锚
+  assert.ok(!/^- \*\*ID\*\*: `ghost`/m.test(injected), "不得出现伪造的条目头");
+});
+
+test("#278: mirror keeps its active-only claim — archived and forgotten rows stay out", () => {
+  const dir = tempDir();
+  let store;
+  try {
+    store = createStore(join(dir, "memory.db"));
+    const service = createService({ store, mirror: createMirror(dir), config: {} });
+    // forgotten 在 INSERT 里硬编码为 0（store.js insertMemoryRow），只能经 setForget
+    // 设置；archived 可以在载荷里给，这里统一走 setter 保持同一个路径。
+    for (const [id, title] of [["keep-c", "留"], ["arch-c", "归档"], ["gone-c", "遗忘"]]) {
+      store.save({ id, type: "constraint", title, content: "c" });
+    }
+    store.setArchived("arch-c", true);
+    store.setForget("gone-c", true);
+    service.saveWithDedupe({ type: "pattern", title: "trigger", content: "x" });
+    const text = readFileSync(join(dir, TYPE_FILE.constraint), "utf8");
+    // 文件头写 coverage: active-only，正文就必须只有活跃行——说一套写一套比没有
+    // 这个字段更糟（外部工具照着聚合）。
+    assert.match(text, /^covered: 1$/m, "覆盖条数只数活跃行");
+    assert.ok(text.includes("keep-c"));
+    assert.ok(!text.includes("arch-c"), "归档行不进镜像");
+    assert.ok(!text.includes("gone-c"), "遗忘行不进镜像");
+  } finally {
+    store?.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("#278: re-syncing unchanged content does not rewrite the file", () => {
+  const dir = tempDir();
+  try {
+    const mirror = createMirror(dir);
+    const rows = [memory("pitfall"), memory("constraint", { id: "m2" })];
+    mirror.sync(rows);
+    const first = readFileSync(join(dir, TYPE_FILE.pitfall), "utf8");
+    const firstAt = first.match(/^generated\.at: (.+)$/m)[1];
+    // generated.at 每次渲染都是新时间戳：无脑落盘会让编辑器、同步盘与 git 在每次
+    // 业务写后都看到全部镜像「被外部修改」，而内容一字未变。
+    mirror.sync(rows);
+    const second = readFileSync(join(dir, TYPE_FILE.pitfall), "utf8");
+    assert.equal(second, first, "内容未变的文件不得被重写");
+    assert.equal(second.match(/^generated\.at: (.+)$/m)[1], firstAt, "未变时保留原时间戳");
+    // 内容真变了必须落盘
+    mirror.sync([memory("pitfall", { content: "改了" })]);
+    const third = readFileSync(join(dir, TYPE_FILE.pitfall), "utf8");
+    assert.notEqual(third, second);
+    assert.ok(third.includes("改了"));
+    // 顺手确认「空 type 删文件」这条防复活行为没被上面的跳过逻辑带坏
+    assert.ok(!existsSync(join(dir, TYPE_FILE.constraint)), "该 type 没行时文件要删掉");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/test/recall-evals.test.js

@@ -233,3 +233,21 @@ test("production search never writes recall_evals, even with the switch on", asy
   assert.deepEqual(store.listRecallEvals(), [], "recall_evals stays untouched by production search");
   store.close();
 });
+
+// ---------------------------------------------------------------- per-source signals in receipt
+
+test("recall receipt: candidates carry per-source signals for offline fusion-weight profiling", async () => {
+  const { store, service } = setup({});
+  const captured = [];
+  service.setRecallRecorder((recall) => captured.push(recall));
+  saveMemory(service, "量子计算入门", "叠加态");
+  const rows = await service.searchMemories("量子", { mode: "hybrid", recordRecall: true });
+  assert.ok(rows.length >= 1, "search returned results");
+  assert.equal(captured.length, 1, "exactly one receipt");
+  for (const c of captured[0].candidates) {
+    assert.ok(c.signals && typeof c.signals === "object", "every candidate carries a signals object");
+    assert.ok("keyword" in c.signals, "raw keyword score present (pre-fusion, unweighted)");
+    assert.ok(!("final" in c.signals), "raw signals only — the fused score already lives in c.score");
+  }
+  store.close();
+});