dsh-engram 0.5.0 → 0.6.0

package/docs/RELEASE-NOTES-v0.5.1.md

@@ -0,0 +1,54 @@
+## dsh-engram v0.5.1
+
+补丁版：修复会话日志扫描对**版本化文件名**的硬编码（issue #8，所有会话扫描
+功能静默返回 0），并补齐记忆查看器的**数据导出/导入**与**替换/冲突可视化**
+（issue #3 收尾）。
+
+### 修复
+
+- **会话扫描识别 `session.v<N>.jsonl.zstd`**（#8）—— `lib/usage.js`、
+  `lib/boundary-prune.js`、`lib/session-cjk.js` 曾硬编码 `session.jsonl.zstd`；
+  当前 DSH 把会话格式版本写进文件名（`0.1.x` → `session.v3.jsonl.zstd`，
+  `0.2.x` → `session.v4.jsonl.zstd`），`statSync` 抛 `ENOENT` 后被循环 `continue`
+  静默吞掉，导致：
+
+  - 设置页 → 遥测恒为「样本不足（0 次）」，`GET /stats`、`GET /toolstats` 全 0；
+  - BoundaryPrune 的 `workspaceHistory()`（L0 偿还输入）看不到任何会话；
+  - CJK 跨会话搜索恒返回 `[]`。
+
+  新增 `sessionLogFile(dir)`：正则匹配 `session[.v<N>].jsonl.zstd`，取目录内
+  **mtime 最新**的一个（迁移会话可能 v3/v4/legacy 并存，最新 = 宿主正在追加的
+  文件），无匹配时回退历史名、调用方保留原有 ENOENT 处理。四处调用点统一改用它。
+  本机实测（14 天窗口）：`files 0 → 17`、`events 0 → 643`。
+
+### 功能
+
+- **数据备份面板**（#3）—— 设置页 → Engram 记忆 →「数据备份」：一键导出当前
+  工作区（或全部）为 `dsh-engram/export` v1 JSON 并下载；导入支持 **dry-run 预览**
+  → `merge`（只补缺失，幂等）/ `replace`（需勾选确认，宿主要求
+  `confirm:"restore"`）。宿主端的 `GET /export`、`POST /import` 早已存在，本版只补
+  GUI 入口，GUI 与 API 走同一格式。
+- **替换 / 冲突可视化**（#3）—— 记忆表给被替代的旧行挂「已替换」徽标、给新行挂
+  「替代 #id」跳转；记忆详情面板新增「替换 / 冲突」双向链（出边来自记录的
+  `supersedes`/`contradicts`，入边由已加载列表反查），元数据露出
+  `source`/`conditions`/`filePath`。
+
+### 测试
+
+- 334/334（新增 5 个 #8 用例：版本化/纯 legacy/v3+v4+legacy 混合/陈旧 legacy
+  不遮蔽 v4/无关文件名不被误选，以及 CJK 版本化读取与 `workspaceHistory` 计数）。
+- `npm run typecheck`、`npm run prepublish-check` 通过；`lib/client.js` 重新构建。
+
+## DSH 版本支持
+
+- **支持的 DSH 范围**：>=0.1.2-alpha.2 <0.3.0-0
+- **peer 声明**：
+  - `@deepseek-ai/dsh-compaction`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-compaction-basic`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-llm`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-settings`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-storage-domain`: `>=0.1.2-alpha.2 <0.3.0-0`
+- **验证版本**：`dsh-v0.2.0-rc.2`（与 0.5.0 相同的宿主依赖集；本版只改会话日志
+  解析与纯客户端界面，未触碰设置/注入路径）
+- **最后验证日期**：2026-10-19
+- **安装方式已验证**：`dsh plugin --profile web add dsh-engram`

package/docs/RELEASE-NOTES-v0.6.0.md

@@ -0,0 +1,64 @@
+## dsh-engram v0.6.0
+
+自 v0.5.1 以来：从「记忆插件」转向**上下文投资组合**——先把省 token 变成可审计的账本，
+再用账本纠正默认值、否决不划算的剪枝，并按确定性事件把记忆推给模型。
+
+### 功能
+
+- **Context Ledger（上下文净收益账本）** — 每个模型请求记一次账：
+  `net = avoided − injected − rewriteChars × (1 − cacheDiscount)`。
+  注入的 `[ENGRAM]`/`[RECALL]`/`[ESR]`/`[JIT]` 块按存活请求计成本；BoundaryPrune 剪掉的
+  结果按后续请求计节省；每次剪枝/推送按前缀重写计价（默认缓存折价 0.1）。
+  `GET /api/dsh-engram/stats` 与 `/overview` 返回 `ledger`（totals / byWorkspace / byDay），
+  落盘 `~/.dsh/engram/ledger.json`（原子写、按天滚动、delta flush）。
+  设置键：`ledgerEnabled`（默认开）、`ledgerCacheDiscount`（默认 0.1）。
+- **GUI 账本可视化** — 遥测页新增「Context Ledger · 上下文净收益」面板（净 token 大数字、
+  节省/注入/重写罚金三卡、近 14 天红绿柱、JIT 推送次数）；记忆概览新增「上下文净 token」卡。
+- **BoundaryPrune 默认开 + 账本否决** — `boundaryPrune` 默认 `true`、`resultPack` 默认 `true`
+  （默认剪枝由归档兜底、无损）；新增 `boundaryPruneAdaptive`（默认开）：某 workspace 真实剪枝
+  后净收益为负且 ≥3 次时，账本自动否决后续剪枝（fail-open，日志一行）。
+- **JIT 推送（v0.6-C）** — 三类确定性事件，命中已有记忆/任务才推，append-only、每会话 ≤3 行、
+  每行 ≤220 字符、无命中沉默：错误复发（同 `cmd:` 第 2 次失败 + 已有 error/procedure）、
+  文件焦点（同文件连续第 2 次编辑 + filePath/dir 锚定记忆）、goal 完成（有 active ESR 任务）。
+  新增 `[JIT]` section（order 40.75）、`/stats.jit` 计数、`jitEnabled` 开关。
+- **设置卡** — 新增「剪枝自适应」「JIT 推送」两个开关。
+
+### 破坏性变更（默认值纠偏）
+
+| 键 | v0.5.1 | v0.6.0 |
+|---|---|---|
+| `boundaryPrune` | `false` | **`true`** |
+| `boundaryPruneAdaptive` | — | **`true`** |
+| `resultPack` | `false` | **`true`** |
+| `gcReplacesCompaction` | `true` | **`false`**（opt-in） |
+| `autoWebCompaction` | `true` | **`false`**（opt-in） |
+
+- 默认剪枝现在**开启**，但被剪中段默认归档到 `resultpack/`（7 天），可用
+  `result_recall(callId)` 召回。要回到纯记忆模式：`boundaryPrune:false`（或
+  `resultPack:false` 接受不可召回）。
+- Context GC 接管改为 **opt-in**。已接管的 web 预设保持 wired，但默认挂宿主
+  `BasicCompactionEngine`（DSH 自己的 LLM 摘要），除非显式打开
+  `gcReplacesCompaction:true`（web 还需 `autoWebCompaction:true`）。
+- 升级后需重启 `dsh web`；账本从下一次会话开始累计。
+
+### 其他
+
+- 测试 **359/359**（新增 ledger 13 例、jit 9 例、adaptive gate 4 例、settings/API/client 渲染用例）；
+  `npm run eval` BENCH PASS；`npm run typecheck` 通过；`lib/client.js` 重建。
+- 文档：`docs/PROPOSAL-evolution.zh.md`（演进提案）、中英 README、`docs/CONTEXT-GC-GUIDE.zh.md`
+  （Context GC 改为 opt-in 的 4 步启用）。
+- 真实实例冒烟（`dsh 0.2.0-rc.2`，临时将 profile 的 `dsh-engram` 指向工作树后还原）：
+  `/overview` 返回 `ledger`、`/stats` 返回 `jit`，defaults 与上表一致，`compaction.host = default`。
+
+## DSH 版本支持
+
+- **支持的 DSH 范围**：`>=0.1.2-alpha.2 <0.3.0-0`
+- **peer 声明**：
+  - `@deepseek-ai/dsh-compaction`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-compaction-basic`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-llm`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-settings`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-storage-domain`: `>=0.1.2-alpha.2 <0.3.0-0`
+- **验证版本**：`dsh 0.2.0-rc.2`
+- **最后验证日期**：2026-10-19
+- **安装方式已验证**：`dsh plugin --profile web add dsh-engram`

package/lib/api.js

@@ -163,6 +163,7 @@ export function makeEngramRoutes(service) {
       captures: service.captureStats ?? { total: 0, git: 0, file: 0, error: 0, preference: 0 },
       gc: service.gcStats ?? { lastRun: 0, archivedMemories: 0, archivedTasks: 0, removedLinks: 0 },
       activation: service.packTelemetry ? service.packTelemetry() : { boundaryPrune: null, recall: null },
+      ledger: service.ledger ? service.ledger() : null,
       compaction: service.compactionStatus ?? { host: "unknown", web: { action: "unknown", presets: [] } },
       config: service.config ?? {},
       anonymous: {
@@ -517,6 +518,10 @@ export function makeEngramRoutes(service) {
       // activation record (fires actually landed on this profile) + the
       // [RECALL] injection-funnel leg (blocks actually injected into sessions).
       activation: service.packTelemetry ? service.packTelemetry() : { boundaryPrune: null, recall: null },
+      // Context Ledger (PROPOSAL-evolution §4 v0.6-A): spent vs saved context,
+      // net of prefix rewrites. Persisted rollup + unflushed live sessions.
+      ledger: service.ledger ? service.ledger() : null,
+      jit: service.jitStats ? service.jitStats() : null,
     });
   };
 

package/lib/boundary-prune.js

@@ -40,6 +40,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+import { sessionLogFile } from "./usage.js";
 import { workspaceKey as wk } from "./util.js";
 
 /** Fixed fallback for the repayment gate when no history exists yet. */
@@ -93,7 +94,7 @@ export function workspaceHistory(root = path.join(os.homedir(), ".dsh", "session
       let sessions = 0;
       const bdir = path.join(root, bucket);
       for (const sid of fs.readdirSync(bdir)) {
-        const file = path.join(bdir, sid, "session.jsonl.zstd");
+        const file = sessionLogFile(path.join(bdir, sid));
         try {
           const st = fs.statSync(file);
           if (st.size > 0) sessions += 1;
@@ -129,7 +130,8 @@ export function expectedSessionRequests(requestsSoFar, history, workspace, floor
 
 /** Install the boundary-prune listener. Returns a disposer. */
 export function installBoundaryPrune(ctx, config, log, hooks = {}, opts = {}) {
-  const enabled = config?.boundaryPrune === true;
+  // Default ON (v0.6 default correction): explicit `false` is the opt-out.
+  const enabled = config?.boundaryPrune !== false;
   if (!enabled) return () => {};
   const pruner = ctx.get?.("toolResultPruner");
   if (!pruner || typeof pruner.pruneSession !== "function") {
@@ -141,6 +143,13 @@ export function installBoundaryPrune(ctx, config, log, hooks = {}, opts = {}) {
     : DEFAULT_MIN_REMAINING;
   // History is injectable for tests; production reads the real session corpus.
   const history = opts?.history ?? workspaceHistory();
+  // Adaptive safety valve (PROPOSAL-evolution v0.6-B): the Context Ledger can
+  // veto further fires when a workspace's own accounting says pruning is net
+  // negative after enough real fires. The repayment gate still runs first;
+  // this is purely evidence-based off, never speculative on.
+  const adaptive = config?.boundaryPruneAdaptive !== false;
+  const allowFire = typeof opts?.allowFire === "function" ? opts.allowFire : () => true;
+  const blockedNotified = new Set();
 
   // Optional threshold override (ResultPack L0, T2048 landing): the host pruner
   // ships a fixed threshold (8192) that the plugin cannot change in place. When
@@ -234,6 +243,24 @@ export function installBoundaryPrune(ctx, config, log, hooks = {}, opts = {}) {
 
   /** Shared fire path for every boundary source (event + step-cadence). */
   const fireBoundary = (session, boundary, state, expectedTotal) => {
+    if (adaptive) {
+      const workspace = wk(session?.header?.cwd);
+      let allowed = true;
+      try {
+        allowed = allowFire(workspace) !== false;
+      } catch {
+        allowed = true; // a gate bug must never disable pruning
+      }
+      if (!allowed) {
+        if (!blockedNotified.has(workspace)) {
+          blockedNotified.add(workspace);
+          log?.info?.(
+            `engram boundary-prune: ledger gate holds for ${workspace} (net negative) — skipping further prunes`,
+          );
+        }
+        return;
+      }
+    }
     const result = activePruner.pruneSession(session);
     const prunedNow = result?.pruned?.length ?? 0;
     if (prunedNow > 0) {