sage-mem 2.1.6 → 2.1.7

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.1.6`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
+**Current release: `2.1.7`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
 [frozen contract](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md).
 
 If it is useful to you, a Star is the most direct feedback.

package/README.zh.md

@@ -14,7 +14,7 @@
 
 > File-based cross-session memory for DeepSeek Harness — every memory is a plain markdown file you can open, edit and delete. No database, no worker, no port.
 
-**当前发布版本：`2.1.6`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.7`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。

package/lib/autodream/rollback.js

@@ -11,9 +11,9 @@ import { readJson, safeName, snapshotEntries, stampCompact, stampHuman } from '.
 import { restoreMemory } from '../memory/archive.js'
 import { nameKey } from '../memory/naming.js'
 import { stripArchiveMeta } from '../memory/scan.js'
-import { writeFileAtomic } from '../memory/util.js'
+import { writeFileAtomic, moveFileExclusive } from '../memory/util.js'
 import { randomUUID } from 'node:crypto'
-import { chmod, link, lstat, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { chmod, lstat, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
 import { basename, dirname, join } from 'node:path'
 
 /** 读回滚留痕（面板也许要显示「最近谁退回过」）。 */
@@ -230,26 +230,19 @@ export async function rollback(opts = {}) {
     await mkdir(archiveDir, { recursive: true })
 
     /**
-     * **排他移动**：先 `link` 到目标（目标已存在 → `EEXIST`，绝不覆盖），成功后再删源。
+     * **排他移动**用 `memory/util.js` 的公共原语 `moveFileExclusive`（2026-10-31 外部审查 Q11）：
+     * 归档 / 恢复 / 回滚只有**一份**实现，避免「公共那侧改了、这边还留着旧降级」的漂移。
      *
      * 为什么不能 `stat → rename`（复审复核实测构造出了覆盖）：`rename` 在目标已存在时
      * **静默覆盖**，而 `stat` 与 `rename` 之间正是别人（面板 / 模型工具的 `archiveMemory`，
      * 它们不取 autodream 这把锁）可能刚把同名归档写进去的窗口 —— 与 R06② 同一类：
-     * 第二次系统调用没有存在性前提。而本函数的注释一直承诺「绝不覆盖」，代码却做不到。
+     * 第二次系统调用没有存在性前提。
      *
-     * 平台不支持硬链接 / 跨卷时退回 `rename`（与 `memory/util.js` 那边的降级口径一致），
-     * 那是已知降级；NTFS / APFS / ext4 上走的是排他路径。
+     * 旧私有实现在「link 不支持」时退回 `rename`，注释写着「与 util 一致」却早已失实：
+     * 目标已存在时那份**历史旧归档**会被当前文件顶掉，回滚还报 ok:true。公共原语现在的
+     * 降级是「COPYFILE_EXCL 排他复制 → 校验 → 才删源」，无法识别的错误直接失败、不默认 rename。
      */
-    const moveExclusive = async (from, to) => {
-      try {
-        await link(from, to)
-      } catch (err) {
-        if (err?.code === 'EEXIST') throw err
-        await rename(from, to)
-        return
-      }
-      await rm(from, { force: true })
-    }
+    const moveExclusive = moveFileExclusive
 
     /**
      * 移进 archive/（不删）。同名时**换一个退役名**落进去，绝不覆盖，也绝不放弃。

package/lib/memory/util.js

@@ -2,8 +2,9 @@
  * sage-mem 记忆层 —— 通用小工具：统一日志出口与原子写。
  */
 
+import { constants } from 'node:fs'
 import { randomUUID } from 'node:crypto'
-import { link, open, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises'
+import { copyFile, link, open, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises'
 
 /**
  * 统一告警出口。所有非 ENOENT 的失败都必须落到日志，绝不静默
@@ -125,6 +126,66 @@ export async function writeFileExclusive(target, content) {
   return { exclusive }
 }
 
+/**
+ * **排他移动**：把 `from` 移到 `to`，目标已存在时原子地报 `EEXIST`（绝不覆盖），
+ * 成功后删源。归档 / 回滚把「不该再留在顶层的文件」移进 `archive/` 时共用这一份。
+ *
+ * 为什么要有它（2026-10-31 外部审查 Q11）：`rename` 在 POSIX 上会**静默覆盖**已存在的
+ * 目标。回滚的旧私有实现是「`link` 失败（非 EEXIST）就 `rename`」—— 在少数网络盘 /
+ * exFAT 上 link 报 EPERM/ENOTSUP，于是一份**历史旧归档**被当前文件顶掉，而回滚报成功。
+ * 「先 stat 再 rename」也修不了：两次系统调用之间正是别人写同名文件的位置。
+ *
+ * 两条路：
+ *   1. **硬链接**（首选）：`link` 在目标存在时原子报 EEXIST；成功后再删源 —— 一次性原子可见；
+ *   2. **降级**（link 不可用）：`copyFile(…, COPYFILE_EXCL)` 排他复制，逐字节校验**之后**
+ *      才删源。降级失去的是「一次性原子可见」，**不能同时放弃「不覆盖已有内容」**。
+ *
+ * ⚠️ 无法识别的错误直接失败，**绝不默认 `rename`** —— 那正是这次修掉的 bug。
+ * 任何一步失败都保证**源原样保留**、目标不留半截（源是唯一内容时不丢）。
+ *
+ * @returns {Promise<{exclusive:boolean}>} `exclusive:false` = 走的是复制降级（诊断用，不改变成败判定）
+ */
+export async function moveFileExclusive(from, to) {
+  try {
+    await link(from, to)
+  } catch (err) {
+    // 目标已存在：这是**预期**的拒绝，原样抛给调用方（它负责换退役名）。
+    if (err?.code === 'EEXIST') throw err
+    if (!LINK_UNSUPPORTED_CODES.has(err?.code)) throw err
+    return copyMoveExclusive(from, to)
+  }
+  try {
+    await rm(from, { force: true })
+  } catch (err) {
+    // link 成功后 from/to 是同一 inode：删源失败时把**新名字**收回去，让调用方能干净重试。
+    await rm(to, { force: true }).catch(() => {})
+    throw err
+  }
+  return { exclusive: true }
+}
+
+/** 降级路径：排他复制 → 逐字节校验 → 删源；任何一步失败都删掉半成品、源原样保留。 */
+async function copyMoveExclusive(from, to) {
+  await copyFile(from, to, constants.COPYFILE_EXCL)
+  try {
+    const [srcBytes, dstBytes] = await Promise.all([readFile(from), readFile(to)])
+    if (Buffer.compare(srcBytes, dstBytes) !== 0) {
+      throw Object.assign(new Error(`sage-mem: 复制 ${from} → ${to} 后内容不一致，已放弃（源未动）`), { code: 'EIO' })
+    }
+  } catch (err) {
+    await rm(to, { force: true }).catch(() => {})
+    throw err
+  }
+  try {
+    await rm(from, { force: true })
+  } catch (err) {
+    // 源删不掉：目标已经是校验过的完整副本，把它删掉让调用方能干净重试（源还在，不丢内容）。
+    await rm(to, { force: true }).catch(() => {})
+    throw err
+  }
+  return { exclusive: false }
+}
+
 /**
  * **事务式接管源文件**：把源 `rename` 到只有本次调用知道的私有名，再逐字节核对
  * 它是不是调用方读到的那些字节。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sage-mem",
   "description": "Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.",
-  "version": "2.1.6",
+  "version": "2.1.7",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./icon.png",