sage-mem 2.1.1 → 2.1.3

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.1.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
+**Current release: `2.1.3`** — 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.1`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.3`** —— 顶部 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

@@ -489,24 +489,65 @@ export function createToolRunner(opts) {
   const readVersions = new Map()
 
   /**
-   * 记下一次读取对应的版本。取不到可信版本就**什么都不记**（宁可让写入走「拒绝」，
-   * 也不要拿一个来路不明的版本假装有守卫）。
+   * 把「这份内容对应磁盘上的哪个版本」记下来（写回时当守卫）。
    *
-   * 一致性：宿主 fs 可用时用 `stat → 读 → stat`，**两次版本相同**才认这份内容是那个版本的快照。
-   * 中间被人改过就不记 —— 分开读拿不到原子快照，那就诚实地说「不知道」。
+   * 取不到可信版本（`version` 为 null）就**什么都不记** —— 宁可让写入走「拒绝」，
+   * 也不要拿一个来路不明的版本假装有守卫。
+   *
+   * ⚠️ 这里只登记、**自己不 stat**。版本由 `readEntryWithVersion` 在**实际读取的前后**
+   * 各取一次得到；以前是在 `readFile` **之后**才 stat 两次，读 A、盘上已是 B 时两次 stat
+   * 都是 B，于是 A 的正文被绑到 B 的版本上（外部审查 2026-10-31，Q01）。
    */
-  async function rememberReadVersion(fullPath, content, truncated) {
+  function rememberReadVersion(fullPath, version, truncated) {
+    if (!version) return
+    const where = memoryPathOf(fullPath, memoryDir)
+    if (where.ok) readVersions.set(where.canon, { version, truncated: truncated === true })
+  }
+
+  /**
+   * 「读内容」与「取版本」共用的**唯一入口**（外部审查 2026-10-31，Q01）。
+   *
+   * 为什么必须是入口、不是两段调用：写回守卫要回答的是「**这份正文**对应哪一个版本」。
+   * 分开写时，调用方手里是 `readFile` 的返回值和两次 `stat` 的结果，把三者拼起来那一步最容易错
+   * —— 真实代码曾是 `readFile → stat → stat`：读的是 A，两次 stat 都读到 B，
+   * 于是 A 的正文被绑到 B 的版本，宿主的 CAS 即使完全正确也救不了这个错配。
+   *
+   * 顺序固定 **stat → read → stat**，两次版本**相同**才认这份内容就是那个版本的快照；
+   * 任何一次取不到（没有宿主 fs 服务 / stat 抛错 / 版本字段缺失）都按「版本未知」处理，
+   * 不拿当前版本补票 —— 补票等于替调用方担保一份它没读过的内容。
+   *
+   * 宿主 `fs` 契约里目前**没有**「原子 read-with-version」这一原语（`readText` 只回正文），
+   * 所以退到两次 stat 夹住实际读取。将来宿主提供这个原语，应当优先在 open 句柄上一次性拿到。
+   *
+   * @returns {Promise<{ok:false, gate:object}|{ok:true, gate:object, content:string, version:string|null}>}
+   *   `gate` 是 `inspectMemoryEntry` 的结果（2.1.4 起内容读还用它做身份核对）
+   */
+  async function readEntryWithVersion(full) {
+    const gate = await inspectMemoryEntry(full)
+    if (!gate.ok) return { ok: false, gate }
+    const fs = hostFs()
+    const hostStat = async () => {
+      if (!fs || typeof fs.stat !== 'function') return null
+      try {
+        const info = await fs.stat(await fs.resolve(full))
+        return info?.version ?? null
+      } catch {
+        return null // 取不到就是未知：不要拿「现在」的版本顶替
+      }
+    }
+    const before = await hostStat()
+    let content
     try {
-      const fs = hostFs()
-      if (!fs || typeof fs.stat !== 'function') return
-      const target = await fs.resolve(fullPath)
-      const before = await fs.stat(target)
-      if (!before?.version) return
-      const after = await fs.stat(target)
-      if (!after?.version || after.version !== before.version) return
-      const where = memoryPathOf(fullPath, memoryDir)
-      if (where.ok) readVersions.set(where.canon, { version: before.version, truncated: truncated === true })
-    } catch { /* 记不下就不记：调用方会按「未知版本」处理 */ }
+      content = await readFile(full, 'utf8')
+    } catch (err) {
+      // 扫到读之间被删是正常状态；其余读失败照旧抛给上层（外层会转成一次工具失败）。
+      if (err?.code === 'ENOENT') return { ok: false, gate: { ok: false, code: 'missing' } }
+      throw err
+    }
+    const after = await hostStat()
+    // 两次版本相同才认「内容 = 版本」；只要中间可能被动过就当作未知。
+    const version = before && after && before === after ? before : null
+    return { ok: true, gate, content, version }
   }
 
   /**
@@ -800,22 +841,21 @@ export function createToolRunner(opts) {
              * 过闸门再读：**名字在记忆目录里不等于内容住在记忆目录里**。
              * 注入与面板两条腿都挡住了，这条腿（模型工具）也必须挡 ——
              * 否则外部文件的内容照样会被读进来、送进模型上下文。
+             *
+             * 内容与版本一起取（`readEntryWithVersion`）：守卫要的是「这份正文对应哪个版本」，
+             * 分开取会把 A 的正文绑到 B 的版本上（Q01）。
              */
-            const gate = await inspectMemoryEntry(full)
-            if (!gate.ok) {
-              return gate.code === 'missing'
+            const seen = await readEntryWithVersion(full)
+            if (!seen.ok) {
+              return seen.gate.code === 'missing'
                 ? `错误：没有这个文件：${basename(full)}`
-                : `错误：拒绝读取 ${basename(full)}：${gate.error}`
+                : `错误：拒绝读取 ${basename(full)}：${seen.gate.error}`
             }
-            const content = await readFile(full, 'utf8').catch((err) => {
-              if (err?.code === 'ENOENT') return null
-              throw err
-            })
-            if (content === null) return `错误：没有这个文件：${basename(full)}`
-            // 记下「这份内容对应磁盘上的哪个版本」——写回时用它当守卫（外部复审 R01）。
+            const content = seen.content
+            // 记下「这份内容对应磁盘上的哪个版本」——写回时用它当守卫（外部复审 R01 / Q01）。
             // 截断的读也要标出来：截断内容不足以作为整份覆盖的依据。
             const truncated = content.length > READ_LIMIT
-            await rememberReadVersion(full, content, truncated)
+            rememberReadVersion(full, seen.version, truncated)
             if (truncated) {
               return `${content.slice(0, READ_LIMIT)}\n\n…（已截断，全文 ${content.length} 字符。注意：截断的读不能作为整份覆盖的依据）`
             }

package/lib/autodream.js

@@ -6,3 +6,8 @@
  */
 
 export { AutodreamEngine } from './autodream/engine.js'
+// 组合根的本地 import 有 ≤20 条的条数护栏（`test/structure-test.mjs`「依赖面不许发散」）。
+// 体检与默认配置本来就是 autodream 这一域的一部分，从这层转出（本文件的存在意义就是
+// 让外部只认一个入口），组合根因此不必再多两条 import —— 不是给组合根找捷径。
+export { auditMemoryDir } from './autodream/audit.js'
+export { DEFAULT_CONFIG } from './autodream/config.js'

package/lib/client.js

@@ -1539,8 +1539,8 @@ const StarmapRuntime = (function (require, _react) {
 		// 基元（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 readSchema = parseSchema({ "name": isStr, "content": isStr });
-		const writeSchema = parseSchema({ "ok": isBool, "file": isStr });
+		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; } };
@@ -1565,12 +1565,40 @@ const StarmapRuntime = (function (require, _react) {
 			},
 		};
 		// 归档文件的读 / 写（B1b）：形状与活跃记忆那套的 readSchema / writeSchema 对称。
-		const archivedReadSchema = parseSchema({ "name": isStr, "content": isStr });
-		const archivedWriteSchema = parseSchema({ "ok": isBool, "file": isStr });
+		const archivedReadSchema = withOptional(parseSchema({ "name": isStr, "content": isStr }), ["revision"]);
+		const archivedWriteSchema = withOptional(parseSchema({ "ok": isBool, "file": isStr }), ["code", "revision"]);
 		// 「彻底删除」的入参：归档代次（`archivedAt`）。它不是装饰 —— 宿主拿它核对
 		// 「要删的是不是用户确认过的那一版」。老归档件没有留痕时传空串，所以只校类型。
 		const archiveStampSchema = strSchema;
 
+		// ── 2.1.2（Q02）写协议：读快照 revision / 写回执的 additive 字段 / 写选项 ──
+		/**
+		 * **可选**字段校型：新宿主一定给（读 revision、写 code / revision），旧宿主没有。
+		 * 混合版本环境里「旧宿主 + 新面板」必须还能用，所以这里不能当必填字段拒掉；
+		 * 但字段给了就必须是字符串 —— 否则面板拿到一个数字或对象会静默走错分支。
+		 */
+		function withOptional(base, keys) {
+			return {
+				parse(v) {
+					base.parse(v);
+					for (let i = 0; i < keys.length; i++) if (keys[i] in v) isStr(v[keys[i]]);
+					return v;
+				},
+			};
+		}
+		/**
+		 * 写协议的第三参（`{ expectedRevision?, create? }`）——**两个字段都可选**。
+		 * 不传 = 旧调用方，行为与从前一致（宿主会打一条 warn）；传了就必须是正确类型。
+		 */
+		const writeOptsSchema = {
+			parse(v) {
+				if (v === null || typeof v !== "object" || Array.isArray(v)) throw new Error("sage-mem: expected object");
+				if ("expectedRevision" in v) isStr(v.expectedRevision);
+				if ("create" in v) isBool(v.create);
+				return v;
+			},
+		};
+
 		// ── autodream 的 codec ──
 		// 刻意写得宽：这几个方法返回的是配置 / 状态对象，字段会随版本增删。
 		// 用 parseSchema 逐字段硬写一遍的代价是 —— host 那边加一个字段，client 的旧
@@ -1736,6 +1764,8 @@ const StarmapRuntime = (function (require, _react) {
 					parameters: [
 						{ name: "name", wire: "name", source: "json", codec: { mode: "strict", typeSymbol: "sage-mem/types#FileName", schema: strSchema, create: () => strSchema } },
 						{ name: "content", wire: "content", source: "json", codec: { mode: "strict", typeSymbol: "sage-mem/types#FileContent", schema: strSchema, create: () => strSchema } },
+						// 2.1.2（Q02）：写协议第三参（expectedRevision / create），可选 —— 与宿主 manifest 同一条。
+						{ name: "opts", wire: "opts", source: "json", acceptsUndefined: true, codec: { mode: "strict", typeSymbol: "sage-mem/types#WriteOpts", schema: writeOptsSchema, create: () => writeOptsSchema } },
 					],
 					result: { mode: "strict", typeSymbol: "sage-mem/types#WriteResult", schema: writeSchema, create: () => writeSchema },
 					sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
@@ -1808,6 +1838,7 @@ const StarmapRuntime = (function (require, _react) {
 					parameters: [
 						{ name: "name", wire: "name", source: "json", codec: { mode: "strict", typeSymbol: "sage-mem/types#ArchivedFileName", schema: strSchema, create: () => strSchema } },
 						{ name: "content", wire: "content", source: "json", codec: { mode: "strict", typeSymbol: "sage-mem/types#ArchivedFileContent", schema: strSchema, create: () => strSchema } },
+						{ name: "opts", wire: "opts", source: "json", acceptsUndefined: true, codec: { mode: "strict", typeSymbol: "sage-mem/types#WriteOpts", schema: writeOptsSchema, create: () => writeOptsSchema } },
 					],
 					result: { mode: "strict", typeSymbol: "sage-mem/types#ArchivedWriteResult", schema: archivedWriteSchema, create: () => archivedWriteSchema },
 					sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
@@ -1932,6 +1963,7 @@ const StarmapRuntime = (function (require, _react) {
 					parameters: [
 						{ name: "name", wire: "name", source: "json", codec: { mode: "strict", typeSymbol: "sage-mem/types#ReservedFileName", schema: strSchema, create: () => strSchema } },
 						{ name: "content", wire: "content", source: "json", codec: { mode: "strict", typeSymbol: "sage-mem/types#RawFileContent", schema: strSchema, create: () => strSchema } },
+						{ name: "opts", wire: "opts", source: "json", acceptsUndefined: true, codec: { mode: "strict", typeSymbol: "sage-mem/types#WriteOpts", schema: writeOptsSchema, create: () => writeOptsSchema } },
 					],
 					result: { mode: "strict", typeSymbol: "sage-mem/types#RawWriteResult", schema: objCodec, create: () => objCodec },
 					sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
@@ -5769,6 +5801,10 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			// 打开时展示给用户的类型（判断他是否真的改过类型）
 			const sFormBaseType = react.useState("");
 			const formBaseType = sFormBaseType[0], setFormBaseType = sFormBaseType[1];
+			// 2.1.2（Q02）：打开编辑时读到的**版本**（readFile 的 revision）。保存时原样带回；
+			// 宿主发现盘上已变就回 stale_revision，编辑框与草稿原地保留，绝不自动重试覆盖。
+			const sFormRevision = react.useState(null);
+			const formRevision = sFormRevision[0], setFormRevision = sFormRevision[1];
 			const sBusy = react.useState(false);
 			const busy = sBusy[0], setBusy = sBusy[1];
 			const sOk = react.useState(false);
@@ -5797,6 +5833,9 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			const archEdit = sArchEdit[0], setArchEdit = sArchEdit[1];
 			const sArchText = react.useState("");
 			const archText = sArchText[0], setArchText = sArchText[1];
+			// 2.1.2（Q02）：这份归档件读到的版本（保存时带回；冲突时草稿保留）
+			const sArchRevision = react.useState(null);
+			const archRevision = sArchRevision[0], setArchRevision = sArchRevision[1];
 			const sArchLoad = react.useState(false);
 			const archLoad = sArchLoad[0], setArchLoad = sArchLoad[1];
 			const sArchSaving = react.useState(false);
@@ -5837,6 +5876,9 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			const rawText = sRawText[0], setRawText = sRawText[1];
 			const sRawIsNew = react.useState(false);
 			const rawIsNew = sRawIsNew[0], setRawIsNew = sRawIsNew[1];
+			// 2.1.2（Q02）：这份保留名文件读到的版本；null + rawIsNew = 走 createIfAbsent 新建
+			const sRawRevision = react.useState(null);
+			const rawRevision = sRawRevision[0], setRawRevision = sRawRevision[1];
 			const sRawBusy = react.useState(false);
 			const rawBusy = sRawBusy[0], setRawBusy = sRawBusy[1];
 			const sRawLoading = react.useState(false);
@@ -5971,6 +6013,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			function closeForm() {
 				setFormOpen(false); setEditingFile(null); setFormName(""); setFormDesc(""); setFormBody(""); setFormType("feedback");
 				setFormFm(null); setFormBaseType(""); setFormTags("");
+				setFormRevision(null);
 			}
 
 			// 空记忆库时「建立索引骨架」写进去的引导文件。它只是给人看的起点：
@@ -6056,6 +6099,8 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 						setFormTags(detectTags(parts.fm).join(", "));
 						// 关键：原 frontmatter 原文留着，保存时「就地合并」而不是重建
 						setFormFm(parts.hasFm ? parts.fm : null);
+						// 2.1.2（Q02）：把这一版的 revision 一起记住（保存时带回；旧宿主没有就是 null）
+						setFormRevision(typeof data.revision === "string" ? data.revision : null);
 						setFormOpen(true);
 					})
 					.catch(function (e) { setError(String((e && e.message) || e)); })
@@ -6072,6 +6117,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				setFormBody("");
 				setFormFm(null);
 				setFormTags("");
+				setFormRevision(null);
 				setFormOpen(true);
 			}
 
@@ -6098,9 +6144,16 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 						tags: tags,
 					});
 				}
-				remote.writeFile(safeName, content)
+				// 2.1.2（Q02）：编辑已有文件时交回读到的 revision（盘上变了 → 宿主拒绝）；
+				// 新建走 createIfAbsent —— 撞上同名文件是**明确报已存在**，绝不覆盖入口。
+				const writeOpts = editingFile
+					? (formRevision ? { expectedRevision: formRevision } : undefined)
+					: { create: true };
+				remote.writeFile(safeName, content, writeOpts)
 					.then(function (r) {
 						// host 侧对保留名 / 非字符串内容 / 超限一律返回 { ok: false, error }，不再抛异常。
+						// 冲突看**结构化 code**（stale_revision / already_exists），不解析文案：
+						// 编辑框不关、草稿原地保留，由用户看过最新内容后自己决定重新应用 —— 绝不自动重试覆盖。
 						if (r && r.ok === false) { setError(r.error || t("error.writeRejected")); return; }
 						closeForm();
 						setNotice(t(editingFile ? "notice.updated" : "notice.saved", { file: safeName }));
@@ -6233,11 +6286,14 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				setArchDelete(null);
 				setArchEdit(file);
 				setArchText("");
+				setArchRevision(null);
 				setArchLoad(true);
 				remote.readArchived(file)
 					.then(function (r) {
 						const d = unwrap(r);
 						setArchText(d && typeof d.content === "string" ? d.content : "");
+						// 2.1.2（Q02）：记住这一版的 revision（保存时带回）
+						setArchRevision(d && typeof d.revision === "string" ? d.revision : null);
 						setArchLoad(false);
 					})
 					.catch(function (e) {
@@ -6254,7 +6310,10 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				}
 				setArchSaving(true); setError(null); setNotice("");
 				// 原样交回：不 trim、不补 frontmatter、不做任何「智能」处理。
-				remote.writeArchived(file, archText)
+				// 2.1.2（Q02）：带上读到的 revision；归档件在别处被改过 → 宿主回 stale_revision，
+				// 编辑框与文本原地保留（不自动重试覆盖）。
+				const writeOpts = archRevision ? { expectedRevision: archRevision } : undefined;
+				remote.writeArchived(file, archText, writeOpts)
 					.then(function (r) {
 						if (r && r.ok === false) { setError(r.error || t("error.saveRejected")); return; }
 						setArchEdit(null);
@@ -6265,7 +6324,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 					.then(function () { setArchSaving(false); });
 			}
 
-			function cancelArchEdit() { setArchEdit(null); setArchText(""); }
+			function cancelArchEdit() { setArchEdit(null); setArchText(""); setArchRevision(null); }
 
 			// ── 工具面板的三个数据通道 ──────────────────────────────────────
 
@@ -6578,11 +6637,14 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				setRawName(name);
 				setRawText("");
 				setRawIsNew(false);
+				setRawRevision(null);
 				setRawLoading(true);
 				remote.readRaw(name)
 					.then(function (r) {
 						const d = unwrap(r);
 						setRawText(d && typeof d.content === "string" ? d.content : "");
+						// 2.1.2（Q02）：记住这一版的 revision（保存时带回）
+						setRawRevision(d && typeof d.revision === "string" ? d.revision : null);
 						setRawLoading(false);
 					})
 					.catch(function (e) {
@@ -6606,11 +6668,18 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				if (typeof remote.writeRaw !== "function") { setError(t("error.noWriteRaw")); return; }
 				setRawBusy(true); setError(null); setNotice("");
 				// 原样交回：不 trim、不补 frontmatter、不做任何「智能」处理。
-				remote.writeRaw(name, rawText)
+				// 2.1.2（Q02）：新建走 createIfAbsent（撞名明确失败、不覆盖）；编辑带读到的 revision
+				// （盘上变了 → stale_revision，文本原地保留，绝不自动重试覆盖）。
+				const writeOpts = rawIsNew
+					? { create: true }
+					: (rawRevision ? { expectedRevision: rawRevision } : undefined);
+				remote.writeRaw(name, rawText, writeOpts)
 					.then(function (r) {
 						if (r && r.ok === false) { setError(r.error || t("error.saveRejected")); return; }
 						setNotice(t(rawIsNew ? "notice.rawNew" : "notice.saved", { file: name }));
 						setRawIsNew(false);
+						// 保存成功后把版本换成刚写下的那一版，连续保存不用重读
+						if (r && typeof r.revision === "string") setRawRevision(r.revision);
 					})
 					.catch(function (e) { setError(String((e && e.message) || e)); })
 					.then(function () { setRawBusy(false); });

package/lib/index.js

@@ -14,9 +14,7 @@
  * 旧 worker 版见 git 分支 `sqlite-worker`。
  */
 
-import { AutodreamEngine } from './autodream.js'
-import { auditMemoryDir } from './autodream/audit.js'
-import { DEFAULT_CONFIG } from './autodream/config.js'
+import { AutodreamEngine, DEFAULT_CONFIG, auditMemoryDir } from './autodream.js'
 import { LIMIT_SPECS, MAX_BASELINE, MAX_CHARS_PER_FILE, MAX_FILE_BYTES, MAX_RESULTS, MAX_SESSION_BYTES, MEMORY_DIR, RECALL_DISCIPLINE, RESERVED_FILES, SESSIONS_ROOT, STALE_DAYS, STATE_ROOT } from './memory/config.js'
 import { INDEX_FILE_KEY, SESSION_LOG_KEY, isPlainMdName } from './shared/md-name.js'
 import { parseAliases, parseBaseline, parseBaselinePriority, parseFrontmatter, parseTags } from './memory/frontmatter.js'
@@ -25,6 +23,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 { archiveMemory, deleteArchivedMemory, restoreMemory } from './memory/archive.js'
 import { flushAccess, pickArchiveCandidates, readAccessLedger } from './memory/access.js'
 import { warnLog, writeFileAtomic } from './memory/util.js'
@@ -131,6 +130,9 @@ export class MemoryGateway extends TypertRemoteService {
    *
    * 过闸门再读：名字在记忆目录里**不等于**内容住在记忆目录里 —— 符号链接 / 目录联接 /
    * 硬链接都能让一次「读自己的记忆」变成读别人的文件，而读到的内容会被注入模型上下文。
+   *
+   * 2.1.2（Q02）：返回值多一个 `revision`（正文字节的 sha256）。保存时把它带回来，
+   * 盘上版本变了就拒绝覆盖（见 `memory/write-protocol.js`）。
    */
   async readFile(name) {
     const safe = safeName(name)
@@ -143,8 +145,7 @@ export class MemoryGateway extends TypertRemoteService {
     }
     const gate = await inspectMemoryEntry(full)
     if (!gate.ok) throw new Error(`sage-mem: refusing to read ${safe}: ${gate.error}`)
-    const content = await readVerified(full, gate, 'utf8')
-    return { name: safe, content }
+    return await readSnapshot(full, gate, safe)
   }
 
   /**
@@ -152,8 +153,16 @@ export class MemoryGateway extends TypertRemoteService {
    *
    * 三道闸：保留名不可写、内容必须是字符串、体积有上限；落盘走原子写。
    * 拒绝一律返回 { ok: false, error }（不是抛异常）——设置页的调用方按 ok 判定。
+   *
+   * 2.1.2（Q02）：可选第三参 `opts`
+   *   · `{ expectedRevision }`：读快照时拿到的 revision；盘上对不上 → `{ok:false, code:'stale_revision'}`，
+   *     当前内容逐字节不变（面板保留草稿，提示重新应用）；
+   *   · `{ create: true }`：新建语义（createIfAbsent）。撞名 → `{ok:false, code:'already_exists'}`，
+   *     **绝不**覆盖已有正文；
+   *   · 不传 `opts`：旧调用方照旧覆盖，但会落一条 warn（additive 契约里只保留兼容，不保留静默）。
+   * 成功时回 `revision`（落盘后的新版本），调用方可以直接拿它继续保存。
    */
-  async writeFile(name, content) {
+  async writeFile(name, content, opts) {
     // 保留名判定放在最前面、且以 nameKey 归一：'memory.md' / 'MEMORY.MD' /
     // 'Session-Log.md' 在 NTFS 上都是同一个文件，必须一律走 { ok: false } 这条路
     // （设置页按 ok 判定，见 client.js 的 submit()）。
@@ -189,8 +198,7 @@ export class MemoryGateway extends TypertRemoteService {
     if (!existing.ok && existing.code !== 'missing') {
       return { ok: false, file: safe, error: `sage-mem: refusing to write ${safe}: ${existing.error}` }
     }
-    await writeFileAtomic(target, content)
-    return { ok: true, file: safe }
+    return await writeSnapshot(target, content, existing, opts, { ctx: this.ctx, name: safe, kind: 'writeFile' })
   }
 
   /** 删除单个记忆文件：保留名一律拒绝（unlink 不可逆）。判定同 writeFile。 */
@@ -301,8 +309,8 @@ export class MemoryGateway extends TypertRemoteService {
       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}`)
     }
-    const content = await readVerified(full, gate, 'utf8')
-    return { name: safe, content }
+    // 2.1.2（Q02）：归档件与活动记忆同一套读快照协议，回 {name, content, revision}。
+    return await readSnapshot(full, gate, safe)
   }
 
   /**
@@ -312,8 +320,11 @@ export class MemoryGateway extends TypertRemoteService {
    * 额外一条：**盘上那份的归档留痕（`archived_at` / `archived_reason`）不许因为改正文而丢**。
    * 调用方若交回一份连留痕都没有的内容（「重建 frontmatter」式编辑器就是这样），
    * 这里按盘上原来的值补回去 —— 归档凭据不该依赖调用方是否体贴。
+   *
+   * 2.1.2（Q02）：与 `writeFile` 同一套写协议 —— 可选 `opts.expectedRevision`，
+   * 归档件在别处被改过就回 `{ok:false, code:'stale_revision'}`，正文逐字节不变。
    */
-  async writeArchived(name, content) {
+  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)}` }
     }
@@ -349,8 +360,8 @@ export class MemoryGateway extends TypertRemoteService {
         toWrite = addArchiveMeta(content, onDisk.archivedReason, onDisk.archivedAt)
       }
     }
-    await writeFileAtomic(full, toWrite)
-    return { ok: true, file: safe }
+    // 2.1.2（Q02）：落盘也走写协议 —— 带 opts 时先比盘上版本，对不上就拒绝（正文逐字节不变）。
+    return await writeSnapshot(full, toWrite, gate, opts, { ctx: this.ctx, name: safe, kind: 'writeArchived' })
   }
 
   /**
@@ -549,8 +560,8 @@ export class MemoryGateway extends TypertRemoteService {
     if (!gate.ok) throw new Error(`sage-mem: refusing to read ${safe}: ${gate.error}`)
     // 读不到就抛（与 readFile 一致）：静默返回空串会让面板显示一份「空的索引」，
     // 用户一存就把真索引顶掉。
-    const content = await readVerified(full, gate, 'utf8')
-    return { name: safe, content }
+    // 2.1.2（Q02）：保留名与普通记忆同一套读快照协议 —— 回 {name, content, revision}。
+    return await readSnapshot(full, gate, safe)
   }
 
   /**
@@ -558,8 +569,12 @@ export class MemoryGateway extends TypertRemoteService {
    *
    * 这就是 2026-09-25 那次 P0 数据丢失事故（表单重建 frontmatter 把 baseline /
    * node_type / originSessionId 全抹掉）的解药：索引与流水只许原样进出。
+   *
+   * 2.1.2（Q02）：与 `writeFile` 同一套写协议 —— `opts.expectedRevision` 对不上则
+   * `{ok:false, code:'stale_revision'}`（索引逐字节不变）；`opts.create` 用于「建立索引骨架」
+   * 这类 createIfAbsent 语义（撞名明确报 `already_exists`，绝不覆盖）。
    */
-  async writeRaw(name, content) {
+  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` }
     }
@@ -584,8 +599,7 @@ export class MemoryGateway extends TypertRemoteService {
     if (!existing.ok && existing.code !== 'missing') {
       return { ok: false, file: safe, error: `sage-mem: refusing to write ${safe}: ${existing.error}` }
     }
-    await writeFileAtomic(target, content)
-    return { ok: true, file: safe }
+    return await writeSnapshot(target, content, existing, opts, { ctx: this.ctx, name: safe, kind: 'writeRaw' })
   }
 }
 

package/lib/memory/write-protocol.js

@@ -0,0 +1,111 @@
+/**
+ * sage-mem 记忆层 —— 写协议：**读快照带 revision、整份覆盖带守卫**（2.1.2 / 外部审查 Q02）。
+ *
+ * 问题：原来的 `readFile` 只交正文、不交「这份正文是哪一版」；`writeFile` / `writeArchived` /
+ * `writeRaw` 只管原子替换（不暴露半截内容），**不保证没有别的更新** —— 面板读 A、别处存 B、
+ * 面板再把基于 A 的 C 存回去，B 就没了，而两边都报成功。
+ *
+ * 契约（additive，旧调用方不受影响）：
+ *   · 读：结果多一个 `revision`（正文**字节**的 sha256）；
+ *   · 写：可选 `opts.expectedRevision`；对不上 → `{ok:false, code:'stale_revision'}`，
+ *     当前内容一个字节不动；调用方拿新 revision 重读、比较、重新应用。
+ *   · 写：可选 `opts.create`（createIfAbsent）—— 新建撞名一律 `{ok:false, code:'already_exists'}`，
+ *     **绝不**走覆盖入口；
+ *   · 不传 `opts` 的旧调用方照旧覆盖，但会落一条 warn（静默无守卫覆盖不再允许）。
+ *
+ * 为什么单列一个模块而不是长在 `lib/index.js`：组合根有 ≤1000 行的结构守卫
+ * （`test/structure-test.mjs`），而「读版本 → 比版本 → 写」这段顺序是**协议**不是组合根的接线。
+ *
+ * ⚠️ 边界：这是**内容 hash 守卫**，不是跨进程锁。校验与落盘之间仍有一个极窄窗口
+ * （外部编辑器恰在此刻改文件仍会被覆盖）；进程内并发由 `createWriteQueue` 那一层负责，
+ * 面板这条路上「读快照 → 用户思考 → 保存」的窗口正是 revision 覆盖的那一段。
+ */
+
+import { createHash } from 'node:crypto'
+import { readVerified } from './scan.js'
+import { warnLog, writeFileAtomic, writeFileExclusive } from './util.js'
+
+/** 冲突码：内容在「读快照」之后被改过。固定字符串，界面与测试都只认它。 */
+export const ERR_STALE_REVISION = 'stale_revision'
+/** 冲突码：`create`（createIfAbsent）撞上已有文件 —— 新建绝不覆盖已有内容。 */
+export const ERR_ALREADY_EXISTS = 'already_exists'
+
+/** 内容 revision：字节的 sha256。读与写必须用同一个算法，调用方原样回传。 */
+export function revisionOf(bytes) {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+
+/**
+ * 读一份**可信快照**：content 与 revision 在同一次读取里拿到。
+ *
+ * 调用方不能只拿一半 —— 「正文来自这次读、版本来自另一次读」正是 Q02 的成因。
+ *
+ * @returns {Promise<{name:string, content:string, revision:string}>}
+ */
+export async function readSnapshot(full, gate, name) {
+  const bytes = await readVerified(full, gate, false)
+  return { name, content: bytes.toString('utf8'), revision: revisionOf(bytes) }
+}
+
+/** 旧调用方的兼容提示（一次写入一行，不做去重 —— 谁漏传一眼就能在日志里翻到）。 */
+const LEGACY_WARN = '没有带 expectedRevision，按旧协议直接覆盖（面板必须带；旧调用方仅兼容，建议尽快带上）'
+
+/**
+ * 整份覆盖写：`create` / `expectedRevision` / 旧调用方三种语义，一个出口。
+ *
+ * @param {string} target — 完整路径（名字闸门由调用方先过）
+ * @param {string} content — 要写的正文
+ * @param {object} gate — 调用方刚取到的 `inspectMemoryEntry` 结果（ok 或 code:'missing'）
+ * @param {object} [opts] — `{ expectedRevision?, create? }`
+ * @param {{ctx:object, name:string, kind:string}} meta — 日志与回执用
+ * @returns {Promise<{ok:true, file:string, revision:string, created?:boolean}
+ *   | {ok:false, code:string, file?:string, error:string}>}
+ */
+export async function writeSnapshot(target, content, gate, opts, meta) {
+  const o = opts && typeof opts === 'object' ? opts : {}
+  const name = meta?.name ?? ''
+  const rejected = (code, error) => ({ ok: false, code, file: name, error })
+
+  // ① createIfAbsent：新建只能「建出来」或「明确报已存在」，没有第三条路。
+  if (o.create === true) {
+    if (gate?.ok) return rejected(ERR_ALREADY_EXISTS, `sage-mem: ${name} 已经存在，新建不会覆盖它（要改正文请打开它）`)
+    try {
+      await writeFileExclusive(target, content)
+    } catch (err) {
+      if (err?.code === 'EEXIST') return rejected(ERR_ALREADY_EXISTS, `sage-mem: ${name} 刚刚被别的写入建出来了，新建没有覆盖它`)
+      return rejected('io_error', `sage-mem: 写入 ${name} 失败：${String(err?.message ?? err)}`)
+    }
+    return { ok: true, file: name, revision: revisionOf(Buffer.from(content, 'utf8')), created: true }
+  }
+
+  // ② 带 expectedRevision：盘上版本与调用方读到的不一致 → 拒绝，内容一个字节不动。
+  if (o.expectedRevision !== undefined && o.expectedRevision !== null) {
+    if (!gate?.ok) {
+      // 读快照时还在、现在没了：这同样是「版本已变」，不能悄悄当成新建写回去。
+      return rejected(ERR_STALE_REVISION, `sage-mem: ${name} 已经不在盘上了（读取之后被删除或改名），没有写入`)
+    }
+    let current
+    try {
+      current = revisionOf(await readVerified(target, gate, false))
+    } catch (err) {
+      return rejected(ERR_STALE_REVISION, `sage-mem: 读不到 ${name} 的当前版本（${err?.code ?? err}），没有写入`)
+    }
+    if (current !== o.expectedRevision) {
+      // 错误正文是给用户看的：草稿还在、下一步该做什么，都要说清楚（界面直接显示它）。
+      return rejected(
+        ERR_STALE_REVISION,
+        `sage-mem: ${name} 在你保存之前已经被别的写入改过（当前版本 ${current.slice(0, 12)}…）。你的草稿还在，请先查看最新内容再决定如何重新应用 —— 没有自动覆盖`,
+      )
+    }
+  } else {
+    // ③ 旧调用方：additive 契约允许继续工作，但必须留痕（否则「静默覆盖」永远查不出来）。
+    warnLog(meta?.ctx, `${meta?.kind ?? 'write'}(${name}) ${LEGACY_WARN}`)
+  }
+
+  try {
+    await writeFileAtomic(target, content)
+  } catch (err) {
+    return rejected('io_error', `sage-mem: 写入 ${name} 失败：${String(err?.message ?? err)}`)
+  }
+  return { ok: true, file: name, revision: revisionOf(Buffer.from(content, 'utf8')) }
+}

package/lib/typert.host.js

@@ -20,6 +20,10 @@ const fileNameSchema = z.string().min(1).max(255).regex(new RegExp(MD_NAME_PATTE
 // 到半兆量级基本是写错了目标（贴了日志/代码进来）。与 lib/index.js 的 MAX_FILE_BYTES 一致。
 const fileContentSchema = z.string().max(MAX_FILE_BYTES)
 
+// 2.1.2（Q02）：写协议第三参（expectedRevision / create）—— 字段与参数都 optional，旧调用方照旧过；
+// 不声明它的话 strictObject 会把新面板传的 revision 整个拒掉（不是弱化，是完全不通）。
+const writeOptsSchema = z.object({ 'expectedRevision': z.string().max(128).readonly().optional(), 'create': z.boolean().readonly().optional() }).readonly()
+
 // autodream 报告引用：比 fileNameSchema 宽——旧版报告列表里的条目带 `dream/` 前缀
 // （新版 `autodream/` 不加前缀只给裸文件名）。这里放行斜杠，真正的目录逃逸防护
 // 在 host 侧 AutodreamEngine.readReport 里（先剥已知前缀、再对 basename 走 safeName）。
@@ -65,6 +69,8 @@ const listResultSchema = z.array(fileSchema)
 const readResultSchema = z.object({
 	'name': z.string().readonly(),
 	'content': z.string().readonly(),
+	// 2.1.2（Q02）：读快照的版本令牌（optional —— additive 契约只许加，不许把已有字段改成必填）。
+	'revision': z.string().readonly().optional(),
 }).readonly()
 // 写/删失败不再抛异常，走 { ok: false, error } 分支：error 必须声明，否则 strict
 // 校验会把它当未知字段剥掉，设置页只能看到一个没有原因的 ok:false。
@@ -72,6 +78,8 @@ const writeResultSchema = z.object({
 	'ok': z.boolean().readonly(),
 	'file': z.string().readonly(),
 	'error': z.string().readonly().optional(),
+	// 2.1.2（Q02）：成功回新 revision；冲突回固定错误码（stale_revision / already_exists）。都是 optional。
+	'revision': z.string().readonly().optional(), 'code': z.string().readonly().optional(),
 }).readonly()
 const deleteResultSchema = z.object({
 	'ok': z.boolean().readonly(),
@@ -129,6 +137,8 @@ const archiveResultSchema = z.object({
 const archivedReadResultSchema = z.object({
 	'name': z.string().readonly(),
 	'content': z.string().readonly(),
+	// 2.1.2（Q02）：与活跃记忆同一套读快照协议（optional，同 readResultSchema 的理由）。
+	'revision': z.string().readonly().optional(),
 }).readonly()
 // 写归档的结果与 writeResultSchema 同形，但**另立一个类型名**：strict 层要能区分
 // 「写活跃记忆」与「写归档记忆」两条路径，将来两者形状分叉时也不必回头改协议。
@@ -136,6 +146,7 @@ const archivedWriteResultSchema = z.object({
 	'ok': z.boolean().readonly(),
 	'file': z.string().readonly(),
 	'error': z.string().readonly().optional(),
+	'revision': z.string().readonly().optional(), 'code': z.string().readonly().optional(),
 }).readonly()
 
 // ── 面板 API（v0.9.0 D1）：体检 / 归档候选 / 设置 / 保留名原样读写 ──────────────
@@ -269,11 +280,14 @@ const rawReadResultSchema = z.object({
 	'content': z.string().readonly().optional(),
 	'ok': z.boolean().readonly().optional(),
 	'error': z.string().readonly().optional(),
+	// 2.1.2（Q02）：保留名读快照的版本令牌（optional，同 readResultSchema 的理由）。
+	'revision': z.string().readonly().optional(),
 }).readonly()
 const rawWriteResultSchema = z.object({
 	'ok': z.boolean().readonly(),
 	'file': z.string().readonly().optional(),
 	'error': z.string().readonly().optional(),
+	'revision': z.string().readonly().optional(), 'code': z.string().readonly().optional(),
 }).readonly()
 // 保留名的体积上限比单条记忆大得多（session-log.md 天然 > 512 KB）—— 4 MB，独立于
 // fileContentSchema，别把两者混用。
@@ -639,6 +653,7 @@ export const TYPERT = {
 			parameters: [
 				{ name: 'name', wire: 'name', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#FileName', schema: fileNameSchema, create: () => fileNameSchema } },
 				{ name: 'content', wire: 'content', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#FileContent', schema: fileContentSchema, create: () => fileContentSchema } },
+				{ name: 'opts', wire: 'opts', source: 'json', acceptsUndefined: true, codec: { mode: 'strict', typeSymbol: 'sage-mem/types#WriteOpts', schema: writeOptsSchema, create: () => writeOptsSchema } },
 			],
 			result: { mode: 'strict', typeSymbol: 'sage-mem/types#WriteResult', schema: writeResultSchema, create: () => writeResultSchema },
 			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
@@ -715,6 +730,7 @@ export const TYPERT = {
 				// 正文与「写活跃记忆」共用同一个 512 KB 上限 schema；类型名沿用 #ArchivedFileContent
 				// 是为了与「读归档」那一侧对称（活跃记忆那套也是 FileContent 一符两用）。
 				{ name: 'content', wire: 'content', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#ArchivedFileContent', schema: fileContentSchema, create: () => fileContentSchema } },
+				{ name: 'opts', wire: 'opts', source: 'json', acceptsUndefined: true, codec: { mode: 'strict', typeSymbol: 'sage-mem/types#WriteOpts', schema: writeOptsSchema, create: () => writeOptsSchema } },
 			],
 			result: { mode: 'strict', typeSymbol: 'sage-mem/types#ArchivedWriteResult', schema: archivedWriteResultSchema, create: () => archivedWriteResultSchema },
 			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
@@ -835,6 +851,7 @@ export const TYPERT = {
 				{ name: 'name', wire: 'name', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#ReservedFileName', schema: fileNameSchema, create: () => fileNameSchema } },
 				// 4 MB：与 fileContentSchema（512 KB）**不是同一个上限**，见 rawFileContentSchema 的注释。
 				{ name: 'content', wire: 'content', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#RawFileContent', schema: rawFileContentSchema, create: () => rawFileContentSchema } },
+				{ name: 'opts', wire: 'opts', source: 'json', acceptsUndefined: true, codec: { mode: 'strict', typeSymbol: 'sage-mem/types#WriteOpts', schema: writeOptsSchema, create: () => writeOptsSchema } },
 			],
 			result: { mode: 'strict', typeSymbol: 'sage-mem/types#RawWriteResult', schema: rawWriteResultSchema, create: () => rawWriteResultSchema },
 			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },

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