sage-mem 2.1.25 → 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.1.25`** — 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.1.25`** —— 顶部 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/autodream/tools.js

@@ -764,7 +764,7 @@ export function createToolRunner(opts) {
     if (guard.refuse) {
       // **不知道就不写。** 以前这条路会退化成「用当前版本当守卫」，等于替调用方担保一份它没读过的
       // 内容 —— 那比「什么都不做」危险得多。转成一条待人工处理的冲突，让人来判。
-      await recordStaleConflict(fullPath, content, { code: 'UNVERIFIED_OVERWRITE', message: guard.why }, 'external_change')
+      await recordStaleConflict(fullPath, content, { code: 'unverified_overwrite', message: guard.why }, 'external_change')
       throw Object.assign(new Error(guard.why), { code: 'SAGE_MEM_UNVERIFIED_OVERWRITE' })
     }
     try {
@@ -959,7 +959,7 @@ export function createToolRunner(opts) {
             const before = await fileFingerprint(full)
             const res = await archiveMemory(memoryDir, basename(full), reason)
             if (!res.ok) {
-              if (res.code === 'not-found') return `错误：没有这个文件：${basename(full)}`
+              if (res.code === 'not_found') return `错误：没有这个文件：${basename(full)}`
               if (res.code === 'exists') return `错误：archive/ 里已有同名文件（${basename(full)}），请先人工处理，避免覆盖。`
               return `错误：${String(res.error).replace(/^sage-mem: /, '')}`
             }

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/archive.js

@@ -34,7 +34,7 @@ function checkName(name, verb) {
     return { ok: false, code: 'reserved', error: `sage-mem: reserved file, refusing to ${verb}: ${nameKey(name)}` }
   }
   const safe = safeName(name)
-  if (!safe) return { ok: false, code: 'invalid-name', error: `sage-mem: invalid file name: ${String(name)}` }
+  if (!safe) return { ok: false, code: 'invalid_name', error: `sage-mem: invalid file name: ${String(name)}` }
   return { ok: true, safe }
 }
 
@@ -63,7 +63,7 @@ export async function archiveMemory(memoryDir, name, reason, at = localStamp())
   if (lock.status === 'unknown') {
     return {
       ok: false,
-      code: 'lock-unknown',
+      code: 'lock_unknown',
       error: `sage-mem: 锁表不可读（${lock.reason}），无法确认这条记忆是否受保护，拒绝归档：${safe}`,
     }
   }
@@ -83,7 +83,7 @@ export async function archiveMemory(memoryDir, name, reason, at = localStamp())
   if (!srcGate.ok) {
     return {
       ok: false,
-      code: srcGate.code === 'missing' ? 'not-found' : srcGate.code,
+      code: srcGate.code === 'missing' ? 'not_found' : srcGate.code,
       error: `sage-mem: file not found: ${safe}（${srcGate.error}）`,
     }
   }
@@ -162,14 +162,14 @@ export async function archiveMemory(memoryDir, name, reason, at = localStamp())
      * 「错误：没有这个文件」—— 诊断是错的，人会去别处找。按真实错误码分流。
      */
     await rm(dst, { force: true }).catch(() => {})
-    if (takenRes.code === 'not-found') {
-      return { ok: false, code: 'not-found', error: `sage-mem: file not found: ${safe}（归档途中源文件消失了）` }
+    if (takenRes.code === 'not_found') {
+      return { ok: false, code: 'not_found', error: `sage-mem: file not found: ${safe}（归档途中源文件消失了）` }
     }
-    if (takenRes.code === 'move-failed') {
+    if (takenRes.code === 'move_failed') {
       const moveErr = takenRes.cause
       return {
         ok: false,
-        code: 'move-failed',
+        code: 'move_failed',
         error: `sage-mem: 归档 ${safe} 时移不动它（${moveErr?.code ?? moveErr}：${moveErr?.message ?? moveErr}）。文件仍在原处、一个字节没动，本次归档未完成 —— 可稍后重试（若是被其它程序占用，关掉它再来）。`,
       }
     }
@@ -241,16 +241,16 @@ export async function restoreMemory(memoryDir, name) {
   if (!dirGate.ok) {
     return {
       ok: false,
-      code: dirGate.code === 'missing' ? 'not-archived' : dirGate.code,
+      code: dirGate.code === 'missing' ? 'not_archived' : dirGate.code,
       error: `sage-mem: not archived: ${safe}（${dirGate.error}）`,
     }
   }
   const srcGate = await inspectMemoryEntry(src, { limitBytes: null })
-  if (!srcGate.ok) return { ok: false, code: 'not-archived', error: `sage-mem: not archived: ${safe}（${srcGate.error}）` }
+  if (!srcGate.ok) return { ok: false, code: 'not_archived', error: `sage-mem: not archived: ${safe}（${srcGate.error}）` }
   // 顶层已有同名（且不是链接）时拒绝：根目录那份是正在用的记忆，归档这份只是退役版。
   const dstGate = await inspectMemoryEntry(dst, { limitBytes: null })
   if (dstGate.ok) {
-    return { ok: false, code: 'target-exists', error: `sage-mem: already exists, refusing to overwrite: ${safe}` }
+    return { ok: false, code: 'target_exists', error: `sage-mem: already exists, refusing to overwrite: ${safe}` }
   }
   if (dstGate.code !== 'missing') {
     return { ok: false, code: dstGate.code, error: `sage-mem: refusing to restore over ${safe}: ${dstGate.error}` }
@@ -278,14 +278,14 @@ export async function restoreMemory(memoryDir, name) {
    */
   const takenRes = await takeOverSource(src, sourceBytes, 'restoring')
   if (!takenRes.ok) {
-    if (takenRes.code === 'not-found') {
-      return { ok: false, code: 'not-archived', error: `sage-mem: not archived: ${safe}（恢复途中源文件消失了）` }
+    if (takenRes.code === 'not_found') {
+      return { ok: false, code: 'not_archived', error: `sage-mem: not archived: ${safe}（恢复途中源文件消失了）` }
     }
-    if (takenRes.code === 'move-failed') {
+    if (takenRes.code === 'move_failed') {
       const moveErr = takenRes.cause
       return {
         ok: false,
-        code: 'move-failed',
+        code: 'move_failed',
         error: `sage-mem: 恢复 ${safe} 时移不动它（${moveErr?.code ?? moveErr}：${moveErr?.message ?? moveErr}）。文件仍在 archive/ 里、一个字节没动 —— 可稍后重试（若是被其它程序占用，关掉它再来）。`,
       }
     }
@@ -318,12 +318,12 @@ export async function restoreMemory(memoryDir, name) {
     if (!back.ok) {
       return {
         ok: false,
-        code: 'restore-failed',
+        code: 'restore_failed',
         error: `sage-mem: 恢复 ${safe} 落位失败（${err?.code ?? err}），且归还归档区原名时被占用 —— **内容仍保留在 archive/${basename(back.keptAt)}**，请手工改回 ${safe} 再试。`,
       }
     }
     if (err?.code === 'EEXIST') {
-      return { ok: false, code: 'target-exists', error: `sage-mem: already exists, refusing to overwrite: ${safe}` }
+      return { ok: false, code: 'target_exists', error: `sage-mem: already exists, refusing to overwrite: ${safe}` }
     }
     throw err
   }
@@ -421,7 +421,7 @@ export async function deleteArchivedMemory(memoryDir, name, expectedArchivedAt =
   if (!dirGate.ok) {
     return {
       ok: false,
-      code: dirGate.code === 'missing' ? 'not-archived' : dirGate.code,
+      code: dirGate.code === 'missing' ? 'not_archived' : dirGate.code,
       error: `sage-mem: not archived: ${safe}（${dirGate.error}）`,
     }
   }
@@ -430,7 +430,7 @@ export async function deleteArchivedMemory(memoryDir, name, expectedArchivedAt =
   if (!srcGate.ok) {
     return {
       ok: false,
-      code: srcGate.code === 'missing' ? 'not-archived' : srcGate.code,
+      code: srcGate.code === 'missing' ? 'not_archived' : srcGate.code,
       error: `sage-mem: not archived: ${safe}（${srcGate.error}）`,
     }
   }
@@ -441,14 +441,14 @@ export async function deleteArchivedMemory(memoryDir, name, expectedArchivedAt =
   const sourceBytes = await readFile(full)
   const takenRes = await takeOverSource(full, sourceBytes, 'deleting')
   if (!takenRes.ok) {
-    if (takenRes.code === 'not-found') {
-      return { ok: false, code: 'not-archived', error: `sage-mem: not archived: ${safe}（删除途中它从归档区消失了）` }
+    if (takenRes.code === 'not_found') {
+      return { ok: false, code: 'not_archived', error: `sage-mem: not archived: ${safe}（删除途中它从归档区消失了）` }
     }
-    if (takenRes.code === 'move-failed') {
+    if (takenRes.code === 'move_failed') {
       const moveErr = takenRes.cause
       return {
         ok: false,
-        code: 'move-failed',
+        code: 'move_failed',
         error: `sage-mem: 删除 ${safe} 时移不动它（${moveErr?.code ?? moveErr}：${moveErr?.message ?? moveErr}）。文件仍在 archive/ 里、一个字节没动 —— 可稍后重试（若是被其它程序占用，关掉它再来）。`,
       }
     }
@@ -513,7 +513,7 @@ export async function deleteArchivedMemory(memoryDir, name, expectedArchivedAt =
     if (!back.ok) {
       return {
         ok: false,
-        code: 'delete-failed',
+        code: 'delete_failed',
         error:
           `sage-mem: 删除 ${safe} 失败（${delErr?.code ?? delErr}），且归还原名时被占用 —— ` +
           `**内容仍保留在 archive/${basename(back.keptAt)}**，请手工改回 ${safe} 再试。`,
@@ -521,7 +521,7 @@ export async function deleteArchivedMemory(memoryDir, name, expectedArchivedAt =
     }
     return {
       ok: false,
-      code: 'delete-failed',
+      code: 'delete_failed',
       error: `sage-mem: 删除 ${safe} 失败（${delErr?.code ?? delErr}：${delErr?.message ?? delErr}），文件已还回 archive/${safe}，没有丢。`,
     }
   }

package/lib/memory/lock.js

@@ -125,7 +125,7 @@ export async function isLocked(memoryDir, name) {
  * RMW 全程在**按锁表路径分键的进程内队列**里：读最新表 → 改一项 → 原子写回。
  * 并发的不同文件因此逐条合并，不再互相覆盖。
  *
- * 坏表上**拒绝写入**（`{ok:false, code:'lock-table-unknown'}`），而不是把表重置成空表 ——
+ * 坏表上**拒绝写入**（`{ok:false, code:'lock_table_unknown'}`），而不是把表重置成空表 ——
  * 后者会静默抹掉用户的全部保护状态，比「这次没锁上」严重得多。
  */
 export async function setLocked(memoryDir, name, locked) {
@@ -136,7 +136,7 @@ export async function setLocked(memoryDir, name, locked) {
     if (read.status === 'unknown') {
       return {
         ok: false,
-        code: 'lock-table-unknown',
+        code: 'lock_table_unknown',
         error: `sage-mem: 锁表不可读（${read.reason}），本次没有写入，也不会把它重置成空表：${name}`,
       }
     }

package/lib/memory/reader.js

@@ -226,7 +226,7 @@ export async function readSlice(req = {}) {
     if (!gate.ok) {
       if (gate.code === 'missing') return { ok: false, code: 'not_found', error: `没有这份记忆：${norm.name}` }
       // stat-failed 不是「形状不对」，是读不到属性（权限 / 盘掉线）→ 归 io_error 更好排查
-      if (gate.code === 'stat-failed') return { ok: false, code: 'io_error', error: `读不到文件属性：${gate.error}` }
+      if (gate.code === 'stat_failed') return { ok: false, code: 'io_error', error: `读不到文件属性：${gate.error}` }
       return { ok: false, code: 'denied', error: `拒绝读取 ${norm.name}：${gate.error}` }
     }
 

package/lib/memory/scan.js

@@ -158,17 +158,17 @@ export async function inspectMemoryEntry(full, opts = {}) {
   } catch (err) {
     return {
       ok: false,
-      code: err?.code === 'ENOENT' ? 'missing' : 'stat-failed',
+      code: err?.code === 'ENOENT' ? 'missing' : 'stat_failed',
       error: `读不到文件属性（${err?.code ?? err}）`,
     }
   }
   if (info.isSymbolicLink()) return { ok: false, code: 'symlink', error: '是指向别处的符号链接 / 目录联接' }
-  if (!info.isFile()) return { ok: false, code: 'not-file', error: '不是普通文件' }
+  if (!info.isFile()) return { ok: false, code: 'not_file', error: '不是普通文件' }
   // null = 明确「不判体积」；其余一律按数值上限处理（0 / NaN / 字符串都会被当成超限）。
   if (limitBytes !== null && (!Number.isFinite(limitBytes) || info.size > limitBytes)) {
     return {
       ok: false,
-      code: 'too-big',
+      code: 'too_big',
       error: Number.isFinite(limitBytes)
         ? `体积 ${info.size} 字节，超过单文件上限 ${limitBytes} 字节`
         : `体积 ${info.size} 字节，上限参数不合法（${String(limitBytes)}）`,
@@ -287,12 +287,12 @@ export async function inspectDir(dir) {
   } catch (err) {
     return {
       ok: false,
-      code: err?.code === 'ENOENT' ? 'missing' : 'stat-failed',
+      code: err?.code === 'ENOENT' ? 'missing' : 'stat_failed',
       error: `读不到目录属性（${err?.code ?? err}）`,
     }
   }
   if (info.isSymbolicLink()) return { ok: false, code: 'symlink', error: '是指向别处的符号链接 / 目录联接' }
-  if (!info.isDirectory()) return { ok: false, code: 'not-dir', error: '不是目录' }
+  if (!info.isDirectory()) return { ok: false, code: 'not_dir', error: '不是目录' }
   return { ok: true }
 }
 

package/lib/memory/util.js

@@ -249,7 +249,7 @@ async function copyMoveExclusive(from, to) {
  * @param {string} tag — 私有名后缀（`archiving` / `restoring`）；体检按它认崩溃残留
  * @returns {Promise<
  *   {ok:true, taken:string} |
- *   {ok:false, code:'not-found'|'move-failed'|'changed', cause?:Error, keptAt?:string}
+ *   {ok:false, code:'not_found'|'move_failed'|'changed', cause?:Error, keptAt?:string}
  * >}
  */
 export async function takeOverSource(from, expected, tag) {
@@ -259,7 +259,7 @@ export async function takeOverSource(from, expected, tag) {
     (err) => err,
   )
   if (moveErr) {
-    return { ok: false, code: moveErr?.code === 'ENOENT' ? 'not-found' : 'move-failed', cause: moveErr }
+    return { ok: false, code: moveErr?.code === 'ENOENT' ? 'not_found' : 'move_failed', cause: moveErr }
   }
   const current = await readFile(taken).catch(() => null)
   if (current !== null && Buffer.compare(current, expected) === 0) return { ok: true, taken }

package/lib/memory/watch.js

@@ -107,7 +107,7 @@ export function createDirWatcher(dir, onChange) {
     floodCount++
     if (floodCount > WATCH_FLOOD_MAX_EVENTS) {
       // 句柄已坏（多半是目录被删 / 被同名重建）：报错这条路会顺手 close 掉，空转立刻停。
-      onError({ code: 'FLOOD', message: `${WATCH_FLOOD_WINDOW_MS}ms 内 ${floodCount} 个变更事件，句柄已不可信` })
+      onError({ code: 'flood', message: `${WATCH_FLOOD_WINDOW_MS}ms 内 ${floodCount} 个变更事件，句柄已不可信` })
       return
     }
     if (!burstOpen) {

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/lib/shared/codes.js

@@ -0,0 +1,71 @@
+/**
+ * sage-mem 业务错误码的**唯一清单**（2026-11-03 归一，2.2.0）。
+ *
+ * 为什么要有它：`code` 曾经同时存在三套命名法 ——
+ *   - snake_case：`io_error` / `not_found` / `stale_version`
+ *   - kebab-case：`not-found` / `move-failed` / `lock-table-unknown`
+ *   - UPPER：`UNVERIFIED_OVERWRITE` / `FLOOD`
+ * 更糟的是**同一概念两个值并存**：`not_found`（reader）与 `not-found`（archive）、
+ * `too_big` 与 `too-big`。消费方只能两边都匹配，漏一边就是静默的错误分支
+ * （`client/50-shared-ui.js` 的 code → i18n 映射表就踩过）。
+ *
+ * 现在：**业务码一律 snake_case，且必须在本文件登记**。
+ * `test/code-registry-test.mjs` 盯着两件事：
+ *   1. `lib/**` 里出现的 `code:` 字面量必须在 `CODES` 里；
+ *   2. 清单里不许出现 kebab-case。
+ *
+ * ⚠️ **不在本清单的三类码，不要往这里加：**
+ *   - **Node errno**：`ENOENT` / `EEXIST` / `EIO` / `EACCES` …——不是我们的命名空间，
+ *     它们来自 `node:fs`，我们只是判读。
+ *   - **宿主的码**：`FS_SANDBOX_DENIED` / `FS_STALE_VERSION`——我们在解读 DSH 的文件沙箱
+ *     与版本闸，改名等于假装自己拥有它。
+ *   - **`Error.code`**：`SAGE_MEM_UNVERIFIED_OVERWRITE` / `LOCK_TABLE_UNKNOWN`——
+ *     挂在**异常对象**上而非返回值里，保留 UPPER 前缀是为了与 errno 区分（`error.code`
+ *     和 `result.code` 是两个命名空间，别合并）。
+ */
+
+/** 全部业务码。值的唯一合法拼写就是键名。 */
+export const CODES = Object.freeze({
+  // ── 读 / 扫描 ──
+  missing: 'missing',
+  not_found: 'not_found',
+  denied: 'denied',
+  symlink: 'symlink',
+  stat_failed: 'stat_failed',
+  not_file: 'not_file',
+  not_dir: 'not_dir',
+  too_big: 'too_big',
+  malformed: 'malformed',
+  // ── 写 ──
+  invalid: 'invalid',
+  invalid_transition: 'invalid_transition',
+  io_error: 'io_error',
+  changed: 'changed',
+  stale_version: 'stale_version',
+  revision_changed: 'revision_changed',
+  unsupported: 'unsupported',
+  exists: 'exists',
+  // ── 归档 ──
+  not_archived: 'not_archived',
+  move_failed: 'move_failed',
+  target_exists: 'target_exists',
+  delete_failed: 'delete_failed',
+  restore_failed: 'restore_failed',
+  invalid_name: 'invalid_name',
+  reserved: 'reserved',
+  locked: 'locked',
+  lock_unknown: 'lock_unknown',
+  lock_table_unknown: 'lock_table_unknown',
+  unverified_overwrite: 'unverified_overwrite',
+  // ── 其它 ──
+  memory_unavailable: 'memory_unavailable',
+  flood: 'flood',
+})
+
+/** 值集合（判据用）。 */
+export const CODE_VALUES = new Set(Object.keys(CODES))
+
+/** 这个 code 是不是登记过的业务码。 */
+export function isKnownCode(value) {
+  return typeof value === 'string' && CODE_VALUES.has(value)
+}

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