sage-mem 2.1.12 → 2.1.14

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**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
+**Current release: `2.1.14`** — 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.
@@ -420,6 +420,8 @@ The two things are moved **differently**, spelled out:
 
 Value semantics: **out-of-range values are clamped to the boundary, illegal values (including pure whitespace) fall back to the default.**
 
+**Scope of the state root, and migration (spelled out since 2.1.13).** `SAGE_MEM_STATE_DIR` is the **single** state root: settings, autodream configuration and reports, the lock table, the access ledger, the conflict queue, task checkpoints, rollback snapshots and its index all live under it, and every module (including the autodream engine and the lock table) resolves it from the same value instead of re-deriving `<parent of the memory directory>/.sage-mem`. **Changing the state root does not migrate old data**: the new root wins, the old `.sage-mem` is left untouched but no longer read, and startup prints one line naming what is still in the old root. Move it by hand if you want to keep it.
+
 ### What the Settings Page Can Change
 
 The panel can change the five caps above (written to `<state directory>/settings.json`, precedence **settings page > environment variable > built-in default**), as well as reserved names (file names that are protected and that the settings page may not write or delete, written to `<state directory>/reserved.json`). **Some items take effect only after restarting DSH**, and the panel writes out both the value in effect now and the value after restart.

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.12`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.14`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。
@@ -420,6 +420,8 @@ sage-mem 给记忆目录的写入加了**版本守卫**：写入前记下当前
 
 取值语义：**越界夹到边界，非法值（含纯空格）回落默认。**
 
+**状态根的范围与迁移（2.1.13 起写清）**：`SAGE_MEM_STATE_DIR` 是**唯一的状态根** —— 设置、自动做梦配置与报告、锁表、访问台账、冲突队列、任务检查点、回滚快照、台账都在它下面，插件内所有模块（含自动做梦引擎与锁表）都从同一个值解析，不再各自按记忆目录的父目录去拼。**更改状态根不会自动迁移旧数据**：新根优先、旧的 `.sage-mem` 原样保留但不再读取，启动时会打印一行提示点名旧根里还有哪些数据；要保留请手动移动。
+
 ### 设置页里能改的
 
 面板可改上面五个上限（写入 `<状态目录>/settings.json`，优先级 **设置页 > 环境变量 > 内置默认**），以及保留名（受保护、设置页不许写删的文件名，写入 `<状态目录>/reserved.json`）。**部分项要重启 DSH 才生效**，面板上会写清「当前生效 / 重启后」。

package/lib/assembly/autodream-mount.js

@@ -6,11 +6,16 @@
  * 这是本插件唯一一处「降级而不是失败」的设计，理由就在这里。
  */
 import { warnLog } from '../memory/util.js'
+import { resolvePaths } from '../memory/config.js'
 
 /** @param {object} ctx @param {{AutodreamEngine:Function, AutodreamGateway:Function, memoryDir:string, sessionsRoot:string, reservedFiles:string[]}} deps */
 export function mountAutodream(ctx, { AutodreamEngine, AutodreamGateway, memoryDir, sessionsRoot, reservedFiles }) {
   try {
-    const engine = new AutodreamEngine(ctx, { memoryDir, sessionsRoot, reservedFiles })
+    // Q09：路径组在 `config.js` 里**一次**解析，这里显式把 stateRoot 交给引擎 ——
+    // 旧实现让引擎从 memoryDir 的父目录重拼 `.sage-mem`，于是 SAGE_MEM_STATE_DIR 只对
+    // 配置模块生效，面板与引擎各读一套（审查实测 engineRoot 指向默认根）。
+    const paths = resolvePaths({ memoryDir, sessionsRoot })
+    const engine = new AutodreamEngine(ctx, { ...paths, reservedFiles })
     new AutodreamGateway(ctx, engine)
     engine.start()
     // 卸载时把定时器与锁收干净。effect 拿不到就交给 unref 兜底（不阻止进程退出）。

package/lib/autodream/engine.js

@@ -40,7 +40,9 @@ import { countSessionsSince, newRunId, stampHuman } from './util.js'
 import { flushAccess, ledgerFileFor, pickArchiveCandidates, readAccessLedger } from '../memory/access.js'
 import { archiveMemory } from '../memory/archive.js'
 import { scanMemoryFiles } from '../memory/scan.js'
-import { dirname, join } from 'node:path'
+import { resolveStateRoot } from '../memory/config.js'
+import { basename, dirname, join } from 'node:path'
+import { stat } from 'node:fs/promises'
 
 import * as gateMod from './gate.js'
 import * as llmloopMod from './llm-loop.js'
@@ -86,7 +88,18 @@ export class AutodreamEngine {
     this.version = opts.version
     /** 使用者自己声明的受保护文件名（`<状态根>/reserved.json`）——注入 prompt，绝不写死。 */
     this.reservedFiles = Array.isArray(opts.reservedFiles) ? opts.reservedFiles : []
-    this.stateRoot = join(dirname(this.memoryDir), STATE_DIR)
+    /**
+     * 状态根（Q09）：装配方**显式传入**（`config.js` 的 `resolvePaths()` 一次解析）；
+     * 直接构造引擎（单测 / 旧调用方）时按 `resolveStateRoot()` 派生 —— 两条路同一判据，
+     * 不再在这里 `dirname(memoryDir)` 重拼 `.sage-mem`。
+     */
+    this.stateRoot = typeof opts.stateRoot === 'string' && opts.stateRoot !== ''
+      ? opts.stateRoot
+      : resolveStateRoot(this.memoryDir)
+    /** 旧状态根：只有「本次状态根 ≠ 按记忆目录派生的那个」时才存在（迁移提示用）。 */
+    const derivedStateRoot = join(dirname(this.memoryDir), STATE_DIR)
+    this.legacyStateRoot = this.stateRoot === derivedStateRoot ? '' : derivedStateRoot
+    this._legacyStateReported = false
     this.home = join(this.stateRoot, FEATURE_DIR)
     this.configPath = join(this.stateRoot, 'autodream.json')
     this.legacyConfigPath = join(this.stateRoot, LEGACY_STATE_FILE)
@@ -128,7 +141,37 @@ export class AutodreamEngine {
   // ────────────────────────────── 配置与状态 ──────────────────────────────
 
   // ── 配置与状态：实现在 lib/autodream/settings.js ──
-  async load() { return settingsMod.load.call(this) }
+  async load() {
+    const state = await settingsMod.load.call(this)
+    // 启动检查 / 面板打开都会走到 load()：在这里提示一次「旧状态根还有数据」。
+    await this.checkLegacyStateRoot()
+    return state
+  }
+
+  /**
+   * Q09 的旧目录规则：**不自动迁移 + 启动提示一次**。
+   *
+   * 为什么不做自动迁移：状态根下住着配置、锁表、台账、冲突、检查点、快照六类数据，
+   * 自动搬移任何一类出错都可能让「锁」或「回滚点」在用户不知情时消失 —— 那是比
+   * 「旧数据暂时看不见」严重得多的损失。所以规则写成：**新状态根优先、旧数据留在原位、
+   * 明确告诉用户手动搬**。README 的措辞由 Lead 统一改，G4 只在报告里给出建议口径。
+   */
+  async checkLegacyStateRoot() {
+    if (this._legacyStateReported || !this.legacyStateRoot) return
+    this._legacyStateReported = true
+    const legacy = this.legacyStateRoot
+    const markers = ['autodream.json', LEGACY_STATE_FILE, 'locked.json', 'access.json', 'settings.json', FEATURE_DIR, 'tasks', 'conflicts']
+    const found = []
+    for (const name of markers) {
+      if (await stat(join(legacy, name)).then(() => true, () => false)) found.push(basename(name))
+    }
+    if (found.length === 0) return
+    this.log('warn',
+      `检测到旧状态根 ${legacy} 仍有数据（${found.join(' / ')}），而本次状态根是 ${this.stateRoot}` +
+      '（SAGE_MEM_STATE_DIR 覆写）。本版不自动迁移：旧数据留在原位、不再读取 —— ' +
+      '需要保留请手动把要用的文件移到新状态根。')
+  }
+
   async persist() { return settingsMod.persist.call(this) }
   async getConfig() { return settingsMod.getConfig.call(this) }
   async setConfig(patch) { return settingsMod.setConfig.call(this, patch) }

package/lib/memory/config.js

@@ -22,11 +22,37 @@ export const SESSIONS_ROOT = process.env.DSH_HOME ? join(process.env.DSH_HOME, '
  * 状态根：配置、锁表、台账、冲突、检查点、快照都住在这里。
  *
  * `SAGE_MEM_STATE_DIR` 显式覆写优先；没设时跟着记忆目录走（它的上一层 + `.sage-mem`）。
- * ⚠️ Q09：**所有子模块都必须从这里取**，不许各自 `dirname(memoryDir)` + 拼 `.sage-mem` ——
- * 那样覆写只对一部分模块生效，面板与引擎会各读一套配置。
+ * ⚠️ Q09：**所有子模块都必须经 `resolveStateRoot()` / `resolvePaths()` 取**，不许各自
+ * `dirname(memoryDir)` + 拼 `.sage-mem` —— 那样覆写只对一部分模块生效，面板与引擎会各读一套。
  */
-export const STATE_ROOT = process.env.SAGE_MEM_STATE_DIR || join(dirname(MEMORY_DIR), '.sage-mem')
+export function resolveStateRoot(memoryDir = MEMORY_DIR) {
+  // 默认记忆目录直接用装配期算好的 STATE_ROOT（含 SAGE_MEM_STATE_DIR 覆写）；
+  // 调用方显式传了**别的**目录（autodream 单测 / 多库场景）时，状态跟着那个目录走 ——
+  // 否则一个全局环境变量会把互不相关的记忆库的锁表 / 快照全灌进同一个目录。
+  if (memoryDir === MEMORY_DIR) return process.env.SAGE_MEM_STATE_DIR || join(dirname(MEMORY_DIR), '.sage-mem')
+  return join(dirname(memoryDir), '.sage-mem')
+}
+
+/**
+ * **装配时一次解析**的路径组（Q09）。
+ *
+ * 三个路径只在这里算一次，然后显式传给子模块 —— 引擎、锁表、台账、冲突、检查点、快照
+ * 不能再各自重拼。可显式覆写（测试 / 多库）：
+ *   - `memoryDir` 给了就用它；没给用模块常量
+ *   - `stateRoot` 给了就用它；否则按 `resolveStateRoot(memoryDir)` 派生
+ *   - `sessionsRoot` 给了（含空串）就用它；否则用模块常量
+ */
+export function resolvePaths(overrides = {}) {
+  const memoryDir = overrides.memoryDir || MEMORY_DIR
+  const stateRoot = typeof overrides.stateRoot === 'string' && overrides.stateRoot !== ''
+    ? overrides.stateRoot
+    : resolveStateRoot(memoryDir)
+  const sessionsRoot = overrides.sessionsRoot !== undefined ? overrides.sessionsRoot : SESSIONS_ROOT
+  return { memoryDir, stateRoot, sessionsRoot }
+}
 
+export const PATHS = Object.freeze(resolvePaths())
+export const STATE_ROOT = PATHS.stateRoot
 /** 读一个整数型环境变量并在范围内收敛；取不到或非法就用默认值。 */
 export function envInt(name, dflt, lo, hi) {
   // ⚠️ 必须先 trim：`Number('   ')` 是 **0** 而不是 NaN，于是纯空格的值会被

package/lib/memory/lock.js

@@ -22,11 +22,19 @@
 import { mkdir, readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { nameKey } from './naming.js'
+import { resolveStateRoot } from './config.js'
 import { createWriteQueue, writeFileAtomic } from './util.js'
 
-/** 锁表文件：状态根下，与记忆文件分开。 */
-export function lockFileOf(memoryDir) {
-  return join(dirname(memoryDir), '.sage-mem', 'locked.json')
+/**
+ * 锁表文件：状态根下，与记忆文件分开。
+ *
+ * ⚠️ Q09：状态根必须经 `config.js` 的 `resolveStateRoot()` 解析（尊重 `SAGE_MEM_STATE_DIR`），
+ * 不许在这里 `dirname(memoryDir)` + 拼 `.sage-mem` —— 旧写法让「状态目录覆写」只对一部分
+ * 模块生效，于是面板读的锁表与引擎写的是两份。装配期显式给了 `stateRoot` 就用它。
+ */
+export function lockFileOf(memoryDir, stateRoot) {
+  const root = typeof stateRoot === 'string' && stateRoot !== '' ? stateRoot : resolveStateRoot(memoryDir)
+  return join(root, 'locked.json')
 }
 
 /**

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