@modusensus/dsh-mneme 0.8.6 → 0.8.7

package/src/write-admission.js

@@ -0,0 +1,259 @@
+// #254 写入准入（第一阶段：只计量，不拦截）。
+//
+// 为什么先只计量：会话写入预算的 N 与同话题冷却的 X 在没有真实分布时拍任何数字
+// 都是误杀面（维护者 2026-09-23 拍板「先记录不拦，由遥测定」）。所以这一阶段只把
+// 两个闸门的原始测量点写进 llm_audit_logs（status='skipped'、metadata.gate='g1'
+// 且同话题重复时附 metadata.g2），不做判定、不改任何写入行为；第二阶段把拦截打开
+// 时才引入阈值与二次确认（memory_save({confirm:true})）。
+//
+// 为什么复用 llm_audit_logs：它是仓库既有的「后台动作回执」表（bookkeeping，不
+// 触发写钩子，见 store.js 的表注释）。第二阶段落地时「第一次 skipped/gate →
+// 第二次 confirm:true 放行」在审计里成对出现，因果可回放。
+//
+// 一行一个新建行（不是一行一个信号）：这样「会话内新建条数」就是按 session_key
+// 的直接计数，不需要任何 JSON 解析；g2 命中时作为该行的 metadata.g2 附带，不做第
+// 二行。测量点只取在新行上——并入已有行是去重机制在正常工作，既不进预算也不记行。
+// 会话身份来自工具 exec（scope.js › sessionKeyOf）：没有会话身份的写入（dream /
+// summarize / import / organize）不进预算，预算管的是「一次对话里写飞了」。
+//
+// 穿透口（与 #275 拍板 5 的 pinned 豁免同口径）：constraint / preference 是 #249
+// 第一批立的逐字保真池，永不进预算；仍记一行审计（metadata.exempt='pinned'）以便
+// 观察穿透频率。穿透行既不参与 g2 判定，也不推进同话题的时间基准——它整个不在闸门
+// 里，成为下一次比较的基准会把 g2 的样本混进穿透流量。
+//
+// 内容哈希（exact duplicate，第三类测量点，维护者 2026-09-24 拍板）：归一化口径定在
+// content-hash.js，命中即「同一内容又被写了一次」。判据用哈希而不是相似度——相似度
+// 阈值在同一件事换个说法 / 不同的事共享话题词之间来回挪，只会换一种错法。候选集先按
+// type 与 scope 三维等值收窄再比哈希（不是全表扫），并把归档行一并纳入：「出口止体积、
+// 不止重复」，被质量闸归档的同一个事实不在 saveWithDedupe 的候选集里（store.list 默认
+// 排除归档），同样的内容再写一次就是一条新行，这正是这条信号要量的穿透。两个穿透口与
+// pinned 豁免同口径：pinned 在这里返回得更早，连候选集查询都不发。
+//
+// 信号跟着同一行审计走，所以内容哈希与 g1/g2 覆盖同一批写入（会话内新建行）；无会话
+// 身份的系统写入（dream / summarize / import / organize）要另立行形状，不在本批。
+//
+// 与 llmAudit.enabled 的关系：那个开关同时关掉审计行的启动期清理（index.js 的
+// deleteOldLlmAudits），所以关掉时本模块一行都不写，否则就是在无保留期的表里做
+// 按写入频次增长。
+import { PINNED_MEMORY_TYPES } from "./service.js";
+import { contentHashOf } from "./content-hash.js";
+
+// 审计口径（llm_audit_logs 的既有列）：trigger_source = 组件名，operation_type =
+// 动作名，status='skipped' = 本行没有产生任何 LLM 花费（与 summarize 的间隔门、
+// 尖峰门同款读法）。
+export const ADMISSION_TRIGGER_SOURCE = "writeAdmission";
+export const ADMISSION_OPERATION_TYPE = "write_admission";
+export const ADMISSION_GATE_SESSION_BUDGET = "g1";
+
+// 首次见到某会话时的回填深度：话题表由审计行重建，只回填最近这么多行。更早的
+// 话题会漏（测量口径可接受），换来的是一次查询与有界的常驻内存。
+export const TOPIC_LOOKBACK_ROWS = 200;
+
+// 话题锚只收机械可判的两类：issue/PR 引用与文件路径。两条都带前缀或分隔符，误报
+// 面小；自由文本里看不出确定性的「同话题」，硬判只会把误杀面提前引进来（#254 已
+// 定：计量信号用确定性锚，不用相似度阈值——同一件事换个说法就掉下去，不同的事
+// 共享话题词又顶上来，阈值怎么挪都是在两种误判之间来回）。
+// 两处收紧都来自误报样本：`(?<![#\w])` 挡掉 Markdown 标题 `###1` 与紧跟标识符的
+// 井号；扩展名要求首字符是字母，挡掉 `3.5/2.0` 这类比值（否则一个算式就成了话题）。
+const ISSUE_REF = /(?<![#\w])#\d{1,7}\b/g;
+const FILE_PATH = /(?:[\w.-]+[\\/])+[\w.-]+\.[A-Za-z][A-Za-z0-9]{0,5}\b/g;
+
+/**
+ * 写入文本里的确定性话题锚：小写归一 + 路径分隔符统一为 `/` + 去重 + 排序。
+ * 同一话题在不同轮次必须逐字节相等，才能用等值比较而不是相似度比较——所以
+ * `src\service.js` 与 `src/service.js` 必须归到同一个锚。
+ * @param {{title?: string, content?: string, tags?: string[]}} memory
+ * @returns {string[]} 排序后的话题锚
+ */
+export function extractTopicKeys(memory) {
+  const text = [memory?.title, memory?.content, ...(Array.isArray(memory?.tags) ? memory.tags : [])]
+    .filter((s) => typeof s === "string")
+    .join("\n");
+  const keys = new Set();
+  const add = (raw) => keys.add(raw.toLowerCase().replace(/\\/g, "/"));
+  for (const m of text.matchAll(ISSUE_REF)) add(m[0]);
+  for (const m of text.matchAll(FILE_PATH)) add(m[0]);
+  return [...keys].sort();
+}
+
+/**
+ * 写入准入（#254）。返回的两个方法就是三个消费方共用的那份接口：
+ *   evaluate 给出决策形状（阶段一恒 allow），record 把测量点写成审计行。
+ * 阶段二在 evaluate 里引入阈值与 confirm 分支；#249 的注入提示与 #275 的水位计数
+ * 都读同一份 decision/审计行，而不是各写一套判定。
+ *
+ * @param {object} deps
+ * @param {object} deps.store 存储层（listLlmAudits / saveLlmAudit）
+ * @param {object} [deps.config] 已解析配置（读 llmAudit.enabled）
+ * @param {object} [deps.logger]
+ * @param {() => number} [deps.now] 时钟注入（测试用）
+ */
+export function createWriteAdmission({ store, config, logger, now = Date.now } = {}) {
+  // sessionKey → Map<话题锚, 最近一次新建行时刻(ms)>。真相源是审计行，这里只是它的
+  // 增量视图：进程重启后按需回填。FIFO 上限防长驻进程内存无界（同 store.js 的
+  // embedding 解析缓存口径）。
+  const topicTables = new Map();
+  const SESSION_CACHE_MAX = 200;
+
+  const warn = (msg) => {
+    // 计量是旁路：任何一环失败都不能影响写入，日志自身故障也一样。
+    try {
+      logger?.warn?.(msg);
+    } catch { /* ignore */ }
+  };
+
+  /** 某会话的话题表（首见时从审计行回填，之后走内存增量）。 */
+  function topicTable(sessionKey) {
+    const cached = topicTables.get(sessionKey);
+    if (cached) return cached;
+    const table = new Map();
+    try {
+      const rows = store?.listLlmAudits?.({ sessionKey, limit: TOPIC_LOOKBACK_ROWS }) ?? [];
+      for (const row of rows) {
+        const metadata = row?.metadata;
+        if (!metadata || typeof metadata !== "object" || !Array.isArray(metadata.topics)) continue;
+        // 穿透行（pinned）整个不在闸门里，也就不该进基准表——只挡内存路径不挡回填，
+        // 重启后口径就变了（同一个话题会因为一条穿透行而被判成重复）。
+        if (metadata.exempt) continue;
+        const at = Date.parse(row.timestamp);
+        // 坏时间戳跳过：落到 0 会让 gap 变成几十年，一个离群值就能带偏按分位定的 X。
+        if (!Number.isFinite(at)) continue;
+        for (const topic of metadata.topics) {
+          // 审计行按时间倒序返回，先到的那条就是该话题最近一次写入——后来的不覆盖。
+          if (!table.has(topic)) table.set(topic, at);
+        }
+      }
+    } catch (e) {
+      // 回填失败降级为「本会话此前的话题不可见」：漏一个 g2 测量点，不影响写入。
+      warn(`[dsh-mneme] write admission topic backfill failed: ${String(e)}`);
+    }
+    if (topicTables.size >= SESSION_CACHE_MAX && !topicTables.has(sessionKey)) {
+      topicTables.delete(topicTables.keys().next().value);
+    }
+    topicTables.set(sessionKey, table);
+    return table;
+  }
+
+  /**
+   * 内容哈希候选集查询（#254 第三类测量点）。失败降级为「没命中」：漏一个测量点，
+   * 不影响写入，也不让计量反噬。
+   * 多条命中时的取舍（活区优先）：有活跃/未遗忘的命中就报它（判据是「去重候选集本该
+   * 拦住」），只有归档/遗忘行命中才报它们。store 侧已把活跃行排在窗口头部，这里的 find
+   * 是防御性重复：排序口径将来再变，本判据也不跟着变。
+   * archived 与 forgotten 分开回：两者都是「出口」，但穿透含义不同——只命中已遗忘行时
+   * 若只回 archived=false，读审计的人会以为库里有活跃重复；而 saveWithDedupe 的候选集
+   * 本来就排除遗忘行（store.list 默认 includeForgotten=false），这类命中同样是穿透。
+   * @returns {{memory_id: string, archived: boolean, forgotten: boolean}|null}
+   */
+  function lookupContentDup(memory) {
+    try {
+      const hash = contentHashOf(memory);
+      if (!hash) return null;
+      const hits = store?.findContentHashMatches?.({
+        type: memory?.type,
+        hash,
+        agent_scope: memory?.agent_scope,
+        workspace_scope: memory?.workspace_scope,
+        sensitivity: memory?.sensitivity
+      }) ?? [];
+      const hit = hits.find((h) => !h.archived && !h.forgotten) ?? hits[0];
+      return hit ? { memory_id: hit.id, archived: hit.archived === true, forgotten: hit.forgotten === true } : null;
+    } catch (e) {
+      warn(`[dsh-mneme] write admission content hash lookup failed: ${String(e)}`);
+      return null;
+    }
+  }
+
+  /**
+   * 阶段一决策：恒 allow（本模块里没有阈值），只算出三个闸门的测量点。返回形状一次
+   * 定死，阶段二只往里加分支、不改字段：
+   *   decision — "allow" | "confirm"（阶段一只可能 allow）
+   *   gate     — "g1" | null（null = 这次写入不进预算，不记行）
+   *   topics   — 本次写入的确定性话题锚
+   *   repeat   — {topic, gapMs} | null（g2 的命中面）
+   *   dup      — {memory_id, archived, forgotten} | null（内容哈希的命中面）
+   *   exempt   — null | "pinned"
+   * @param {{memory: object, sessionKey?: string|null}} input
+   */
+  function evaluate({ memory, sessionKey } = {}) {
+    const verdict = { decision: "allow", gate: null, topics: [], repeat: null, dup: null, exempt: null };
+    // 无会话身份 = 系统写入（dream / summarize / import / organize），不进预算。
+    if (!sessionKey) return verdict;
+    // 审计关掉时不记行、也不推进话题表（见文件头：那个开关连启动期清理一起关掉）。
+    if (config?.llmAudit?.enabled === false) return verdict;
+    const topics = extractTopicKeys(memory);
+    const pinned = PINNED_MEMORY_TYPES.has(String(memory?.type ?? ""));
+    if (pinned) return { ...verdict, gate: ADMISSION_GATE_SESSION_BUDGET, topics, exempt: "pinned" };
+    const dup = lookupContentDup(memory);
+    const table = topicTable(sessionKey);
+    const at = now();
+    let repeat = null;
+    for (const topic of topics) {
+      if (!table.has(topic)) continue;
+      const gapMs = Math.max(0, at - table.get(topic));
+      // 同一行可能命中多个锚：取最近的那次（间隔最短＝最有价值的那次重复）。
+      if (!repeat || gapMs < repeat.gapMs) repeat = { topic, gapMs };
+    }
+    return { ...verdict, gate: ADMISSION_GATE_SESSION_BUDGET, topics, repeat, dup };
+  }
+
+  /**
+   * 把测量点落成审计行（一行一个新建行）。三个信号的读法：
+   *   g1 会话写入预算：`GROUP BY session_key` 计数即得「会话内新建条数」分布；要剔
+   *      掉穿透行（pinned 不进预算）就加 `json_extract(metadata,'$.exempt') IS NULL`。
+   *   g2 同话题冷却：`json_extract(metadata,'$.g2.gap_ms')` 即得「同话题新建行间隔」
+   *      分布。间隔算的是同一话题两次**新建行**之间——标题命中走并入的那次不在这里
+   *      （并入正是冷却要做的事，已经做到了）。
+   *   dup 内容哈希：`json_extract(metadata,'$.dup.memory_id')` 非空即「这条新行的内容
+   *      与某条既有行归一化后逐字节相同」；`$.dup.archived` 区分命中那条在活区还是
+   *      归档区——归档区命中就是去重候选集漏掉的那一类穿透。
+   * 计量绝不影响写入：任何异常只 warn。
+   * @returns {object[]} 落下的审计行（无测量点或失败时为空数组）
+   */
+  function record({ sessionKey, verdict, memoryId } = {}) {
+    if (!sessionKey || !verdict || verdict.gate == null) return [];
+    const at = now();
+    const topics = Array.isArray(verdict.topics) ? verdict.topics : [];
+    const rows = [];
+    try {
+      rows.push(store.saveLlmAudit({
+        timestamp: new Date(at).toISOString(),
+        trigger_source: ADMISSION_TRIGGER_SOURCE,
+        operation_type: ADMISSION_OPERATION_TYPE,
+        // 不是模型调用，但该列 NOT NULL——用显式占位串，免得被当成某条路由的
+        // 花费来源统计进去。
+        model_id: "-",
+        status: "skipped",
+        related_memory_ids: memoryId ? [memoryId] : [],
+        session_key: sessionKey,
+        metadata: {
+          gate: verdict.gate,
+          topics,
+          ...(verdict.exempt ? { exempt: verdict.exempt } : {}),
+          ...(verdict.repeat ? { g2: { topic: verdict.repeat.topic, gap_ms: verdict.repeat.gapMs } } : {}),
+          // dup 两个出口分字段落盘：archived 与 forgotten 是两类不同的穿透，合成一个布尔
+          // 会让「只剩遗忘行命中」读起来像「库里有活跃重复」（见 lookupContentDup 注释）。
+          ...(verdict.dup
+            ? { dup: {
+              memory_id: verdict.dup.memory_id,
+              archived: verdict.dup.archived === true,
+              forgotten: verdict.dup.forgotten === true
+            } }
+            : {})
+        }
+      }));
+    } catch (e) {
+      // 审计失败只 warn（同 saveLlmAudit 的调用惯例），写入本身照常完成。
+      warn(`[dsh-mneme] write admission audit failed: ${String(e)}`);
+    }
+    // 只有真正落库、且不是穿透口的行才推进话题表：审计写失败时内存视图不能跑在审计
+    // 前面（重启回填会得到另一条时间线），pinned 写入整个不在闸门里。
+    if (rows.length > 0 && !verdict.exempt) {
+      const table = topicTable(sessionKey);
+      for (const topic of topics) table.set(topic, at);
+    }
+    return rows;
+  }
+
+  return { evaluate, record };
+}

package/test/api.test.js

@@ -1010,6 +1010,18 @@ test("GET /api/dsh-mneme/export markdown feeds straight back through import", as
   const md = res.body;
   assert.ok(md.includes("- **ID**: `" + a.memory.id + "`"), "anchor line present (readHumanEdits-compatible)");
 
+  // 导出是一个文档（#278 审查 F1/F3）：frontmatter 只能有一份并在最前，分节不带
+  // 各自的文件头；而且它的覆盖声明必须与正文条目数一致——「说一套写一套」比没有
+  // 这个字段更糟，外部工具会照着它聚合。
+  assert.equal([...md.matchAll(/^type: /gm)].length, 1, "只有一个 frontmatter 的 type 键");
+  assert.match(md, /^type: memory-export$/m);
+  assert.match(md, /^coverage: all$/m, "导出含归档/已遗忘行，声明要说实话");
+  assert.equal(
+    Number(md.match(/^covered: (\d+)$/m)[1]),
+    (md.match(/^- \*\*ID\*\*: /gm) ?? []).length,
+    "covered 必须等于实际导出的条目数"
+  );
+
   // 黄金用例：导出文本原样导入 → 解析出全部条目，且字段无漂移
   const back = new FakeRes();
   await importRoute.handler(req("/api/dsh-mneme/import", "POST", { type: "preference", markdown: md }), back);

package/test/client.test.js

@@ -25,6 +25,15 @@ test("client bundle is lib-only with no src counterpart", () => {
   assert.equal(existsSync(join(root, "lib/client.js")), true, "lib/client.js must exist");
 });
 
+// 归档侧第五指标（#275）自己按「归档区为空就整段省略」门控，但整卡还有一道 hasData 门：
+// 那道门只认召回回执与活跃僵尸行时，「全归档 + 窗口内无回执」的库会直接 return null，
+// 指标永远不显示（自动评审 #312 指出的回归）。这里锁死 hasData 必须把 archive.total 计进来。
+test("status card: hasData counts the archive metric", () => {
+  const m = clientSource.match(/const hasData =[^;]+;/);
+  assert.ok(m, "the status card must declare hasData");
+  assert.match(m[0], /d\.archive\?\.total/, "hasData must count archive.total, not just runs/active rows");
+});
+
 // The memory entry lives at the sidebar foot, not in the settings modal: the
 // migration must register into `sidebar.footer.action` (the list slot the
 // sidebar shell renders beside Settings) and must not keep a `settings.section`
@@ -208,8 +217,8 @@ test("entry tracks native class, inherits native sizing, and lifts the toolbar d
     "the entry must use the native button width, which reserves its horizontal margins"
   );
   assert.ok(
-    clientSource.includes(".mneme-topentry{display:flex;flex-direction:column}"),
-    "the entry wrapper must stretch the native button within a column flex layout"
+    clientSource.includes(".mneme-topentry{display:flex;flex-direction:column;position:relative}"),
+    "the entry wrapper must stretch the native button within a column flex layout (position:relative hosts the #177 badge)"
   );
   assert.equal(
     clientSource.includes(".mneme-topentry-native .mneme-topentry-label{flex:1;min-width:0;text-align:left;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}"),
@@ -313,6 +322,35 @@ test("graph toggle uses a node-graph glyph, not the share icon", () => {
   );
 });
 
+// #287 跨代图标守卫：primitives 在 0.1.7 把归档图标从「像素后缀」改名成「字重后缀」
+// （IconArchiveOutline20 → …OutlineRegular / …OutlineMedium），旧名不留别名，而
+// peerDependencies 仍同时覆盖 0.1.6 与 0.1.7 两代宿主。只认某一代的名字，另一代就会
+// 把 undefined 交给 h()，落成 slot entry 里的 React #130（该 entry 整块崩），因此必须
+// 探测两代名字、并在全缺时降级为不渲染图标。
+test("#287: archive glyph probes both naming generations and degrades to no glyph", () => {
+  assert.ok(
+    /primitives\.IconArchiveOutline20\s*\?\?\s*primitives\.IconArchiveOutlineRegular\s*\?\?\s*primitives\.IconArchiveOutlineMedium/.test(clientSource),
+    "the glyph must probe the 0.1.6 pixel name before the 0.1.7 weight names"
+  );
+  assert.equal(
+    /h\(IconArchiveOutline20/.test(clientSource),
+    false,
+    "the raw constant must never reach h() — on a host lacking that name it renders undefined (React #130)"
+  );
+  assert.ok(
+    /const renderArchiveIcon = \(props\) => \(IconArchive \? h\(IconArchive, props\) : null\)/.test(clientSource),
+    "the glyph must render through a null-guarded helper so a missing icon degrades to nothing"
+  );
+  for (const site of [
+    "renderArchiveIcon({ size: 15 })",              // 浮层标题栏
+    "renderArchiveIcon({ size: wide ? 16 : 18 })",  // 侧栏 trigger
+    "renderArchiveIcon({ size: wide ? 15 : 18 })",  // portal 到宿主原生侧栏的入口
+    "renderArchiveIcon({ size })"                   // better-sidebar tab 图标
+  ]) {
+    assert.ok(clientSource.includes(site), `every render site must go through the helper: ${site}`);
+  }
+});
+
 // 方案 A：查询收敛。状态页只做仪表盘（小页预览 + 服务端 total + 查看全部），
 // 沉淀/归档的完整浏览走记忆库的 deposited/archived 筛选视图（chip 预置 +
 // 状态页入口跳转），详情抽屉给归档记忆一个反向的「恢复」。
@@ -665,7 +703,7 @@ test("settings feedback card: prefilled issue + mailto + browse, version from /i
   );
   // 2. GitHub 新建 issue：issues/new?title=&body= 预填环境信息（当前仓库无模板）
   assert.ok(
-    clientSource.includes("https://github.com/slow-stack/dsh-mneme/issues/new?title="),
+    clientSource.includes("https://github.com/slow-stack/mneme/issues/new?title="),
     "the issue link must prefill title+body on issues/new"
   );
   assert.ok(
@@ -679,7 +717,7 @@ test("settings feedback card: prefilled issue + mailto + browse, version from /i
   );
   // 4. 浏览已知问题：跳仓库 issues 列表页（去重前置步骤）
   assert.ok(
-    clientSource.includes('href: "https://github.com/slow-stack/dsh-mneme/issues"'),
+    clientSource.includes('href: "https://github.com/slow-stack/mneme/issues"'),
     "the browse link must open the repo issues list"
   );
   // 5. 双语 i18n
@@ -844,8 +882,55 @@ test("a11y: entity graph svg exposes a count summary", () => {
   }
 });
 
-// --- issue #179：注入预览（状态页卡片 + /inject-preview 端点透传的旁路快照） ---
+// --- issue #177：冲突队列交互与视觉重做 ---
 
+// 相似度进度条：只从「相似度 X / similarity X」锚定短语回收数字（防把年份当
+// 相似度），A/B 卡片带侧色类，冻结徽章替代预裁决阶段的「已归档」徽章。
+test("conflict queue: similarity bar, side colors and frozen badge", () => {
+  assert.ok(clientSource.includes("similarityOf(it.reason)"), "reason must be parsed for similarity");
+  assert.ok(clientSource.includes("/(?:相似度|similarity)\\s*([01](?:\\.\\d+)?)/i"), "parse must anchor on the similarity phrase");
+  for (const key of ["memory.status.conflictQueue.similarity", "memory.status.conflictQueue.frozenBadge"]) {
+    const occurrences = clientSource.split(`"${key}"`).length - 1;
+    assert.ok(occurrences >= 2, `i18n key ${key} must exist in both zh and en (got ${occurrences})`);
+  }
+  assert.ok(clientSource.includes('"mneme-conflict-side--a"'), "side A must carry the A color class");
+  assert.ok(clientSource.includes('"mneme-conflict-side--b"'), "side B must carry the B color class");
+  assert.ok(!/s\.archived && h\("span", \{ className: "mneme-badge mneme-badge--archived"/.test(clientSource),
+    "the pre-ruling archived badge must be replaced by the frozen badge");
+  assert.ok(clientSource.includes("mneme-badge--frozen"), "frozen badge class must exist");
+});
+
+// 词级 diff：LCS 对齐是纯函数，锁它的存在、上限护栏与渲染接线（无损性由
+// difftest 独立验证，此处只锁形状）。
+test("conflict queue: word diff is wired with size guards", () => {
+  assert.ok(clientSource.includes("function wordDiff(aText, bText)"), "wordDiff must exist");
+  assert.ok(clientSource.includes("mneme-conflict-mark--del"), "del highlight class must exist");
+  assert.ok(clientSource.includes("mneme-conflict-mark--ins"), "ins highlight class must exist");
+  assert.ok(clientSource.includes("n > 800 || m > 800"), "DP must bail on oversized inputs");
+});
+
+// 空态教育卡：0 冲突时也渲染（原来整块 return null），解释冻结是什么。
+test("conflict queue: empty-state explainer card", () => {
+  assert.ok(!/if \(!items \|\| items\.length === 0\) return null;/.test(clientSource),
+    "empty queue must render the explainer instead of nothing");
+  for (const key of ["memory.status.conflictQueue.emptyTitle", "memory.status.conflictQueue.emptyBody"]) {
+    const occurrences = clientSource.split(`"${key}"`).length - 1;
+    assert.ok(occurrences >= 2, `i18n key ${key} must exist in both zh and en (got ${occurrences})`);
+  }
+});
+
+// 状态卡待处理高亮 + 侧边栏入口 badge（挂 portal 与回退两个按钮）。
+test("conflict queue: actionable status card and sidebar entry badge", () => {
+  assert.ok(clientSource.includes('"mneme-conflict-jump"'), "pending>0 card must carry the highlight class");
+  assert.ok(clientSource.includes("mneme-statuscard--actionable"), "highlight CSS must exist");
+  assert.ok((clientSource.match(/h\(ConflictBadge, \{ pending \}\)/g) || []).length === 2,
+    "badge must be wired into both entry buttons");
+  assert.ok((clientSource.match(/= useConflictBadgeCount\(t\)/g) || []).length === 2,
+    "both entry components must subscribe to the badge count");
+  assert.ok(clientSource.includes('"/api/dsh-mneme/dream-status"'), "badge must reuse the dream-status endpoint");
+});
+
+// --- issue #179：注入预览（状态页卡片 + /inject-preview 端点透传的旁路快照） ---
 test("a11y+preview: inject preview card is wired on the status tab", () => {
   assert.ok(clientSource.includes('"/api/dsh-mneme/inject-preview"'), "card must fetch the preview endpoint");
   assert.ok(clientSource.includes("h(InjectPreviewCard, { t })"), "status grid must render the preview card");

package/test/content-hash.test.js

@@ -0,0 +1,204 @@
+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 { contentHashOf, normalizeForHash } from "../src/content-hash.js";
+
+// #254 内容哈希（写入准入的确定性计量锚）。
+// 这批用例锁三件事：归一化口径（只差格式不算两次）、派生列随内容走（insert/update/
+// CAS 三处都得重算，漏一处标记就在说谎）、以及老库打开时的迁移顺序（索引必须在加列
+// 之后建，否则 exec(SCHEMA) 直接报 no such column，插件整树加载失败）。
+
+test("归一化口径：大小写/空白/标点/全角差异落在同一个键上", () => {
+  assert.equal(normalizeForHash("Hello,  World!\n"), "hello world");
+  assert.equal(normalizeForHash("ｈｅｌｌｏ　ｗｏｒｌｄ"), "hello world", "NFKC 折全角");
+  assert.equal(
+    contentHashOf({ title: "Task A", content: "Line1.\n\nLine2" }),
+    contentHashOf({ title: "task a", content: "line1 line2" })
+  );
+  // 分隔符防拼接歧义：('ab','c') 与 ('a','bc') 不能同键
+  assert.notEqual(contentHashOf({ title: "ab", content: "c" }), contentHashOf({ title: "a", content: "bc" }));
+  assert.notEqual(contentHashOf({ title: "t", content: "同一件事" }), contentHashOf({ title: "t", content: "另一件事" }));
+});
+
+test("归一化口径：同义词与词序不折叠（哈希只认逐字节相同）", () => {
+  assert.notEqual(contentHashOf({ title: "t", content: "a b" }), contentHashOf({ title: "t", content: "b a" }));
+});
+
+test("已知等价类：去标点让 3.5 与 35 同键（口径选择的结果，不是判据出错）", () => {
+  // 这条把「已知会误报」的样子钉住，防止有人把文件头的「命中即精确重复」当承诺、
+  // 进而以为这是个 bug 去改归一化——改口径要带存量重算（见 content-hash.js 文件头）。
+  assert.equal(contentHashOf({ title: "t", content: "版本 3.5" }), contentHashOf({ title: "t", content: "版本 35" }));
+  assert.equal(contentHashOf({ title: "t", content: "a-b" }), contentHashOf({ title: "t", content: "ab" }));
+  // 但数字本身没被折叠：不同数值不落同一键
+  assert.notEqual(contentHashOf({ title: "t", content: "3.5" }), contentHashOf({ title: "t", content: "3.6" }));
+});
+
+test("空标题空正文没有可比内容 → null（不互相匹配成「全是重复」）", () => {
+  assert.equal(contentHashOf({ title: "", content: "" }), null);
+  assert.equal(contentHashOf({ title: "   ", content: "\n\t" }), null);
+  assert.equal(contentHashOf({}), null);
+  assert.ok(contentHashOf({ title: "只有标题" }));
+});
+
+test("save 落 content_hash，findContentHashMatches 按 type + scope 收窄", () => {
+  const store = createStore(":memory:");
+  const a = store.save({ type: "project", title: "同一件事", content: "正文", agent_scope: "A" });
+  assert.equal(a.content_hash, contentHashOf({ title: "同一件事", content: "正文" }));
+
+  const sameScope = store.findContentHashMatches({ type: "project", hash: a.content_hash, agent_scope: "A" });
+  assert.deepEqual(sameScope.map((m) => m.id), [a.id]);
+
+  // 跨 scope 永不互判（与 saveWithDedupe 的三维去重键同口径）
+  const otherScope = store.findContentHashMatches({ type: "project", hash: a.content_hash, agent_scope: "B" });
+  assert.equal(otherScope.length, 0);
+  const unannotated = store.findContentHashMatches({ type: "project", hash: a.content_hash });
+  assert.equal(unannotated.length, 0, "已标注行不与未标注行匹配");
+
+  // 入参先按 store 自己的口径归一，免得调用方传 " A " 就漏配
+  assert.equal(store.findContentHashMatches({ type: "project", hash: a.content_hash, agent_scope: " A " }).length, 1);
+  // type 不同不互判
+  assert.equal(store.findContentHashMatches({ type: "preference", hash: a.content_hash, agent_scope: "A" }).length, 0);
+  store.close();
+});
+
+test("归档行在候选集内（#275 分界：出口止体积、不止重复）", () => {
+  const store = createStore(":memory:");
+  const saved = store.save({ type: "project", title: "被归档的事实", content: "同样的正文" });
+  store.setArchived(saved.id, true);
+  const hits = store.findContentHashMatches({ type: "project", hash: saved.content_hash });
+  assert.deepEqual(hits, [{ id: saved.id, archived: true, forgotten: false }]);
+  store.close();
+});
+
+test("同键命中超过窗口宽度时，活跃行仍在窗口内（归档动作会顶 updated_at）", () => {
+  // 回归（自动评审 #311 store.js:1055）：LIMIT 先于调用方的「活区优先」执行。若只按
+  // updated_at 倒序，第 11 条起写下的归档行会把更早的活跃行挤出窗口，调用方只能看见
+  // 归档命中，把「活跃重复」错记成「归档重复」——正是 dup 信号要分流的两类。
+  const store = createStore(":memory:");
+  const live = store.save({ type: "project", title: "窗口内", content: "同一段正文" });
+  assert.ok(live.content_hash, "写入即落 content_hash");
+  const sinks = [];
+  for (let i = 0; i < 10; i++) {
+    sinks.push(store.save({ type: "project", title: "窗口内", content: "同一段正文" }));
+  }
+  for (const row of sinks) store.setArchived(row.id, true);
+  const hits = store.findContentHashMatches({ type: "project", hash: live.content_hash });
+  assert.equal(hits.length, 10, "窗口宽度不变");
+  assert.deepEqual(hits[0], { id: live.id, archived: false, forgotten: false });
+  store.close();
+});
+
+test("update 与 compareAndUpdate 都重算 content_hash", () => {
+  const store = createStore(":memory:");
+  const saved = store.save({ type: "project", title: "T", content: "旧正文" });
+  assert.equal(store.findContentHashMatches({ type: "project", hash: contentHashOf({ title: "T", content: "旧正文" }) }).length, 1);
+
+  const updated = store.update(saved.id, { content: "新正文" });
+  assert.equal(updated.content_hash, contentHashOf({ title: "T", content: "新正文" }));
+  assert.equal(
+    store.findContentHashMatches({ type: "project", hash: contentHashOf({ title: "T", content: "旧正文" }) }).length,
+    0,
+    "旧内容的锚必须失效"
+  );
+
+  const cas = store.compareAndUpdate(updated.id, updated.updated_at, { title: "T2" });
+  assert.equal(cas.content_hash, contentHashOf({ title: "T2", content: "新正文" }));
+  assert.equal(
+    store.findContentHashMatches({ type: "project", hash: contentHashOf({ title: "T", content: "新正文" }) }).length,
+    0,
+    "CAS 路径漏重算的话标记会指向不再存在的内容"
+  );
+  store.close();
+});
+
+test("demoteToSummary 与 restoreContent 也重算 content_hash", () => {
+  const store = createStore(":memory:");
+  const saved = store.save({ type: "project", title: "T", content: "完整正文" });
+  const demoted = store.demoteToSummary(saved.id, "摘要行");
+  assert.equal(demoted.content_hash, contentHashOf({ title: "T", content: "摘要行" }));
+  assert.equal(
+    store.findContentHashMatches({ type: "project", hash: contentHashOf({ title: "T", content: "完整正文" }) }).length,
+    0,
+    "降级后的行装的是摘要，锚不能还指着完整正文"
+  );
+
+  const restored = store.restoreContent(saved.id);
+  assert.equal(restored.content_hash, contentHashOf({ title: "T", content: "完整正文" }));
+  store.close();
+});
+
+test("老库打开：加列 + 建索引 + 存量回填（索引顺序错会直接开不起来）", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-hash-migrate-"));
+  const dbPath = join(dir, "legacy.db");
+  try {
+    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
+      .prepare(
+        "INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, created_at, updated_at) VALUES (?, ?, ?, ?, '[]', 3, 0, ?, NULL, ?, ?)"
+      )
+      .run("legacy-1", "project", "老库事实", "同一件事的正文", 0, "2026-01-01T00:00:00.000Z", "2026-01-01T00:00:00.000Z");
+    legacy
+      .prepare(
+        "INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, created_at, updated_at) VALUES (?, ?, ?, ?, '[]', 3, 0, ?, NULL, ?, ?)"
+      )
+      .run("legacy-2", "project", "被归档的老事实", "归档区里同一件事的正文", 1, "2026-01-02T00:00:00.000Z", "2026-01-02T00:00:00.000Z");
+    legacy.close();
+
+    const store = createStore(dbPath);
+    const index = store.db
+      .prepare("SELECT name FROM sqlite_master WHERE type='index' AND name='idx_memories_content_hash'")
+      .get();
+    assert.ok(index, "老库也要建上索引（候选集靠它 seek，否则每次写入都是全表扫）");
+
+    // 索引不只是「存在」：回填的 NULL 扫描与准入的候选集查询都得真的走它。列序写反
+    // （type 打头）时前者退化成全表扫——每次打开都要把全部正文读一遍。
+    const planOf = (sql, ...params) =>
+      store.db.prepare(`EXPLAIN QUERY PLAN ${sql}`).all(...params).map((r) => r.detail).join(" | ");
+    assert.match(
+      planOf("SELECT id, title, content FROM memories WHERE content_hash IS NULL"),
+      /idx_memories_content_hash/,
+      "存量回填走索引"
+    );
+    assert.match(
+      planOf("SELECT id FROM memories WHERE type = ? AND content_hash = ?", "project", "x"),
+      /idx_memories_content_hash/,
+      "候选集查询走索引"
+    );
+
+    const backfilled = store.getById("legacy-1");
+    assert.equal(backfilled.content_hash, contentHashOf({ title: "老库事实", content: "同一件事的正文" }));
+    assert.deepEqual(
+      store.findContentHashMatches({ type: "project", hash: backfilled.content_hash }).map((m) => m.id),
+      ["legacy-1"]
+    );
+    const archivedBackfilled = store.getById("legacy-2");
+    assert.deepEqual(
+      store.findContentHashMatches({ type: "project", hash: archivedBackfilled.content_hash }),
+      [{ id: "legacy-2", archived: true, forgotten: false }],
+      "存量归档行回填后也要在候选集里（不然这条信号在老库上量不到归档区）"
+    );
+
+    // 回填后仍能正常写入（幂等迁移没有把表锁死）
+    const fresh = store.save({ type: "project", title: "新行", content: "新正文" });
+    assert.ok(fresh.content_hash);
+    const firstPassHash = archivedBackfilled.content_hash;
+    store.close();
+
+    // 再开一次：只算 NULL 行，已有锚原样保留
+    const again = createStore(dbPath);
+    assert.equal(again.getById("legacy-2").content_hash, firstPassHash, "重复打开不得改写已有锚");
+    again.close();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});