sage-mem 2.1.24 → 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.24`** — 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.24`** —— 顶部 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/client.js

@@ -31,6 +31,10 @@ window.__ModuleLoader__.load({
 		const isNum = (v) => { if (typeof v !== "number") throw new Error("expected number"); };
 		function parseSchema(shape) {
 			return {
+				// 字段清单**暴露出来**：`test/client-exec-test.mjs` 第 3.1 组拿它跟宿主 zod 的
+				// shape 逐条对表。没有这一项，「strict」只意味着「不查多余键」——
+				// 宿主加了字段、客户端没声明这种漂移它挡不住（2026-11-03 实测已漂三处）。
+				fields: Object.keys(shape),
 				parse(value) {
 					if (value === null || typeof value !== "object") throw new Error("sage-mem: invalid payload");
 					for (const [key, check] of Object.entries(shape)) {
@@ -1650,13 +1654,21 @@ const StarmapRuntime = (function (require, _react) {
 
 		// ── 手写 strict codec（浏览器无 zod，typert 只要求 parse 方法）──
 		// 基元（parseSchema / isStr / isBool / isNum / strSchema）在 05-shared.js。
-		const fileSchema = parseSchema({ "file": isStr, "type": isStr, "description": isStr, "size": isNum });
-		const listSchema = { parse(v) { if (!Array.isArray(v)) throw new Error("expected array"); v.forEach((f) => fileSchema.parse(f)); return v; } };
+		const isStrArr = (v) => { if (!Array.isArray(v)) throw new Error("expected string array"); for (const x of v) isStr(x); };
+		// 字段必须与宿主 `lib/typert.host.js` 的 fileSchema **同宽**（strict 会剥掉未声明字段）：
+		// 少了 tags / locked，列表页的「按标签筛」与「锁定」按钮就永远拿到 undefined。
+		const fileSchema = parseSchema({ "file": isStr, "type": isStr, "description": isStr, "size": isNum, "tags": isStrArr, "locked": isBool });
+		const listSchema = { fields: fileSchema.fields, parse(v) { if (!Array.isArray(v)) throw new Error("expected array"); v.forEach((f) => fileSchema.parse(f)); return v; } };
 		const readSchema = withOptional(parseSchema({ "name": isStr, "content": isStr }), ["revision"]);
-		const writeSchema = withOptional(parseSchema({ "ok": isBool, "file": isStr }), ["code", "revision"]);
-		const deleteSchema = parseSchema({ "ok": isBool });
-		const starmapStarSchema = parseSchema({ "file": isStr, "kind": isStr, "title": isStr, "desc": isStr, "bytes": isNum, "mtimeMs": isNum });
-		const starmapListSchema = { parse(v) { if (!v || typeof v !== "object") throw new Error("expected object"); if (!Array.isArray(v.stars)) throw new Error("expected stars array"); v.stars.forEach((f) => starmapStarSchema.parse(f)); return v; } };
+		const writeSchema = optionalFields(parseSchema({ "ok": isBool, "file": isStr }), { "error": isStr, "code": isStr, "revision": isStr });
+		const deleteSchema = optionalFields(parseSchema({ "ok": isBool }), { "error": isStr });
+		// `archived` 每颗星都有（活动星是 false）；archivedAt / archivedReason 只对归档星出现，
+		// 且旧版 autodream 归档的文件没有它们 —— 所以是 optional（与宿主 manifest 一致）。
+		const starmapStarSchema = withOptional(
+			parseSchema({ "file": isStr, "kind": isStr, "title": isStr, "desc": isStr, "bytes": isNum, "mtimeMs": isNum, "archived": isBool }),
+			["archivedAt", "archivedReason"],
+		);
+		const starmapListSchema = { fields: ["count", "stars"], elementFields: starmapStarSchema.fields, parse(v) { if (!v || typeof v !== "object") throw new Error("expected object"); if (!Array.isArray(v.stars)) throw new Error("expected stars array"); v.stars.forEach((f) => starmapStarSchema.parse(f)); return v; } };
 		const starmapReadSchema = parseSchema({ "name": isStr, "content": isStr });
 
 		// ── 归档区（v0.9.0 档案馆）──
@@ -1664,15 +1676,24 @@ const StarmapRuntime = (function (require, _react) {
 		// 结果 codec 与宿主 manifest 逐字段对齐（ArchiveResult 的 file / error 都可选，
 		// 成功回 file、失败回 error，所以这里只硬校 ok）。
 		const boolSchema = { parse(v) { isBool(v); return v; } };
-		const archiveSchema = parseSchema({ "ok": isBool });
+		// 归档结果（宿主的 archiveResultSchema）：**除 ok 外全部 optional**。失败分支没有 file，
+		// 把它当必填会把「失败」判成坏结果 —— 宿主的 typert.host.js 有同一条注释。
+		// `unindexed` / `indexed` 是 boolean，所以不能套 withOptional（那个只做 isStr）。
+		const archiveResultFields = { "file": isStr, "error": isStr, "archivedReason": isStr, "unindexed": isBool, "indexed": isBool, "indexError": isStr };
+		const archiveResultSchema = optionalFields(parseSchema({ "ok": isBool }), archiveResultFields);
+		// archive / restore / deleteArchived / writeArchived 四个 remote 共用这一个形状。
+		const archiveSchema = archiveResultSchema;
 		const archivedFileSchema = parseSchema({
 			"file": isStr, "type": isStr, "description": isStr, "size": isNum,
+			"tags": isStrArr,
 			"archivedAt": isStr, "archivedReason": isStr,
 			// 2.1.6（外部审查 Q07）：内容身份（归档代次 + 正文 revision）。它不是装饰 ——
 			// 「彻底删除」必须把它原样交回宿主，否则只能按名字删，而名字不是身份。
 			"revision": isStr,
 		});
 		const archivedListSchema = {
+			fields: ["count", "files"],
+			elementFields: archivedFileSchema.fields,
 			parse(v) {
 				if (!v || typeof v !== "object") throw new Error("sage-mem: expected object");
 				if (!Array.isArray(v.files)) throw new Error("sage-mem: expected files array");
@@ -1682,7 +1703,9 @@ const StarmapRuntime = (function (require, _react) {
 		};
 		// 归档文件的读 / 写（B1b）：形状与活跃记忆那套的 readSchema / writeSchema 对称。
 		const archivedReadSchema = withOptional(parseSchema({ "name": isStr, "content": isStr }), ["revision"]);
-		const archivedWriteSchema = withOptional(parseSchema({ "ok": isBool, "file": isStr }), ["code", "revision"]);
+		// 宿主 `archivedWriteResultSchema` 与 `writeResultSchema` **同形、只是类型名不同**
+		// （typert.host.js 的注释明说这一点）——所以直接复用 writeSchema 的字段面。
+		const archivedWriteSchema = writeSchema;
 		// 「彻底删除」的入参：`archivedAt`（展示时间）+ `revision`（内容身份，见 archive.js 的
 		// archivedRevisionOf）。两个都不是装饰 —— 宿主拿它们核对「要删的是不是用户确认过的那一版」；
 		// 只有前者的旧确认在 2.1.6 起会被宿主拒绝（分钟精度的时间不是内容身份）。
@@ -1695,15 +1718,22 @@ const StarmapRuntime = (function (require, _react) {
 		 * 混合版本环境里「旧宿主 + 新面板」必须还能用，所以这里不能当必填字段拒掉；
 		 * 但字段给了就必须是字符串 —— 否则面板拿到一个数字或对象会静默走错分支。
 		 */
-		function withOptional(base, keys) {
+		function optionalFields(base, spec) {
 			return {
+				// 可选字段并入字段集：对表时宿主 zod 的 optional 字段也在它的 shape 里，
+				// 两边必须一样宽，否则「客户端没声明 optional 字段」会被误报成漂移。
+				fields: (base.fields || []).concat(Object.keys(spec)),
 				parse(v) {
 					base.parse(v);
-					for (let i = 0; i < keys.length; i++) if (keys[i] in v) isStr(v[keys[i]]);
+					for (const [k, check] of Object.entries(spec)) if (k in v) check(v[k]);
 					return v;
 				},
 			};
 		}
+		/** 可选字段全是字符串时的简写（读 revision / 写 code / revision）。 */
+		function withOptional(base, keys) {
+			return optionalFields(base, Object.fromEntries(keys.map((k) => [k, isStr])));
+		}
 		/**
 		 * 写协议的第三参（`{ expectedRevision?, create? }`）——**两个字段都可选**。
 		 * 不传 = 旧调用方，行为与从前一致（宿主会打一条 warn）；传了就必须是正确类型。

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