sage-mem 2.1.11 → 2.1.12

package/README.md

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

package/lib/index.js

@@ -19,7 +19,7 @@ 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 { serializeByKey, warnLog, writeFileAtomic } from './memory/util.js'
-import { readLockSet, setLocked as setLockedImpl } from './memory/lock.js'
+import { readLockState, setLocked as setLockedImpl } from './memory/lock.js'
 import { openMemoryFolder } from './memory/open-folder.js'
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import { mkdir, unlink, writeFile } from 'node:fs/promises'
@@ -99,7 +99,9 @@ export class MemoryGateway extends TypertRemoteService {
 
   /** 列出 memory 目录全部记忆文件（文件名 + 类型 + 描述 + 大小 + 自定义标签 + 是否锁定）。 */
   async listFiles() {
-    const [files, locked] = await Promise.all([scanMemoryFiles(this.ctx, ''), readLockSet(MEMORY_DIR)])
+    const [files, lockState] = await Promise.all([scanMemoryFiles(this.ctx, ''), readLockState(MEMORY_DIR)])
+    // Q05：锁表坏了也照样列文件，但不假装「都没锁」；逐条 locked 只有布尔，未知只能靠日志。
+    if (lockState.status === 'unknown') warnLog(this.ctx, `锁表不可读，列表里的锁定状态未知（不是「都没锁」）：${lockState.reason}`)
     return files.map(f => {
       const meta = parseFrontmatter(f.content)
       return {
@@ -109,7 +111,7 @@ export class MemoryGateway extends TypertRemoteService {
         size: f.content.length,
         tags: meta.tags,
         // 锁定状态跟着每条一起给：卡片上的「锁定 / 已锁定」按钮要据此渲染
-        locked: locked.has(nameKey(f.file)),
+        locked: lockState.status === 'unknown' ? false : lockState.locked.has(nameKey(f.file)),
       }
     })
   }
@@ -134,18 +136,11 @@ 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`（落盘后的新版本），调用方可以直接拿它继续保存。
+   * 2.1.2（Q02）新增可选第三参 `opts`：`{ expectedRevision }` 对不上 → `stale_revision`（当前内容逐字节
+   * 不变，面板保留草稿）；`{ create: true }` 撞名 → `already_exists`（绝不覆盖）；不传 opts 走旧行为但落
+   * 一条 warn（additive 契约只保留兼容，不保留静默）。成功时回 `revision`（落盘后的新版本）。
    */
   async writeFile(name, content, opts) {
     // 保留名判定放在最前面、且以 nameKey 归一：'memory.md' / 'MEMORY.MD' /
@@ -408,11 +403,13 @@ export class MemoryGateway extends TypertRemoteService {
 
   async archiveCandidates() {
     await flushAccess(MEMORY_DIR)
-    const [ledger, files, locked] = await Promise.all([
+    const [ledger, files, lockState] = await Promise.all([
       readAccessLedger(),
       scanMemoryFiles(this.ctx, ''),
-      readLockSet(MEMORY_DIR),
+      readLockState(MEMORY_DIR),
     ])
+    // Q05：锁表不可读时如实标记（候选清单仍可看，自动归档由 archiveMemory 直接拒绝）。
+    if (lockState.status === 'unknown') warnLog(this.ctx, `锁表不可读，候选清单的锁定状态未知（自动归档会拒绝执行）：${lockState.reason}`)
     const cfg = await autodreamConfigSnapshot()
     const thresholds = {
       project: cfg.archiveAfterDaysProject,
@@ -420,14 +417,17 @@ export class MemoryGateway extends TypertRemoteService {
       user: cfg.archiveAfterDaysUser,
     }
     // 锁表交给候选计算：锁上的记忆一个都不选（用户对**单条**记忆说的话优先于阈值）。
-    const candidates = pickArchiveCandidates(files, ledger, { thresholds, locked })
+    const candidates = pickArchiveCandidates(files, ledger, { thresholds, locked: lockState.locked })
     return {
       count: candidates.length,
       candidates,
       autoArchive: cfg.autoArchive,
       thresholds,
       // 面板要显示「哪些锁着」，所以把锁表也带回去（已按 nameKey 归一）
-      locked: [...locked],
+      locked: [...lockState.locked],
+      // Q05：保护状态未知时明确标出来，不把「不知道」渲染成「都没锁」。
+      lockedUnknown: lockState.status === 'unknown',
+      lockedError: lockState.reason,
     }
   }
 

package/lib/memory/archive.js

@@ -19,7 +19,7 @@ import { ARCHIVE_DIR_NAME, addArchiveMeta, inspectDir, inspectMemoryEntry, local
 import { isReserved, nameKey, safeName } from './naming.js'
 import { revisionOf } from './chunks.js'
 import { retireTaken, returnSource, takeOverSource, writeFileAtomic, writeFileExclusive } from './util.js'
-import { isLocked } from './lock.js'
+import { readLockState } from './lock.js'
 import { ensureIndexEntry, dropIndexEntry } from './index-file.js'
 import { mkdir, readFile, rm, stat } from 'node:fs/promises'
 import { basename, join } from 'node:path'
@@ -54,8 +54,20 @@ export async function archiveMemory(memoryDir, name, reason, at = localStamp())
   /**
    * 「锁定」优先于一切：锁上的记忆**自动与手动都不许归档**。
    * 放在最前面判 —— 名字合法之后立刻拒绝，不读目录、不算理由。
+   *
+   * ⚠️ 2.1.12（Q05）：锁表读不出来时**不猜**。旧实现把「保护状态未知」当成空表，
+   * 于是坏表会让受保护的记忆照常被移走。现在未知 = 拒绝归档（危险操作暂停），
+   * 错误码 `lock-unknown` 让调用方/报告能说清是「锁表坏了」而不是「文件有问题」。
    */
-  if (await isLocked(memoryDir, safe)) {
+  const lock = await readLockState(memoryDir)
+  if (lock.status === 'unknown') {
+    return {
+      ok: false,
+      code: 'lock-unknown',
+      error: `sage-mem: 锁表不可读（${lock.reason}），无法确认这条记忆是否受保护，拒绝归档：${safe}`,
+    }
+  }
+  if (lock.locked.has(nameKey(safe))) {
     return { ok: false, code: 'locked', error: `sage-mem: locked, refusing to archive: ${safe}（先在界面里解锁）` }
   }
   const src = join(memoryDir, safe)

package/lib/memory/lock.js

@@ -9,11 +9,20 @@
  *
  * 锁表按 `nameKey()` 归一存放：NTFS 不区分大小写，`User_Persona.MD` 与 `user_persona.md`
  * 是同一个文件 —— 锁必须认得出这一点（与保留名保护同一套判据）。
+ *
+ * ── 2.1.12（外部审查 Q05）──────────────────────────────────────────────
+ * 旧实现两处硬伤，都已修：
+ *   1. 整文件 read-modify-write **没有排队**：两个并发上锁各自读到旧表，后写的把先写的
+ *      盖掉，而两边都报成功。原子 rename 只保证「不写半截」，不负责「合并两处修改」。
+ *      现在按锁表路径分键复用 `util.js` 的 `createWriteQueue()` 串行 RMW。
+ *   2. 读任何异常都返回空 Set —— 「保护状态未知」与「确实没有锁」因此无法区分，
+ *      自动归档会把**受保护**的记忆当成没锁继续删。现在只有 ENOENT 算「确实没有锁」；
+ *      坏 JSON / 权限失败 / 路径是目录……一律 `status:'unknown'`，危险操作据此暂停。
  */
 import { mkdir, readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { nameKey } from './naming.js'
-import { writeFileAtomic } from './util.js'
+import { createWriteQueue, writeFileAtomic } from './util.js'
 
 /** 锁表文件：状态根下，与记忆文件分开。 */
 export function lockFileOf(memoryDir) {
@@ -21,24 +30,83 @@ export function lockFileOf(memoryDir) {
 }
 
 /**
- * 读锁表。读不到 / JSON 坏 / 不是对象 / 值不是 `true` → 一律当空表。
- * **绝不抛**：锁表坏了最坏是「锁没生效」，不该升级成「读不了记忆」。
+ * 锁表的**进程内串行队列**，按锁表路径分键（不同记忆目录互不阻塞）。
+ *
+ * ⚠️ 边界与 `util.js` 的说明一致：进程内串行，不是跨进程文件锁。真实并发（面板 remote、
+ * 模型工具、归档策略）都在同一个插件进程里；同时开两个 DSH 实例写同一个记忆目录时仍可能
+ * 丢一次 —— 那要另加文件锁，本版明确不做。
  */
-export async function readLockSet(memoryDir) {
+const lockQueues = new Map()
+function lockQueueFor(file) {
+  let queue = lockQueues.get(file)
+  if (!queue) {
+    queue = createWriteQueue()
+    lockQueues.set(file, queue)
+  }
+  return queue
+}
+
+/**
+ * 读锁表**原始对象**，区分「确实没有」与「不知道」。
+ *
+ * @returns {Promise<{status:'ok'|'missing'|'unknown', table:object, reason:string}>}
+ */
+async function readLockTable(memoryDir) {
+  let text
   try {
-    const parsed = JSON.parse(await readFile(lockFileOf(memoryDir), 'utf8'))
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return new Set()
-    const out = new Set()
-    for (const [k, v] of Object.entries(parsed)) {
-      if (v === true) out.add(nameKey(k))
-    }
-    return out
-  } catch {
-    return new Set()
+    text = await readFile(lockFileOf(memoryDir), 'utf8')
+  } catch (err) {
+    // 只有 ENOENT 可以当空表：文件不存在 = 一次锁都没上过。
+    if (err?.code === 'ENOENT') return { status: 'missing', table: {}, reason: '' }
+    return { status: 'unknown', table: {}, reason: `读锁表失败（${err?.code || err?.message}）` }
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch (err) {
+    return { status: 'unknown', table: {}, reason: `锁表不是合法 JSON（${err?.message ?? err}）` }
   }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { status: 'unknown', table: {}, reason: '锁表不是 JSON 对象' }
+  }
+  return { status: 'ok', table: parsed, reason: '' }
 }
 
-/** 这条记忆锁上了吗。 */
+/**
+ * 读锁状态 —— **安全路径唯一该用的读口**。
+ *
+ *   - `{status:'ok', locked:Set}`：读到有效表（可能为空）
+ *   - `{status:'missing', locked:Set()}`：锁表不存在 = 确实没有锁
+ *   - `{status:'unknown', locked:Set(), reason}`：保护状态**未知**，自动归档必须暂停
+ *
+ * ⚠️ `unknown` 时返回的 `locked` 是**空集合**，但它不表示「没有锁」；调用方必须先看
+ * `status`，拿它当空表用就是把 Q05 原样放回去。
+ */
+export async function readLockState(memoryDir) {
+  const read = await readLockTable(memoryDir)
+  if (read.status === 'unknown') return { status: 'unknown', locked: new Set(), reason: read.reason }
+  const out = new Set()
+  for (const [k, v] of Object.entries(read.table)) {
+    if (v === true) out.add(nameKey(k))
+  }
+  return { status: read.status, locked: out, reason: '' }
+}
+
+/**
+ * 兼容出口：只要集合的调用方用这个。
+ *
+ * 与 `readLockState` 的差别只有一条：`unknown` 时**抛** `LOCK_TABLE_UNKNOWN`，而不是
+ * 返回空 Set —— 返回空 Set 正是「坏表当全解锁」这个 bug 的入口。缺文件仍返回空 Set。
+ */
+export async function readLockSet(memoryDir) {
+  const state = await readLockState(memoryDir)
+  if (state.status === 'unknown') {
+    throw Object.assign(new Error(`sage-mem: ${state.reason}`), { code: 'LOCK_TABLE_UNKNOWN', reason: state.reason })
+  }
+  return state.locked
+}
+
+/** 这条记忆锁上了吗。`unknown` 时抛错（调用方不能把「不知道」当成「没锁」）。 */
 export async function isLocked(memoryDir, name) {
   return (await readLockSet(memoryDir)).has(nameKey(name))
 }
@@ -46,23 +114,29 @@ export async function isLocked(memoryDir, name) {
 /**
  * 上锁 / 解锁。
  *
- * 读-改-写：两张并发的锁操作理论上会互相覆盖（丢一次锁）。这里**不引入锁**：
- * 代价是「同时锁两条记忆时可能少一条」，而这远轻于给一个状态文件加一套锁 ——
- * 重按一次就好，用户看得见结果。
+ * RMW 全程在**按锁表路径分键的进程内队列**里：读最新表 → 改一项 → 原子写回。
+ * 并发的不同文件因此逐条合并，不再互相覆盖。
+ *
+ * 坏表上**拒绝写入**（`{ok:false, code:'lock-table-unknown'}`），而不是把表重置成空表 ——
+ * 后者会静默抹掉用户的全部保护状态，比「这次没锁上」严重得多。
  */
 export async function setLocked(memoryDir, name, locked) {
   const key = nameKey(name)
   const file = lockFileOf(memoryDir)
-  let table = {}
-  try {
-    const parsed = JSON.parse(await readFile(file, 'utf8'))
-    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) table = parsed
-  } catch {
-    table = {}
-  }
-  if (locked) table[key] = true
-  else delete table[key]
-  await mkdir(dirname(file), { recursive: true })
-  await writeFileAtomic(file, JSON.stringify(table, null, 2) + '\n')
-  return { ok: true, file: name, locked: !!locked }
+  return lockQueueFor(file)(async () => {
+    const read = await readLockTable(memoryDir)
+    if (read.status === 'unknown') {
+      return {
+        ok: false,
+        code: 'lock-table-unknown',
+        error: `sage-mem: 锁表不可读（${read.reason}），本次没有写入，也不会把它重置成空表：${name}`,
+      }
+    }
+    const table = { ...read.table }
+    if (locked) table[key] = true
+    else delete table[key]
+    await mkdir(dirname(file), { recursive: true })
+    await writeFileAtomic(file, JSON.stringify(table, null, 2) + '\n')
+    return { ok: true, file: name, locked: !!locked }
+  })
 }

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