sage-mem 2.1.7 → 2.1.8

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

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(
@@ -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,8 +19,18 @@
 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:` 嵌套块里同名的键不是我们的）。 */
@@ -177,6 +187,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 层按「未标注」处理、
   // 记忆照常注入 —— 用户会看到「标了却没用」，那是最难查的一类静默失效。
@@ -213,6 +228,11 @@ export async function invalidateMemory({ ctx, memoryDir }, input) {
  *   | {ok:false, code:'invalid'|'missing'|'stale_version'|'write_denied'|'unsupported'|'io_error', error:string}>}
  */
 export async function undoMemoryInvalidation({ ctx, memoryDir }, file) {
+  // 2.1.8（N02）：与 invalidateMemory 同一条文件级串行（撤销和标记可能同时发生）。
+  return withFileLock(String(safeName(file) ?? ''), () => undoMemoryInvalidationLocked({ ctx, memoryDir }, file))
+}
+
+async function undoMemoryInvalidationLocked({ ctx, memoryDir }, file) {
   const read = await readForWrite(ctx, memoryDir, file)
   if (!read.ok) return read
   const built = removeValidityLines(read.content)

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