sage-mem 2.1.8 → 2.1.10

package/README.md

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

package/lib/client.js

@@ -3223,6 +3223,8 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			malformed: "conflict.code.malformed",
 			invalid_transition: "conflict.code.invalidTransition",
 			stale_version: "conflict.code.staleVersion",
+			// 2.1.9（N01）：撤销时发现标记已被后来人重写 —— 不删别人的判断，交给用户比较。
+			stale_decision: "conflict.code.staleDecision",
 			write_denied: "conflict.code.writeDenied",
 			unsupported: "conflict.code.unsupported",
 			io_error: "conflict.code.ioError",
@@ -3909,6 +3911,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			"conflict.code.malformed": "这条记录格式损坏：可以删除记录，或手工检查状态目录里的 JSON。",
 			"conflict.code.invalidTransition": "这条记录的状态已经变了：刷新列表后按当前状态再操作。",
 			"conflict.code.staleVersion": "记忆文件在你打开之后被改过：先刷新列表、确认最新内容再裁决（本次不会覆盖你的改动）。",
+			"conflict.code.staleDecision": "文件上的失效标记已经被后来人重写过：撤销它等于删掉别人的判断，本次没有改动任何字节。请先比较记录里的 invalid_at / superseded_by 与盘上现值，确认后再决定。",
 			"conflict.code.writeDenied": "宿主拒绝了写入（只读 / 沙箱策略）：把 DSH 的写入权限调宽后重试，或手工在记忆 frontmatter 里加 invalid_at。",
 			"conflict.code.unsupported": "宿主没有可用的写入接口：升级插件，或手工在记忆 frontmatter 里加 invalid_at。",
 			"conflict.code.ioError": "读写磁盘失败：稍后重试；记录仍是待裁决状态，不会留下半份文件。",
@@ -4387,6 +4390,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			"conflict.code.malformed": "This record is malformed: delete the record, or inspect the JSON in the state directory by hand.",
 			"conflict.code.invalidTransition": "This record already changed state: refresh the list and act on its current state.",
 			"conflict.code.staleVersion": "The memory file changed after you opened it: refresh the list and check the latest content before deciding (your changes are not overwritten).",
+			"conflict.code.staleDecision": "The validity marker on disk was rewritten by someone else: undoing it would erase their decision, so nothing was changed. Compare invalid_at / superseded_by in the record with the current values before deciding.",
 			"conflict.code.writeDenied": "The host refused the write (read-only / sandbox policy): widen DSH write permissions and retry, or add invalid_at to the memory frontmatter by hand.",
 			"conflict.code.unsupported": "The host has no usable write API: upgrade the plugin, or add invalid_at to the memory frontmatter by hand.",
 			"conflict.code.ioError": "Disk read/write failed: retry later; the record stays pending and no half-written file is left behind.",
@@ -6047,23 +6051,22 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			function createIndexSkeleton() {
 				setError(null);
 				setNotice("");
-				if (!remote || typeof remote.readRaw !== "function" || typeof remote.writeRaw !== "function") {
+				if (!remote || typeof remote.writeRaw !== "function") {
 					setError(t("error.noRaw"));
 					return;
 				}
 				setBusy(true);
-				// 先读再写：**已有索引绝不覆盖**。readRaw 对不存在的文件会 reject，正好当探针。
-				remote.readRaw("MEMORY.md").then(function () {
+				// 2.1.10（Q10）：只调**一个意图接口**（writeRaw 的 createIfAbsent）：
+				// 服务端负责「全新安装、memory 目录还不存在」时先建父目录；
+				// 已有索引 → 明确回 already_exists（逐字节不动）。绝不再「先读一次、读失败就当
+				// 可以覆盖」—— 读失败也可能是权限错误，而那正是会顶掉一份真索引的路。
+				remote.writeRaw("MEMORY.md", INDEX_SKELETON, { create: true }).then(function (res) {
+					const out = unwrap(res);
 					setBusy(false);
-					setNotice(t("notice.indexExists"));
-				}, function () {
-					return remote.writeRaw("MEMORY.md", INDEX_SKELETON).then(function (res) {
-						const out = unwrap(res);
-						setBusy(false);
-						if (out && out.ok === false) { setError(out.error || t("error.skeletonFailed")); return; }
-						setNotice(t("notice.indexCreated"));
-						load();
-					});
+					if (out && out.code === "already_exists") { setNotice(t("notice.indexExists")); return; }
+					if (out && out.ok === false) { setError(out.error || t("error.skeletonFailed")); return; }
+					setNotice(t("notice.indexCreated"));
+					load();
 				}).catch(function (e) {
 					setBusy(false);
 					setError(String((e && e.message) || e));

package/lib/index.js

@@ -825,7 +825,7 @@ export class ConflictGateway extends TypertRemoteService {
       return { ok: false, code: 'invalid_transition', error: '这条记录没有标过失效，没有可撤销的标记' }
     }
     const target = record.invalidatedFile || record.file
-    const cleared = await undoMemoryInvalidation({ ctx: this.ctx, memoryDir: MEMORY_DIR }, target)
+    const cleared = await undoMemoryInvalidation({ ctx: this.ctx, memoryDir: MEMORY_DIR }, target, record.decidedAt ? { expectedInvalidAt: record.decidedAt, expectedSupersededBy: target === record.file ? record.otherFile : record.file } : undefined)
     if (!cleared.ok) return { ok: false, code: cleared.code, error: cleared.error }
 
     const patched = await patchConflict(

package/lib/memory/arbitrate.js

@@ -36,6 +36,12 @@ const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/
 /** 失效标记的两行（只认顶层键：`metadata:` 嵌套块里同名的键不是我们的）。 */
 const VALIDITY_LINE_RE = /^(?:invalid_at|superseded_by):/
 
+/**
+ * 2.1.9（外部审查 N01）：撤销时发现「文件上的标记已经不是这条记录写的那份」。
+ * 固定字符串，界面与测试都只认它（不解析错误文案）。
+ */
+export const ERR_STALE_DECISION = 'stale_decision'
+
 function eolOf(text) {
   const src = String(text ?? '')
   const i = src.indexOf('\r\n')
@@ -97,6 +103,36 @@ export function removeValidityLines(content) {
   return { ok: true, content: next, changed: next !== content }
 }
 
+/** 裸值 / 单引号 / 双引号（`yamlScalar` 会按需加引号）→ 原始字符串。 */
+function unquoteScalar(raw) {
+  const s = String(raw ?? '').trim()
+  if (s.length >= 2 && s[0] === "'" && s[s.length - 1] === "'") return s.slice(1, -1).replace(/''/g, "'")
+  if (s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"') return s.slice(1, -1)
+  return s
+}
+
+/**
+ * 读文件**当前**的失效标记（只认顶层两行）。没有 `invalid_at` 就返回 null。
+ *
+ * 2.1.9（N01）：撤销要先知道「现在文件上写的是哪一次判断」。读回来的值可能是带引号的
+ * 形式（`yamlScalar` 对含 `: ` 之类的值会加引号），所以这里统一去引号后再比对。
+ *
+ * @returns {{invalidAt:string, supersededBy:string} | null}
+ */
+export function readValidityMarker(content) {
+  if (typeof content !== 'string') return null
+  const m = content.match(FRONTMATTER_RE)
+  if (!m) return null
+  const marker = { invalidAt: '', supersededBy: '' }
+  for (const line of m[1].split(/\r?\n/)) {
+    const hit = line.match(/^(invalid_at|superseded_by)\s*:\s*(.*)$/)
+    if (!hit) continue
+    if (hit[1] === 'invalid_at') marker.invalidAt = unquoteScalar(hit[2])
+    else marker.supersededBy = unquoteScalar(hit[2])
+  }
+  return marker.invalidAt ? marker : null
+}
+
 /** 从宿主的 `fs` 服务取版本（拿不到就是 undefined —— 那就**不写**，不拿「现在」冒充）。 */
 function versionOf(info) {
   return info && info.version !== undefined && info.version !== null ? info.version : undefined
@@ -224,17 +260,44 @@ async function invalidateMemoryLocked({ ctx, memoryDir }, input) {
 /**
  * 撤销失效：删掉 `invalid_at` / `superseded_by` 两行，其余字节不动。
  *
+ * 2.1.9（N01）：可选第三参 `opts` 是**这次撤销的操作身份**（来自冲突记录：
+ * `expectedInvalidAt = record.decidedAt`，`expectedSupersededBy` = 记录里的另一方）。
+ * 文件当前标记对不上 → `stale_decision`，**一个字节都不删**：后来人改过标记，那已经是
+ * 别人的判断，撤销它等于把别人的决定抹掉。正文变化不参与比对 —— 撤销只删两行标记，
+ * 正文照旧保留。
+ *
+ * @param {object} deps `{ctx, memoryDir}`
+ * @param {string} file
+ * @param {{expectedInvalidAt?:string, expectedSupersededBy?:string}} [opts]
  * @returns {Promise<{ok:true, file:string, cleared:boolean, version:string}
- *   | {ok:false, code:'invalid'|'missing'|'stale_version'|'write_denied'|'unsupported'|'io_error', error:string}>}
+ *   | {ok:false, code:'invalid'|'missing'|'stale_version'|'stale_decision'|'write_denied'|'unsupported'|'io_error', error:string}>}
  */
-export async function undoMemoryInvalidation({ ctx, memoryDir }, file) {
+export async function undoMemoryInvalidation({ ctx, memoryDir }, file, opts) {
   // 2.1.8（N02）：与 invalidateMemory 同一条文件级串行（撤销和标记可能同时发生）。
-  return withFileLock(String(safeName(file) ?? ''), () => undoMemoryInvalidationLocked({ ctx, memoryDir }, file))
+  return withFileLock(String(safeName(file) ?? ''), () => undoMemoryInvalidationLocked({ ctx, memoryDir }, file, opts))
 }
 
-async function undoMemoryInvalidationLocked({ ctx, memoryDir }, file) {
+async function undoMemoryInvalidationLocked({ ctx, memoryDir }, file, opts) {
   const read = await readForWrite(ctx, memoryDir, file)
   if (!read.ok) return read
+  // 2.1.9（N01）：先确认「现在文件上的标记仍是这条记录写的那一份」，再决定删不删。
+  const expect = opts && typeof opts === 'object' ? opts : null
+  const expectedInvalidAt = typeof expect?.expectedInvalidAt === 'string' ? expect.expectedInvalidAt : ''
+  if (expectedInvalidAt) {
+    const marker = readValidityMarker(read.content)
+    if (!marker) {
+      // 标记已经不在了（可能已撤销过 / 被别的写入清掉）：不删任何东西，幂等返回。
+      return { ok: true, file: safeName(file), cleared: false, version: String(read.version ?? '') }
+    }
+    const expectedSupersededBy = typeof expect?.expectedSupersededBy === 'string' ? expect.expectedSupersededBy : ''
+    if (marker.invalidAt !== expectedInvalidAt || marker.supersededBy !== expectedSupersededBy) {
+      return {
+        ok: false,
+        code: ERR_STALE_DECISION,
+        error: `文件上的失效标记已不是这条记录写下的那一份（记录：invalid_at=${expectedInvalidAt} / superseded_by=${expectedSupersededBy}；盘上：invalid_at=${marker.invalidAt} / superseded_by=${marker.supersededBy}）—— 没有删除别人的判断，请先比较两边内容`,
+      }
+    }
+  }
   const built = removeValidityLines(read.content)
   if (!built.ok) return built
   if (!built.changed) {

package/lib/memory/write-protocol.js

@@ -22,6 +22,8 @@
  */
 
 import { createHash } from 'node:crypto'
+import { mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
 import { readVerified } from './scan.js'
 import { warnLog, writeFileAtomic, writeFileExclusive } from './util.js'
 
@@ -70,6 +72,10 @@ export async function writeSnapshot(target, content, gate, opts, meta) {
   if (o.create === true) {
     if (gate?.ok) return rejected(ERR_ALREADY_EXISTS, `sage-mem: ${name} 已经存在，新建不会覆盖它（要改正文请打开它）`)
     try {
+      // 2.1.10（Q10）：createIfAbsent 也负责「全新安装、父目录还不存在」这一种：
+      // writeFileExclusive 的临时文件落在同一目录，目录不在就会 ENOENT（审查实测）。
+      // 只建父目录、绝不动目标文件 —— 「建立索引骨架」这个意图由调用方一次说清。
+      await mkdir(dirname(target), { recursive: true })
       await writeFileExclusive(target, content)
     } catch (err) {
       if (err?.code === 'EEXIST') return rejected(ERR_ALREADY_EXISTS, `sage-mem: ${name} 刚刚被别的写入建出来了，新建没有覆盖它`)

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