sage-mem 2.1.7 → 2.1.9

package/README.md

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

package/lib/index.js

@@ -1,17 +1,11 @@
 /**
- * sage-mem — 文件式记忆插件。
+ * sage-mem — 文件式记忆插件。记忆存在本地 markdown 目录（frontmatter + 正文，4 类），不是数据库。
+ * host 侧三件事：① 按问题检索注入：system-prompt/assemble 时扫 memory 目录、按双字匹配选相关文件，
+ * 读全文注入 system prompt，让 agent 第一轮就「想起」；② TypertRemoteService：给设置页「记忆管理」
+ * 提供文件列表/读/写/删；③ autodream（自动做梦）：可选的记忆整理，见 lib/autodream.js。
  *
- * 记忆存在本地 markdown 文件目录（frontmatter + 正文，4 类），不是数据库。
- * host 侧三件事：
- *   1. 按问题检索注入：system-prompt/assemble 时扫 memory 目录，按双字匹配
- *      选相关文件，读全文注入 system prompt，让 agent 第一轮就「想起」
- *   2. TypertRemoteService：给设置页「记忆管理」提供文件列表/读/写/删
- *   3. autodream（自动做梦）：可选的记忆整理，见 lib/autodream.js
- *
- * 写入靠 AGENTS.md 的「记忆使用」规则引导 agent 自己判断 + 用文件工具写
- * memory 目录——透明、可检查、防膨胀。无 worker、无 SQLite、无端口。
- *
- * 旧 worker 版见 git 分支 `sqlite-worker`。
+ * 写入靠 AGENTS.md 的「记忆使用」规则引导 agent 自己判断 + 用文件工具写 memory 目录——透明、可检查、
+ * 防膨胀。无 worker、无 SQLite、无端口。旧 worker 版见 git 分支 `sqlite-worker`。
  */
 
 import { AutodreamEngine, DEFAULT_CONFIG, auditMemoryDir } from './autodream.js'
@@ -26,7 +20,7 @@ import { invalidateMemory, undoMemoryInvalidation } from './memory/arbitrate.js'
 import { 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 { warnLog, writeFileAtomic } from './memory/util.js'
+import { serializeByKey, warnLog, writeFileAtomic } from './memory/util.js'
 import { readLockSet, setLocked as setLockedImpl } from './memory/lock.js'
 import { openMemoryFolder } from './memory/open-folder.js'
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
@@ -694,20 +688,14 @@ markRemote(StarmapGateway, 'listStars', 'listStars')
 markRemote(StarmapGateway, 'readFile', 'readFile')
 
 /**
- * 2.0.0 的裁决入口：冲突队列的「可列、可读、可裁、可撤销」。
+ * 2.0.0 的裁决入口：冲突队列的「可列、可读、可裁、可撤销」。单独一个 namespace（`conflict`）
+ * 不并进 `memory`：这一层会**写用户的记忆文件**，与 memory 的读写正文不是一个权限面。
  *
- * 为什么单独一个 namespace（`conflict`）而不并进 `memory`：这一层会**写用户的记忆文件**
- * （把 `invalid_at` 写进 frontmatter），而 memory 面是读写正文。两张契约表的失败语义、
- * 危险等级都不同，混在一起只会让「读一下」和「改有效性」共用一个权限面。
- *
- * 四条硬约束（对应 `docs/2.0.0-plan.md` §5.5 / §7.3 / §7.6）：
- *   1. **先写文件、后改记录**。反过来会出现「记录说已裁决、文件没改」的半态，
- *      用户再也看不到它（记录已 resolved，文件仍照旧注入）。
- *   2. `invalidate` 只能写**这条记录自己提到的那一方**（`file` / `otherFile`）——
- *      防「借裁决入口写任意记忆文件」。文件名本身还要再过 `safeName` 闸门。
- *   3. 失败一律返回对象、绝不抛；`ok` 只在真的做了报告里那件事时为 true。
- *   4. 写路径走宿主 `fs.writeText`：版本守卫 + 逐次沙箱策略（收窄到记忆目录），
- *      与 autodream 同一口径 —— `read-only` 不替用户翻案。
+ * 四条硬约束（`docs/2.0.0-plan.md` §5.5 / §7.3 / §7.6）：① 先写文件、后改记录（反过来会出现
+ * 「记录说已裁决、文件没改」的半态，用户再也看不到它）；② `invalidate` 只能写这条记录自己提到的
+ * 那一方（`file` / `otherFile`，文件名再过 `safeName` 闸门），防「借裁决入口写任意记忆文件」；
+ * ③ 失败一律返回对象、绝不抛，`ok` 只在真的做了报告里那件事时为 true；④ 写路径走宿主
+ * `fs.writeText`：版本守卫 + 逐次沙箱策略（收窄到记忆目录），与 autodream 同一口径。
  */
 export class ConflictGateway extends TypertRemoteService {
   constructor(ctx) { super(ctx, 'conflict') }
@@ -809,6 +797,9 @@ export class ConflictGateway extends TypertRemoteService {
   async dismiss(opts) {
     const read = await readConflict(opts?.id, { stateRoot: STATE_ROOT })
     if (!read.ok) return { ok: false, code: read.code, error: read.error }
+    // 2.1.8（N02）：已裁决为「标失效」的记录不能直接驳回 —— 记忆上的失效标记还在，
+    // 驳回只会让它变成一条没有撤销入口的孤儿标记。要收掉判断请先撤销。
+    if (read.record.status === 'resolved' && read.record.decision === 'invalidate') return { ok: false, code: 'invalid_transition', error: '这条记录已裁决为失效且记忆仍带失效标记：先撤销，再决定要不要驳回' }
     // 记录里的 `note` 是冲突的由来（写进记录那一刻的事实），裁决理由**不覆盖**它 ——
     // 覆盖等于把证据改写成结论。
     const patched = await patchConflict(
@@ -834,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(
@@ -863,6 +854,10 @@ export class ConflictGateway extends TypertRemoteService {
    * 这条改名不影响对外承诺。
    */
   async removeRecord(opts) {
+    // 2.1.8（N02）：删掉一条「记忆仍标着失效」的记录等于删掉撤销入口 —— 标记就永久留在了
+    // 用户文件里。先撤销、再删记录。读不出来（坏记录）时照旧允许删：那是清理坏数据的出路。
+    const cur = await readConflict(opts?.id, { stateRoot: STATE_ROOT })
+    if (cur.ok && cur.record.status === 'resolved' && cur.record.decision === 'invalidate') return { ok: false, code: 'invalid_transition', error: '这条记录的记忆仍标着失效：先撤销（撤销会清掉标记）再删记录' }
     const removed = await removeConflict(opts?.id, { stateRoot: STATE_ROOT })
     if (!removed.ok) return { ok: false, code: removed.code, error: removed.error }
     return { ok: true }
@@ -876,6 +871,9 @@ markRemote(ConflictGateway, 'dismiss', 'dismiss')
 markRemote(ConflictGateway, 'undo', 'undo')
 markRemote(ConflictGateway, 'removeRecord', 'removeRecord')
 
+// 2.1.8（N02）：裁决入口整段按冲突 id 串行（第二方进队后重新读状态；理由见 util.js 的 serializeByKey）。
+serializeByKey(ConflictGateway, ['invalidate', 'dismiss', 'undo', 'removeRecord'])
+
 /**
  * autodream 的 remote 面：设置页「自动做梦」标签页唯一的数据通道。
  *

package/lib/memory/arbitrate.js

@@ -19,13 +19,29 @@
 import { join } from 'node:path'
 import { inspectMemoryEntry, readVerified, yamlScalar } from './scan.js'
 import { safeName } from './naming.js'
+import { createKeyedWriteQueue } from './util.js'
 import { parseValidityTime } from './validity.js'
 
+/**
+ * 2.1.8（外部审查 N02）：同一份记忆文件的「读快照 → 改标记 → 写回」整段串行。
+ *
+ * 单文件的版本 CAS 只覆盖「这一次读写窗口」，保护不了「两个不同冲突同时标同一文件」：
+ * 两边都基于旧字节改写，后写的那个会把前一个标记静默盖掉，而两份收据都声称成功。
+ * 串行之后后一个读到的就是前一个写完的字节（跨进程仍由宿主 replaceIfVersion 兜底）。
+ */
+const withFileLock = createKeyedWriteQueue()
+
 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')
@@ -87,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
@@ -177,6 +223,11 @@ async function readForWrite(ctx, memoryDir, file) {
  *   | {ok:false, code:'invalid'|'missing'|'stale_version'|'write_denied'|'unsupported'|'io_error', error:string}>}
  */
 export async function invalidateMemory({ ctx, memoryDir }, input) {
+  // 2.1.8（N02）：按记忆文件串行（见 withFileLock 的注释）。文件名归一后当 key。
+  return withFileLock(String(safeName(input?.file) ?? ''), () => invalidateMemoryLocked({ ctx, memoryDir }, input))
+}
+
+async function invalidateMemoryLocked({ ctx, memoryDir }, input) {
   const invalidAt = typeof input?.invalidAt === 'string' ? input.invalidAt.trim() : ''
   // 写进用户文件的标记必须是我们能解析的格式：坏值会被 validity 层按「未标注」处理、
   // 记忆照常注入 —— 用户会看到「标了却没用」，那是最难查的一类静默失效。
@@ -209,12 +260,44 @@ export async function invalidateMemory({ 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, opts))
+}
+
+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/util.js

@@ -290,6 +290,62 @@ export function createWriteQueue() {
   }
 }
 
+/**
+ * 造一个**按 key 分队列**的进程内串行器（2.1.8 / 外部审查 N02 引入）。
+ *
+ * 为什么不能用一个全局队列：冲突裁决按 conflict id 串行，但不同 id 之间不该互相排队 ——
+ * 一条卡住的写入不该拖住整张冲突表。同一个 key 上，整段「读记录 → 写记忆 → 写收据」
+ * 必须一个接一个：两个相反裁决并发时，各自改不同记忆文件都能合法成功，最后同一份收据
+ * 只剩最后一份，而两份记忆都失效了 —— 单文件的版本 CAS 保护不了整项操作。
+ *
+ * 队列空闲后把 entry 摘掉：长进程里 id 会不断累积，不能每个 key 永久留一条闭包链。
+ * ⚠️ 与 `createWriteQueue` 同一条边界：**进程内**串行，不是跨进程锁。
+ *
+ * @returns {(key:string, fn:()=>Promise<any>)=>Promise<any>}
+ */
+export function createKeyedWriteQueue() {
+  const entries = new Map()
+  return function enqueue(key, fn) {
+    const k = String(key)
+    let entry = entries.get(k)
+    if (!entry) {
+      entry = { queue: createWriteQueue(), pending: 0 }
+      entries.set(k, entry)
+    }
+    entry.pending += 1
+    const done = () => {
+      entry.pending -= 1
+      // pending 归零且这一条还是当前那条时才摘：期间有人入队的话 pending 不会到 0。
+      if (entry.pending === 0 && entries.get(k) === entry) entries.delete(k)
+    }
+    const run = entry.queue(fn)
+    // 只挂回调、不改返回的那条 promise（失败仍由调用方接住）。
+    run.then(done, done)
+    return run
+  }
+}
+
+/**
+ * 把一组「第一个参数是 `{id}`」的 remote 方法按 id 串行（2.1.8 / N02 的用法）。
+ *
+ * 为什么用原型包装而不是给每个方法再写一层：四个入口（invalidate / dismiss / undo /
+ * removeRecord）的**方法体本身要重新读状态**（这是队列内重读的实现），外面只多一层
+ * 「按 id 排队」的接线。包装发生在 class 定义之后、宿主清单之外；typert 的调用是
+ * `Reflect.get(receiver, method)` 现取，所以包装后的原型方法就是真正被执行的那个。
+ *
+ * @param {Function} cls — 目标类（方法定义在它的 prototype 上）
+ * @param {string[]} methods — 方法名
+ */
+export function serializeByKey(cls, methods) {
+  const withLock = createKeyedWriteQueue()
+  for (const name of methods) {
+    const run = cls.prototype[name]
+    cls.prototype[name] = function serializeOne(first) {
+      return withLock(String(first?.id ?? ''), () => run.call(this, first))
+    }
+  }
+}
+
 /**
  * ⚠️ 回滚写回请用 **`writeFileAtomic`**，不要用 `copyFile(src, dst)`。
  *

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