@a9i5k4/dsh-auto-memory 2.5.2 → 3.0.0

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)
+}

package/lib/memory-writer.js

@@ -17,8 +17,10 @@ import { createHash, randomUUID } from 'node:crypto'
 import { promises as fsDefault } from 'node:fs'
 import {
   parseAnchors, buildSidecar, parseSidecar, newMemoryId, MEMORY_ID_RE, ANCHOR_PREFIX, detectNewline,
+  MARKER_OPEN, checkReservedSyntaxInContent,
 } from './memory-anchor.js'
 import { INDEX_MAX_FILE_BYTES } from './memory-index.js'
+import { retryRename } from './fs-retry.js'
 
 function sha256Hex(buf) {
   return createHash('sha256').update(buf).digest('hex')
@@ -40,6 +42,28 @@ function markerBuf(memoryId, nl) {
   return Buffer.from('<!-- memory:' + memoryId + ' -->' + nl, 'utf8')
 }
 
+/**
+ * issue #54 P1（可诊断性）：把 `parseAnchors` 的 conflicts 格式化为**带行号**的 reason。
+ *
+ * 旧实现统一 `.map(c => c.type)` ⇒ 丢掉 `line`/`byteStart`/`byteEnd`
+ * （`memory-anchor.js:184` 其实已经算好了），报错只说"冲突"，
+ * 使用者（和模型）无从定位是哪一行，也不知道是自己这次写入引入的还是文件本来就有。
+ *
+ * 保持 `conflict:` 前缀不变（既有测试断言 `reason.startsWith('conflict')`）。
+ * @param {Array} conflicts parseAnchors 返回的冲突对象数组
+ * @returns {string} 形如 `conflict:orphan-content@12`（多个以 `,` 连接）
+ */
+function formatConflicts(conflicts) {
+  return 'conflict:' + (conflicts || [])
+    .map((c) => c.type + (Number.isFinite(c.line) ? '@' + c.line : ''))
+    .join(',')
+}
+
+/** issue #54 P0：写入路径统一的保留语法前置校验（复用 memory-anchor-pre 的同一判据）。 */
+function reservedSyntaxGuard(text) {
+  return checkReservedSyntaxInContent(text)
+}
+
 /** 逆序插入 marker 到指定行首位置(批次内部按 atByte 升序传入)。 */
 function insertMarkers(buf, inserts, nl) {
   let out = buf
@@ -65,7 +89,7 @@ export function applyMigrationPlan(content, plan) {
   if (plan.expectedFileDigest !== sha256Hex(buf)) return { ok: false, reason: 'stale-plan' }
   const parsed = parseAnchors(buf)
   if (parsed.status === 'oversized') return { ok: false, reason: 'oversized' }
-  if (parsed.status !== 'clean') return { ok: false, reason: 'conflict:' + parsed.conflicts.map((c) => c.type).join(',') }
+  if (parsed.status !== 'clean') return { ok: false, reason: formatConflicts(parsed.conflicts), conflicts: parsed.conflicts }
   const pending = plan.operations.filter((op) => op && op.kind === 'insert-anchor')
   if (!pending.length) return { ok: true, applied: 0, text: buf }
   const legacyStarts = new Set(parsed.records.filter((r) => r.kind === 'legacy').map((r) => r.byteStart))
@@ -95,11 +119,14 @@ export function applyMigrationPlan(content, plan) {
 export function appendAnchoredRecord(content, { memoryId, text }) {
   if (typeof memoryId !== 'string' || !MEMORY_ID_RE.test(memoryId)) return { ok: false, reason: 'bad-id' }
   if (typeof text !== 'string' || !text.trim()) return { ok: false, reason: 'empty-record' }
+  // issue #54 P0:先校验**本次要写的正文**,再校验文件已有内容——顺序不可颠倒。
+  const guard = reservedSyntaxGuard(text)
+  if (!guard.ok) return { ok: false, reason: guard.reason, line: guard.line, detail: guard.detail }
   const buf = toBuf(content)
   if (buf.length > INDEX_MAX_FILE_BYTES) return { ok: false, reason: 'oversized' }
   const parsed = parseAnchors(buf)
   if (parsed.status === 'oversized') return { ok: false, reason: 'oversized' }
-  if (parsed.status !== 'clean') return { ok: false, reason: 'conflict:' + parsed.conflicts.map((c) => c.type).join(',') }
+  if (parsed.status !== 'clean') return { ok: false, reason: formatConflicts(parsed.conflicts), conflicts: parsed.conflicts }
   if (parsed.records.some((r) => r.kind === 'anchored' && r.memoryId === memoryId)) return { ok: false, reason: 'duplicate-id' }
   const nl = parsed.newline === 'crlf' ? '\r\n' : '\n'
   const body = toEol(text, parsed.newline)
@@ -127,10 +154,10 @@ export function renderReplace(content, replacement, opts = {}) {
   if (rep.length > INDEX_MAX_FILE_BYTES) return { ok: false, reason: 'oversized-replacement' }
   const oldParsed = parseAnchors(oldBuf)
   if (oldParsed.status === 'oversized') return { ok: false, reason: 'oversized' }
-  if (oldParsed.status !== 'clean') return { ok: false, reason: 'conflict:' + oldParsed.conflicts.map((c) => c.type).join(',') }
+  if (oldParsed.status !== 'clean') return { ok: false, reason: formatConflicts(oldParsed.conflicts), conflicts: oldParsed.conflicts }
   const rp = parseAnchors(rep)
   if (rp.status === 'oversized') return { ok: false, reason: 'oversized-replacement' }
-  if (rp.status !== 'clean') return { ok: false, reason: 'conflict:' + rp.conflicts.map((c) => c.type).join(','), conflicts: rp.conflicts }
+  if (rp.status !== 'clean') return { ok: false, reason: formatConflicts(rp.conflicts), conflicts: rp.conflicts }
   const oldIds = new Set(oldParsed.records.filter((r) => r.kind === 'anchored' && r.memoryId).map((r) => r.memoryId))
   const idFactory = (typeof opts.idFactory === 'function' ? opts.idFactory : newMemoryId)
   const used = new Set(oldIds)
@@ -169,11 +196,14 @@ export function renderReplace(content, replacement, opts = {}) {
 export function replaceSingleRecord(content, text, opts = {}) {
   const body = typeof text === 'string' ? text : String(text == null ? '' : text)
   if (!body.trim()) return { ok: false, reason: 'empty-record' }
+  // issue #54 P0:单记录写入的正文**整段都是内容**(marker 由本函数生成),故正文内出现保留语法必属误用 ⇒ 前置拒绝。
+  const guard = reservedSyntaxGuard(body)
+  if (!guard.ok) return { ok: false, reason: guard.reason, line: guard.line, detail: guard.detail }
   const oldBuf = toBuf(content)
   if (oldBuf.length > INDEX_MAX_FILE_BYTES) return { ok: false, reason: 'oversized' }
   const oldParsed = parseAnchors(oldBuf)
   if (oldParsed.status === 'oversized') return { ok: false, reason: 'oversized' }
-  if (oldParsed.status !== 'clean') return { ok: false, reason: 'conflict:' + oldParsed.conflicts.map((c) => c.type).join(',') }
+  if (oldParsed.status !== 'clean') return { ok: false, reason: formatConflicts(oldParsed.conflicts), conflicts: oldParsed.conflicts }
   const idFactory = typeof opts.idFactory === 'function' ? opts.idFactory : newMemoryId
   const used = new Set(oldParsed.records.filter((r) => r.kind === 'anchored').map((r) => r.memoryId))
   let memoryId
@@ -186,7 +216,7 @@ export function replaceSingleRecord(content, text, opts = {}) {
   const nl = detectNewline(oldBuf.length ? oldBuf : Buffer.from(body, 'utf8')) === 'crlf' ? '\r\n' : '\n'
   const candidate = Buffer.concat([markerBuf(memoryId, nl), Buffer.from(toEol(body, nl), 'utf8')])
   const check = parseAnchors(candidate)
-  if (check.status !== 'clean') return { ok: false, reason: 'conflict:' + check.conflicts.map((c) => c.type).join(','), conflicts: check.conflicts }
+  if (check.status !== 'clean') return { ok: false, reason: formatConflicts(check.conflicts), conflicts: check.conflicts }
   const anchored = check.records.filter((r) => r.kind === 'anchored')
   if (anchored.length !== 1 || anchored[0].memoryId !== memoryId) return { ok: false, reason: 'not-single-record' }
   return { ok: true, text: candidate, memoryId }
@@ -194,24 +224,70 @@ export function replaceSingleRecord(content, text, opts = {}) {
 
 /**
  * 原子替换默认 fs 适配器之外的注入目标(测试故障注入/sidecar 目录等)。
- * 同目录临时文件 + fsync + rename;任何失败清理临时文件并抛出。
+ * 同目录临时文件 + fsync + **有界 rename 重试**(issue #48);替换失败保留完整候选快照,不覆盖回放。
+ *
+ * 2026-09-16 修正(issue #48):旧实现 rename 一次失败即硬失败并 unlink 临时文件,
+ * 在 Windows 并发子代理下(DSH 仍持有目标句柄)会把本可成功的写入连残骸一起丢掉。
+ * 现在:① 瞬时错误码(EPERM/EACCES/EBUSY)走退避重试;② 仍失败则把**完整候选快照**
+ * 改名保留为 `.dam-failed-*.tmp` 并在错误上回传 `recoveryPath`,由调用方人工比对
+ * (候选是**整篇快照**而非追加指令,绝不允许自动回放——期间可能有别的写入者推进了目标)。
  */
-export async function atomicReplace(target, data, fsApi = fsDefault) {
+export async function atomicReplace(target, data, fsApi = fsDefault, opts = {}) {
   const dir = path.dirname(target)
-  const tmp = path.join(dir, '.dam-pre-tmp-' + randomUUID().slice(0, 8) + '-' + path.basename(target))
+  const nonce = randomUUID()
+  // .tmp 后缀保证 待处理/恢复 快照不进入 *.md / *.json 扫描(见 issue #51 同类问题)
+  const tmp = path.join(dir, '.dam-pre-tmp-' + nonce + '-' + path.basename(target) + '.tmp')
   await fsApi.mkdir(dir, { recursive: true })
   let handle = null
+  let created = false
+  let complete = false
+  let stage = 'open'
   try {
-    handle = await fsApi.open(tmp, 'w')
+    // 独占创建:碰撞时绝不截断/删除别人的临时文件
+    handle = await fsApi.open(tmp, 'wx', 0o600)
+    created = true
+    stage = 'write'
     await handle.writeFile(data)
+    stage = 'sync'
     await handle.sync()
+    stage = 'close'
     await handle.close()
     handle = null
-    await fsApi.rename(tmp, target)
-  } catch (e) {
+    complete = true
+    stage = 'rename'
+    await retryRename(tmp, target, { fs: fsApi, delays: opts.renameDelays, sleep: opts.sleep })
+  } catch (cause) {
     if (handle) { try { await handle.close() } catch (_) {} }
-    try { await fsApi.unlink(tmp) } catch (_) {}
-    throw e
+    const details = { stage, targetPath: target, recoveryComplete: false }
+    if (created && complete && opts.preserveOnFailure !== false) {
+      // 这是**整篇文档的候选快照**,不是追加指令 —— 绝不自动回放(别的写入者可能已推进目标)。
+      let recoveryPath = tmp
+      const failed = path.join(dir, '.dam-failed-' + Date.now() + '-' + nonce + '-' + path.basename(target) + '.tmp')
+      try { await fsApi.rename(tmp, failed); recoveryPath = failed } catch (_) {
+        // 恢复用的 rename 本身也可能被占用 ⇒ 保留原临时路径
+      }
+      try {
+        const retained = await fsApi.stat(recoveryPath)
+        if (!retained.isFile()) throw new Error('recovery snapshot is not a file')
+        details.recoveryPath = recoveryPath
+        details.recoveryComplete = true
+      } catch (_) {
+        // 快照可能已被扫描器/其它进程移走 —— 不能仅凭"本函数没 unlink"就宣称保全成功
+        details.recoveryUnavailable = true
+      }
+    } else if (created) {
+      try { await fsApi.unlink(tmp) } catch (cleanupError) {
+        details.partialPath = tmp
+        details.cleanupCode = cleanupError && cleanupError.code
+      }
+    }
+    // 默认保留原始 fs 错误(含 code/errno/syscall/path/dest)。
+    // 冻结/非 Error 抛出不得用 TypeError 掩盖真实写入失败。
+    const error = cause instanceof Error && Object.isExtensible(cause)
+      ? cause : new Error(cause && cause.message ? cause.message : String(cause), { cause })
+    if (error !== cause && cause && typeof cause.code === 'string') error.code = cause.code
+    Object.assign(error, details)
+    throw error
   }
 }
 
@@ -222,6 +298,39 @@ export async function atomicReplace(target, data, fsApi = fsDefault) {
  * expectedDigest 不匹配(外部编辑) → 拒绝且不写。同文件并发写经队列串行,不丢失。
  * fs/sidecarDir/backupDir 可注入(故障注入测试);sidecarDir 未配置则不做 sidecar 落盘。
  */
+// 同一 fs 后端共享队列(注入的虚拟文件系统之间仍互相隔离)。**注意:这不是跨进程锁。**
+const queuesByFs = new WeakMap()
+function queuesFor(fsApi) {
+  let queues = queuesByFs.get(fsApi)
+  if (!queues) { queues = new Map(); queuesByFs.set(fsApi, queues) }
+  return queues
+}
+
+/** 队列键:Windows 下大小写不敏感且需规范化,避免同一文件两条队列并行。 */
+export function memoryWriteLockKey(filePath, platform = process.platform) {
+  const resolved = (platform === 'win32' ? path.win32 : path.posix).resolve(filePath)
+  return platform === 'win32' ? resolved.toLowerCase() : resolved
+}
+
+/** 把 store 的结构化写状态保留成 Error（issue #48）：写入失败不可降级为一句无信息的文案。 */
+export function memoryWriteError(operation, result) {
+  let message = 'memory-anchor-' + operation + '-failed:' + result.reason
+  if (result.recoveryPath) {
+    message += '; recoveryPath=' + JSON.stringify(result.recoveryPath) +
+      '; recovery is a candidate snapshot, compare with current document before manual recovery'
+  }
+  if (result.partialPath) message += '; partialPath=' + JSON.stringify(result.partialPath) + '; incomplete, not safe to restore'
+  if (result.written === true) message += '; written=true, verify current document before retrying'
+  const error = new Error(message)
+  error.code = result.errorCode || (result.written === true ? 'MEMORY_WRITE_VERIFY_FAILED' : 'MEMORY_WRITE_FAILED')
+  error.fsCode = result.fsCode
+  error.written = result.written === true
+  error.recoveryPath = result.recoveryPath
+  error.recoveryComplete = result.recoveryComplete === true
+  error.partialPath = result.partialPath
+  return error
+}
+
 export class MemoryDocumentStore {
   constructor(opts = {}) {
     this.fs = opts.fs || fsDefault
@@ -229,11 +338,12 @@ export class MemoryDocumentStore {
     this.backupDir = opts.backupDir || null
     this.now = opts.now || (() => Date.now())
     this.idFactory = opts.idFactory || newMemoryId
-    this._locks = new Map()
+    this._locks = queuesFor(this.fs)
+    this.atomicOptions = opts.atomicOptions || {}
   }
 
   _queue(filePath, job) {
-    const key = path.resolve(filePath)
+    const key = memoryWriteLockKey(filePath)
     const prev = this._locks.get(key) || Promise.resolve()
     const run = prev.then(job, job)
     const settled = run.then(() => {}, () => {})
@@ -247,13 +357,68 @@ export class MemoryDocumentStore {
     try {
       const buf = await this.fs.readFile(filePath)
       const parsed = parseAnchors(buf)
-      return { buf, parsed, fileDigest: sha256Hex(buf) }
+      // P1 步 3：状态版本（`expectedStateVersion`）取自 sidecar 的 `sourceVersion` + `epoch`。
+      // 仅当 sidecarDir 配置且 sidecar 可读时才有值；否则为 null ⇒ 状态闸按 "(unknown)" 拒绝
+      // （fail-closed：证明不了"同一版本"就不写，与身份门的既有口径一致）。
+      let stateVersion = null
+      if (this.sidecarDir) {
+        const cur = await this.readSidecar(filePath)
+        if (cur && cur.ok && cur.sidecar) {
+          const sv = cur.sidecar.sourceVersion
+          const ep = cur.sidecar.epoch
+          if (sv != null) stateVersion = (ep != null ? String(ep) + ':' : '') + String(sv)
+        }
+      }
+      return { buf, parsed, fileDigest: sha256Hex(buf), stateVersion }
     } catch (e) {
-      if (e && e.code === 'ENOENT') return { buf: null, parsed: null, fileDigest: null }
+      if (e && e.code === 'ENOENT') return { buf: null, parsed: null, fileDigest: null, stateVersion: null }
       throw e
     }
   }
 
+  /**
+   * ★2026-09-15（P1 步 3 · 设计稿 §2.3）：**提交边界内**的版本校验（并发原子边界）。
+   *
+   * **为什么必须在这里、而不是调用方**：P1 卡明确 —— "两个写者都先读 D、都通过比较、再分别
+   * 写 A 和 B ⇒ 后写者仍会覆盖前写者"。唯一正确的做法是让"读当前状态 → 比较 → 写"三步
+   * **在同一个队列任务内**完成（`_queue` 按路径串行，见 `:235`）。本助手只被 `_queue(...)`
+   * **内部**调用，因此天然满足该边界；绝不要在队列外用它做预检。
+   *
+   * 双闸（各自独立，都可单独启用）：
+   *   - `expectedDigest`：字节级（防"用户改了文件"）—— 既有语义，保持不动。
+   *   - `expectedStateVersion`：状态级（防"另一个窗口改了图/换了状态"）—— P1 新增。
+   *
+   * **兼容档（T1-8）**：两者都可缺省；缺省即不校验，行为与 P1 之前**逐字节一致**。
+   * **可见冲突（T1-7C）**：拒绝时带 `expected/observed/target`，由调用方决定是否渲染成文本。
+   *
+   * ⚠️ 副作用零：只读 `state` 入参，不写盘、不改 state。
+   */
+  _checkCommitBoundary(filePath, state, opts) {
+    const target = String(filePath || '')
+    const wantsDigest = opts.expectedDigest != null
+    const wantsStateVersion = opts.expectedStateVersion != null
+    // ① 字节闸（既有语义）：不匹配 ⇒ 拒绝且不写
+    if (wantsDigest && state.fileDigest !== opts.expectedDigest) {
+      return {
+        ok: false,
+        reason: 'conflict-external-edit',
+        conflict: { kind: 'digest', target, expected: String(opts.expectedDigest), observed: state.fileDigest == null ? '(missing)' : String(state.fileDigest) },
+      }
+    }
+    // ② 状态闸（P1 新增）：sidecar 的 sourceVersion 为状态版本；无 sidecar/无 prev 时视为 unknown
+    if (wantsStateVersion) {
+      const cur = state.stateVersion == null ? null : String(state.stateVersion)
+      if (cur !== String(opts.expectedStateVersion)) {
+        return {
+          ok: false,
+          reason: 'conflict-state-version',
+          conflict: { kind: 'state-version', target, expected: String(opts.expectedStateVersion), observed: cur == null ? '(unknown)' : cur },
+        }
+      }
+    }
+    return { ok: true }
+  }
+
   /** sidecar 路径:sidecarDir + '<sha256(canonicalSourcePath)>.json'(契约 §6;canonical=resolve+正斜杠+小写)。 */
   sidecarPath(filePath) {
     if (!this.sidecarDir) return null
@@ -266,7 +431,9 @@ export class MemoryDocumentStore {
     const sp = this.sidecarPath(filePath)
     if (!sp) throw new Error('no-sidecar-dir')
     await this.fs.mkdir(path.dirname(sp), { recursive: true })
-    await atomicReplace(sp, Buffer.from(JSON.stringify(sidecar, null, 2) + '\n', 'utf8'), this.fs)
+    // sidecar 是**可重建的派生数据**:失败时保留候选快照只会积累垃圾,故显式关闭 preserveOnFailure
+    // (与 Markdown 正文档相反——正文档失败必须保住快照供人工比对)。
+    await atomicReplace(sp, Buffer.from(JSON.stringify(sidecar, null, 2) + '\n', 'utf8'), this.fs, { ...this.atomicOptions, preserveOnFailure: false })
   }
 
   /** 读已落盘 sidecar;损坏返回 {ok:false,reason} 由调用方隔离并从 Markdown 重建。 */
@@ -297,9 +464,16 @@ export class MemoryDocumentStore {
       }
     }
     try {
-      await atomicReplace(filePath, out, this.fs)
+      await atomicReplace(filePath, out, this.fs, this.atomicOptions)
     } catch (e) {
-      return { ok: false, reason: 'write-failed:' + (e && e.message ? e.message : String(e)) }
+      // issue #48:结构化保留失败态(含 recoveryPath/partialPath),供上层给出可操作报错
+      return {
+        ok: false, reason: 'write-failed:' + (e && e.message ? e.message : String(e)),
+        errorCode: 'MEMORY_WRITE_FAILED', fsCode: e && e.code, written: false,
+        recoveryPath: e && e.recoveryPath, recoveryComplete: !!(e && e.recoveryComplete),
+        partialPath: e && e.partialPath, stage: e && e.stage,
+        recoveryUnavailable: !!(e && e.recoveryUnavailable),
+      }
     }
     let reread
     try { reread = await this.fs.readFile(filePath) } catch (e) { return { ok: false, reason: 'verify-read-failed', written: true } }
@@ -331,7 +505,8 @@ export class MemoryDocumentStore {
   append(filePath, text, opts = {}) {
     return this._queue(filePath, async () => {
       const state = await this._readState(filePath)
-      if (opts.expectedDigest != null && state.fileDigest !== opts.expectedDigest) return { ok: false, reason: 'conflict-external-edit' }
+      const gate = this._checkCommitBoundary(filePath, state, opts)
+      if (!gate.ok) return gate
       const memoryId = opts.memoryId || this.idFactory()
       const app = appendAnchoredRecord(state.buf, { memoryId, text })
       if (!app.ok) return app
@@ -344,7 +519,8 @@ export class MemoryDocumentStore {
   replace(filePath, replacement, opts = {}) {
     return this._queue(filePath, async () => {
       const state = await this._readState(filePath)
-      if (opts.expectedDigest != null && state.fileDigest !== opts.expectedDigest) return { ok: false, reason: 'conflict-external-edit' }
+      const gate = this._checkCommitBoundary(filePath, state, opts)
+      if (!gate.ok) return gate
       const rr = renderReplace(state.buf, replacement, { idFactory: opts.idFactory || this.idFactory })
       if (!rr.ok) return rr
       const res = await this._commit(filePath, rr.text, { prevSidecar: opts.prevSidecar })
@@ -356,7 +532,8 @@ export class MemoryDocumentStore {
   replaceSingle(filePath, text, opts = {}) {
     return this._queue(filePath, async () => {
       const state = await this._readState(filePath)
-      if (opts.expectedDigest != null && state.fileDigest !== opts.expectedDigest) return { ok: false, reason: 'conflict-external-edit' }
+      const gate = this._checkCommitBoundary(filePath, state, opts)
+      if (!gate.ok) return gate
       const rr = replaceSingleRecord(state.buf, text, { idFactory: opts.idFactory || this.idFactory })
       if (!rr.ok) return rr
       const res = await this._commit(filePath, rr.text, { prevSidecar: opts.prevSidecar })
@@ -368,6 +545,9 @@ export class MemoryDocumentStore {
   applyPlan(filePath, plan, opts = {}) {
     return this._queue(filePath, async () => {
       const state = await this._readState(filePath)
+      // P1 步 3：本方法同样写盘 ⇒ 必须走同一边界校验（此前它连 expectedDigest 都未检查）
+      const gate = this._checkCommitBoundary(filePath, state, opts)
+      if (!gate.ok) return gate
       const ap = applyMigrationPlan(state.buf, plan)
       if (!ap.ok) return ap
       const res = await this._commit(filePath, ap.text, { prevSidecar: opts.prevSidecar })