@a9i5k4/dsh-auto-memory 2.5.3 → 3.0.1

package/lib/memory-hub.js

@@ -1,3 +1,5 @@
+import { stripRuntimeIntentPre, looksRuntimeResiduePre } from './intent-clean-safe.js'
+import { isObservationOnlyPre } from './procedure-observation.js'
 /**
  * M8-3 Memory Hub 编排器(docs/PROJECT-FREEZE-AND-ROADMAP.md M8/M9; 记忆中枢)。
  * 纯内存编排,零 IO 依赖(node:crypto 仅身份);把三层记忆串成一条可即插即用的链:
@@ -49,6 +51,9 @@ export function createMemoryHubPre(opts = {}) {
   const { createEpisodicStorePre } = opts._stores || {}
   const { createFactStorePre } = opts._stores || {}
   const { createProcedureStorePre } = opts._stores || {}
+  // ★T10：机械 procedure 切片开关（默认关闭；缺省值在 index.js 的 DEFAULT_CONFIG）。
+  //   这里只读、不判定语义 —— 具体用途见 crossFeed() 的 procedure 分支。
+  const mechanicalProcedureFeedEnabled = opts.mechanicalProcedureFeedEnabled === true
   const nowFn = typeof opts.now === 'function' ? opts.now : () => Date.now()
   const log = typeof opts.log === 'function' ? opts.log : () => {}
 
@@ -94,10 +99,25 @@ export function createMemoryHubPre(opts = {}) {
         return { consumed: 'procedure', outcome: r.ok ? 'observed' : r.reason }
       }
       if (layer === 'episodic' && stores.episodic) {
-        // episodic_candidate 已是巩固后的 episode,直接喂
-        const r = stores.episodic.restore({ schemaVersion: 1, episodes: [row] })
-        stats.consumedEpisodic++
-        return { consumed: 'episodic', outcome: r.ok ? 'restored' : r.reason }
+        // ★ 2026-09-19 上游 PR #77 / issue #63 同步落地（**P0 数据丢失**）：
+        //   旧实现走 `stores.episodic.restore({schemaVersion:1, episodes:[row]})`，而 `restore()` 是
+        //   **快照整体替换**语义（先清空 episodes）。候选行普遍缺 validateEpisodePre 必填字段
+        //   ⇒ 校验拒（restored:0），**但 episodes 已被清空、current 已置 null**，且仍返回 {ok:true}
+        //   ⇒ 一次 ingest 抹掉全部已巩固 episode，不可逆。
+        //   现改走**增量导入**：不清空、逐条校验、按 episodeId 幂等。
+        //   fallback：老 store 无 importEpisodes 时退化为"不导入"，**绝不回退到 restore**。
+        if (typeof stores.episodic.importEpisodes !== 'function') {
+          stats.skipped++
+          return { skipped: true, reason: 'no-import-episodes' }
+        }
+        const r = stores.episodic.importEpisodes([row])
+        if (r.ok && r.imported > 0) {
+          stats.consumedEpisodic++
+          return { consumed: 'episodic', outcome: 'imported' }
+        }
+        // 如实区分：非法行 / 重复行都不算 consumed（旧实现把两种情况都记成 'restored'）
+        stats.skipped++
+        return { skipped: true, reason: r.duplicates > 0 ? 'duplicate-episode' : 'rejected:' + r.rejected }
       }
     } catch (e) {
       log('memory-hub ingest error: ' + String(e && e.message || e))
@@ -128,11 +148,20 @@ export function createMemoryHubPre(opts = {}) {
     const out = []
     for (const ep of eps) {
       // 成功 episode → procedure 观察(固定流程雏形)
-      if (ep.success && stores.procedures && ep.intent && ep.actions && ep.actions.length) {
+      // issue #30:episode 只提供"观察到一件事"的线索,**不足以**构成可晋升技能 ——
+      // 把 actions 直接当成 steps 会让观察行看起来像真流程,且与后续同名富候选撞车后被合并
+      // 而丢失富候选的 successCriteria(晋升永久卡死)。现在显式标 observationOnly=true,
+      // 并在 title 前过滤运行时信封(避免注入文本变成技能标题)。
+      const procedureIntent = stripRuntimeIntentPre(ep.intent).trim()
+      // ★T10（2026-09-20 用户报「技能名/内容看不懂」）：**门控机械切片**。
+      //   关闭时整段跳过 ⇒ 不再产出 `intent.slice(0,40)` 这种机械观察行。
+      //   ⚠️ 只包住 procedure 分支：下方 fact 分支与循环外的逻辑一律不受影响。
+      if (mechanicalProcedureFeedEnabled && ep.success && stores.procedures && procedureIntent && procedureIntent !== '(未提取)' && ep.actions && ep.actions.length) {
         const cand = {
-          title: ep.intent.slice(0, 40),
+          title: procedureIntent.slice(0, 40),
           riskLevel: 'low',
-          steps: ep.actions.map((a, i) => '步骤' + (i + 1) + ': ' + a),
+          steps: ['观察任务：' + procedureIntent.slice(0, 80)],
+          observationOnly: true,
           sourceEpisodes: [ep.episodeId],
           sourceMemoryIds: [],
         }
@@ -141,9 +170,24 @@ export function createMemoryHubPre(opts = {}) {
       }
       // 有未决事项的 episode → 事实候选(不直接固化,留给 judgement)
       if (ep.unresolved && ep.unresolved.length && stores.facts) {
+        // ★ T1-1（2026-09-19 真机追加）：**fact 分支必须与 procedure 分支同样过清洗器**。
+        //   根因：上面 procedure 分支早已调 `stripRuntimeIntentPre`（:152），但本分支直接用
+        //   **未清洗**的 `ep.intent` ⇒ 运行时信封/U+FFFD 原样进 facts.json ⇒ 前端面板乱码（⑩-a），
+        //   且经 `hubFlushTick` 写回 `MEMORY.md` 污染注入面与语义语料（⑩-b）。实测证据：
+        //   `fact_ac4920327df6601f25200d66e52df71f` 的 subject 含 22 个 U+FFFD；
+        //   另两条的 object 内嵌 `Current DSH file policy: …` / `Approval prompts are disabled …`。
+        //   清洗后再截断，且**空值回退**到 'episode'（保持原 `|| 'episode'` 语义不变）。
+        //   ★ F5（行内残留）：清洗器是**按行**判断的，真人与信封挤在同一行时整行必须保留
+        //   （删了会丢人话）⇒ 此时「清洗后是否变化」检测不到脏。故再补一道 `looksRuntimeResiduePre`：
+        //   该字段**含任何运行时痕迹即整体判脏并丢弃**（置空 ⇒ 走下面的空值回退），
+        //   而不是把半截信封写进 facts.json。
+        const rawIntent = String(ep.intent == null ? '' : ep.intent)
+        const rawObject = String(ep.unresolved[0] == null ? '' : ep.unresolved[0])
+        const factIntent = looksRuntimeResiduePre(rawIntent) ? '' : stripRuntimeIntentPre(rawIntent).trim()
+        const factObject = looksRuntimeResiduePre(rawObject) ? '' : stripRuntimeIntentPre(rawObject).trim()
         const cand = {
-          scope: 'Workspace', subject: ep.intent.slice(0, 30) || 'episode', predicate: '有未决事项',
-          object: ep.unresolved[0].slice(0, 60), sourceKind: 'inference',
+          scope: 'Workspace', subject: factIntent.slice(0, 30) || 'episode', predicate: '有未决事项',
+          object: factObject.slice(0, 60), sourceKind: 'inference',
           sourceClass: 'semantic-candidate', provenance: [ep.episodeId],
         }
         const r = stores.facts.upsert(cand)
@@ -188,7 +232,27 @@ export function createMemoryHubPre(opts = {}) {
         // 供 hubTab 审批按钮(晋升/激活/弃用)操作
         pipeline: stores.procedures.query()
           .filter((p) => p.stage !== 'active' && p.stage !== 'deprecated')
-          .map((p) => ({ procedureId: p.procedureId, title: p.title, stage: p.stage, riskLevel: p.riskLevel, evidence: p.evidence, pinned: !!p.pinned })),
+          // issue #30:如实暴露 observationOnly —— 审批面必须能区分"可晋升技能"与"仅观察线索",
+          // 否则使用者会对着一个结构上不可能晋升的条目反复点晋升。
+          // ★R2（2026-09-20）：补 `promotion` 判定投影 —— 用户要「晋升原因必须显式展示」。
+          //   走**纯只读**的 evaluatePromotion()，绝不在 overview 里碰 promote()（它写盘）。
+          //   失败时置 null（fail-soft：判定异常不得拖垮整个面板）。
+          .map((p) => {
+            let promotion = null
+            try {
+              promotion = stores.procedures.evaluatePromotion
+                ? stores.procedures.evaluatePromotion(p.procedureId)
+                : null
+            } catch (_) { promotion = null }
+            return {
+              procedureId: p.procedureId, title: p.title, stage: p.stage, riskLevel: p.riskLevel,
+              evidence: p.evidence, pinned: !!p.pinned, observationOnly: isObservationOnlyPre(p),
+              // R4 预览用：晋升后会注入的真实 checklist 文本
+              steps: Array.isArray(p.steps) ? p.steps.slice(0, 12) : [],
+              successCriteria: Array.isArray(p.successCriteria) ? p.successCriteria.slice(0, 6) : [],
+              promotion,
+            }
+          }),
         stats: stores.procedures.getStats ? stores.procedures.getStats() : null,
       } : null,
     }
@@ -226,11 +290,24 @@ export function factCandidateFromRow(row) {
   if (kind !== 'semantic_candidate' && kind !== 'profile_candidate') return null
   const sourceIds = Array.isArray(row.sourceIds) ? row.sourceIds : []
   if (!sourceIds.length) return null
+  // ★ T1-2（2026-09-19 真机追加）：这是 fact 的**第二条入口**（judgement shadow 行），
+  //   与 `crossFeed` 的 fact 分支同源，同样必须过清洗器 —— 否则「补了 A 口、漏了 B 口」，
+  //   脏数据仍会经本函数进入 facts.json（再被 hubFlushTick 写回 MEMORY.md）。
+  //   ★ F5：清洗器按行判断，**行内混信封**时整行保留 ⇒ 再加一道 `looksRuntimeResiduePre`，
+  //   命中即置空（走下面的空值回退），不把半截信封写进库。
+  const rawSubject = String(row.subject == null ? '' : row.subject)
+  const rawPredicate = String(row.predicate == null ? '' : row.predicate)
+  const rawObject = row.object === undefined || row.object === null ? null : String(row.object)
+  const cSubject = looksRuntimeResiduePre(rawSubject) ? '' : stripRuntimeIntentPre(rawSubject).trim()
+  const cPredicate = looksRuntimeResiduePre(rawPredicate) ? '' : stripRuntimeIntentPre(rawPredicate).trim()
+  const cObject = rawObject === null
+    ? null
+    : (looksRuntimeResiduePre(rawObject) ? null : (stripRuntimeIntentPre(rawObject).trim() || null))
   return {
     scope: row.scope === 'User' ? 'User' : 'Workspace',
-    subject: String(row.subject || sourceIds[0]),
-    predicate: String(row.predicate || 'relation'),
-    object: row.object === undefined || row.object === null ? null : String(row.object),
+    subject: cSubject || String(sourceIds[0]),
+    predicate: cPredicate || 'relation',
+    object: cObject,
     sourceKind: 'inference',
     sourceClass: kind === 'profile_candidate' ? 'profile-candidate' : 'semantic-candidate',
     provenance: [...sourceIds],
@@ -257,3 +334,51 @@ export function procedureCandidateFromRow(row) {
     successCriteria: Array.isArray(row.successCriteria) ? row.successCriteria : [],
   }
 }
+
+/**
+ * ④ 教训 → 观察型候选（2026-09-19 R5）。
+ *
+ * **用户裁定（2026-09-18 00:20）**：
+ *   「**教训肯定得进 C 啊，它不自动晋升，但是可以形成候选，模型也可以通过搜索搜索到**。
+ *    因为教训那边，我现在**自动注入的硬约束也是某种教训，把它上升到了约束层面**。」
+ *
+ * **通路设计**：
+ *   `retracted` 条目 + 撤回原因（reason）→ 本函数 → `observationOnly: true` 观察型候选
+ *   → `procedure-store.observe()` → **`promote()` 短路返回 `observation-only` ⇒ 永不自动晋升**
+ *   → 但 `query()` 可检索到 ⇒ 模型能主动搜到「这条曾经被判错、原因是什么」。
+ *
+ * **三条硬约束（缺一即错）**：
+ *  1. **必须 `observationOnly: true`** —— 这是「永不自动晋升」的**唯一结构保证**。
+ *     若漏掉，它会变成可晋升富候选，与用户裁定直接冲突。
+ *  2. **`sourceMemoryIds` 必须带被撤回条目的 id** —— 教训的 provenance 是那条 retracted 记忆本身；
+ *     不得留空（留空会让 `addEvidence` 的 sourceMemoryIds 匹配计数恒零，且与
+ *     episode→观察行 那条通路的语义混淆）。
+ *     注意：这与 `crossFeed()` 里 `sourceMemoryIds: []` 的**有意留空不同** ——
+ *     那里是"episode 只提供线索、不得凭空造 provenance"；这里 id 是**真实存在**的。
+ *  3. **title/intent 必须先过信封清洗** —— 否则运行时信封会再次变成"教训标题"（H-3 同款）。
+ *
+ * @param {{memoryId?: string, title?: string, text?: string, reason?: string, retractedReason?: string}} row
+ * @returns {object|null} procedure candidate（observationOnly），输入不合法返回 null
+ */
+export function lessonCandidateFromRetractedPre(row) {
+  if (!row || typeof row !== 'object') return null
+  const memoryId = String(row.memoryId || '').trim()
+  // 只认严格锚点 id 形态：与 G3 状态行同一套判据（防任意文本被当成 provenance 拼进去）
+  if (!/^mem_[0-9a-f]{32}$/.test(memoryId)) return null
+  const rawTitle = String(row.title || row.text || '').trim()
+  const title = stripRuntimeIntentPre(rawTitle).trim()
+  if (!title) return null
+  const reasonRaw = String(row.reason || row.retractedReason || '').trim()
+  const reason = stripRuntimeIntentPre(reasonRaw).trim().replace(/\s+/g, ' ').slice(0, 120)
+  return {
+    title: ('教训：' + title).slice(0, 60),
+    riskLevel: 'low',
+    // 步骤形态：明说「这是一条教训」+ 撤回原因（原因才是教训的正文）
+    steps: [reason ? ('曾判错，原因：' + reason + '。下次避免：' + title.slice(0, 60)) : ('曾判错：' + title.slice(0, 80))],
+    // ★ 约束 1：永不自动晋升的结构保证
+    observationOnly: true,
+    sourceEpisodes: [],
+    // ★ 约束 2：真实 provenance（非凭空构造）
+    sourceMemoryIds: [memoryId],
+  }
+}

package/lib/memory-index.js

@@ -55,10 +55,12 @@ function decodedLine(buf, s, e) {
 function buildIndex(sourceFile, content, prev) {
   const buf = Buffer.isBuffer(content) ? content : Buffer.from(String(content), 'utf8')
   if (buf.length > INDEX_MAX_FILE_BYTES) {
-    return { sourceFile, fileDigest: '', sourceVersion: (prev && prev.version) || 1, skipped: true, records: [] }
+    // ★2026-09-20 移植（issue #92 / PR #97）：宿主缓存只写 sourceVersion，旧读 prev.version
+  //   在生产路径恒为 undefined ⇒ 版本封顶 2、未变重读回退 1。
+  return { sourceFile, fileDigest: '', sourceVersion: (prev && prev.sourceVersion) || 1, skipped: true, records: [] }
   }
   const fileDigest = createHash('sha256').update(buf).digest('hex')
-  const sourceVersion = prev && prev.fileDigest === fileDigest ? (prev.version || 1) : (prev ? (prev.version || 1) + 1 : 1)
+  const sourceVersion = prev && prev.fileDigest === fileDigest ? (prev.sourceVersion || 1) : (prev ? (prev.sourceVersion || 1) + 1 : 1)
   const lines = splitByteLines(buf)
   const records = []
   let cur = null

package/lib/memory-mutation.js

@@ -0,0 +1,246 @@
+/**
+ * 记忆写入保护门（memory_mutation_v1）—— 3.0 主体拥有「共同提交与保护入口」。
+ *
+ * 2026-09-14 建立（P0）。**边界（总纲 §0.5 / ROUND3 §3.1 定案，必须遵守）**：
+ *   - **本模块**只接收**规范化投影**：`{beforeIds, afterIds, protectedRegions, changes}`。
+ *     它**不自行解释图格式** —— 不知道 `### ` 是什么、不知道 `<!-- user -->` 是什么。
+ *   - **格式由适配器提供**：白板走 `lib/wb-contract.js:parseWhiteboardPre` → `toMutationProjectionPre`；
+ *     账本/笔记等其他目标各给各的投影。**格式只维护一份**。
+ *
+ * **为什么要这个门**（不是一个好想法，是事故根因）：
+ *   `WB-FORMAT-CONVENTION.md` §4 的写入门只做一件事 —— **重写前后比对卡片集合**：
+ *   允许移动、改状态、改正文、加卡；**不允许卡片凭空消失**；要消失必须显式移入 `archived` 并留痕。
+ *   实际事故是「白板被整篇覆盖成骨架」（规范已批准、代码从未实现）。
+ *   2026-09-14 实测缺口：`PLAN.md` 一个锚点、一个分区标记都没有。
+ *
+ * **三条保护**（每条都有能红断言，见 `tests/smoke/smoke-test-t0-8-mutation-gate-pre.mjs`）：
+ *   M1 **丢卡保护**：`beforeIds` 里有、`afterIds` 里没有的 id，必须出现在 `archived` 里（显式归档 + 留痕）；
+ *      否则**拒绝写入**并报出差异清单（不是静默接受）。
+ *   M2 **用户区保护**（B4 预授权默认值：每卡分「模型维护区 / 用户备注区」）：
+ *      `protectedRegions` 的 digest 必须原样出现在 after 侧 —— 模型整篇重写**必须原样带回**用户段。
+ *   M3 **重复 id 保护**：after 侧同一 id 出现两次即拒绝（契约 §2 禁止复用同一 id 指两个卡片）。
+ *
+ * **fail-open 不得绕过保护**（ROUND3 §3.7 第 4 条，总纲 v2 明确）：
+ *   `criteriaGate=false` 与"骨架 fail-soft"**只能退掉可选质量门**（H1–H4/S1–S4/P-H1/P-H2 那类
+ *   判据），**不得**跳过丢卡、用户区、版本、状态保护。本模块的 `strict` 参数**只影响
+ *   `changes` 类软项**（例如"本次是骨架写入"的提示），**对 M1/M2/M3 无任何影响** ——
+ *   这三条是**无条件**的。测试 `T0-8C` 专门锁这一点。
+ *
+ * S9 合规：零 IO、零外部依赖（只用 node:crypto 做摘要）、纯函数、无网络/无 LLM/无子进程/无 await。
+ * UTF-8 无 BOM。
+ */
+import { createHash } from 'node:crypto'
+
+export const MEMORY_MUTATION_VERSION = 'memory_mutation_v1'
+
+/** 拒绝/提示的原因码 → 可读中文。 */
+export const MUTATION_REASONS_V1 = Object.freeze({
+  'card-disappeared': '卡片消失且无归档记录（契约 §4：不允许凭空消失）',
+  'protected-region-lost': '受保护区域（用户备注区）未被原样带回',
+  'protected-region-modified': '受保护区域被改动（必须逐字节保留）',
+  'duplicate-id': '同一 id 在写入后出现两次（契约 §2 禁止）',
+  'invalid-projection': '规范化投影形状非法（缺 beforeIds/afterIds）',
+  'not-object': '传入的不是对象',
+})
+
+/** 原因码 → 可读中文（未知码原样返回）。 */
+export function describeMutationReasonPre(code) {
+  const k = String(code == null ? '' : code)
+  return MUTATION_REASONS_V1[k] || k || '未知原因'
+}
+
+const asStringArray = (v) => (Array.isArray(v) ? v.map((x) => String(x == null ? '' : x)).filter(Boolean) : null)
+const sha = (s) => createHash('sha256').update(String(s == null ? '' : s)).digest('hex').slice(0, 16)
+
+/**
+ * 共同提交与保护入口（**纯函数**）。
+ *
+ * @param {object} input
+ * @param {string[]} input.beforeIds 写入前该目标拥有的卡片 id 集合（规范化投影；首建传 `[]`）
+ * @param {string[]} input.afterIds  写入后将要拥有的卡片 id 集合
+ * @param {Array<{key:string,digest:string,chars?:number}>} [input.protectedRegions]
+ *   受保护区域的摘要清单（前后比对用；通常来自适配器的 `extractProtectedRegionsPre`）
+ * @param {Array<{key:string,digest:string}>} [input.afterProtectedRegions]
+ *   写入后同区域的实际摘要。**省略时的语义必须明确**：视为"无法证明被保留" ⇒ **拒绝**（fail closed），
+ *   而不是"默认通过"。这是因为"忘了传"和"真的丢了"在保护语义上必须同样处理。
+ * @param {string[]} [input.archivedIds] 显式归档的 id（进入归档集合 + 留痕 = 合法"消失"）
+ * @param {object} [input.changes] 供报告使用的变更描述（**不参与保护判定**）
+ * @param {string} [input.target] 'plan' | 'handoff' | 'note' | 'other'（仅用于报告）
+ * @param {boolean} [input.strict=true] 只影响软提示（如"骨架写入"）；**不影响 M1/M2/M3**
+ * @returns {{ok:boolean, version:string, target:string, gate:string,
+ *            hard:Array<{id:string, pass:boolean, missing:Array, detail:string}>,
+ *            soft:Array<{id:string, pass:boolean, detail:string}>,
+ *            report:{disappeared:string[], archived:string[], unarchived:string[],
+ *                    protectedChecked:number, protectedOk:number, duplicateIds:string[]}}}
+ */
+export function validateMutationBoundaryPre(input = {}) {
+  const o = input && typeof input === 'object' ? input : null
+  const target = String((o && o.target) || 'other')
+  const strict = !o || o.strict !== false
+  const hard = []
+  const soft = []
+
+  if (!o) {
+    hard.push({ id: 'M0', pass: false, missing: ['projection'], detail: describeMutationReasonPre('not-object') })
+    return report(false, target, hard, soft, emptyReport())
+  }
+
+  const beforeIds = asStringArray(o.beforeIds)
+  const afterIds = asStringArray(o.afterIds)
+  if (!beforeIds || !afterIds) {
+    hard.push({ id: 'M0', pass: false, missing: ['beforeIds', 'afterIds'].filter((k) => !Array.isArray(o[k])), detail: describeMutationReasonPre('invalid-projection') })
+    return report(false, target, hard, soft, emptyReport())
+  }
+
+  const archived = asStringArray(o.archivedIds) || []
+  const afterSet = new Set(afterIds)
+  const beforeSet = new Set(beforeIds)
+
+  // ── M1 丢卡保护（无条件；`strict`/质量门开关都绕不过） ──
+  const disappeared = beforeIds.filter((id) => !afterSet.has(id))
+  const unarchived = disappeared.filter((id) => !archived.includes(id))
+  hard.push({
+    id: 'M1',
+    pass: unarchived.length === 0,
+    missing: unarchived.slice(),
+    detail: unarchived.length
+      ? '这些卡片消失了且没有归档记录：' + unarchived.slice(0, 8).join('、')
+        + (unarchived.length > 8 ? ' 等 ' + unarchived.length + ' 张' : '')
+        + '。契约 §4：要"消失"必须显式移入归档集合并留痕（时间 + 原因）。'
+      : '前后比对无未归档的丢卡（消失 ' + disappeared.length + ' 张，其中已归档 ' + (disappeared.length - unarchived.length) + ' 张）',
+  })
+  const newlyArchived = archived.filter((id) => !beforeSet.has(id))
+
+  // ── M3 重复 id 保护（契约 §2：禁止复用同一个 id 指两个卡片） ──
+  const seen = new Set()
+  const duplicateIds = []
+  for (const id of afterIds) {
+    if (seen.has(id)) { if (!duplicateIds.includes(id)) duplicateIds.push(id) }
+    else seen.add(id)
+  }
+  hard.push({
+    id: 'M3',
+    pass: duplicateIds.length === 0,
+    missing: duplicateIds.slice(),
+    detail: duplicateIds.length
+      ? '写入后同一 id 出现两次：' + duplicateIds.slice(0, 6).join('、') + '。契约 §2 禁止复用同一 id 指两个卡片。'
+      : '写入后无重复 id（' + afterIds.length + ' 张）',
+  })
+
+  // ── M2 用户区保护（无条件；**省略 afterProtectedRegions = fail closed**） ──
+  const prot = Array.isArray(o.protectedRegions) ? o.protectedRegions.filter(Boolean) : []
+  const afterProtRaw = o.afterProtectedRegions
+  const afterProtMissing = !Array.isArray(afterProtRaw)
+  const afterProt = afterProtMissing ? [] : afterProtRaw.filter(Boolean)
+  const afterByKey = new Map(afterProt.map((r) => [String((r && r.key) || ''), String((r && r.digest) || '')]))
+  const lost = []
+  const modified = []
+  for (const r of prot) {
+    const key = String((r && r.key) || '')
+    const want = String((r && r.digest) || '')
+    if (!afterByKey.has(key)) { lost.push(key); continue }
+    if (afterByKey.get(key) !== want) modified.push(key)
+  }
+  const m2pass = !afterProtMissing && lost.length === 0 && modified.length === 0
+  hard.push({
+    id: 'M2',
+    pass: m2pass,
+    missing: lost.concat(modified),
+    detail: afterProtMissing
+      ? '未提供写入后的受保护区域摘要（afterProtectedRegions）⇒ 无法证明用户备注区被保留，按 fail closed 拒绝。'
+        + '（"忘了传"与"真的丢了"在保护语义上必须同样处理。）'
+      : (m2pass
+        ? '受保护区域 ' + prot.length + ' 处全部原样保留（逐摘要比对）'
+        : '受保护区域未原样保留：丢失 ' + lost.length + ' 处、被改动 ' + modified.length + ' 处'
+          + (lost.concat(modified).length ? '（' + lost.concat(modified).slice(0, 6).join('、') + '）' : '')
+          + '。契约 §5：模型整篇重写必须原样带回用户段。'),
+  })
+
+  // ── 软项：只做提示，不拦截（`strict=false` 只影响这里） ──
+  const newCards = afterIds.filter((id) => !beforeSet.has(id))
+  soft.push({
+    id: 'S-cards',
+    pass: true,
+    detail: '新增 ' + newCards.length + ' 张 · 消失 ' + disappeared.length + ' 张（已归档 ' + newlyArchived.length + ' 张）'
+      + ' · 保留 ' + afterIds.filter((id) => beforeSet.has(id)).length + ' 张',
+  })
+  if (strict && beforeIds.length > 0 && afterIds.length === 0) {
+    soft.push({ id: 'S-empty', pass: false, detail: '写入后卡片集合为空（整篇被覆盖成空白板的典型形态）—— 已由 M1 硬拦，此处仅提示' })
+  }
+  if (!strict) {
+    soft.push({ id: 'S-strict-off', pass: true, detail: 'strict=false：已退掉可选质量门（不影响 M1/M2/M3 三条共同保护）' })
+  }
+
+  return report(hard.every((h) => h.pass), target, hard, soft, {
+    disappeared, archived, unarchived, newlyArchived,
+    protectedChecked: prot.length, protectedOk: prot.length - lost.length - modified.length,
+    protectedLost: lost, protectedModified: modified,
+    duplicateIds,
+  })
+}
+
+function emptyReport() {
+  return {
+    disappeared: [], archived: [], unarchived: [], newlyArchived: [],
+    protectedChecked: 0, protectedOk: 0, protectedLost: [], protectedModified: [], duplicateIds: [],
+  }
+}
+
+function report(hardPass, target, hard, soft, r) {
+  return {
+    version: MEMORY_MUTATION_VERSION,
+    target,
+    // gate 名与 WB-GRAPH §2.4 的既有约定一致，便于工具层按 `gate==='criteria'`/`'mutation'` 分支
+    gate: 'mutation',
+    ok: hardPass,
+    hardPass,
+    hard,
+    soft,
+    report: r,
+  }
+}
+
+/**
+ * 把校验报告压成**给模型看的可执行拒绝文案**（不是给作者看的日志）。
+ *
+ * 为什么单独一个函数：拒绝文案要能直接驱动"改写后重试"。缺什么、哪张卡、哪个区，
+ * 必须逐条列出 —— 模型拿到"写入失败"四个字是修不回来的。
+ *
+ * @param {object} res `validateMutationBoundaryPre` 的返回值
+ * @returns {string}
+ */
+export function mutationRefusalTextPre(res) {
+  const r = res && typeof res === 'object' ? res : {}
+  const failed = (Array.isArray(r.hard) ? r.hard : []).filter((h) => !h.pass)
+  if (!failed.length) return ''
+  const lines = failed.map((h) => '· [' + h.id + '] ' + h.detail)
+  return '写入被记忆保护门拦截（' + failed.map((h) => h.id).join('/') + '），原文件未改动：\n' + lines.join('\n')
+    + '\n请修正后重试：消失的卡片要么原样保留，要么显式写入归档集合（并在归档文件里留痕）；'
+    + '每张卡的用户备注区必须原样带回、逐字节不变。'
+}
+
+/**
+ * 便捷入口：把"before 投影 + after 投影"直接对照（两端都由适配器产出）。
+ *
+ * @param {{before:object, after:object, archivedIds?:string[], target?:string, strict?:boolean}} input
+ */
+export function validateProjectionPairPre(input = {}) {
+  const o = input && typeof input === 'object' ? input : {}
+  const before = o.before && typeof o.before === 'object' ? o.before : null
+  const after = o.after && typeof o.after === 'object' ? o.after : null
+  return validateMutationBoundaryPre({
+    target: o.target,
+    strict: o.strict,
+    beforeIds: before ? before.cardIds || before.ids || [] : null,
+    afterIds: after ? after.cardIds || after.ids || [] : null,
+    protectedRegions: before ? before.protectedRegions || [] : [],
+    afterProtectedRegions: after ? after.protectedRegions || [] : undefined,
+    archivedIds: o.archivedIds || [],
+    changes: o.changes,
+  })
+}
+
+/** 受保护区域摘要（给适配器与测试共用的唯一算法：只取 16 位十六进制，够比对、不泄露原文）。 */
+export function protectedRegionDigestPre(text) {
+  return sha(text)
+}