@modusensus/dsh-mneme 0.8.5 → 0.8.7

package/src/mirror.js

@@ -2,17 +2,37 @@ import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from "node
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { STR, langOf } from "./lang.js";
+import { PACKAGE_VERSION } from "./version-check.js";
 
 export const TYPE_FILE = {
   preference: "preferences.md",
   project: "projects.md",
   decision: "decisions.md",
   history: "history.md",
-  summary: "summary.md"
+  summary: "summary.md",
+  pitfall: "pitfalls.md",
+  constraint: "constraints.md",
+  rejected_solution: "rejected-solutions.md",
+  pattern: "patterns.md",
+  document: "documents.md"
 };
 
+// 不落镜像的 type。现在是空集：document 由 #296 第二批收进来——第一版排除它的
+// 理由是「镜像块渲染的字段里没有 doc_path，落一个 documents.md 会得到看着完整、
+// 其实找不到文件的视图」，doc_path 进指针行以后这条理由不再成立。这个集合由
+// test/mirror-types.test.js 钉死（TYPES \ TYPE_FILE 必须恰好等于本集合）：将来
+// 新增 type 时必须显式决定它落不落镜像，静默漏掉才是 #278 要修的那种盲区。
+export const MIRROR_EXCLUDED_TYPES = new Set([]);
+
+// 只读视图（#296）：document 的镜像只有指针行（id + 标题 + 摘要首句 + doc_path），
+// 没有可编辑的正文，所以它不参与 readHumanEdits 的人改合并，手工改动一律被下次
+// 同步覆盖；导出/导入也不带它（那两个是 round-trip 通道，见 api.js）。
+export const MIRROR_READONLY_TYPES = new Set(["document"]);
+
 const ESCAPE = /([\\`*_[\]{}()#+.!|>~-])/g;
 const UNESCAPE = new RegExp("\\\\" + ESCAPE.source, "g");
+// 只读视图里摘要首句的字符上限（#296）：够定位就行，长摘要不该把一行撑成一段。
+const POINTER_MAX = 120;
 
 function esc(text) {
   return String(text).replace(ESCAPE, "\\$1");
@@ -22,6 +42,36 @@ function unescape(text) {
   return String(text).replace(UNESCAPE, "$1");
 }
 
+// 元数据标签的唯一来源是 STR.mirrorLabel（lang.js）：渲染按实例语言取，解析两套
+// 都认。下面的正则从那张表现算——旧实现把手写正则与 lang.js 的两处文案分开维护，
+// 加一个字段要改三处，漏改一处那一行就会随 /import 写进 entry 的 content。
+const META_LABELS = [];
+for (const language of Object.keys(STR.mirrorLabel)) META_LABELS.push(...Object.values(STR.mirrorLabel[language]));
+
+function reEsc(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// 元数据行的值必须单行：值里带换行会多出一行，轻则破坏「整段元数据行」的解析契约，
+// 重则伪造出一个条目头（sensitivity 是调用方传入的任意字符串，属信任边界）。
+function oneLine(text) {
+  return String(text).replace(/\s+/g, " ").trim();
+}
+
+// 结构头锚：ID 行紧跟类型行才算条目头（正文里机器格式的 ID 行不会切开块）。
+const ANCHOR_RE = new RegExp(
+  "^- \\*\\*ID\\*\\*: `([^`]+)`\\n- \\*\\*(?:" +
+    [STR.mirrorLabel.zh.type, STR.mirrorLabel.en.type].map(reEsc).join("|") +
+    ")\\*\\*:", "gm"
+);
+// 渲染出的整段元数据行（加字段只需改 lang.js 的 mirrorLabel）。
+const META_RUN_RE = new RegExp(`^(- \\*\\*(?:${META_LABELS.map(reEsc).join("|")})\\*\\*:.*\\n?)+`);
+// 三方合并用的版本令牌（service.syncMirror 比对并发写）。
+const UPDATED_RE = new RegExp(
+  "- \\*\\*(?:" + [STR.mirrorLabel.zh.updated, STR.mirrorLabel.en.updated].map(reEsc).join("|") +
+    ")\\*\\*: ([^\\n]+)"
+);
+
 function renderMemory(m, language = "zh") {
   // last-rendered digest baseline: sha256(title \x00 content). service.js
   // compares the file hash against this to tell "untouched by a human" (machine
@@ -40,6 +90,12 @@ function renderMemory(m, language = "zh") {
   lines.push(`- **${ML.tags}**: ${m.tags.map((t) => `\`${esc(t)}\``).join(" ")}`);
   lines.push(`- **${ML.updated}**: ${m.updated_at}`);
   if (m.source) lines.push(`- **${ML.source}**: ${esc(m.source)}`);
+  // scope / sensitivity 是只读展示字段（#278：sensitivity 的过滤语义另有归属，见
+  // 那条讨论；这里只把值摆出来）。只在真有值时渲染——本机 2843 条里只有 37 条带
+  // scope 标签，无条件渲染会给每条目多添两行空字段。
+  const scopeText = [m.agent_scope, m.workspace_scope].filter(Boolean).map(oneLine).join(" / ");
+  if (scopeText) lines.push(`- **${ML.scope}**: ${scopeText}`);
+  if (m.sensitivity) lines.push(`- **${ML.sensitivity}**: ${oneLine(m.sensitivity)}`);
   lines.push("");
   lines.push(`<!-- mirror-digest: ${digest} -->`);
   lines.push(m.content);
@@ -49,22 +105,76 @@ function renderMemory(m, language = "zh") {
   return lines.join("\n");
 }
 
+/**
+ * 文件头 frontmatter（#278 第一批）。按 type 分文件时一个文件装 N 条，所以
+ * frontmatter 只能落在文件级；条目级元数据仍是块内的 `- **字段**:` 行（见
+ * renderMemory）。
+ *
+ * `covered` / `coverage` 是覆盖范围的自述，必须与这份文本**实际包含的行集**一致：
+ * 磁盘镜像写活跃集（active-only），/export 的文档写全表（all）。说一套写一套比
+ * 没有这个字段更糟——外部工具会照着它聚合条数与标签。
+ *
+ * 键名对齐 OKF v0.2：`type` 是 §4.1 唯一必填键，`tags` 是 §4.1 的推荐键，
+ * `generated.by` / `generated.at` 是 §5.2 的 trust 族。`generated.by` 按 §7 的
+ * actor 约定写 `<producer>/<version>`（所以带版本号）；`generated.at` 按 §5.2 的
+ * 语义只记「内容上次真正变化」，sync 因此只在正文变化时才落盘。v0.2 已用
+ * `generated.at` 取代 v0.1 的 `timestamp`，没有 `updated` 这个顶层键。
+ * `covered` / `coverage` 是 §4.1 允许的 producer 自定义扩展。
+ */
+export function renderFileHeader(type, items, coverage = "active-only") {
+  const tags = [...new Set(items.flatMap((m) => (m.tags ?? []).map(String)))].sort();
+  return [
+    "---",
+    `type: ${type}`,
+    `generated.by: dsh-mneme/${PACKAGE_VERSION}`,
+    `generated.at: ${new Date().toISOString()}`,
+    `covered: ${items.length}`,
+    `coverage: ${coverage}`,
+    `tags: [${tags.map((t) => JSON.stringify(t)).join(", ")}]`,
+    "---",
+    ""
+  ].join("\n");
+}
+
+/**
+ * document 的只读视图一行（#296）：一句话定位 + 文件指针，正文按 doc_path 去读。
+ * 摘要首句按句末标点切，切不出来就整段（超长再按字符数兜底），保证「一行一个
+ * 文档」的形态不被长摘要撑破。
+ */
+function renderPointer(m) {
+  const flat = String(m.content ?? "").replace(/\s+/g, " ").trim();
+  // 句末标点切首句：中文的。！？ 后面通常不跟空格，不能像英文那样要求一个空白
+  // （要求了就一句都切不出来，整段摘要被当成「首句」塞进视图）。英文的 . 仍要求
+  // 后接空白或结尾，免得把 e.g. / v1.2 这类点号当成句末。
+  const first = flat.match(/^.*?(?:[。！？]|[!?]|[.](?=\s|$))|^.*$/s)?.[0] ?? flat;
+  // 按码点切，不按 UTF-16 码元：后者会在 emoji / 代理对中间落刀，落盘成 U+FFFD。
+  const chars = [...first];
+  const summary = chars.length > POINTER_MAX ? `${chars.slice(0, POINTER_MAX).join("")}…` : first;
+  const where = m.doc_path ? ` · \`${oneLine(m.doc_path)}\`` : "";
+  return `- \`${m.id}\` **${oneLine(m.title)}**：${oneLine(summary)}${where}\n`;
+}
+
 /**
  * Render one type's memories into exactly the mirror-file text (header +
  * per-memory blocks, updated_at DESC like sync). sync() writes this to disk;
- * the /export endpoint returns the same text, so an exported markdown is
- * byte-compatible with a mirror file and can be fed straight back through
- * parseHumanEdits → mergeHumanEdits. Unknown type → undefined.
+ * the /export endpoint reuses the same entry blocks for its per-type sections,
+ * so an exported markdown round-trips back through parseHumanEdits →
+ * mergeHumanEdits. Unknown type → undefined.
+ *
+ * `fileHeader: false` 供 /export 用：一个文档只能有一个 frontmatter 块（在文档
+ * 最前，见 api.js 的 /export），所以分节不再各自带文件头。只读 type（#296 的
+ * document）只走磁盘镜像这一条：渲染指针行 + 只读文件头，导出侧不取它。
  */
-export function renderMirrorText(type, memories, language = "zh") {
+export function renderMirrorText(type, memories, language = "zh", { fileHeader = true } = {}) {
   const name = TYPE_FILE[type];
   if (!name) return undefined;
   const items = (memories ?? [])
     .slice()
     .sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
-  const header = STR.mirrorHeader[language](name);
-  const body = items.map((m) => renderMemory(m, language)).join("\n");
-  return header + body;
+  const readonly = MIRROR_READONLY_TYPES.has(type);
+  const header = readonly ? STR.mirrorReadonlyHeader[language](name) : STR.mirrorHeader[language](name);
+  const body = items.map((m) => (readonly ? renderPointer(m) : renderMemory(m, language))).join("\n");
+  return (fileHeader ? renderFileHeader(type, items) : "") + header + body;
 }
 
 /**
@@ -91,7 +201,7 @@ export function parseHumanEdits(text) {
   // A body line like "- **ID**: `x`" is not, so it never splits the block
   // or produces a ghost entry.
   // 解析同时接受两种语言的标签：切换语言前渲染的镜像文件仍能合并。
-  const anchors = [...normalized.matchAll(/^- \*\*ID\*\*: `([^`]+)`\n- \*\*(?:类型|Type)\*\*:/gm)];
+  const anchors = [...normalized.matchAll(ANCHOR_RE)];
   let prevEnd = 0;
   for (let i = 0; i < anchors.length; i++) {
     const anchor = anchors[i];
@@ -109,7 +219,7 @@ export function parseHumanEdits(text) {
     let body = normalized
       .slice(blockStart, blockEnd)
       .replace(/^- \*\*ID\*\*: `[^`]+`\n?/, "")
-      .replace(/^(- \*\*(?:类型|重要性|标签|更新时间|来源|Type|Importance|Tags|Updated|Source)\*\*:.*\n?)+/, "")
+      .replace(META_RUN_RE, "")
       .replace(/^<!-- mirror-digest: [a-f0-9]+ -->\n?/m, "");
     const separators = [...body.matchAll(/^---\s*$/gm)];
     const lastSep = separators[separators.length - 1];
@@ -120,7 +230,7 @@ export function parseHumanEdits(text) {
     // render time — the version token for detecting a concurrent store write
     // during a three-way merge of human edits (see service.syncMirror).
     const block = normalized.slice(blockStart, blockEnd);
-    const updatedMatch = block.match(/- \*\*(?:更新时间|Updated)\*\*: ([^\n]+)/);
+    const updatedMatch = block.match(UPDATED_RE);
     const digestMatch = block.match(/<!-- mirror-digest: ([a-f0-9]+) -->/);
     edits.push({
       id: anchor[1],
@@ -136,6 +246,15 @@ export function parseHumanEdits(text) {
   return edits;
 }
 
+/**
+ * 判断「这份文本的内容有没有变」时忽略 generated.at：它每次渲染都是新时间戳，
+ * 带上它就永远判为变化。其余字节必须逐字相同才算没变——镜像的幂等性（同样的库
+ * 渲染两次得到同样的文件）才是可断言的。
+ */
+function stripGeneratedAt(text) {
+  return String(text).replace(/^generated\.at: .*$/m, "");
+}
+
 export function createMirror(dir, language = "zh") {
   mkdirSync(dir, { recursive: true });
 
@@ -150,7 +269,10 @@ export function createMirror(dir, language = "zh") {
    * this wrapper only owns the "read file → text" side.
    */
   function readHumanEdits(type = undefined) {
-    const types = type ? [type] : Object.keys(TYPE_FILE);
+    // 只读 type 不参与人改合并（#296）：它们的文件里没有可编辑的正文，解析出来的
+    // 指针行文本若被当成「人改」写回库，会污染摘要。整类跳过，包括 type 指定的
+    // 那条调用路径。
+    const types = (type ? [type] : Object.keys(TYPE_FILE)).filter((t) => !MIRROR_READONLY_TYPES.has(t));
     const edits = [];
     for (const t of types) {
       const file = filePath(t);
@@ -182,9 +304,19 @@ export function createMirror(dir, language = "zh") {
           // memories do not "resurrect" via readHumanEdits
           rmSync(file, { force: true });
         } else {
-          // 渲染走 renderMirrorText（与 /export 共用同一条渲染路径），磁盘镜像
-          // 与导出文本永远同构。
-          writeFileSync(file, renderMirrorText(type, items, language), "utf8");
+          // 渲染走 renderMirrorText（与 /export 共用同一条渲染路径）。
+          const text = renderMirrorText(type, items, language);
+          // 内容没变就不落盘。generated.at 每次渲染都新，无脑写会让编辑器、同步盘
+          // 与 git 在每次业务写后看到全部镜像文件「被外部修改」，而内容其实一字未
+          // 变；按 OKF 的语义它只该记内容变化，未变就保留旧值。这也是同步读 9 个
+          // 小文件的代价，比无谓写 9 次盘便宜。
+          let prev = null;
+          try {
+            prev = readFileSync(file, "utf8");
+          } catch { /* 首次写：读不到就是没有旧文件 */ }
+          if (prev === null || stripGeneratedAt(prev) !== stripGeneratedAt(text)) {
+            writeFileSync(file, text, "utf8");
+          }
         }
         results[type] = { ok: true };
       } catch (error) {

package/src/recall-stats.js

@@ -5,6 +5,8 @@
 // 新内聚块从第一行就落在自己的文件里，service.js 保留 barrel 出口、调用方零改动。
 // 纯读不写，绝不触发任何 write hook。
 
+import { scopeKeyOf } from "./scope.js";
+
 /**
  * 口径（issue #217 评论 2026-09-18，锚 5bd2dab）：
  *  - Top-N：窗口内 recall_runs.candidates（最终返回集）按 id 计数，join
@@ -20,6 +22,17 @@
  *  - coverage：recallRecordDefault 开启前的窗口算不到，earliestRunAt 为
  *    null（窗口内无回执）或早于窗口起点时，前端标注可信度；扫描行数有
  *    上限，超出标 truncated（degraded 口径），不静默少算。
+ *  - archive（#275 拍板的第五指标，与上面几项同位）：
+ *    · total = 归档区现有行数；addedInWindow / perDay = 窗口内进入归档区的行数
+ *      与其日均（净增速率）。归档时刻只能取 updated_at（setArchived 翻标志位时刷
+ *      它）——这是代理口径：对已归档行做一次 memory_update，或对同一行重复调
+ *      setArchived(…, true)，都会被算成「本窗口新进归档」，perDay 因此偏高。精确
+ *      口径要一个 archived_at 列（schema 变更，属第二批题材），本版不加；真正的
+ *      「净」增本来也要跨快照比 total（物理删除落地后，差值才会由负向变化体现）。
+ *    · compressible = 可压掉行数：同 type、同 scope 三维且内容哈希完全相同的归档
+ *      行里，多出来的那些（每组留一行）。用内容哈希而不是向量近重复，是因为回收
+ *      动作本身会清掉归档行向量（clearArchivedEmbeddings）——指标不能建在它自己
+ *      的输入会被回收掉的数据上；精确重复与 #254 的计量口径同一把尺。
  *
  * @param {object} store - createStore 产物（只调用 listRecallRunsSince / all）
  * @param {{ windowDays?: number, exemptDays?: number }} [options]
@@ -36,7 +49,8 @@ export function recallStats(store, options = {}) {
   const rawSlots = Number(options.maxInjectSlots ?? 5);
   const maxInjectSlots = Number.isInteger(rawSlots) && rawSlots >= 1 ? rawSlots : 5;
   const now = Date.now();
-  const since = new Date(now - windowDays * 86400000).toISOString();
+  const sinceMs = now - windowDays * 86400000;
+  const since = new Date(sinceMs).toISOString();
 
   const { rows: runs, total } = store.listRecallRunsSince(since);
   const hits = new Map(); // id -> { count, title, source }
@@ -67,8 +81,29 @@ export function recallStats(store, options = {}) {
   let activeCount = 0;
   let zombieCount = 0;
   let exemptCount = 0;
+  // 第五指标（#275）：归档区一侧单独累计，分组键与 #254 的去重候选集同构
+  // （type + 哈希 + scope 三维）——可压掉的必须是「本来就会被判成同一件事」的行。
+  let archivedTotal = 0;
+  let archivedInWindow = 0;
+  const hashGroups = new Map();
   for (const m of memories) {
-    if (m.archived || m.forgotten) continue;
+    if (m.archived) {
+      archivedTotal += 1;
+      const archivedMs = Date.parse(m.updated_at ?? "");
+      if (Number.isFinite(archivedMs) && archivedMs >= sinceMs) archivedInWindow += 1;
+      if (m.content_hash) {
+        const key = [
+          m.type ?? "",
+          m.content_hash,
+          scopeKeyOf(m.agent_scope) ?? "",
+          scopeKeyOf(m.workspace_scope) ?? "",
+          scopeKeyOf(m.sensitivity) ?? ""
+        ].join("\u0000");
+        hashGroups.set(key, (hashGroups.get(key) ?? 0) + 1);
+      }
+      continue;
+    }
+    if (m.forgotten) continue;
     const createdMs = Date.parse(m.created_at ?? "");
     // created_at 解析不了时无法证明已过机会期 → 归入豁免，宁漏勿误伤
     if (!Number.isFinite(createdMs) || now - createdMs < EXEMPT_MS) {
@@ -98,6 +133,14 @@ export function recallStats(store, options = {}) {
     .sort((a, b) => b.count - a.count || a.id.localeCompare(b.id))
     .slice(0, 10);
 
+  let compressibleGroups = 0;
+  let compressibleRows = 0;
+  for (const n of hashGroups.values()) {
+    if (n < 2) continue;
+    compressibleGroups += 1;
+    compressibleRows += n - 1;
+  }
+
   return {
     windowDays,
     generatedAt: new Date(now).toISOString(),
@@ -113,6 +156,13 @@ export function recallStats(store, options = {}) {
       slotFillRate: injectRuns > 0 ? injectedCount / (injectRuns * maxInjectSlots) : null
     },
     topRecalled,
+    // #275 第五指标：归档净增速率 + 可压掉行数（口径见文件头）
+    archive: {
+      total: archivedTotal,
+      addedInWindow: archivedInWindow,
+      perDay: Math.round((archivedInWindow / windowDays) * 100) / 100,
+      compressible: { rows: compressibleRows, groups: compressibleGroups }
+    },
     zombie: {
       activeCount,
       zombieCount,

package/src/scope.js

@@ -34,12 +34,7 @@ export function createScopeResolver({ ctx, config, logger } = {}) {
   };
 
   return function resolveWriteScope(exec) {
-    let session = null;
-    try {
-      session = exec?.agent?.session ?? null;
-    } catch {
-      session = null;
-    }
+    const session = sessionOf(exec);
 
     // 持久化 header（issue #17 的身份契约）：session.header 是创建时冻结的
     // SessionHeader（含 agentPreset/cwd）。⚠️ 不能先读 requestHeader()——那返回
@@ -83,6 +78,39 @@ export function createScopeResolver({ ctx, config, logger } = {}) {
   };
 }
 
+/**
+ * 工具 exec 上的会话对象。宿主 ctx 是 Proxy（cordis 4），裸读未 inject 的属性会
+ * 抛错——所以取值恒包在 try 里，取不到返回 null。scope 解析与写入准入的会话键
+ * 共用这一处取值口径。
+ * @param {object} exec
+ * @returns {object|null}
+ */
+export function sessionOf(exec) {
+  try {
+    return exec?.agent?.session ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 写入准入的会话键（#254 G1 会话写入预算的计数单位）。session_id 在这里只作
+ * 「同一段对话」的标识，不作为作用域键（见文件头：记忆挂在持久化身份标签上）；
+ * 取不到会话身份（系统写入）返回 null = 不进预算。
+ * @param {object} exec
+ * @returns {string|null}
+ */
+export function sessionKeyOf(exec) {
+  // 整个取值（含 .id）都在 try 里：宿主 session 可能是会抛错的 accessor，而这个
+  // 函数在 memory_save 的保存之前被调用——抛出去就是一次工具调用直接失败。
+  try {
+    const id = sessionOf(exec)?.id;
+    return id == null ? null : String(id);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * v0.8.1 底座（issue #170）：显式 scope 参数（memory_save / memory_update /
  * 面板编辑）的归一化。约定：

package/src/service.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { TYPE_FILE } from "./mirror.js";
+import { TYPE_FILE, MIRROR_READONLY_TYPES } from "./mirror.js";
 import { updatedAtBounds } from "./store.js";
 import { normalizeExplicitScope, scopeKeyOf } from "./scope.js";
 import { STR, langOf } from "./lang.js";
@@ -29,7 +29,9 @@ const CODING_MEMORY_TYPES = new Set(["rejected_solution", "pitfall", "constraint
 // 注意 constraint 同时属于 CODING_MEMORY_TYPES，非编码任务里已被 codingGate
 // 滤掉，pin 池同样拿不到它；是否豁免该门控是待维护者拍板的口径问题，本批次
 // 不动既有门控（不放大行为面）。
-const PINNED_MEMORY_TYPES = new Set(["constraint", "preference"]);
+// 导出给写入准入（#254 的穿透口）与注入侧共用一份定义：两处各写一份 list 迟早
+// 漂移成「pin 池豁免了、预算没豁免」这类两套口径。
+export const PINNED_MEMORY_TYPES = new Set(["constraint", "preference"]);
 
 /**
  * 判断一段文本是否编码类任务（关键词匹配，codingRetrospect 读取侧门控）。
@@ -167,7 +169,7 @@ export function computeRetrievalMetrics(actualIds, expectedIds) {
   };
 }
 
-export function createService({ store, mirror, config, onWrite, logger }) {
+export function createService({ store, mirror, config, onWrite, logger, documentIndex, writeAdmission }) {
   const language = langOf(config);
   // Optional dream scheduler hook, installed via setDreamHook after creation
   // (the scheduler holds a reference back to the service, so it cannot be
@@ -876,12 +878,17 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           mode,
           topK: lim,
           threshold: threshold ?? null,
+          // Per-source 信号随回执落盘（fuseRecall 本就无条件计算，此前只服务
+          // signalTransparency 展示）：复用侧查询画像（query 型 → 各路权重的
+          // 离线聚合，AssoMem arXiv 2510.10397 消融所示收益大头）需要这份原料。
+          // 纯加字段——recall_runs 无 schema 变更，旧行 candidates 缺该键照常读。
           candidates: result.map((m) => ({
             id: m.id,
             title: m.title,
             content: m.content,
             score: m.score ?? null,
-            source: m.source ?? "keyword"
+            source: m.source ?? "keyword",
+            signals: signals.get(m.id) ?? {}
           })),
           createdAt: new Date().toISOString()
         });
@@ -1243,6 +1250,17 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       scheduleEmbed(result);
       return { action: "merged", memory: result };
     }
+    // #254 写入准入（第一阶段只计量）：决策恒 allow、不拦写入，只把两个闸门的
+    // 测量点算出来。放在 store.save 之前——第二阶段要在这里拦下写入，接缝先摆好。
+    // 计量是旁路：任何一环失败只 warn，绝不反噬写入（与质量打分同款容错）。
+    let admission = null;
+    if (writeAdmission) {
+      try {
+        admission = writeAdmission.evaluate({ memory, sessionKey: memory._sessionKey });
+      } catch (e) {
+        try { logger?.warn?.(`[dsh-mneme] write admission evaluate failed: ${String(e)}`); } catch { /* 不反噬 */ }
+      }
+    }
     const created = store.save({
       type: memory.type,
       title: memory.title,
@@ -1263,6 +1281,17 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       ...(quality ? { quality_score: quality.score } : {})
     });
     const result = applyQualityDisposition(created, quality, qf);
+    if (admission) {
+      try {
+        writeAdmission.record({
+          sessionKey: memory._sessionKey,
+          verdict: admission,
+          memoryId: created.id
+        });
+      } catch (e) {
+        try { logger?.warn?.(`[dsh-mneme] write admission record failed: ${String(e)}`); } catch { /* 不反噬 */ }
+      }
+    }
     afterSync("write");
     notifyWrite();
     scheduleEmbed(result);
@@ -1560,6 +1589,10 @@ export function createService({ store, mirror, config, onWrite, logger }) {
    * Only content/title are taken; structure fields stay machine-owned.
    */
   function mergeHumanEdits(type, edits) {
+    // #296：只读 type 的结构性守卫。调用点（启动合并 / reconcileHumanEdits）都已
+    // 跳过它们，但这条不变量属于「人改回填」本身——将来多一个调用点不该重开这个口
+    // （指针行文本被当正文写回 document 行会污染摘要）。
+    if (MIRROR_READONLY_TYPES.has(type)) return 0;
     let applied = 0;
     for (const edit of edits) {
       if (!edit.id) continue; // corrupt/malformed edit: skip it, keep merging the rest
@@ -1787,6 +1820,26 @@ export function createService({ store, mirror, config, onWrite, logger }) {
    * non-forgotten memories are mirrored: forgotten entries must not reach the
    * human-editable file (a human "edit" could otherwise resurrect them).
    */
+  // #296 第二批：documentDir/index.md 的写后语。与注册入口共用同一个
+  // documentMemoryEnabled 闸（默认关）：闸开时只列活跃指针行（正文永远不进这个
+  // 文件），闸关时把索引删掉——document 子系统整体退出，留一份陈旧索引会列出已
+  // 归档的行，正是镜像侧 documents.md 在闸关时被删掉要避免的那种「看着还在、其实
+  // 已关」的视图。两步都只 warn：索引是机器产物，不能让触发它的业务写失败。
+  function syncDocumentIndex() {
+    if (!documentIndex) return;
+    if (config?.documentMemoryEnabled !== true) {
+      const removed = documentIndex.remove();
+      if (!removed?.ok) logger?.warn?.("document index remove failed:", removed?.error);
+      return;
+    }
+    try {
+      const result = documentIndex.sync(store.list({ type: "document", limit: null }));
+      if (!result?.ok) logger?.warn?.("document index sync failed:", result?.error);
+    } catch (error) {
+      logger?.warn?.("document index sync failed:", error);
+    }
+  }
+
   // syncMirror: 同步 mirror，并在失败/成功时持久记录 dirty 状态；保证自身不抛出。
   // v0.3.6（audit peer 4 阻断）：
   //   - 开始时 incrementGeneration 绑定本次期望轮次 gen；成功用
@@ -1796,7 +1849,12 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   //   - 逐 type 用 setTypeStatus 记录部分成功/失败（type_status JSON）；
   //   - 所有 store 状态写入各自 try/catch，失败只 warn，绝不向外抛（F-NEW-03）。
   function syncMirror() {
-    if (txDepth > 0 || !mirror) return { success: true, deferred: true }; // deferred to the transaction's commit
+    if (txDepth > 0) return { success: true, deferred: true }; // deferred to the transaction's commit
+    // #296 第二批：documentDir/index.md 走同一条写后语——它与镜像一样是「从库渲染
+    // 的机器产物」，同样只在内容变化时落盘、同样自己吞掉失败。放在 !mirror 短路
+    // 之前：索引在不在，不该取决于镜像是否装配（无镜像的宿主与测试同样要有它）。
+    syncDocumentIndex();
+    if (!mirror) return { success: true, deferred: true };
     const now = new Date().toISOString();
     let gen;
     try {
@@ -1812,8 +1870,20 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     // 合法的空 Set 可迭代，保证 syncMirror 自身绝不抛（fail-safe）。
     const coveredTypes = new Set();
     try {
-      // 预先获取本次要覆盖的 type 集合（只调一次 store.list）
-      const list = store.list({ limit: 500, includeForgotten: false });
+      // 预先取本次要覆盖的全部活跃行（只读一次）。这里曾经是
+      // store.list({ limit: 500 })——活跃集超过 500 时镜像会静默少掉尾部记忆，
+      // 而文件本身没有任何提示（#278 第一批）。store.list 的 limit 默认值只有
+      // 50，比原来显式传的 500 更小，所以改用 all() 并在这里做同一套过滤
+      // （forgotten/archived 都不进镜像，与 includeForgotten:false + 默认
+      // includeArchived:false 等价）。
+      // 代价是全表读，且落在每次业务写后的最热路径上（#202 自记 all() 5k 行
+      // 231ms → ~135ms）。要压这一层得换按 type 分页取，属另一批的事；
+      // 在这里退回任何截断都不行——「宣称覆盖活跃集」与静默截断不能共存。
+      const list = store.all().filter((m) => !m.forgotten && !m.archived
+        // #296 第二批：镜像里的 documents.md 与 index.md 共用 documentMemoryEnabled
+        // 闸。关掉时把 document 行也从渲染集里去掉——sync 对「空 type」的既有处理
+        // 会把陈旧的 documents.md 删掉，不留一个「看着还在、其实已关」的视图。
+        && (m.type !== "document" || config?.documentMemoryEnabled === true));
       for (const memory of list) {
         if (memory?.type && TYPE_FILE[memory.type]) {
           coveredTypes.add(memory.type);
@@ -2092,6 +2162,12 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   function archiveMemory(id, f) {
     const updated = store.setArchived(id, f);
     afterSync("write");
+    // #275 B 项：归档行的向量会被手动回收清掉（检索恒带 archived = 0，按定义不可达），
+    // 还原回活跃面时补一次嵌入——否则那行只剩关键词可检索，回收就成了单程票。
+    // 判据用真值（`!f`）而不是 `f === false`：store.setArchived 自己就是按真值归一
+    // （`archived ? 1 : 0`），API/工具传 0 或空串同样会把行放回活跃面，口径必须同一把尺。
+    // 排队语义与写入路径同一处（txDepth / 未就绪由 scheduleEmbed 自己挡）。
+    if (!f) scheduleEmbed(updated);
     return updated;
   }
 
@@ -2105,6 +2181,9 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     embedQuery,
     pushContentHistory,
     transaction,
+    // #275 拍板 5：升格吸收的 evidence 行随之归档，但 pinned 池（#249）永不自动归档
+    // ——注册器不 import 这个集合，方向反了会成环，所以在这里注入。
+    pinnedTypes: PINNED_MEMORY_TYPES,
     finalize: (rows) => {
       for (const row of rows) scheduleEmbed(row);
     }

package/src/settings.js

@@ -45,7 +45,8 @@ const FEATURE_FLAG_BOOLEANS = [
   "hotMemoryEnabled",
   // Issue #239 第 5 项：注入条数的查询自适应（确定性强则收缩注入条数，默认关）。
   "injectUncertaintyAdaptive",
-  // Issue #249 第一批：能力说明（工具描述判断指引 + order 150 总则段，默认关）。
+  // Issue #249：能力说明（工具描述判断指引 + order 150 总则段）。第二批起它是
+  // 注入父开关 autoInject 的子项、默认开（父关时不生效，闸门见 config.js）。
   "injectGuidanceEnabled",
   "entityExtractionEnabled",
   // Issue #219：图召回轴——查询命中实体名时把挂联记忆并入检索融合池
@@ -172,8 +173,10 @@ const FEATURE_FLAG_ENUMS = {
   summarizeDedupeMode: ["off", "title", "vector"],
   // Issue #126：sleep 冲突阶段的动作集（conflict 默认 = 现状；full = 六分支）。
   sleepActionSet: ["conflict", "full"],
-  // Issue #125：dream 候选集构造方式（window 默认 = 现状；hybrid 并入向量组）。
-  dreamCandidateMode: ["window", "hybrid"]
+    // Issue #125：dream 候选集构造方式（window 默认 = 现状；hybrid 并入向量组）。
+    dreamCandidateMode: ["window", "hybrid"],
+    // 本地嵌入池化：auto = 按模型族判定（BGE → cls），可显式覆盖为 cls / mean。
+    localEmbedPooling: ["auto", "cls", "mean"]
 };
 const FEATURE_FLAG_STRING_MAX = 200;