sage-mem 2.1.25 → 2.2.0

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.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
 [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.0`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。

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