sage-mem 2.1.13 → 2.1.15

package/README.md

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

package/lib/memory/checkpoint.js

@@ -497,26 +497,22 @@ export async function writeCheckpoint(taskId, text, opts) {
 /** 注入用的短句柄硬上限（字节）。它要跟正文抢上下文，不能自己长起来。 */
 const HANDLE_MAX_BYTES = 160
 
-/** 按**码点**截断到不超过 maxBytes 字节：不许把一个字符切成半个（注入文本里会变 U+FFFD）。 */
-function truncateByBytes(s, maxBytes) {
-  if (Buffer.byteLength(s, 'utf8') <= maxBytes) return s
-  let out = ''
-  let used = 0
-  for (const ch of s) {
-    const b = Buffer.byteLength(ch, 'utf8')
-    if (used + b > maxBytes) break
-    out += ch
-    used += b
-  }
-  return out
-}
+/**
+ * 句柄里相对路径的**基准标记**：相对路径只说「相对谁」，不说清基准就是歧义的
+ * （去记忆目录里找？去状态根里找？）。生成与解析**共用这一个常量** ——
+ * 两边各写一份字符串，改了一边就会静默给出读不到的路径（Q12 的旧句柄正是这么坏的）。
+ */
+const HANDLE_BASE_MARK = '状态根下'
 
 /**
- * 注入用的短句柄（一行，≤ 160 字节）：说清「有这个检查点、revision 几、怎么读」。
+ * 注入用的短句柄（一行，≤ 160 字节）：说清「有这个检查点、revision 几、去哪读」。
  *
- * 预算是硬的，所以按优先级退化：**id 与 revision 不可丢**（它们才是身份），项目是可选线索
- * （放不下就截短或整个丢掉），最后连「重复一次 id 的完整相对路径」放不下时（64 字符的
- * 极端 id），退成不含重复路径的说法。绝不把多字节字符截半个。taskId 非法返回 ''。
+ * 预算是硬的，按优先级退化：**可解析路径与 revision 不可丢**，项目名是可选线索
+ * （放不下就整个丢掉），「续做前先读」是纯提示（再放不下就丢它）。taskId 非法返回 ''。
+ *
+ * ⚠️ **id 只出现一次**：完整相对路径 `tasks/<id>/WORKING.md` 已经含它了。
+ * 旧版在头部又重复了一遍 id，预算被耗光后退化成一条**不存在的路径**
+ * `tasks/WORKING.md`（2026-10-31 外部审查 Q12）—— 短了，但不再是准确的读取指令。
  *
  * revision 缺省按 0（与 renderCheckpoint 的缺省一致）。
  */
@@ -526,21 +522,43 @@ export function checkpointHandleText({ taskId, revision, project } = {}) {
   const rev = Number.isInteger(revision) && revision >= 0 ? revision : 0
   const proj = String(project ?? '').replace(/\s+/g, ' ').trim()
 
-  const head = `检查点 ${id}（revision ${rev}）：`
-  const detail = `读 tasks/${id}/WORKING.md`
+  // 身份只表达一次：id 在路径里，revision 在头部。
+  const head = `检查点 revision ${rev}：`
+  const rel = `${TASKS_DIR_NAME}/${id}/${CHECKPOINT_FILE_NAME}`
   const tail = '，续做前先读'
-  const build = (p) => `${head}${p === '' ? '' : `项目 ${p}，`}${detail}${tail}`
-
-  let line = build(proj)
-  if (Buffer.byteLength(line, 'utf8') > HANDLE_MAX_BYTES) {
-    // 项目放不下：按剩余预算截断它，截不下就整个丢掉。
-    const fixed = Buffer.byteLength(build(''), 'utf8')
-    const room = HANDLE_MAX_BYTES - fixed - Buffer.byteLength('项目 ，', 'utf8')
-    line = build(room > 0 ? truncateByBytes(proj, room) : '')
-  }
-  if (Buffer.byteLength(line, 'utf8') > HANDLE_MAX_BYTES) {
-    // 到这儿只剩「id 太长」一种可能：完整相对路径（id 出现两次）放不下，退成不重复的写法。
-    line = `${head}读 ${TASKS_DIR_NAME}/${CHECKPOINT_FILE_NAME}`
-  }
+  const build = (p, withTail) =>
+    `${head}${HANDLE_BASE_MARK} ${rel}${withTail ? tail : ''}${p === '' ? '' : `（项目 ${p}）`}`
+
+  let line = build(proj, true)
+  if (Buffer.byteLength(line, 'utf8') > HANDLE_MAX_BYTES) line = build('', true)
+  if (Buffer.byteLength(line, 'utf8') > HANDLE_MAX_BYTES) line = build('', false)
+  // 到这儿只剩「revision 是天文数字」一种可能，合法整数不会触发。宁可给一条超长句柄，
+  // 也不截断路径：截出来的路径定位不到真实文件，比多占几个字节更糟。
   return line
 }
+
+/**
+ * 从短句柄里解析回检查点身份（生成规则见 `checkpointHandleText`）。
+ *
+ * 为什么需要它：句柄是**给模型执行的读取指令**，必须能被机器核对「它说的是不是真实文件」。
+ * 旧版退化成 `读 tasks/WORKING.md`，字节数达标、也含 id —— 只断言「≤160 字节 + 包含 id」
+ * 的测试正是这么放它过去的。断言要看的是**用同一解析规则能不能定位到真实文件**。
+ *
+ * 解析要求基准标记 + `tasks/<id>/WORKING.md`：没有基准的裸相对路径是歧义的，按失败处理。
+ *
+ * @param {string} text
+ * @returns {{taskId: string, revision: number} | null}
+ */
+export function parseCheckpointHandle(text) {
+  if (typeof text !== 'string') return null
+  const file = CHECKPOINT_FILE_NAME.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const re = new RegExp(
+    `检查点\\s+revision\\s+(\\d+)[：:]\\s*${HANDLE_BASE_MARK}\\s+${TASKS_DIR_NAME}/([A-Za-z0-9._-]{1,64})/${file}`,
+  )
+  const m = text.match(re)
+  if (!m) return null
+  const id = normalizeTaskId(m[2])
+  if (id === null) return null
+  const revision = Number(m[1])
+  return Number.isSafeInteger(revision) ? { taskId: id, revision } : null
+}

package/lib/recall/injector.js

@@ -110,9 +110,9 @@ export function createRecallInjector({ ctx, state, tools, taskIdOf }) {
       const files = await scanMemoryFiles(ctx, sessionId)
 
       // ── 代次：**先处理状态转换，再算正文与控制提示** ──
-      // 压缩 / 清空（消息条数下降）在这一行里就让签名、两本账、卡签名、baseline 标记
-      // 一起归零。放到后面（比如去重之后再算）就等于「拿上一代的账本判这一代」——
-      // 复审 R03 的「同题压缩后仍被挡住」正是这么来的。
+      // `begin()` 会把「这一次观测到的消息条数」立刻落进状态（Q08）——去重 / 零命中 /
+      // 预算拒绝的轮次不会走到 commit，若不在这里落账，下一次 begin 就还拿旧基数比，
+      // 压缩就永远判不出来。条数下降时它同时把签名、两本账、卡签名、baseline 标记归零。
       const ledgerKey = session.id || 'no-session-id'
       const st = state.begin(ledgerKey, messages.length)
 
@@ -249,9 +249,10 @@ export function createRecallInjector({ ctx, state, tools, taskIdOf }) {
         return assembled
       }
 
-      // 状态一次写回：签名、两本账、卡签名、缺口卡、条数、baseline 标记。
-      // 放在这里（而不是更早）是刻意的 —— 上面每一步都可能没真注进去东西，
-      // 那就不该让状态前进；一次失败把一条记忆永久挡在门外是最难查的一种。
+      // 投递账一次写回：签名、两本账、卡签名、缺口卡、baseline 标记，以及
+      // **delivered 条数**（`messageCount`）。放在这里（而不是更早）是刻意的 ——
+      // 上面每一步都可能没真注进去东西，那就不该让投递账前进；一次失败把一条记忆永久
+      // 挡在门外是最难查的一种。压缩判据用的**观测账**在 `begin()` 里已经落过了（Q08）。
       state.commit(ledgerKey, {
         signature,
         contentBytes,

package/lib/recall/state.js

@@ -6,9 +6,20 @@
  * 否则一次失败会把这条记忆永久挡在门外。唯一的例外是代次变化：那是**已经发生的事实**
  * （上下文真的被压缩了），必须在算任何东西之前生效，否则这一步会拿着上一代的账做判断。
  *
- * ⚠️ 诚实边界：压缩信号是「消息条数下降」这条启发式，它**覆盖不了条数不降的压缩**
- * （宿主原地改写历史，或截断后又在同一步补足条数）。那种情况下这里看不出代次变化，
- * 记忆仍会被去重挡住。要真正解决得等宿主给出可比的上下文代次标识（目前没有）。
+ * ── 2.1.14（外部审查 Q08）：两本账拆开 ─────────────────────────────────
+ * 旧实现只有一个 `messageCount`，记的是「上一次**见效**时的条数」，只有真正提交才前进。
+ * 于是被去重 / 零命中 / 预算拒绝的那些轮次从不更新它 —— 2 条时注入过、涨到 20 条被去重、
+ * 压缩到 10 条再问时，压缩判定拿 10 比的是 2（投递账），不是 20（刚观测到的实况），
+ * 判不出压缩，签名没清，继续去重、不注入。
+ *
+ * 现在两本账：
+ *   - `lastObservedMessageCount`：**每次 assemble 都推进**（观测是既成事实，与是否投递无关）；
+ *   - `messageCount`（delivered 账）：只有成功投递才前进。
+ * 压缩判定只看观测账；`begin()` 会在返回前把观测写回状态，所以「不提交的轮次」也不会丢。
+ *
+ * ⚠️ 诚实边界（作者已声明，本版不越界）：压缩信号是「消息条数下降」这条启发式，它
+ * **覆盖不了条数不降的压缩**（宿主原地改写历史，或截断后又在同一步补足条数）。那种情况下
+ * 这里看不出代次变化，记忆仍会被去重挡住。要真正解决得等宿主给出可比的上下文代次标识。
  */
 export function createSessionInjectState(maxSessions = 64) {
   const sessions = new Map()
@@ -18,27 +29,44 @@ export function createSessionInjectState(maxSessions = 64) {
     cardBytes: 0,         // 本代状态卡累计字节（与正文分账，见 config.js）
     cardSig: '',          // 本代已发过的那张卡（含检查点句柄的合成文本）
     gapCard: '',          // 本代渲染过的缺口卡正文（签名没变时沿用，避免换个数字重发）
-    messageCount: -1,     // 上一次见效时的消息条数（压缩判据）
+    lastObservedMessageCount: -1, // 上一次 assemble **观测到**的消息条数（压缩判据的唯一基点）
+    messageCount: -1,     // 上一次**成功投递**时的消息条数（delivered 账，只有 commit 推进）
     baselineDone: false,  // 本代是否已经给过 baseline
   })
   return {
     /**
      * 处理代次变化，取回本会话这一代的起点。**必须在算正文与控制提示之前调用。**
      * 返回值是一份快照 —— 调用方只读，写回统一走 `commit()`。
+     *
+     * ⚠️ 与旧实现不同：这里会**立刻**把观测到的条数写回状态。观测是已经发生的事实，
+     * 而「去重 / 零命中 / 预算拒绝」的轮次不会调用 `commit()` —— 不在这里落账，
+     * 下一次 begin 就还拿着旧基数比（Q08）。
      */
     begin(key, messageCount) {
       const prev = sessions.get(key)
-      const generationChanged = !!prev && messageCount < prev.messageCount
-      // 条数下降 → 四样东西一起归零。少清任何一样都会留下一个「上一代的真相」：
+      const observed = Number.isFinite(messageCount) ? messageCount : -1
+      // 压缩判据对着**观测账**比，不是对着上一次投递比。
+      const generationChanged = !!prev && observed >= 0 && prev.lastObservedMessageCount >= 0 &&
+        observed < prev.lastObservedMessageCount
+      // 条数下降 → 除了观测基点，四样东西一起归零。少清任何一样都会留下一个「上一代的真相」：
       // 字节账残留 → 新内容注不进来；baseline 残留 → 它再也不出现；
-      // 卡签名残留 → 恢复入口永久失效。
-      if (generationChanged) sessions.set(key, { ...fresh(), messageCount })
-      const cur = sessions.get(key) ?? fresh()
-      return { ...cur, generationChanged }
+      // 卡签名残留 → 恢复入口永久失效；投递账残留 → 调试/诊断把旧代当新代。
+      const base = generationChanged ? fresh() : { ...(prev ?? fresh()) }
+      base.lastObservedMessageCount = observed
+      sessions.set(key, base)
+      // 只 begin 不提交的会话（全程被去重）也会进 Map —— 长驻宿主里必须同样按 FIFO 收敛。
+      if (sessions.size > maxSessions) sessions.delete(sessions.keys().next().value)
+      return { ...base, generationChanged }
     },
-    /** 一次写回。只防长驻进程无限增长：被挤掉的老会话下次醒来至多把同一批记忆再注一次。 */
+    /**
+     * 一次写回。只防长驻进程无限增长：被挤掉的老会话下次醒来至多把同一批记忆再注一次。
+     *
+     * 合并（而不是整体替换）是刻意的：`begin()` 刚写下的观测账必须留在状态里 ——
+     * 调用方只回传投递账（签名 / 字节 / 卡 / baseline），不该关心、也不该覆盖观测账。
+     */
     commit(key, next) {
-      sessions.set(key, { ...next })
+      const prev = sessions.get(key) ?? fresh()
+      sessions.set(key, { ...prev, ...(next && typeof next === 'object' ? next : {}) })
       // FIFO 而不是 LRU：Map 重写已存在的键不会挪动位置，与旧行为一致。
       if (sessions.size > maxSessions) sessions.delete(sessions.keys().next().value)
     },

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