@a9i5k4/dsh-auto-memory 2.5.3 → 3.0.1

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

package/lib/note-status-apply.js

@@ -0,0 +1,118 @@
+/**
+ * 结论层状态 · **条目级应用**（G3 写盘的核心纯函数）
+ *
+ * 职责：把一条 `status` 落到**指定 memoryId 的条目正文末尾**，返回**新文本**（不写盘）。
+ * 与 `note-status.js` 的分工：
+ *   - `note-status.js` = 状态行的**语法**（渲染/解析/剥离）
+ *   - 本模块            = 状态行的**定位与落点**（在文件里找到那条、放到末尾）
+ *
+ * ── 与既有写入通道的关系（重要）───────────────────────────────
+ * 本模块**不代替** `memory-writer` 事务写入，只产出**新全文**；
+ * 落盘仍由调用方走既有通道（备份/校验/无 BOM 等纪律不绕过）。
+ *
+ * ── 为什么必须「只动目标条目」─────────────────────────────────
+ * MEMORY.md 是**用户可见的明文**且 25+ 锚点共存。任何"顺手重排/格式化"都会：
+ *   ① 让无关条目的 `recordDigest` 变化 ⇒ sidecar sourceVersion 无谓 +1 ⇒ 全量缓存失效；
+ *   ② 制造巨大的 diff，用户在 GUI 里看不出"到底改了什么"。
+ * ⇒ 契约：**除目标条目的状态行外，逐字节保持原样**（含 CRLF 行尾）。
+ *
+ * 纪律：纯函数、零 IO、fail-soft（不改动即返回 null，绝不返回半成品文本）。
+ */
+import { NOTE_STATUS_OPEN_V1, renderStatusLinePre, stripStatusLinePre, statusOfBodyPre } from './note-status.js'
+
+/** 锚点：与 `l0-extract.js` / `memory-anchor.js` 同形态（此处独立声明，避免耦合）。 */
+const ANCHOR_RE = /<!--\s*memory:(mem_[0-9a-f]{32})\s*-->/g
+
+/**
+ * 定位一条条目在原文中的**正文区间**。
+ *
+ * 语义与 `parseMemoryItemsPre` 一致：anchor marker **其后**的内容归该条，
+ * 直到**下一个** marker 之前（或文件末尾）。
+ *
+ * @param {string} text 文件全文
+ * @param {string} memoryId
+ * @returns {{start:number, end:number, id:string}|null} 正文的 [start,end) 字符区间
+ */
+export function locateRecordBodyPre(text, memoryId) {
+  try {
+    const src = String(text == null ? '' : text)
+    if (!src || !/^mem_[0-9a-f]{32}$/.test(String(memoryId || ''))) return null
+    ANCHOR_RE.lastIndex = 0
+    const marks = []
+    let m
+    while ((m = ANCHOR_RE.exec(src)) !== null) {
+      // 同时记录 marker 的**真实**起止（不重建字符串 —— 锚点允许空白浮动）
+      marks.push({ id: m[1], start: m.index, end: m.index + m[0].length })
+      if (m.index === ANCHOR_RE.lastIndex) ANCHOR_RE.lastIndex++
+    }
+    for (let i = 0; i < marks.length; i++) {
+      if (marks[i].id !== memoryId) continue
+      const start = marks[i].end
+      // 正文止于**下一个 marker 的起始**（该 marker 及其后内容不属于本条）
+      const end = i + 1 < marks.length ? marks[i + 1].start : src.length
+      return { start, end, id: memoryId }
+    }
+    return null
+  } catch (_) { return null }
+}
+
+/**
+ * ★ 主函数：给指定条目应用状态，返回**新全文**。
+ *
+ * 行为契约：
+ *   - 目标不存在 ⇒ `null`（**fail-soft**：绝不凭空创建条目）
+ *   - `status === 'current'` ⇒ **剥掉**既有状态行（撤销通道；正文其余不变）
+ *   - 已是目标状态且 reason/by 未变 ⇒ 返回**原文**（幂等，调用方可据此跳过写盘）
+ *   - 其余 ⇒ 剥旧状态行 + 在**正文末尾**追加新状态行
+ *   - **行尾风格沿用原文件**（CRLF 保持 CRLF；本仓文件全 CRLF）
+ *   - 任何异常 ⇒ `null`（绝不返回半成品）
+ *
+ * @param {string} text 文件全文
+ * @param {string} memoryId 目标条目
+ * @param {string} status current | superseded | retracted
+ * @param {{supersededBy?:string, reason?:string}} [opts]
+ * @returns {string|null} 新全文；不可应用时为 null
+ */
+export function applyStatusToRecordPre(text, memoryId, status, opts = {}) {
+  try {
+    const src = String(text == null ? '' : text)
+    if (!src) return null
+    const loc = locateRecordBodyPre(src, memoryId)
+    if (!loc) return null
+
+    const seg = src.slice(loc.start, loc.end)
+    // CRLF 感知：本仓文件全 CRLF，必须沿用，否则整文件 diff 爆炸
+    const eol = seg.includes('\r\n') ? '\r\n' : '\n'
+
+    // 先把段落按当前 EOL 归一化切分，处理后再拼回
+    const bodyClean = stripStatusLinePre(seg)
+    const trimmed = bodyClean.replace(/[\r\n\s]+$/, '')
+
+    const line = renderStatusLinePre(status, opts)
+    let next = line ? trimmed + eol + line + eol : (trimmed ? trimmed + eol : '')
+    // 段落与下一个 marker 之间保留一个空行（与既有文件形态一致）
+    next = next ? next + eol : next
+
+    const out = src.slice(0, loc.start) + next + src.slice(loc.end)
+    // 幂等：无变化 ⇒ 返回原文（调用方可据此跳过写盘，避免无谓 sourceVersion +1）
+    return out === src ? src : out
+  } catch (_) { return null }
+}
+
+/**
+ * 只读查询：某条目当前状态（供接线侧判断是否需要写）。
+ * 与 `statusOfBodyPre` 同源，此处补上「文件级」定位。
+ *
+ * @returns {{status:string, supersededBy?:string, reason?:string}|null} 条目不存在 ⇒ null
+ */
+export function readRecordStatusPre(text, memoryId) {
+  try {
+    const src = String(text == null ? '' : text)
+    const loc = locateRecordBodyPre(src, memoryId)
+    if (!loc) return null
+    return statusOfBodyPre(src.slice(loc.start, loc.end))
+  } catch (_) { return null }
+}
+
+/** 供反向锁使用：确认本模块**不碰锚点语法**。 */
+export const NOTE_STATUS_MARKER_V1 = NOTE_STATUS_OPEN_V1