@modusensus/dsh-mneme 0.8.15 → 0.9.0

package/test/session-usage.test.js

@@ -0,0 +1,308 @@
+/**
+ * 会话日志使用证据（src/session-usage.js）的回归测试。
+ *
+ * 本文件锁的重点是**两类「静默少一大截」的坑**（都真踩过）：
+ *   ① **zstd 多帧**：`zlib.zstdDecompressSync(buf)` 只解**第一帧**且不报错——实测一个
+ *      1.5 MB 的会话文件只解出 291 字节，于是扫描得出「零命中」的假结论。所以这里用
+ *      **两帧拼接的夹具**钉死「两帧都要解出来」。
+ *   ② **参数在 `arguments` 且是 JSON 字符串**：取 `parameters` 会得到 null，看着像
+ *      「调用了但没记参数」。夹具按真实形态写。
+ *
+ * 另外钉住状态推导的语义边界：`candidate` 是「现存日志里没记录」，不是「从未使用」。
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import zlib from "node:zlib";
+
+import {
+  forEachFrame,
+  toolCallsInLine,
+  identifyCapability,
+  deriveUsageState,
+  collectUsage,
+  summarizeUsage,
+  resolveSessionDir,
+  findSessionFiles,
+  STALE_AFTER_DAYS
+} from "../src/session-usage.js";
+
+const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+
+/** 把若干段文本各压成一帧再拼起来，模拟真实的多帧文件。 */
+function multiFrameBuffer(chunks) {
+  return Buffer.concat(chunks.map((c) => zlib.zstdCompressSync(Buffer.from(c, "utf8"))));
+}
+
+/** 造一行真实的 tool-call 记录（参数是 JSON 字符串，不是对象）。 */
+function toolCallLine({ name, args, turn = 1, time = 1700000000000 }) {
+  const item = { type: "tool-call", id: `call_${Math.random().toString(36).slice(2)}`, name };
+  if (args !== undefined) item.arguments = JSON.stringify(args);
+  return JSON.stringify({
+    type: "assistant/message",
+    time,
+    data: { turn, step: 1, message: { role: "assistant", content: [item] } }
+  });
+}
+
+/** 造一个会话目录，内容按给定数组写进一个文件。 */
+function makeSessionDir(lines) {
+  const base = mkdtempSync(join(tmpdir(), "mneme-usage-"));
+  const sessionId = "session-test-0001";
+  const dir = join(base, "sessions", `--work-${sessionId.slice(0, 8)}--`, sessionId);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "session.v4.jsonl.zstd"), multiFrameBuffer(lines), "utf8");
+  return { base, dir: join(base, "sessions"), cleanup: () => rmSync(base, { recursive: true, force: true }) };
+}
+
+test("多帧 zstd：**每一帧**都要解出来（只解第一帧是踩过的坑）", () => {
+  const buf = multiFrameBuffer(["第一帧的内容", "第二帧的内容", "第三帧的内容"]);
+  const seen = [];
+  const stat = forEachFrame(buf, (text) => seen.push(text));
+  assert.deepEqual(seen, ["第一帧的内容", "第二帧的内容", "第三帧的内容"], "三帧都要被回调到");
+  assert.equal(stat.frames, 3);
+  assert.equal(stat.failed, 0);
+  // 反证：证明这个夹具真能暴露「只解第一帧」——直接 zstdDecompressSync 只能拿到第一段
+  assert.equal(zlib.zstdDecompressSync(buf).toString("utf8"), "第一帧的内容");
+});
+
+test("多帧 zstd：每帧都解；截断产生的**半行**由 jsonl 层丢掉（宁可少一条，不要错一条）", () => {
+  // 真实的「坏帧」不是帧头损坏，而是**文件正在写**：末帧被截断。
+  // 实测结论（写这条时验过）：zstd 是流式格式，截断帧会**解出部分文本而不抛错**，
+  // 且 Node 的绑定不暴露「还有多少输入未消费」，所以帧层的完整性判不了。
+  // 兜底放在**行层**：半行 JSON 解析失败会被丢弃——代价是少一条记录，收益是绝不误用。
+  const good = zlib.zstdCompressSync(Buffer.from("完整帧的内容", "utf8"));
+
+  // 帧层：两帧都要回调到（这是最初踩的坑——只解第一帧）
+  const seen = [];
+  const stat = forEachFrame(Buffer.concat([good, good]), (t) => seen.push(t));
+  assert.equal(stat.frames, 2);
+  assert.equal(seen.length, 2);
+
+  // 行层兜底：一个被截断的 tool-call 行不能被当完整记录用
+  const fullLine = toolCallLine({ name: "skill", args: { name: "agent-reach" } });
+  assert.equal(toolCallsInLine(fullLine).length, 1, "完整行要解析出来");
+  const halfLine = fullLine.slice(0, Math.floor(fullLine.length / 2));
+  assert.deepEqual(toolCallsInLine(halfLine), [], "半行必须被丢掉，不能猜出一个不完整的调用");
+
+  // 真实截断文件：整帧 + 半帧 → 完整的那些记录照常统计，半行被丢
+  const base = mkdtempSync(join(tmpdir(), "mneme-usage-trunc-"));
+  try {
+    const sessionId = "session-trunc-0001";
+    const dir = join(base, "sessions", "work", sessionId);
+    mkdirSync(dir, { recursive: true });
+    const truncated = zlib.zstdCompressSync(Buffer.from(fullLine, "utf8")).subarray(0, 12);
+    writeFileSync(join(dir, "session.v4.jsonl.zstd"), Buffer.concat([good, truncated]));
+    const c = collectUsage({ sessionDir: join(base, "sessions") });
+    assert.equal(c.scannedFiles, 1);
+    // 好帧里没有 tool-call，截断帧里的调用不完整 → 一条都不该被记
+    assert.equal(c.skillCalls, 0, "截断的半行不能被算成一次调用");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("tool-call 解析：参数在 arguments 且是 JSON 字符串", () => {
+  // 真实形态：{"type":"tool-call","name":"skill","arguments":"{\"name\":\"agent-reach\"}"}
+  const line = toolCallLine({ name: "skill", args: { name: "agent-reach" }, turn: 7, time: 1792000000000 });
+  const calls = toolCallsInLine(line);
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].name, "skill");
+  assert.equal(calls[0].args.name, "agent-reach", "arguments 要二次解析成对象");
+  assert.equal(calls[0].turn, 7);
+  assert.equal(calls[0].time, 1792000000000);
+});
+
+test("tool-call 解析：坏 JSON、非 tool-call 行、参数缺失都要能分清", () => {
+  assert.deepEqual(toolCallsInLine("{ 这不是 JSON"), []);
+  assert.deepEqual(toolCallsInLine(JSON.stringify({ type: "user/message" })), []);
+  // 参数缺失：**调用本身要保留**（它确实发生过），只是 args 为 null
+  const noArgs = toolCallLine({ name: "skill" });
+  const calls = toolCallsInLine(noArgs);
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].args, null);
+});
+
+test("能力识别：skill 取 arguments.name；MCP 取 mcp__<server>__<tool> 的 server 段", () => {
+  assert.deepEqual(identifyCapability({ name: "skill", args: { name: "agent-reach" } }), {
+    kind: "skill",
+    name: "agent-reach"
+  });
+  const mcp = identifyCapability({ name: "mcp__github__get_file_contents", args: {} });
+  assert.equal(mcp.kind, "mcp");
+  assert.equal(mcp.name, "github", "MCP 按 server 聚合（清单里的条目是 server 粒度）");
+  assert.equal(mcp.tool, "get_file_contents");
+  // 内置工具不是能力清单里的东西 → null（丢掉，不计 unmatched）
+  assert.equal(identifyCapability({ name: "read", args: {} }), null);
+  assert.equal(identifyCapability({ name: "pwsh", args: {} }), null);
+  // skill 没记 name → 返回 name:null，让上层计入 unmatched（如实报，不硬凑）
+  assert.deepEqual(identifyCapability({ name: "skill", args: {} }), { kind: "skill", name: null });
+  // mcp__ 后面 server 段为空同理
+  assert.equal(identifyCapability({ name: "mcp____x", args: {} }).name, null);
+});
+
+test("状态推导：没记录=candidate、用过=trusted、久未用=stale", () => {
+  const now = Date.parse("2026-10-16T00:00:00Z");
+  assert.equal(deriveUsageState(null, { now }), "candidate");
+  assert.equal(deriveUsageState({ uses: 0, lastUsedAt: null }, { now }), "candidate", "0 次也算没记录");
+  // 30 天前用过 → trusted
+  assert.equal(deriveUsageState({ uses: 3, lastUsedAt: now - 30 * 86400000 }, { now }), "trusted");
+  // 超过阈值 → stale
+  assert.equal(deriveUsageState({ uses: 3, lastUsedAt: now - (STALE_AFTER_DAYS + 1) * 86400000 }, { now }), "stale");
+  // 恰好在阈值上不算 stale（边界）
+  assert.equal(deriveUsageState({ uses: 3, lastUsedAt: now - STALE_AFTER_DAYS * 86400000 }, { now }), "trusted");
+  // 没有时间戳但有次数 → 不能判 stale，保守给 trusted
+  assert.equal(deriveUsageState({ uses: 1, lastUsedAt: null }, { now }), "trusted");
+});
+
+test("整条链路：从会话文件聚合出技能与 MCP 计数", () => {
+  const ctx = makeSessionDir([
+    toolCallLine({ name: "skill", args: { name: "agent-reach" }, turn: 1, time: 1792000000000 }),
+    toolCallLine({ name: "mcp__github__get_file_contents", args: {}, turn: 1 }),
+    toolCallLine({ name: "skill", args: { name: "agent-reach" }, turn: 2, time: 1792050000000 }),
+    toolCallLine({ name: "skill", args: { name: "euthyna" }, turn: 3 }),
+    toolCallLine({ name: "read", args: { path: "x" }, turn: 3 }), // 内置，忽略
+    toolCallLine({ name: "skill", args: {}, turn: 4 }) // 缺 name → unmatched
+  ]);
+  try {
+    const c = collectUsage({ sessionDir: ctx.dir });
+    assert.equal(c.present, true);
+    assert.equal(c.scannedFiles, 1);
+    assert.equal(c.skillCalls, 3, "两次 agent-reach + 一次 euthyna");
+    assert.equal(c.mcpCalls, 1);
+    assert.equal(c.unmatched, 1, "缺 name 的那次要对不上，不能静默丢");
+    assert.equal(c.skills.get("agent-reach").uses, 2);
+    // 最近一次使用要取最大的那个时间戳
+    assert.equal(c.skills.get("agent-reach").lastUsedAt, 1792050000000);
+    assert.equal(c.mcp.get("github").uses, 1);
+  } finally {
+    ctx.cleanup();
+  }
+});
+
+test("降级：会话目录不存在时如实报 present=false，不抛错不编造", () => {
+  const base = mkdtempSync(join(tmpdir(), "mneme-usage-none-"));
+  try {
+    const c = collectUsage({ sessionDir: join(base, "no-such-dir") });
+    assert.equal(c.present, false);
+    assert.equal(c.scannedFiles, 0);
+    assert.equal(c.skillCalls, 0);
+    assert.deepEqual([...c.skills.keys()], []);
+    const s = summarizeUsage(c);
+    assert.deepEqual(s.skills, []);
+    assert.deepEqual(s.mcp, []);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("会话目录默认值由 dshHome 推导，不写死本机路径", () => {
+  const dir = resolveSessionDir({ dshHome: "/custom/dsh" });
+  assert.ok(dir.includes("sessions"), "默认落在 sessions 子目录");
+  assert.ok(!/[A-Za-z]:\\Users/i.test(dir), "不得出现本机盘符路径");
+  // 环境变量优先
+  assert.ok(resolveSessionDir({ dshHome: join(tmpdir(), "x") }).includes("x"));
+});
+
+test("文件发现：**所有版本**的会话文件都要收（只认 v4 会漏掉一半历史）", () => {
+  // 实测回归：本机同一会话树下并存三种格式——v4（219）、v3（218）、无版本号（72）。
+  // 早期版本只认 `session.v4`，静默漏掉 50 次技能调用（euthyna 44 次），
+  // 导致三个明明用过的技能被报成 candidate。所以只要求「以 session 开头」。
+  const base = mkdtempSync(join(tmpdir(), "mneme-usage-find-"));
+  try {
+    const sessions = join(base, "sessions");
+    mkdirSync(join(sessions, "a", "id1"), { recursive: true });
+    mkdirSync(join(sessions, "b", "id2"), { recursive: true });
+    writeFileSync(join(sessions, "a", "id1", "session.v4.jsonl.zstd"), multiFrameBuffer(["x"]));
+    writeFileSync(join(sessions, "b", "id2", "session.v3.jsonl.zstd"), multiFrameBuffer(["y"]));
+    writeFileSync(join(sessions, "b", "id2", "session.jsonl.zstd"), multiFrameBuffer(["z"]));
+    writeFileSync(join(sessions, "a", "id1", "other.jsonl"), "不该被收");
+    const found = findSessionFiles(sessions);
+    assert.equal(found.files.length, 3, "v4 / v3 / 无版本号三种都要找到，other.jsonl 不要");
+    assert.equal(found.unreadable.length, 0);
+    assert.equal(found.present, true);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("文件上限可注入，且截断要留痕（CodeRabbit 抓到的静默截断）", () => {
+  // 实测回归：早期版本把上限写死在遍历里（MAX_SESSION_FILES=2000），于是
+  //   · 调用方传 maxFiles: 5000 也只拿到 2000 个——参数无效，无从察觉；
+  //   · 截断发生在内层，外层算不出 truncated（`found.files.length > maxFiles` 永假）。
+  // 结果就是「只扫了一部分」却看起来像扫全了——本仓库反复防的那类静默错。
+  const base = mkdtempSync(join(tmpdir(), "mneme-usage-cap-"));
+  try {
+    const sessions = join(base, "sessions");
+    // 造 12 个会话文件，限 5 个：应拿到 5 个 + truncated=true
+    for (let i = 0; i < 12; i++) {
+      const d = join(sessions, `s${String(i).padStart(2, "0")}`);
+      mkdirSync(d, { recursive: true });
+      writeFileSync(join(d, "session.v4.jsonl.zstd"), multiFrameBuffer([`line${i}`]));
+    }
+
+    // ① limit 真的生效（不是被内层写死的上限压住）
+    const capped = findSessionFiles(sessions, { limit: 5 });
+    assert.equal(capped.files.length, 5, "limit=5 就该只拿 5 个");
+    assert.equal(capped.truncated, true, "被截断必须留痕");
+
+    // ② 不设限时全拿到，且不报截断
+    const all = findSessionFiles(sessions);
+    assert.equal(all.files.length, 12);
+    assert.equal(all.truncated, false, "没截断就不该报截断");
+
+    // ③ collectUsage 透传：maxFiles 生效，且 truncated 透出来
+    const c = collectUsage({ sessionDir: sessions, maxFiles: 5 });
+    assert.equal(c.scannedFiles, 5);
+    assert.equal(c.truncated, true, "collectUsage 要把截断标记透出来");
+    assert.equal(c.totalFiles, 5, "totalFiles 是被限制后的数量（不是磁盘总数）");
+
+    // ④ 给足够大的 maxFiles 时能扫全（旧实现这里会失败：内层卡 2000）
+    const c2 = collectUsage({ sessionDir: sessions, maxFiles: 9999 });
+    assert.equal(c2.scannedFiles, 12);
+    assert.equal(c2.truncated, false);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("目录不可读要与「空目录」**可分辨**（不许同形）", () => {
+  // 实测回归：早期版本用 existsSync 定 present、readdirSync 失败直接 return，
+  // 于是 ACL 拒绝的目录产出与「可读空目录」逐字段相同的读数
+  // （present=true, scannedFiles=0, unreadable=[]），清单侧 175 条全 candidate。
+  // 这正是本仓库反复防的那类错：读不到被显示成「读到但没有」。
+  const base = mkdtempSync(join(tmpdir(), "mneme-usage-unreadable-"));
+  try {
+    // ① 不存在的目录：present=false
+    const missing = findSessionFiles(join(base, "nope"));
+    assert.equal(missing.present, false);
+    assert.equal(missing.files.length, 0);
+
+    // ② 存在的空目录：present=true、无 unreadable
+    const empty = join(base, "empty");
+    mkdirSync(empty, { recursive: true });
+    const emptyRes = findSessionFiles(empty);
+    assert.equal(emptyRes.present, true);
+    assert.equal(emptyRes.files.length, 0);
+    assert.equal(emptyRes.unreadable.length, 0, "空目录不该有 unreadable");
+
+    // ③ 悬空符号链接：present=true，但**必须有 unreadable**，与空目录不同形
+    try {
+      symlinkSync(join(base, "no-such-target"), join(empty, "session.dangling.jsonl.zstd"), "junction");
+    } catch (error) {
+      if (error.code === "EPERM" || error.code === "EACCES") return; // 无权限则跳过本断言
+      throw error;
+    }
+    const dangling = findSessionFiles(empty);
+    assert.ok(dangling.unreadable.length > 0, "读不到的项必须留痕，否则与空目录同形");
+    // 而且上层能区分：collectUsage 的 readable 会变 false
+    const c = collectUsage({ sessionDir: empty });
+    assert.equal(c.present, true);
+    assert.equal(c.readable, false, "有读不动的项时 readable 必须为 false");
+    assert.ok(c.unreadable.length > 0, "unreadable 要透到 collectUsage");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/test/settings.test.js

@@ -182,6 +182,8 @@ test("feature flags accept the new boolean, string, url and enum keys", () => {
   settings.setFeatureFlags({
     "memoryQualityFilter.enabled": false,
     "llmAudit.enabled": false,
+    "distillRecords.enabled": false,
+    "distillRecords.retentionDays": 30,
     bm25SearchEnabled: false,
     conflictFreezeEnabled: true,
     trustEpistemicWeighting: true,
@@ -196,6 +198,9 @@ test("feature flags accept the new boolean, string, url and enum keys", () => {
   const flags = settings.getFeatureFlags();
   assert.equal(flags["memoryQualityFilter.enabled"], false, "nested keys stored flat");
   assert.equal(flags["llmAudit.enabled"], false);
+  // #399：布尔与整数范围两类键都要能过白名单（retentionDays 是 natural 1..3650）
+  assert.equal(flags["distillRecords.enabled"], false);
+  assert.equal(flags["distillRecords.retentionDays"], 30);
   assert.equal(flags.bm25SearchEnabled, false);
   assert.equal(flags.conflictFreezeEnabled, true);
   assert.equal(flags.trustEpistemicWeighting, true);
@@ -215,6 +220,9 @@ test("nested feature flag keys are validated as booleans and rejected otherwise"
   const { store, settings } = setup();
   assert.throws(() => settings.setFeatureFlags({ "memoryQualityFilter.enabled": "yes" }), /memoryQualityFilter\.enabled/);
   assert.throws(() => settings.setFeatureFlags({ "llmAudit.enabled": 1 }), /llmAudit\.enabled/);
+  assert.throws(() => settings.setFeatureFlags({ "distillRecords.enabled": 1 }), /distillRecords\.enabled/);
+  // 范围外的整数也要被挡（retentionDays 上限 3650）
+  assert.throws(() => settings.setFeatureFlags({ "distillRecords.retentionDays": 0 }), /distillRecords\.retentionDays/);
   assert.deepEqual(settings.getFeatureFlags(), {}, "failed writes persist nothing");
   store.close();
 });

package/test/store-write-path-columns.test.js

@@ -0,0 +1,191 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, writeFileSync, existsSync, 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 { createMirror } from "../src/mirror.js";
+
+// 回归（issue #430）：写路径上的全表物化。此前每一次业务写都要走两处
+// all() + 逐行 toRow（27 字段 + 三次 JSON.parse）：
+//   1. 质量过滤的近重复判定只要最近 20 条 content，却先物化整库再 slice(0,20)
+//      （5k 行实测 100ms 级 → 本批换成单列有界查询后 0.06ms 级）；
+//   2. syncMirror 先物化整库再逐行 filter 掉 archived/forgotten/document。
+// 本批修复：store 新增单列有界读 recentContents()；list() 两条分支的 SELECT *
+// 换成显式列清单（memoryColumns，排除 embedding）；syncMirror 改走 list 的无界
+// 档 + SQL 侧过滤。下面四条锁不测墙钟（CI 矩阵 ubuntu+windows × node 22/24 并行，
+// 计时断言不稳），锁的是「谁被物化」这个形状本身。
+
+function make(over = {}) {
+  const store = createStore(":memory:");
+  return { store, config: { memoryQualityFilter: { enabled: true }, ...over } };
+}
+
+test("#430: recentContents mirrors the all() prefix it replaced", () => {
+  const { store } = make();
+  for (let i = 0; i < 25; i += 1) {
+    store.save({ type: "project", title: `t${i}`, content: `c${i}`, importance: 3 });
+  }
+  // 旧写法：all().slice(0, 20).map((m) => m.content ?? "")。集合锁与逐位锁都要：
+  // 一旦把 ORDER BY 丢掉（或反向），只要 LIMIT 不低于表行数，取到的行一个不少、
+  // 只是顺序全反过来，集合锁抓不到这类回归（变异检验证实，见 PR 讨论）。
+  // 逐位比较在此安全：store.js 的 per-instance 单调时间戳守卫保证同一实例内
+  // updated_at 严格递增，故这几行的先后关系是确定的。
+  const expected = store.all().slice(0, 20).map((m) => m.content ?? "");
+  const actual = store.recentContents(20);
+  assert.equal(actual.length, 20);
+  assert.deepEqual(actual, expected, "same 20 contents in the same order as the old prefix");
+  assert.deepEqual([...actual].sort(), [...expected].sort(), "same 20 contents as the old prefix (order-agnostic backstop)");
+  assert.equal(store.recentContents().length, 20, "default limit is 20");
+  assert.equal(store.recentContents(3).length, 3);
+  // sanitizePage 口径：0 / 负数 / 非整数落回默认值，而不是 SQLite 里 LIMIT 无界
+  assert.equal(store.recentContents(0).length, 20, "limit 0 falls back to the default, never unbounded");
+  assert.equal(store.recentContents(-1).length, 20);
+  assert.equal(store.recentContents(undefined).length, 20);
+  // 口径与 all() 一致：不过滤 archived（近重复判定要连归档内容一起看）
+  const { id } = store.save({ type: "project", title: "旧", content: "归档正文", importance: 3 });
+  store.setArchived(id, true);
+  assert.ok(store.recentContents(20).includes("归档正文"), "archived rows still take part in near-duplicate detection");
+  // 空库不炸
+  const fresh = createStore(":memory:");
+  assert.deepEqual(fresh.recentContents(20), []);
+  store.close();
+  fresh.close();
+});
+
+test("#430: list() projects columns and never leaks embedding", () => {
+  const { store } = make();
+  const { id } = store.save({ type: "project", title: "带向量", content: "正文", importance: 3 });
+  store.setEmbedding(id, [1, 0, 0]);
+  for (const opts of [{ limit: 50 }, { limit: null }, { order: "chrono", limit: 10 }, { type: "project", limit: null }]) {
+    const rows = store.list(opts);
+    assert.ok(rows.length > 0, `list(${JSON.stringify(opts)}) returned rows`);
+    for (const row of rows) {
+      assert.equal("embedding" in row, false, `embedding never leaks into list rows (${JSON.stringify(opts)})`);
+      assert.equal(typeof row.content, "string", "content still projected");
+    }
+  }
+  store.close();
+});
+
+test("#430: the write path reads explicit, bounded columns (no SELECT *, no embedding)", () => {
+  const { store } = make();
+  store.save({ type: "project", title: "带向量", content: "正文", importance: 3 });
+  // 语句级探针（不测墙钟）：SELECT * 会把全表最重的 embedding 列拖进内存再被
+  // toRow 丢掉，且无界档实测 5k 行 263ms → 117ms。这里直接看发出去的 SQL——
+  // 将来谁把列投影改回 SELECT *（或手工把 embedding 加回清单），本锁立刻转红，
+  // 而「行里没有 embedding」那条锁抓不到这种回归（toRow 本就不输出向量）。
+  const seen = [];
+  const orig = store.db.prepare.bind(store.db);
+  store.db.prepare = (sql) => { seen.push(String(sql)); return orig(sql); };
+  const listSql = seen.length;
+  store.list({ limit: 50 });
+  store.list({ limit: null });
+  store.list({ type: "project", limit: 10, order: "chrono" });
+  const probed = seen.length - listSql;
+  assert.ok(probed >= 3, `expected three distinct list queries, saw ${probed}`);
+  for (const sql of seen) {
+    assert.ok(!/SELECT\s+\*/i.test(sql), `write path must project explicit columns: ${sql}`);
+    assert.ok(!/\bembedding\b/.test(sql), `write path must not read the embedding column: ${sql}`);
+  }
+  // 质量过滤那条单列读同样要探：它一旦退回 SELECT *，多读的正是全表最重的列。
+  seen.length = 0;
+  store.recentContents(20);
+  assert.equal(seen.length, 1, "recentContents issues exactly one query");
+  assert.ok(!/SELECT\s+\*/i.test(seen[0]), `recentContents must read one column: ${seen[0]}`);
+  assert.ok(!/\bembedding\b/.test(seen[0]), "recentContents must not read the embedding column");
+  assert.match(seen[0], /\bLIMIT\b/i, `recentContents must stay bounded: ${seen[0]}`);
+  store.close();
+});
+
+test("#430: quality filter reads recent contents without materializing the table", () => {
+  const { store, config } = make();
+  // 抛错探针（先例 audit.test.js:182、mirror-dirty.test.js:383）：写路径一旦再退回
+  // all()，本用例立刻失败，而不是等到某个 profile 上再被观测到。
+  store.all = () => { throw new Error("write path must not materialize the whole table"); };
+  const service = createService({ store, mirror: null, config });
+  const base = "今天下午去操场跑步三圈然后回来洗澡";
+  const first = service.saveWithDedupe({ type: "history", title: "记录A", content: base });
+  assert.equal(first.action, "created");
+  const second = service.saveWithDedupe({ type: "history", title: "记录B", content: `${base}${base}${base}` });
+  const row = store.getById(second.memory.id);
+  assert.equal(row.archived, true, "near-duplicate still archived");
+  assert.ok(row.tags.includes("low_quality"), "low_quality tag still added");
+  assert.ok(row.quality_score < 30, `score still below the archive threshold: ${row.quality_score}`);
+});
+
+test("#430: syncMirror covers the active set without materializing it", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-430-"));
+  try {
+    const { store, config } = make();
+    const mirror = createMirror(dir);
+    // 先按正常路径写一次，把镜像文件建起来
+    const seed = createService({ store, mirror, config });
+    const a = store.save({ type: "project", title: "活跃项目", content: "项目正文", importance: 3 });
+    store.save({ type: "preference", title: "偏好", content: "偏好正文", importance: 3 });
+    const hidden = store.save({ type: "project", title: "归档项目", content: "归档正文", importance: 3 });
+    store.setArchived(hidden.id, true);
+    const held = store.save({ type: "project", title: "遗忘项目", content: "遗忘正文", importance: 3 });
+    store.setForget(held.id, true);
+    seed.saveWithDedupe({ type: "project", title: "触发同步", content: "第一次触发同步的正文，长度足够不触发短内容规则", importance: 3 });
+
+    // 写路径不得再出现全表物化
+    store.all = () => { throw new Error("syncMirror must not materialize the whole table"); };
+    const svc = createService({ store, mirror, config });
+    const res = svc.saveWithDedupe({ type: "project", title: "第二次触发", content: "第二次触发同步的正文，内容与上一句不同以免被判近重复", importance: 3 });
+    assert.equal(res.action, "created");
+    assert.equal(res.memory.archived, false, "quality filter left it active (mirror only renders active rows)");
+
+    const text = readFileSync(join(dir, "projects.md"), "utf8");
+    assert.ok(text.includes(a.id), "active row still rendered");
+    assert.ok(text.includes(res.memory.id), "new row still rendered");
+    assert.ok(!text.includes("归档项目"), "archived row stays out");
+    assert.ok(!text.includes("遗忘项目"), "forgotten row stays out");
+    assert.ok(readFileSync(join(dir, "preferences.md"), "utf8").includes("偏好正文"), "sibling type rendered");
+    store.close();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("#430: the document gate is decided in SQL, before anything is rendered", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-430-doc-"));
+  try {
+    const { store, config } = make({ memoryQualityFilter: { enabled: true }, documentMemoryEnabled: false });
+    const mirror = createMirror(dir);
+    const svc = createService({ store, mirror, config });
+    // 真 document 行：doc_path 只能经 store.saveDocument 铸造（通用 save 整类拒绝）。
+    // 这条用例必须让库里真的有 document 行——上一版用例库里一行都没有，
+    // 「闸关时不渲染 document」就无法与「根本没见过 document」区分（变异检验漏网）。
+    const doc = store.saveDocument({
+      type: "document",
+      title: "指针文档",
+      content: "文档摘要正文，长度足够",
+      doc_path: "docs/pointer.md",
+      importance: 3
+    });
+    svc.saveWithDedupe({ type: "project", title: "项目", content: "项目正文，长度足够绕开短内容归档规则", importance: 3 });
+    const docPath = mirror.filePath("document");
+    // 闸关（#296 第二批默认）：有真指针行也不许渲染出 documents.md
+    assert.equal(existsSync(docPath), false, "documents.md stays absent while the gate is off");
+    // 陈旧视图必须被删掉：不留一个「看着还在、其实已关」的视图
+    writeFileSync(docPath, "陈旧视图", "utf8");
+    svc.saveWithDedupe({ type: "project", title: "再写一条", content: "再写一条正文，与上一条正文互不相似", importance: 3 });
+    assert.equal(existsSync(docPath), false, "stale documents.md pruned while the gate is off");
+    assert.equal(existsSync(join(dir, "index.md")), false, "index.md pruned while the gate is off");
+    assert.ok(readFileSync(join(dir, "projects.md"), "utf8").includes("项目正文"), "sibling type still rendered");
+    // 反向：闸开时同一份指针行确实会渲染（证明上面那条断言有判别力，而不是
+    // 因为 document 行从没进入过渲染集），关回去再必须删掉。
+    config.documentMemoryEnabled = true;
+    svc.saveWithDedupe({ type: "project", title: "闸开", content: "闸开后的正文，与前面几条互不相似", importance: 3 });
+    assert.ok(existsSync(docPath), "documents.md rendered while the gate is on");
+    assert.ok(readFileSync(docPath, "utf8").includes(doc.id), "pointer row is what gets rendered");
+    config.documentMemoryEnabled = false;
+    svc.saveWithDedupe({ type: "project", title: "闸关回去", content: "闸关回去后的正文，同样互不相似", importance: 3 });
+    assert.equal(existsSync(docPath), false, "documents.md pruned again once the gate flips back off");
+    store.close();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/test/store.test.js

@@ -213,6 +213,114 @@ test("search excludes archived by default", () => {
   store.close();
 });
 
+// ============================ #275 第二批：archived_at 精确归档时刻
+
+test("schema migration adds archived_at column to legacy database", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-migrate-at-"));
+  const dbPath = join(dir, "legacy.db");
+  try {
+    // 存量库：有 archived 标志位，但没有 archived_at（#275 第一批时代的库）
+    const legacy = new DatabaseSync(dbPath);
+    legacy.exec(`CREATE TABLE memories (
+      id TEXT PRIMARY KEY, type TEXT NOT NULL, title TEXT NOT NULL, content TEXT NOT NULL,
+      tags TEXT NOT NULL DEFAULT '[]', importance INTEGER NOT NULL DEFAULT 3,
+      forgotten INTEGER NOT NULL DEFAULT 0, archived INTEGER NOT NULL DEFAULT 0,
+      source TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+    );`);
+    legacy.exec(`INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, created_at, updated_at)
+      VALUES ('old1', 'history', 't', 'c', '[]', 3, 0, 1, NULL, '2026-01-01T00:00:00.000Z', '2026-01-02T00:00:00.000Z');`);
+    legacy.close();
+
+    const store = createStore(dbPath);
+    const cols = store.db.prepare("PRAGMA table_info(memories)").all().map((c) => c.name);
+    assert.ok(cols.includes("archived_at"), "archived_at column added");
+    // 存量归档行零重写：不回填 updated_at（那等于把被推翻的代理口径固化进列里）
+    const raw = store.db.prepare("SELECT archived_at FROM memories WHERE id = 'old1'").get();
+    assert.equal(raw.archived_at, null, "legacy archived row keeps NULL, not backfilled from updated_at");
+    assert.equal(store.getById("old1").archived_at, undefined, "NULL 读作 undefined，调用方须显式处理");
+    store.close();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("archived_at migration is idempotent: reopening the upgraded database is a no-op", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-migrate-at2-"));
+  const dbPath = join(dir, "upgraded.db");
+  try {
+    const first = createStore(dbPath);
+    const m = first.save({ type: "history", title: "t", content: "c" });
+    first.setArchived(m.id, true);
+    const stamp = first.getById(m.id).archived_at;
+    first.close();
+
+    // 再开一次：addColumn 先 PRAGMA 后 ALTER，不该报错、不该重建、不该动已有值
+    const second = createStore(dbPath);
+    const cols = second.db.prepare("PRAGMA table_info(memories)").all().filter((c) => c.name === "archived_at");
+    assert.equal(cols.length, 1, "列只存在一份，没被重复 ALTER");
+    assert.equal(second.getById(m.id).archived_at, stamp, "重开不动已落盘的归档时刻");
+    second.close();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("setArchived stamps archived_at on archive, clears it on restore", () => {
+  const store = openMemory();
+  const saved = store.save({ type: "project", title: "t", content: "c", importance: 3 });
+  assert.equal(saved.archived_at, undefined, "新建行未归档 → 无时刻");
+
+  const archived = store.setArchived(saved.id, true);
+  assert.equal(archived.archived, true);
+  assert.ok(archived.archived_at, "活跃 → 归档落时刻");
+  assert.ok(
+    Math.abs(Date.parse(archived.archived_at) - Date.now()) < 5000,
+    "落的是当下时刻，不是别的行的 updated_at"
+  );
+
+  const restored = store.setArchived(saved.id, false);
+  assert.equal(restored.archived, false);
+  assert.equal(restored.archived_at, undefined, "取消归档清空");
+  store.close();
+});
+
+test("setArchived keeps updated_at semantics (existing readers depend on it)", () => {
+  // archived_at 是新增列，不是 updated_at 的替代品：面板排序、快照哈希、CAS 都读
+  // updated_at，本函数自 v0.2 起就无条件刷它——改口径不得顺手改掉这条既有语义。
+  const store = openMemory();
+  const saved = store.save({ type: "project", title: "t", content: "c", importance: 3 });
+  const before = store.getById(saved.id).updated_at;
+  const archived = store.setArchived(saved.id, true);
+  assert.ok(Date.parse(archived.updated_at) >= Date.parse(before), "updated_at 照旧被刷");
+  const again = store.setArchived(saved.id, false);
+  assert.ok(Date.parse(again.updated_at) >= Date.parse(archived.updated_at), "取消归档也刷");
+  store.close();
+});
+
+test("save with archived:true stamps archived_at at insert time", () => {
+  // 铸造即归档的行：archived=1 而 archived_at=NULL 会落进「存量行」语义，读侧只能
+  // 当它时刻不可追溯——明明是当下发生的归档，白丢一条记录。
+  const store = openMemory();
+  const born = store.save({ type: "history", title: "生来就归档", content: "c", archived: true });
+  assert.equal(born.archived, true);
+  assert.ok(born.archived_at, "入库即归档 → 归档时刻 = 入库时刻");
+  assert.equal(born.archived_at, born.created_at, "两列同源（同一个 nowIso）");
+
+  const live = store.save({ type: "history", title: "活跃", content: "c" });
+  assert.equal(live.archived_at, undefined);
+  store.close();
+});
+
+test("update() cannot set archived_at (archived is not an updatable field)", () => {
+  // 归档时刻只能由 setArchived 落。若 update 的 patch 能写它，就等于给精确口径开了
+  // 一个绕过 setArchived 语义（幂等 / 清空）的后门，代理口径会从缝里长回来。
+  const store = openMemory();
+  const saved = store.save({ type: "history", title: "t", content: "c" });
+  store.update(saved.id, { archived_at: "2020-01-01T00:00:00.000Z", content: "改过" });
+  assert.equal(store.getById(saved.id).archived_at, undefined, "patch 里的 archived_at 被忽略");
+  store.close();
+});
+
 // --- vector search ---
 
 test("save/update persist embedding vector and searchVector ranks by cosine", () => {