sage-mem 2.2.0 → 2.2.1

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.2.0`** — 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.2.1`** — 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.2.0`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.2.1`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。

package/lib/autodream/engine.js

@@ -35,6 +35,7 @@
 
 import { auditMemoryDir } from './audit.js'
 import { autodreamToolSchemas, createToolRunner } from './tools.js'
+import { warnLog } from '../memory/util.js'
 import { CONFIG_VERSION, DEFAULT_CONFIG, DEFAULT_TOKEN_BUDGET, FAILURE_BACKOFF_MS, FEATURE_DIR, LEGACY_SNAPSHOT_DIR, LEGACY_STATE_FILE, SCHEDULE_INTERVAL_MS, STARTUP_CHECK_DELAY_MS, STATE_DIR } from './config.js'
 import { countSessionsSince, newRunId, stampHuman } from './util.js'
 import { flushAccess, ledgerFileFor, pickArchiveCandidates, readAccessLedger } from '../memory/access.js'
@@ -131,11 +132,10 @@ export class AutodreamEngine {
   }
 
   log(level, msg) {
-    const line = `sage-mem autodream: ${msg}`
-    const logger = this.ctx?.logger
-    if (level === 'error' && logger?.error) logger.error(line)
-    else if (logger?.warn) logger.warn(line)
-    else console.warn(line)
+    // 2.2.1：统一走 warnLog —— 前缀 `sage-mem: `，子系统名进正文。原来这里手搓了第二套
+    // logger（`sage-mem autodream: ` 前缀 + 自己的 fallback），与 util.js「所有失败都要落到
+    // 日志」那条规则重复，而且日志里因此出现两种前缀。
+    warnLog(this.ctx, `autodream${level === 'error' ? ' [error]' : ''}: ${msg}`)
   }
 
   // ────────────────────────────── 配置与状态 ──────────────────────────────

package/lib/client.js

@@ -113,6 +113,11 @@ window.__ModuleLoader__.load({
 		 * 那种情况下**不能**把目标当成「不存在」去覆盖写（2.1.10 / Q10 的教训）。
 		 */
 		function isNotFoundError(error) {
+			// 2.2.1：**优先看结构化码** —— 宿主读方法现在抛带 `.code` 的 Error
+			// （not_found / invalid_name / reserved / io_error…）。文案正则只留兜底：
+			// 换一句措辞就会让降级链走错边，那是 2026-11-01 真机踩过的形状。
+			const code = error && error.code;
+			if (code === "not_found" || code === "missing" || code === "ENOENT") return true;
 			return /ENOENT|no such file|not exist/i.test(String((error && error.message) || error));
 		}
 
@@ -137,7 +142,12 @@ window.__ModuleLoader__.load({
 				throw error;
 			};
 			return call.then(function (result) {
-				if (result && result.ok === false && result.error) return classify(result.error);
+				if (result && result.ok === false) {
+					// 2.2.1：结构化码在**信封外层**（RemoteResult 的 `{ok:false, code, error}`）——
+					// 只看 error 里的文案会漏掉这一半形态。
+					if (result.code === "not_found" || result.code === "missing" || result.code === "ENOENT") return false;
+					if (result.error) return classify(result.error);
+				}
 				return true;
 			}, classify);
 		}

package/lib/index.js

@@ -15,7 +15,7 @@ import { isReserved, nameKey, safeName } from './memory/naming.js'
 import { MEMORY_ARCHIVE_DIR, addArchiveMeta, extractTitle, inspectDir, inspectMemoryEntry, readArchivedMeta, readVerified, scanArchived, scanMemoryFiles, scanStars, shadowsReserved } from './memory/scan.js'
 import { listConflicts, patchConflict, readConflict, removeConflict, summarizeConflict } from './memory/conflicts.js'
 import { invalidateMemory, undoMemoryInvalidation } from './memory/arbitrate.js'
-import { readSnapshot, writeSnapshot } from './memory/write-protocol.js'
+import { prepareWrite, readSnapshot, writeSnapshot } from './memory/write-protocol.js'
 import { archiveMemory, archivedRevisionOf, deleteArchivedMemory, restoreMemory } from './memory/archive.js'
 import { flushAccess, pickArchiveCandidates, readAccessLedger } from './memory/access.js'
 import { serializeByKey, warnLog, writeFileAtomic } from './memory/util.js'
@@ -29,6 +29,16 @@ import { autodreamConfigSnapshot, clampInt, MAX_RAW_BYTES, parseUiPatch, pending
 import { createRecallInjector, createSessionInjectState, readRecallDebug } from './recall/index.js'
 import { mountAutodream, mountMemoryTools, mountObserve, mountWriteGate } from './assembly/index.js'
 
+/**
+ * 读方法的拒绝：**抛**一个带 `.code` 的 Error（写方法返回 `{ok:false, code}` 回执，见 prepareWrite）。
+ *
+ * 为什么读要抛：调用方拿不到内容就没法继续，异常语义比「回一个空结果」更难被静默忽略。
+ * 为什么必须带 code：客户端要靠结构化码判断「是不是真的不存在」——它以前只能正则匹配
+ * ENOENT 文案，宿主改一个措辞就会让陈旧宿主降级链走错边。
+ */
+function readReject(code, message) {
+  return Object.assign(new Error(message), { code })
+}
 /**
  * 手动 @Remote marker 注册（Node 24 不解析装饰器语法，手写 decorator context）。
  */
@@ -123,62 +133,37 @@ export class MemoryGateway extends TypertRemoteService {
    */
   async readFile(name) {
     const safe = safeName(name)
-    if (!safe) throw new Error('sage-mem: invalid file name')
+    if (!safe) throw readReject('invalid_name', 'sage-mem: invalid file name')
     const full = join(MEMORY_DIR, safe)
     // 名字不是保留名 ≠ 文件不是保留名：8.3 短名（`MEMORY~1.MD`）文本上与索引毫无关系，
     // 却是同一个文件。别把索引当普通记忆交出去。
     if (await shadowsReserved(full)) {
-      throw new Error(`sage-mem: refusing to read ${safe}: 这是某个保留名（索引 / 流水）的另一个名字`)
+      throw readReject('reserved', `sage-mem: refusing to read ${safe}: 这是某个保留名（索引 / 流水）的另一个名字`)
     }
     const gate = await inspectMemoryEntry(full)
-    if (!gate.ok) throw new Error(`sage-mem: refusing to read ${safe}: ${gate.error}`)
+    if (!gate.ok) throw readReject(gate.code || 'io_error', `sage-mem: refusing to read ${safe}: ${gate.error}`)
     return await readSnapshot(full, gate, safe)
   }
 
   /**
    * 写（新增或覆盖）单个记忆文件。三道闸：保留名不可写、内容必须是字符串、体积有上限；落盘走原子写。
-   * 拒绝一律返回 { ok: false, error }（不是抛异常）——设置页的调用方按 ok 判定。
+   * **错误形态**：拒绝一律返回 `{ ok: false, code, error }`，**不抛异常**——设置页的调用方按 ok 判定。
+   * （2.2.1 起「名字不合法」也走回执：原来它是同方法里唯一的 throw，让这句话变成假话。）
    * 2.1.2（Q02）新增可选第三参 `opts`：`{ expectedRevision }` 对不上 → `stale_revision`（当前内容逐字节
    * 不变，面板保留草稿）；`{ create: true }` 撞名 → `already_exists`（绝不覆盖）；不传 opts 走旧行为但落
    * 一条 warn（additive 契约只保留兼容，不保留静默）。成功时回 `revision`（落盘后的新版本）。
    */
   async writeFile(name, content, opts) {
-    // 保留名判定放在最前面、且以 nameKey 归一：'memory.md' / 'MEMORY.MD' /
-    // 'Session-Log.md' 在 NTFS 上都是同一个文件，必须一律走 { ok: false } 这条路
-    // （设置页按 ok 判定，见 client.js 的 submit()）。
-    if (isReserved(name)) {
-      return { ok: false, file: nameKey(name), error: `sage-mem: reserved file, edit it with the file tools: ${nameKey(name)}` }
-    }
-    const safe = safeName(name)
-    if (!safe) throw new Error('sage-mem: invalid file name')
-    // 名字文本不是保留名 **不等于** 文件不是保留名：NTFS 的 8.3 短名（`MEMORY~1.MD`）
-    // 在文本上跟索引毫无关系，inode 却是同一个 —— 实测它能改写索引。
-    // 保留名保护必须落在**文件身份**上，否则「保留名不可写」这句承诺是假的。
-    if (await shadowsReserved(join(MEMORY_DIR, safe))) {
-      return { ok: false, file: safe, error: `sage-mem: reserved file (它的另一个名字是 ${safe})，请用文件工具改` }
-    }
-    // 不加这一层，传个对象进来会被 String() 写成 "[object Object]" 还回 { ok: true }，
-    // 原文件就此被一行垃圾顶掉，且没有任何错误信号。
-    if (typeof content !== 'string') {
-      return { ok: false, file: safe, error: `sage-mem: content must be a string, got ${typeof content}` }
-    }
-    const bytes = Buffer.byteLength(content, 'utf8')
-    if (bytes > MAX_FILE_BYTES) {
-      return { ok: false, file: safe, error: `sage-mem: content too large (${bytes} bytes > ${MAX_FILE_BYTES})` }
-    }
-    /**
-     * 目标已存在时也要过闸门：链接 / 硬链接一律拒绝。
-     *
-     * 原子写本身不会写穿链接（rename 换掉的是链接本身），但那样「改这条记忆」就变成了
-     * 「把这个名字指向别处」—— 用户以为改的是记忆，实际磁盘上多了一个指向外部的名字。
-     * `limitBytes = 0` 表示不在这里判体积（上面刚按字符数查过）。
-     */
-    const target = join(MEMORY_DIR, safe)
-    const existing = await inspectMemoryEntry(target, { limitBytes: null })
-    if (!existing.ok && existing.code !== 'missing') {
-      return { ok: false, file: safe, error: `sage-mem: refusing to write ${safe}: ${existing.error}` }
-    }
-    return await writeSnapshot(target, content, existing, opts, { ctx: this.ctx, name: safe, kind: 'writeFile' })
+    // 三道闸（保留名 / 名字合法 / 影子文件）在 prepareWrite 里，顺序与另外两个写入口一致。
+    const pre = await prepareWrite({
+      name, content, limitBytes: MAX_FILE_BYTES,
+      isReserved, nameKey, safeName,
+      shadowCheck: (full) => shadowsReserved(full),
+      dir: MEMORY_DIR,
+      inspectEntry: inspectMemoryEntry,
+    })
+    if (!pre.ok) return pre
+    return await writeSnapshot(pre.target, content, pre.gate, opts, { ctx: this.ctx, name: pre.safe, kind: "writeFile" })
   }
 
   /** 删除单个记忆文件：保留名一律拒绝（unlink 不可逆）。判定同 writeFile。 */
@@ -187,7 +172,7 @@ export class MemoryGateway extends TypertRemoteService {
       return { ok: false, error: `sage-mem: reserved file, refusing to delete: ${nameKey(name)}` }
     }
     const safe = safeName(name)
-    if (!safe) throw new Error('sage-mem: invalid file name')
+    if (!safe) return { ok: false, code: 'invalid_name', error: 'sage-mem: invalid file name' }
     // 同 writeFile：8.3 短名能绕过名字文本判据，删除保护也必须看文件身份。
     if (await shadowsReserved(join(MEMORY_DIR, safe))) {
       return { ok: false, error: `sage-mem: reserved file (它的另一个名字是 ${safe})，拒绝删除` }
@@ -275,10 +260,10 @@ export class MemoryGateway extends TypertRemoteService {
    */
   async readArchived(name) {
     const safe = safeName(name)
-    if (!safe) throw new Error('sage-mem: invalid file name')
+    if (!safe) throw readReject('invalid_name', 'sage-mem: invalid file name')
     // 归档区本身先过目录闸门：它若是指向别处的联接，读归档就等于读外部的文件。
     const dirGate = await inspectDir(MEMORY_ARCHIVE_DIR)
-    if (!dirGate.ok) throw new Error(`sage-mem: archive dir unavailable: ${dirGate.error}`)
+    if (!dirGate.ok) throw readReject('io_error', `sage-mem: archive dir unavailable: ${dirGate.error}`)
     const full = join(MEMORY_ARCHIVE_DIR, safe)
     const gate = await inspectMemoryEntry(full)
     // 找不到就抛：与 readFile 一致。静默返回空串会让面板显示一个「空的记忆」，
@@ -286,8 +271,8 @@ export class MemoryGateway extends TypertRemoteService {
     if (!gate.ok) {
       // ⚠️「形状不对」与「不存在」是两回事：把联接 / 超限都报成「文件不存在」，
       // 会让用户去找一个明明躺在盘上的文件。
-      if (gate.code === 'missing') throw new Error(`sage-mem: archived file not found: ${safe}`)
-      throw new Error(`sage-mem: refusing to read archived ${safe}: ${gate.error}`)
+      if (gate.code === 'missing') throw readReject('not_found', `sage-mem: archived file not found: ${safe}`)
+      throw readReject(gate.code || 'io_error', `sage-mem: refusing to read archived ${safe}: ${gate.error}`)
     }
     // 2.1.2（Q02）：归档件与活动记忆同一套读快照协议，回 {name, content, revision}。
     return await readSnapshot(full, gate, safe)
@@ -296,7 +281,8 @@ export class MemoryGateway extends TypertRemoteService {
   /**
    * 写一份**已归档**记忆的正文（覆盖整份文件，形状与 `writeFile` 一致）。
    *
-   * 三道闸照抄 writeFile：名字先过 safeName、内容必须是字符串、体积上限，最后原子写。
+   * 闸门与 `writeFile` 共用 `prepareWrite`（同一顺序）：名字先过 safeName、内容必须是字符串、
+   * 体积上限、磁盘探针。**错误形态**：返回 `{ ok: false, code, error }`，**不抛异常**。
    * 额外一条：**盘上那份的归档留痕（`archived_at` / `archived_reason`）不许因为改正文而丢**。
    * 调用方若交回一份连留痕都没有的内容（「重建 frontmatter」式编辑器就是这样），
    * 这里按盘上原来的值补回去 —— 归档凭据不该依赖调用方是否体贴。
@@ -305,33 +291,15 @@ export class MemoryGateway extends TypertRemoteService {
    * 归档件在别处被改过就回 `{ok:false, code:'stale_revision'}`，正文逐字节不变。
    */
   async writeArchived(name, content, opts) {
-    if (isReserved(name)) {
-      return { ok: false, file: nameKey(name), error: `sage-mem: reserved file, edit it with the file tools: ${nameKey(name)}` }
-    }
-    const safe = safeName(name)
-    if (!safe) throw new Error('sage-mem: invalid file name')
-    const dirGate = await inspectDir(MEMORY_ARCHIVE_DIR)
-    if (!dirGate.ok) return { ok: false, file: safe, error: `sage-mem: archive dir unavailable: ${dirGate.error}` }
-    const full = join(MEMORY_ARCHIVE_DIR, safe)
-    const gate = await inspectMemoryEntry(full, { limitBytes: null })
-    // 只改归档区里**已经存在**的文件：这条 remote 不是「把任意文件写进归档区」的后门。
-    if (!gate.ok) {
-      return {
-        ok: false,
-        file: safe,
-        error:
-          gate.code === 'missing'
-            ? `sage-mem: archived file not found: ${safe}`
-            : `sage-mem: refusing to write archived ${safe}: ${gate.error}`,
-      }
-    }
-    if (typeof content !== 'string') {
-      return { ok: false, file: safe, error: `sage-mem: content must be a string, got ${typeof content}` }
-    }
-    const bytes = Buffer.byteLength(content, 'utf8')
-    if (bytes > MAX_FILE_BYTES) {
-      return { ok: false, file: safe, error: `sage-mem: content too large (${bytes} bytes > ${MAX_FILE_BYTES})` }
-    }
+    const pre = await prepareWrite({
+      name, content, limitBytes: MAX_FILE_BYTES,
+      isReserved, nameKey, safeName,
+      dirCheck: () => inspectDir(MEMORY_ARCHIVE_DIR),
+      dir: MEMORY_ARCHIVE_DIR,
+      inspectEntry: inspectMemoryEntry,
+      allowMissing: false,
+    })
+    if (!pre.ok) return pre
     const given = readArchivedMeta(content)
     let toWrite = content
     /**
@@ -340,14 +308,14 @@ export class MemoryGateway extends TypertRemoteService {
      * 丢了它删除确认的内容身份就少了一半）。任何一个缺了才重写整块 frontmatter。
      */
     if (!given.archivedAt || !given.archivedReason || !given.archivedRev) {
-      const onDisk = readArchivedMeta(await readVerified(full, gate, 'utf8'))
+      const onDisk = readArchivedMeta(await readVerified(pre.target, pre.gate, "utf8"))
       const at = given.archivedAt || onDisk.archivedAt
       const reason = given.archivedReason || onDisk.archivedReason
       const rev = given.archivedRev || onDisk.archivedRev
       if (at || reason || rev) toWrite = addArchiveMeta(content, reason, at, rev)
     }
     // 2.1.2（Q02）：落盘也走写协议 —— 带 opts 时先比盘上版本，对不上就拒绝（正文逐字节不变）。
-    return await writeSnapshot(full, toWrite, gate, opts, { ctx: this.ctx, name: safe, kind: 'writeArchived' })
+    return await writeSnapshot(pre.target, toWrite, pre.gate, opts, { ctx: this.ctx, name: pre.safe, kind: "writeArchived" })
   }
 
   /**
@@ -563,7 +531,7 @@ export class MemoryGateway extends TypertRemoteService {
     // 它有自己的上限（`MAX_RAW_BYTES`，见上面的注释）。
     const full = join(MEMORY_DIR, safe)
     const gate = await inspectMemoryEntry(full, { limitBytes: null })
-    if (!gate.ok) throw new Error(`sage-mem: refusing to read ${safe}: ${gate.error}`)
+    if (!gate.ok) throw readReject(gate.code || 'io_error', `sage-mem: refusing to read ${safe}: ${gate.error}`)
     // 读不到就抛（与 readFile 一致）：静默返回空串会让面板显示一份「空的索引」，
     // 用户一存就把真索引顶掉。
     // 2.1.2（Q02）：保留名与普通记忆同一套读快照协议 —— 回 {name, content, revision}。
@@ -576,36 +544,24 @@ export class MemoryGateway extends TypertRemoteService {
    * 这就是 2026-09-25 那次 P0 数据丢失事故（表单重建 frontmatter 把 baseline /
    * node_type / originSessionId 全抹掉）的解药：索引与流水只许原样进出。
    *
+   * **错误形态**：返回 `{ ok: false, code, error }`，**不抛异常**（名字判据用 `rawName`，因为服务对象就是保留名）。
+   *
    * 2.1.2（Q02）：与 `writeFile` 同一套写协议 —— `opts.expectedRevision` 对不上则
    * `{ok:false, code:'stale_revision'}`（索引逐字节不变）；`opts.create` 用于「建立索引骨架」
    * 这类 createIfAbsent 语义（撞名明确报 `already_exists`，绝不覆盖）。
    */
   async writeRaw(name, content, opts) {
-    if (!isReserved(name)) {
-      return { ok: false, error: `sage-mem: ${String(name)} is not a reserved file; normal memories use the memory form or writeFile` }
-    }
-    const safe = rawName(name)
-    if (!safe) return { ok: false, error: `sage-mem: invalid file name: ${String(name)}` }
-    if (typeof content !== 'string') {
-      return { ok: false, file: safe, error: `sage-mem: content must be a string, got ${typeof content}` }
-    }
-    const bytes = Buffer.byteLength(content, 'utf8')
-    // ⚠️ 与 writeFile 的 512 KB 上限**不是同一个数**：流水天然更大（见 MAX_RAW_BYTES 的注释）。
-    if (bytes > MAX_RAW_BYTES) {
-      return {
-        ok: false,
-        file: safe,
-        error: `sage-mem: content too large (${bytes} bytes > ${MAX_RAW_BYTES / (1024 * 1024)} MB raw limit)`,
-      }
-    }
-    const target = join(MEMORY_DIR, safe)
-    // 与 `writeFile` 同一条理由：目标已存在时若是链接 / 硬链接，一律拒绝 ——
-    // 「改这份索引」不该变成「把这个名字指向别处」。体积由上面那道 `MAX_RAW_BYTES` 管。
-    const existing = await inspectMemoryEntry(target, { limitBytes: null })
-    if (!existing.ok && existing.code !== 'missing') {
-      return { ok: false, file: safe, error: `sage-mem: refusing to write ${safe}: ${existing.error}` }
-    }
-    return await writeSnapshot(target, content, existing, opts, { ctx: this.ctx, name: safe, kind: 'writeRaw' })
+    const pre = await prepareWrite({
+      name, content, limitBytes: MAX_RAW_BYTES, limitLabel: `${MAX_RAW_BYTES / (1024 * 1024)} MB raw limit`,
+      // ⚠️ writeRaw 服务的就是**保留名**，所以名字判据是 `rawName`（它接受索引 / 流水），
+      // 不是 `safeName`（那个会把保留名判成非法）。
+      isReserved, nameKey, safeName: rawName,
+      requireReserved: true,
+      dir: MEMORY_DIR,
+      inspectEntry: inspectMemoryEntry,
+    })
+    if (!pre.ok) return pre
+    return await writeSnapshot(pre.target, content, pre.gate, opts, { ctx: this.ctx, name: pre.safe, kind: "writeRaw" })
   }
 }
 
@@ -672,15 +628,15 @@ export class StarmapGateway extends TypertRemoteService {
     // 与 MemoryGateway.readFile 收敛到同一个 safeName：它现在同时排除
     // MEMORY.md 与 session-log.md，且大小写不敏感。
     const safe = safeName(name)
-    if (!safe) throw new Error('sage-starmap: invalid file name')
+    if (!safe) throw readReject('invalid_name', 'sage-starmap: invalid file name')
     const full = join(MEMORY_DIR, safe)
     // 2026-10-23 审查 R19：面板读原先只过 safeName，与注入链 / 工具读不是同一套闸门。
     // 面板读不进模型上下文，但「同一个名字在不同入口有不同含义」本身就是缺陷面 —— 收口。
     if (await shadowsReserved(full)) {
-      throw new Error(`sage-starmap: refusing to read ${safe}: 这是某个保留名（索引 / 流水）的另一个名字`)
+      throw readReject('reserved', `sage-starmap: refusing to read ${safe}: 这是某个保留名（索引 / 流水）的另一个名字`)
     }
     const gate = await inspectMemoryEntry(full)
-    if (!gate.ok) throw new Error(`sage-starmap: refusing to read ${safe}: ${gate.error}`)
+    if (!gate.ok) throw readReject(gate.code || 'io_error', `sage-starmap: refusing to read ${safe}: ${gate.error}`)
     const content = await readVerified(full, gate, 'utf8')
     return { name: safe, content }
   }

package/lib/memory/access.js

@@ -76,8 +76,13 @@ export function injectedAt(value) {
 /** 落盘节流：内存先累计，最多每 30 秒写一次盘。 */
 export const ACCESS_FLUSH_INTERVAL_MS = 30 * 1000
 
-/** 开了才出声：台账写不进去是**静默降级**，没有这个开关就查不出「为什么阈值算不准」。 */
-const DEBUG = process.env.SAGE_MEM_DEBUG === '1'
+/**
+ * 开了才出声：台账写不进去是**静默降级**，没有这个开关就查不出「为什么阈值算不准」。
+ *
+ * 2.2.1：**每次现读**，不做模块级常量 —— 常量在「运行中打开开关」和「测试用 query 重载模块」
+ * 两种场景都会停在旧值（`recall/debug.js` 的头注记过同一个坑，那里也是现读）。
+ */
+const debugEnabled = () => process.env.SAGE_MEM_DEBUG === '1'
 
 /** 「永不自动归档」的类型：feedback 是用户给的做事方式，退役它等于把人的交代扔掉。 */
 export const NEVER_ARCHIVE_TYPES = new Set(['feedback'])
@@ -292,7 +297,9 @@ async function flushAccessLocked(memoryDir) {
       })
     }
     // 静默降级：注入是插件最核心的事，台账写不进去不许把它拖下水。开了 DEBUG 才出声。
-    if (DEBUG) console.warn(`[sage-mem][debug] access ledger flush failed: ${err?.message ?? err}`)
+    // 2.2.1：前缀归一（原来是 `[sage-mem][debug] `）。本函数签名里没有 ctx，
+    // 所以用 console.warn —— 与 warnLog 的 fallback 形态一致。
+    if (debugEnabled()) console.warn(`sage-mem: access ledger flush failed: ${err?.message ?? err}`)
     return { ok: false, error: err?.message ?? String(err) }
   }
 }

package/lib/memory/write-protocol.js

@@ -23,7 +23,7 @@
 
 import { createHash } from 'node:crypto'
 import { mkdir } from 'node:fs/promises'
-import { dirname } from 'node:path'
+import { dirname, join } from 'node:path'
 import { readVerified } from './scan.js'
 import { warnLog, writeFileAtomic, writeFileExclusive } from './util.js'
 
@@ -52,6 +52,109 @@ export async function readSnapshot(full, gate, name) {
 /** 旧调用方的兼容提示（一次写入一行，不做去重 —— 谁漏传一眼就能在日志里翻到）。 */
 const LEGACY_WARN = '没有带 expectedRevision，按旧协议直接覆盖（面板必须带；旧调用方仅兼容，建议尽快带上）'
 
+/**
+ * 写入前置闸门：**一套顺序**，三处写路径（`writeFile` / `writeArchived` / `writeRaw`）共用。
+ *
+ * 为什么要有它：这三处曾经各写一遍，闸门顺序还不一样 —— 内容类型检查分别排在
+ * 第 3 / 第 6 / 第 3 位，`writeRaw` 用的上限常量也不同。于同一个坏输入从三个入口进去
+ * 会报三个不同的「第一个错」，而这里正是历史事故最集中的地方（D4、2026-09-25 P0、R01）。
+ *
+ * 现在的顺序**固定为**：
+ *   ① 保留名（`requireReserved` 时反向：只许保留名）
+ *   ② 名字合法（唯一判据 `shared/md-name.js` 的 `safeName`）
+ *   ③ 目录闸（归档区专属，可选）
+ *   ④ 影子文件 / 8.3 短名（内存区专属，可选）
+ *   ⑤ 内容必须是字符串
+ *   ⑥ 体积上限
+ *   ⑦ 磁盘探针（链接 / 硬链接拒绝；`allowMissing` 决定「不存在」算不算合法）
+ *
+ * 失败一律返回 `{ok:false, code, file, error}` —— **不抛异常**（调用方按 ok 判定）。
+ *
+ * @param {object} spec
+ * @param {string} spec.name       调用方给的名字（未归一）
+ * @param {unknown} spec.content   待写正文
+ * @param {number} spec.limitBytes 体积上限
+ * @param {string} [spec.limitLabel] 错误文案里的上限描述（默认字节数）
+ * @param {(n:string)=>boolean} spec.isReserved
+ * @param {(n:string)=>string} spec.nameKey
+ * @param {(n:string)=>string|null} spec.safeName
+ * @param {boolean} [spec.requireReserved=false]
+ * @param {((full:string)=>Promise<boolean>)} [spec.shadowCheck]
+ * @param {(()=>Promise<{ok:boolean,error?:string}>)} [spec.dirCheck]
+ * @param {string} spec.dir         目标目录
+ * @param {(full:string, opts:object)=>Promise<object>} spec.inspectEntry
+ * @param {boolean} [spec.allowMissing=true] 磁盘探针是否允许「不存在」
+ * @returns {Promise<{ok:true, safe:string, target:string, gate:object}
+ *   | {ok:false, code:string, file?:string, error:string}>}
+ */
+export async function prepareWrite(spec) {
+  const {
+    name, content, limitBytes, limitLabel,
+    isReserved, nameKey, safeName,
+    requireReserved = false,
+    shadowCheck = null,
+    dirCheck = null,
+    dir,
+    inspectEntry,
+    allowMissing = true,
+  } = spec
+
+  // ① 保留名。writeRaw 是反向的：它**只**服务索引 / 流水。
+  const reserved = typeof isReserved === 'function' ? isReserved(name) : false
+  if (requireReserved ? !reserved : reserved) {
+    return requireReserved
+      ? { ok: false, code: 'reserved', error: `sage-mem: ${String(name)} is not a reserved file; normal memories use the memory form or writeFile` }
+      : { ok: false, code: 'reserved', file: nameKey(name), error: `sage-mem: reserved file, edit it with the file tools: ${nameKey(name)}` }
+  }
+
+  // ② 名字合法。这里**返回回执而不是抛** —— 同一方法里「保留名回执、非法名抛异常」曾经
+  // 让 writeFile 的 JSDoc（「拒绝一律返回 { ok: false }」）变成假话。
+  const safe = safeName(name)
+  if (!safe) return { ok: false, code: 'invalid_name', file: '', error: `sage-mem: invalid file name: ${String(name)}` }
+
+  // ③ 目录闸（归档区：目录读不了就别谈写）
+  if (dirCheck) {
+    const d = await dirCheck()
+    if (!d.ok) return { ok: false, code: 'io_error', file: safe, error: `sage-mem: archive dir unavailable: ${d.error}` }
+  }
+
+  const target = join(dir, safe)
+
+  // ④ 影子文件：名字文本不是保留名 ≠ 文件不是保留名（NTFS 8.3 短名能改写索引）
+  if (shadowCheck && (await shadowCheck(target))) {
+    return { ok: false, code: 'reserved', file: safe, error: `sage-mem: reserved file (它的另一个名字是 ${safe})，请用文件工具改` }
+  }
+
+  // ⑤ 内容类型。不加这一层，传个对象进来会被 String() 写成 "[object Object]" 还回 ok:true。
+  if (typeof content !== 'string') {
+    return { ok: false, code: 'invalid', file: safe, error: `sage-mem: content must be a string, got ${typeof content}` }
+  }
+
+  // ⑥ 体积
+  const bytes = Buffer.byteLength(content, 'utf8')
+  if (bytes > limitBytes) {
+    return { ok: false, code: 'too_big', file: safe, error: `sage-mem: content too large (${bytes} bytes > ${limitLabel || limitBytes})` }
+  }
+
+  // ⑦ 磁盘探针：目标已存在时若是链接 / 硬链接，一律拒绝 ——
+  // 「改这条记忆」不该变成「把这个名字指向别处」。体积上面刚查过，这里不判。
+  const gate = await inspectEntry(target, { limitBytes: null })
+  if (!gate.ok && !(allowMissing && gate.code === 'missing')) {
+    return {
+      ok: false,
+      code: gate.code || 'io_error',
+      file: safe,
+      error: allowMissing
+        ? `sage-mem: refusing to write ${safe}: ${gate.error}`
+        : gate.code === 'missing'
+          ? `sage-mem: archived file not found: ${safe}`
+          : `sage-mem: refusing to write archived ${safe}: ${gate.error}`,
+    }
+  }
+
+  return { ok: true, safe, target, gate }
+}
+
 /**
  * 整份覆盖写：`create` / `expectedRevision` / 旧调用方三种语义，一个出口。
  *

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.2.0",
+  "version": "2.2.1",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./icon.png",