dsh-engram 0.5.1 → 0.6.0

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

@@ -130,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") {
@@ -142,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
@@ -235,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) {

package/lib/client.js

@@ -2023,6 +2023,11 @@ function pct(v) {
   if (v === null || v === void 0) return "\u2013";
   return `${Math.round(v * 100)}%`;
 }
+function tokenCount(n) {
+  const sign = n > 0 ? "+" : n < 0 ? "\u2212" : "";
+  const abs = Math.abs(n);
+  return abs >= 1e3 ? `${sign}${(abs / 1e3).toFixed(1)}k` : `${sign}${abs}`;
+}
 function EngramTelemetry({ api, workspace }) {
   const { dark, vars } = useEngramTheme();
   const [stats, setStats] = (0, import_react5.useState)(null);
@@ -2065,6 +2070,10 @@ function EngramTelemetry({ api, workspace }) {
   }, [stats]);
   const dose = stats && stats.ratios ? stats.ratios : null;
   const sampleText = stats && stats.ratios && stats.ratios.calls < 10 ? `\u6837\u672C\u4E0D\u8DB3\uFF08${stats.ratios.calls} \u6B21\uFF09\uFF0C\u6BD4\u4F8B\u4EC5\u4F9B\u53C2\u8003` : null;
+  const ledger = stats?.ledger ?? null;
+  const ledgerBucket = ledger === null ? null : workspace === "" ? ledger.totals : ledger.byWorkspace?.[workspace] ?? null;
+  const ledgerDays = ledger === null || workspace !== "" ? [] : [...ledger.byDay ?? []].slice(0, 14).reverse();
+  const ledgerMax = Math.max(1, ...ledgerDays.map((d) => Math.abs(d.netTokens)));
   const hb2 = {
     root: { display: "flex", flexDirection: "column", gap: 12, ...vars },
     head: { display: "flex", alignItems: "center", gap: 8, flexWrap: "wrap" },
@@ -2178,6 +2187,68 @@ function EngramTelemetry({ api, workspace }) {
           /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.statLabel, children: "\u5931\u8D25\u6B21\u6570" })
         ] })
       ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: hb2.panel, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: { ...hb2.panelTitle, display: "flex", alignItems: "baseline", gap: 8, flexWrap: "wrap" }, children: [
+          "Context Ledger \xB7 \u4E0A\u4E0B\u6587\u51C0\u6536\u76CA",
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("span", { style: hb2.sub, children: workspace === "" ? "\u5168\u90E8\u5DE5\u4F5C\u533A" : workspace })
+        ] }),
+        !ledger ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.sub, children: "\u8D26\u672C\u672A\u542F\u7528\uFF08`ledgerEnabled:false`\uFF09\u6216\u5BBF\u4E3B API \u672A\u5C31\u7EEA\u3002" }) : !ledgerBucket ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.sub, children: "\u8BE5\u5DE5\u4F5C\u533A\u8FD8\u6CA1\u6709\u8D26\u672C\u8BB0\u5F55\u3002" }) : /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)(import_jsx_runtime5.Fragment, { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: { display: "flex", alignItems: "baseline", gap: 10, flexWrap: "wrap" }, children: [
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("span", { style: { ...hb2.statNum, fontSize: 24, color: ledgerBucket.netTokens >= 0 ? "#059669" : "#dc2626" }, children: tokenCount(ledgerBucket.netTokens) }),
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("span", { style: hb2.statLabel, children: "\u51C0 token\uFF08\u8282\u7701 \u2212 \u6CE8\u5165 \u2212 \u91CD\u5199\u7F5A\u91D1\uFF09" }),
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("span", { style: hb2.gaugeSub, children: [
+              "\u8BF7\u6C42 ",
+              ledgerBucket.requests,
+              " \xB7 \u4F1A\u8BDD ",
+              ledgerBucket.sessions,
+              " \xB7 open ",
+              ledger.openSessions,
+              stats.jit ? ` \xB7 JIT \u63A8\u9001 ${stats.jit.pushes}` : ""
+            ] })
+          ] }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: { ...hb2.grid, marginTop: 8 }, children: [
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: hb2.statCard, children: [
+              /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { ...hb2.statNum, color: "#059669" }, children: tokenCount(ledgerBucket.avoidedTokens) }),
+              /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.statLabel, children: "\u8282\u7701 \xB7 \u526A\u679D/\u538B\u7F29" })
+            ] }),
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: hb2.statCard, children: [
+              /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { ...hb2.statNum, color: "#d97706" }, children: tokenCount(-ledgerBucket.injectedTokens) }),
+              /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.statLabel, children: "\u6CE8\u5165\u6210\u672C \xB7 \u7D22\u5F15/\u53EC\u56DE/ESR" })
+            ] }),
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: hb2.statCard, children: [
+              /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { ...hb2.statNum, color: "#dc2626" }, children: tokenCount(-Math.round(ledgerBucket.rewritesCostChars / ledger.charsPerToken)) }),
+              /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: hb2.statLabel, children: [
+                "\u91CD\u5199\u7F5A\u91D1 \xB7 ",
+                ledgerBucket.rewriteCount,
+                " \u6B21"
+              ] })
+            ] })
+          ] }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: { ...hb2.sub, marginTop: 6 }, children: [
+            "\u53E3\u5F84\uFF1Achars/",
+            ledger.charsPerToken,
+            " \u4F30\u7B97 \xB7 \u7F13\u5B58\u6298\u4EF7 ",
+            Math.round(ledger.cacheDiscount * 100),
+            "% \uFF08\u91CD\u5199\u6309 ",
+            Math.round((1 - ledger.cacheDiscount) * 100),
+            "% \u8BA1\uFF09\xB7 \u672A\u8BA1\u6A21\u578B\u8D28\u91CF\u5DEE"
+          ] }),
+          ledgerDays.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("svg", { width: 460, height: 96, viewBox: "0 0 460 96", style: { display: "block", maxWidth: "100%", marginTop: 8 }, children: [
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("line", { x1: 0, y1: 48, x2: 460, y2: 48, stroke: dark ? "rgba(148,163,184,.35)" : "rgba(107,114,128,.35)", strokeDasharray: "3 3" }),
+            ledgerDays.map((d, i) => {
+              const w = Math.max(6, Math.min(22, 420 / ledgerDays.length - 4));
+              const x = 8 + i * (w + 4);
+              const h = Math.abs(d.netTokens) / ledgerMax * 38;
+              const positive = d.netTokens >= 0;
+              return /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("g", { children: [
+                /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("rect", { x, y: positive ? 48 - h : 48, width: w, height: Math.max(1, h), rx: 2, fill: positive ? "#059669" : "#dc2626", children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("title", { children: `${d.day} \xB7 net ${d.netTokens} tok \xB7 \u8BF7\u6C42 ${d.requests}` }) }),
+                /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("text", { x: x + w / 2, y: 92, fontSize: 8, fill: dark ? "#8b93a7" : "#6b7280", textAnchor: "middle", children: (d.day ?? "").slice(5).replace("-", "/") })
+              ] }, d.day);
+            })
+          ] }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { ...hb2.sub, marginTop: 4 }, children: "\u7EFF = \u5F53\u65E5\u51C0\u7701 \xB7 \u7EA2 = \u5F53\u65E5\u51C0\u4E8F\uFF08\u6309\u5929\u6EDA\u52A8\uFF0C\u6700\u8FD1 14 \u5929\uFF09" })
+        ] })
+      ] }),
       /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: hb2.panel, children: [
         /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.panelTitle, children: "\u8FD1 14 \u5929\u6BCF\u65E5\u6D3B\u52A8 \xB7 mem vs esr" }),
         daily.rows.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.sub, children: "\u8FD8\u6CA1\u6709\u6309\u5929\u6570\u636E\uFF08\u5DE5\u5177\u8C03\u7528\u4F1A\u5B9E\u65F6\u7D2F\u8BA1\uFF09\u3002" }) : /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("svg", { width: BW, height: BH, viewBox: `0 0 ${BW} ${BH}`, style: { display: "block", maxWidth: "100%" }, children: daily.rows.map((d, i) => {
@@ -2636,6 +2707,11 @@ function EngramDetail({ target, api, tasks, nodes, links, memories = [], onClose
 
 // client/src/EngramSection.tsx
 var import_jsx_runtime7 = require("react/jsx-runtime");
+function signedTokens(n) {
+  const sign = n > 0 ? "+" : n < 0 ? "\u2212" : "";
+  const abs = Math.abs(n);
+  return abs >= 1e3 ? `${sign}${(abs / 1e3).toFixed(1)}k` : `${sign}${abs}`;
+}
 var KIND_COLORS2 = {
   preference: "#b45309",
   decision: "#2563eb",
@@ -3140,6 +3216,7 @@ function EngramSection({ api, t }) {
             const memNum = wsCounts ? wsCounts.memories : overview.totals.memories;
             const taskNum = wsCounts ? wsCounts.tasks : overview.totals.tasks;
             const linkNum = wsCounts ? wsCounts.links : overview.totals.links;
+            const ledgerBucket = overview.ledger ? workspace && overview.ledger.byWorkspace[workspace] || overview.ledger.totals : null;
             return /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)("div", { style: s2.stats, children: [
               /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(StatCard, { num: String(memNum), label: wsCounts ? "\u8BB0\u5FC6 (active)" : "\u8BB0\u5FC6 (active, \u5168\u5C40)" }),
               /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(StatCard, { num: String(taskNum), label: wsCounts ? "\u4EFB\u52A1 (active)" : "\u4EFB\u52A1 (active, \u5168\u5C40)" }),
@@ -3161,6 +3238,13 @@ function EngramSection({ api, t }) {
                   num: String(gc.archivedMemories + gc.archivedTasks),
                   label: `GC \u5DF2\u5F52\u6863 \xB7 \u94FE\u63A5-${gc.removedLinks}`
                 }
+              ),
+              ledgerBucket && /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+                StatCard,
+                {
+                  num: signedTokens(ledgerBucket.netTokens),
+                  label: `\u4E0A\u4E0B\u6587\u51C0 token \xB7 \u8BF7\u6C42 ${ledgerBucket.requests}`
+                }
               )
             ] });
           })(),
@@ -3613,10 +3697,12 @@ var import_jsx_runtime8 = require("react/jsx-runtime");
 var COMMON_FIELDS = [
   { key: "autoCapture", label: "\u81EA\u52A8\u6355\u83B7", hint: "\u96F6 LLM \u4ECE\u5DE5\u5177\u7ED3\u679C\u63D0\u53D6\u8BB0\u5FC6\uFF08git/\u5173\u952E\u6587\u4EF6/\u9519\u8BEF\uFF09", kind: "bool" },
   { key: "autoCapturePreferences", label: "\u504F\u597D\u6355\u83B7", hint: "\u7528\u6237\u7EA0\u6B63/\u504F\u597D\u5B66\u4E60\uFF1A\u68C0\u6D4B\u6D88\u606F\u91CC\u7684\u300C\u4E0D\u8981\u7528X/\u6539\u7528Y/prefer/never use\u300D\u53E5\u5F0F\uFF0C\u81EA\u52A8\u6C89\u6DC0\u4E3A preference \u8BB0\u5FC6\u5E76\u7F6E\u9876 [ENGRAM]\uFF08correx/PAHF \u5F0F\uFF0C\u96F6 LLM\uFF09", kind: "bool" },
-  { key: "boundaryPrune", label: "\u8FB9\u754C\u526A\u679D", hint: "ResultPack L1\uFF1Atodo \u5B8C\u6210/goal \u7EC8\u6001\u8FB9\u754C\u4E3B\u52A8\u526A\u6389\u8D85\u9608\u503C\u65E7\u5DE5\u5177\u7ED3\u679C\uFF08DSH \u786E\u5B9A\u6027 surface-replace\u3001\u507F\u8FD8\u95E8\u3001\u96F6 LLM\uFF1B\u9ED8\u8BA4\u5173\uFF09", kind: "bool" },
+  { key: "boundaryPrune", label: "\u8FB9\u754C\u526A\u679D", hint: "ResultPack L1\uFF1Atodo \u5B8C\u6210/goal \u7EC8\u6001\u8FB9\u754C\u4E3B\u52A8\u526A\u6389\u8D85\u9608\u503C\u65E7\u5DE5\u5177\u7ED3\u679C\uFF08DSH \u786E\u5B9A\u6027 surface-replace\u3001\u507F\u8FD8\u95E8\u3001\u96F6 LLM\uFF1B\u9ED8\u8BA4\u5F00\uFF0C\u5173=opt-out\uFF09", kind: "bool" },
+  { key: "boundaryPruneAdaptive", label: "\u526A\u679D\u81EA\u9002\u5E94", hint: "\u8D26\u672C\u5426\u51B3\uFF1A\u8BE5 workspace \u771F\u5B9E\u526A\u679D\u540E\u51C0\u6536\u76CA\u4E3A\u8D1F\uFF08\u22653 \u6B21\uFF09\u65F6\u81EA\u52A8\u505C\u6B62\u7EE7\u7EED\u526A\uFF1B\u8BC1\u636E\u53EA\u80FD\u5173\u3001\u4E0D\u4F1A\u81EA\u884C\u5F00", kind: "bool" },
   { key: "boundaryPruneThresholdChars", label: "\u526A\u679D\u9608\u503C(\u5B57\u7B26)", hint: "\u8986\u76D6\u5BBF\u4E3B 8192\uFF1A\u8BBE 2048 \u53EF\u66F4\u65E9\u5F00\u526A\uFF0C\u5E76\u914D L2 \u5F52\u6863\u627E\u56DE\u88AB\u526A\u4E2D\u6BB5\uFF1B\u7559\u7A7A=\u5BBF\u4E3B\u9ED8\u8BA4\u3002\u5EFA\u8BAE\u540C\u65F6\u628A\u4FDD\u7559\u8FB9\u7F18\u8C03\u5C0F\uFF08\u5982 1024/256\uFF09\u4EE5\u83B7\u5F97\u6700\u5927\u8282\u7701", kind: "num", min: 256, max: 16384, step: 256 },
-  { key: "resultPack", label: "\u7ED3\u679C\u5F52\u6863\u53EC\u56DE", hint: "ResultPack L2\uFF1A\u526A\u6389\u7684\u4E2D\u6BB5\u8131\u654F\u5F52\u6863\uFF0C\u8282\u70B9\u5C3E\u90E8\u9644 handle\uFF0C\u6A21\u578B\u53EF\u7528 result_recall(callId) \u6309\u9875\u53EC\u56DE\uFF08\u5B8C\u6574 ObservationPack\uFF1B\u9700\u4E0E\u8FB9\u754C\u526A\u679D\u4E00\u8D77\u5F00\uFF09", kind: "bool" },
+  { key: "resultPack", label: "\u7ED3\u679C\u5F52\u6863\u53EC\u56DE", hint: "ResultPack L2\uFF1A\u526A\u6389\u7684\u4E2D\u6BB5\u8131\u654F\u5F52\u6863\uFF0C\u8282\u70B9\u5C3E\u90E8\u9644 handle\uFF0C\u6A21\u578B\u53EF\u7528 result_recall(callId) \u6309\u9875\u53EC\u56DE\uFF08\u5B8C\u6574 ObservationPack\uFF1B\u9ED8\u8BA4\u5F00\uFF0C\u4FDD\u8BC1\u9ED8\u8BA4\u526A\u679D\u65E0\u635F\uFF1B\u9700\u4E0E\u8FB9\u754C\u526A\u679D\u4E00\u8D77\u5F00\uFF09", kind: "bool" },
   { key: "autoRecallOnStart", label: "\u4F1A\u8BDD\u542F\u52A8\u81EA\u52A8\u53EC\u56DE", hint: "\u65B0\u4F1A\u8BDD\u6309\u9996\u6761\u6D88\u606F\u81EA\u52A8\u628A\u6700\u76F8\u5173\u8BB0\u5FC6\u6CE8\u5165 [RECALL] \u5757\uFF08\u65E0\u9700\u6A21\u578B\u60F3\u8D77\u8C03 engram_recall\uFF09\uFF1B\u5173\u6389=\u56DE\u5230\u7EAF\u62C9\u53D6", kind: "bool" },
+  { key: "jitEnabled", label: "JIT \u63A8\u9001", hint: "\u9519\u8BEF\u590D\u53D1 / \u6587\u4EF6\u7126\u70B9 / goal \u5B8C\u6210\u65F6\uFF0C\u628A\u5DF2\u6709\u8BB0\u5FC6\u538B\u6210\u4E00\u884C\u63A8\u8FDB\u4E0A\u4E0B\u6587\uFF08append-only\u3001\u6BCF\u4F1A\u8BDD\u22643 \u884C\u3001\u65E0\u547D\u4E2D\u6C89\u9ED8\uFF1B\u6BCF\u6B21\u63A8\u9001\u6309\u524D\u7F00\u91CD\u5199\u8BA1\u5165\u8D26\u672C\uFF09", kind: "bool" },
   { key: "maxRecallPerSession", label: "\u6BCF\u4F1A\u8BDD\u53BB\u91CD\u4E0A\u9650", hint: "recall \u6BCF\u4F1A\u8BDD\u6700\u591A\u4FDD\u7559 N \u6761\uFF08\u8DE8\u4F1A\u8BDD\u53BB\u91CD\uFF09", kind: "num", min: 1, max: 10 },
   { key: "expireDays", label: "TTL\uFF08\u5929\uFF09", hint: "0 = \u4E0D\u8FC7\u671F", kind: "num", min: 0, max: 3650 },
   { key: "indexMaxChars", label: "\u7D22\u5F15\u5B57\u7B26\u4E0A\u9650", hint: "[ENGRAM] \u5757 token \u9884\u7B97", kind: "num", min: 0, max: 4e3 }

package/lib/index.js

@@ -27,6 +27,8 @@ import { installPreferenceCapture } from "./preference.js";
 import { installBoundaryPrune } from "./boundary-prune.js";
 import { resultPackDir, archivePrunedResults, resultRecallTool, sweepExpired } from "./result-pack.js";
 import { recordBoundaryPruneFire, recordRecallInjection, readPackTelemetry, engramHome } from "./pack-telemetry.js";
+import { createLedger, estimatePrefixChars } from "./ledger.js";
+import { createJit } from "./jit.js";
 import { renderIndex, renderStartRecall, firstUserMessageText, renderEsr, esrMethodology, buildEsrSnapshot, buildFrozenEsrBlock } from "./index-block.js";
 import { makeTriggerRecorder } from "./trigger.js";
 import { pendingTodosFromSession, sinkPendingTodos } from "./todo-sink.js";
@@ -92,9 +94,11 @@ const DEFAULTS = {
   gcStableRetentionDays: 120,
   // Context GC — the auto-GC that REPLACES DSH's built-in lossy LLM-summary
   // compaction (pi-esr CONTEXT_GC): mechanical eviction + re-fetch pointers,
-  // NOT the memory-panel GC above. `gcReplacesCompaction` off → the host keeps
-  // its default compaction backend; `gcNarrative` off → fully mechanical.
-  gcReplacesCompaction: true,
+  // NOT the memory-panel GC above. Opt-in since v0.6: rewriting host presets is
+  // the highest-maintenance action in the plugin (DSH broke the settings API
+  // twice), so the default is the host summarizer; `gcNarrative` off → fully
+  // mechanical. Turn this on to replace compaction with pointer summaries.
+  gcReplacesCompaction: false,
   gcNarrative: true,
   gcNarrativeMaxTokens: 1024,
   gcNarrativeMaxChars: 4000,
@@ -109,6 +113,21 @@ const DEFAULTS = {
   engramIndexOrder: 40,
   esrMethodOrder: 40.5, // static ESR protocol section (byte-identical every turn)
   esrOrder: 41,
+  // Context Ledger (PROPOSAL-evolution §4 v0.6-A): per-session accounting of
+  // injected block chars, pruned/compacted savings and prefix-rewrite penalty.
+  // In-memory + daily rollup at ~/.dsh/engram/ledger.json; never on the hot
+  // path of model calls (one integer add per request). `ledgerCacheDiscount`
+  // is the cached-prefix price share (0.1 = cache hit costs 10%, so a rewrite
+  // costs 90% of the prefix).
+  ledgerEnabled: true,
+  ledgerCacheDiscount: 0.1,
+  // JIT push (v0.6-C): append at most a few one-line, high-precision hints at
+  // deterministic events (error recurrence, file focus, goal completion).
+  // Append-only; every push pays a prefix rewrite in the ledger.
+  jitEnabled: true,
+  jitMaxLines: 3,
+  jitMaxLineChars: 220,
+  engramJitOrder: 40.75,
   // decision-point triggers (P0-A): promote a session plan to an ESR task
   // when the pending-todo count is at least minTodosForPromote and exceeds
   // active ESR tasks × todoPromoteRatio (default: pending > active).
@@ -134,7 +153,8 @@ const DEFAULTS = {
   // validation + idempotent; a preset with a custom compaction layout — or
   // none, like `minimal` — is never touched). Off = every preset keeps DSH's
   // default LLM summarizer; the host plane (headless/TUI/base) is unaffected.
-  autoWebCompaction: true,
+  // Opt-in since v0.6: never rewrite presets unless the user asks.
+  autoWebCompaction: false,
   // Memory-to-memory semantics (zero LLM): when ON, an entity-anchored write
   // that carries a replacement/negation cue ("改用 / no longer / switched…")
   // auto-marks the matching older same-entity+kind memory as superseded.
@@ -145,9 +165,13 @@ const DEFAULTS = {
   // (deterministic surface-replace, zero LLM). L0 simulation (77 sessions):
   // todo-progress boundaries cover 79% of replay exposure; the repayment
   // gate below lifted cache-aware net savings 12–32% on every threshold.
-  // Default OFF (SoL-Pi C13: a dormant mechanism costs nothing); the
-  // pruner service is feature-detected — absent ⇒ disabled with one log.
-  boundaryPrune: false,
+  // Default ON since v0.6 (PROPOSAL-evolution §3.5): `false` is the opt-out;
+  // the pruner service is feature-detected — absent ⇒ disabled with one log.
+  boundaryPrune: true,
+  // Adaptive off-switch (v0.6-B): the Context Ledger vetoes further fires in a
+  // workspace whose own accounting is net negative after real fires. Evidence
+  // can only turn pruning OFF — never on. `false` = repayment gate only.
+  boundaryPruneAdaptive: true,
   // Repayment gate: prune only while the session is expected to run at
   // least this many more requests (empirical workspace prior, see
   // lib/boundary-prune.js). 50 = L0 sweep optimum.
@@ -170,9 +194,10 @@ const DEFAULTS = {
   // append a `[middle archived: result_recall(<callId>) 可取]` handle tail to
   // each pruned node; register `result_recall(callId, offset?)` for paged
   // recall — the full ObservationPack pattern (SoL-Pi mech ③; paired
-  // EdgeBench −23.58%). Requires `boundaryPrune: true` to have anything to
-  // archive (L2 without L1 is a no-op with a log line). Default OFF (C13).
-  resultPack: false,
+  // EdgeBench −23.58%). Requires boundary pruning to have anything to
+  // archive (L2 without L1 is a no-op with a log line). Default ON since v0.6:
+  // default pruning must be lossless (the archive is the recovery path).
+  resultPack: true,
   // result_recall page budget (chars per page). 4000 fits a typical model
   // context band without re-materializing huge results whole.
   resultPackPageChars: 4000,
@@ -304,6 +329,55 @@ export function apply(ctx, config) {
   // todo_write promote hook. Process-local; fed by a tools/result listener.
   const recorder = makeTriggerRecorder(resolved);
 
+  // Context Ledger: created before the service object so /stats can read it.
+  // `ledgerEnabled:false` leaves a null instance (zero listeners, zero writes).
+  const ledger = resolved.ledgerEnabled === false
+    ? null
+    : createLedger({
+      home: engramHome(),
+      cacheDiscount: resolved.ledgerCacheDiscount,
+      log,
+    });
+
+  // Ledger-driven off-switch for BoundaryPrune (PROPOSAL-evolution v0.6-B):
+  // per-workspace, 30s-cached, reads the same summary /stats exposes. Evidence
+  // can only turn pruning OFF. No ledger → allow (repayment gate still runs).
+  const boundaryGate = (() => {
+    const cache = new Map();
+    const TTL_MS = 30_000;
+    return (workspace) => {
+      if (ledger === null) return true;
+      const now = Date.now();
+      const hit = cache.get(workspace);
+      if (hit !== void 0 && now - hit.at < TTL_MS) return hit.ok;
+      let ok = true;
+      try {
+        const summary = ledger.summary();
+        const bucket = summary.byWorkspace[workspace] ?? summary.totals;
+        ok = !(bucket.rewriteCount >= 3 && bucket.netChars < 0);
+      } catch {
+        ok = true; // accounting must never disable the mechanism by accident
+      }
+      if (cache.size > 64) cache.clear();
+      cache.set(workspace, { at: now, ok });
+      return ok;
+    };
+  })();
+
+  // JIT push (v0.6-C): append-only hints, priced through the ledger.
+  const jit = resolved.jitEnabled === false
+    ? null
+    : createJit({
+      maxLines: resolved.jitMaxLines,
+      maxLineChars: resolved.jitMaxLineChars,
+      log,
+      onPush: ({ session, workspace, chars }) => {
+        ledger?.noteRewrite(session?.id, workspace, {
+          chars: estimatePrefixChars(session) + chars,
+        });
+      },
+    });
+
   const service = {
     config: resolved,
     getDomain,
@@ -319,6 +393,10 @@ export function apply(ctx, config) {
     /** SoL-Pi activation telemetry (M15/C13): durable boundary-prune fires +
      *  [RECALL] injection funnel, read at request time (readPackTelemetry). */
     packTelemetry: () => readPackTelemetry({ home: engramHome() }),
+    /** Context Ledger snapshot: spent vs saved context, net of cache rewrites. */
+    ledger: () => (ledger === null ? null : ledger.summary()),
+    /** JIT push counters (per process; /stats diagnostic surface). */
+    jitStats: () => (jit === null ? null : jit.stats()),
     /** Last GC sweep totals (GUI overview observability). */
     gcStats: { lastRun: 0, archivedMemories: 0, archivedTasks: 0, removedLinks: 0 },
     /** Live Context GC status (API overview + durable status file). */
@@ -452,6 +530,7 @@ export function apply(ctx, config) {
     // [RECALL] block.
     if (pendingRecall) return block;
     sessionCache.set(session, block);
+    ledger?.noteInjection(session.id, wk(cwd), "index", block.length);
     return block;
   };
 
@@ -500,9 +579,22 @@ export function apply(ctx, config) {
     } catch (error) {
       log?.warn?.(`engram esr render failed: ${String(error)}`);
     }
+    if (block.length > 0) ledger?.noteInjection(session.id, wk(cwd), "esr", block.length);
     return block;
   };
 
+  // JIT block: append-only lines accumulated by lib/jit.js (never edited).
+  const jitFor = (agent) => {
+    const session = agent?.session;
+    if (session === void 0) return "";
+    const text = jit === null ? "" : jit.textFor(session);
+    const cwd = session.header?.cwd;
+    if (text.length > 0 && typeof cwd === "string" && cwd.length > 0) {
+      ledger?.noteInjection(session.id, wk(cwd), "jit", text.length);
+    }
+    return text;
+  };
+
   ctx.effect(() => {
     const disposers = [];
 
@@ -649,6 +741,18 @@ export function apply(ctx, config) {
       });
       disposers.push(() => indexDispose());
 
+      // JIT push block — empty until a deterministic event fires, then
+      // append-only (prefix changes at most once per push).
+      const jitDispose = systemPrompt.section({
+        name: "engram:jit",
+        order: resolved.engramJitOrder,
+        text: (assemblyContext) => {
+          const agent = assemblyContext?.agent;
+          return agent === void 0 ? "" : jitFor(agent);
+        },
+      });
+      disposers.push(() => jitDispose());
+
       // Static ESR protocol (pi-esr rule 1): byte-identical every turn, so
       // the model never depends on runtime nudges to know WHEN to use ESR.
       const esrMethodDispose = systemPrompt.section({
@@ -677,6 +781,39 @@ export function apply(ctx, config) {
     });
     disposers.push(disposeTrigger);
 
+    // Context Ledger ticks: one model request completed → charge the injected
+    // blocks (held in the prefix) and credit pruned/compacted chars that would
+    // otherwise replay in this request. Session teardown folds the tail into
+    // the daily rollup. Both listeners are no-ops when the ledger is disabled.
+    if (ledger !== null) {
+      const disposeLedgerTick = ctx.on("session/event", (session, event) => {
+        if (event?.type !== "assistant/message") return;
+        ledger.tick(session?.id, wk(session?.header?.cwd));
+      });
+      disposers.push(disposeLedgerTick);
+      const disposeLedgerSession = ctx.on("session/disposed", (session) => {
+        ledger.dispose(session?.id);
+      });
+      disposers.push(disposeLedgerSession);
+    }
+
+    // JIT observers: tool results (error recurrence / file focus) and goal
+    // completion. `opened` may be undefined early — the observers no-op.
+    if (jit !== null) {
+      const disposeJitTool = ctx.on("tools/result", (exec, result) => {
+        jit.observeToolResult(exec, result, opened);
+      });
+      disposers.push(disposeJitTool);
+      const disposeJitEvent = ctx.on("session/event", (session, event) => {
+        jit.observeEvent(session, event, opened);
+      });
+      disposers.push(disposeJitEvent);
+      const disposeJitSession = ctx.on("session/disposed", (session) => {
+        jit.dispose(session?.id);
+      });
+      disposers.push(disposeJitSession);
+    }
+
     // session-end todo auto-sink: a session whose plan still has pending todos
     // lands them as ESR drafts at its teardown edge, so the plan survives the
     // session (flip `autoSinkTodosOnEnd` off to opt out). Live-toggleable — the
@@ -765,14 +902,23 @@ export function apply(ctx, config) {
         // independent of `resultPack`: /stats must be able to prove the L1
         // mechanism actually fires on the live profile.
         onPruned: (session, report, boundary) => {
+          const workspace = wk(session?.header?.cwd);
           recordBoundaryPruneFire({
             home: engramHome(),
             boundary,
             report,
-            workspace: wk(session?.header?.cwd),
+            workspace,
+          });
+          // Ledger: the removed chars stop replaying from the next request;
+          // the prefix invalidation is priced with the pre-prune size (the
+          // surface is already rewritten when this hook runs).
+          const removed = Number.isFinite(report?.charsRemoved) ? report.charsRemoved : 0;
+          const prefixChars = estimatePrefixChars(session);
+          ledger?.notePrune(session?.id, workspace, {
+            charsRemoved: removed,
+            rewriteChars: prefixChars + removed,
           });
           if (resolved.resultPack !== true) return;
-          const workspace = wk(session?.header?.cwd);
           archivePrunedResults({
             dir: l2Dir,
             session,
@@ -781,15 +927,16 @@ export function apply(ctx, config) {
             log,
           });
         },
-      });
+      }, { allowFire: boundaryGate });
       disposers.push(disposeBoundaryPrune);
 
-      // ResultPack L2 tool (default OFF with L1): `result_recall(callId, offset?)`
-      // pages back an archived middle. Independent of the memory domain — the
-      // archive lives on the filesystem. Registers only when enabled; without
-      // boundayPrune there is nothing to archive, so it self-disables.
+      // ResultPack L2 tool (default ON with L1 since v0.6): `result_recall(callId,
+      // offset?)` pages back an archived middle. Independent of the memory
+      // domain — the archive lives on the filesystem. Registers only when
+      // enabled; without boundaryPrune there is nothing to archive, so it
+      // self-disables.
       if (resolved.resultPack === true) {
-        if (resolved.boundaryPrune !== true) {
+        if (resolved.boundaryPrune === false) {
           log?.warn?.("engram result-pack: requires boundaryPrune: true to prune middles — result_recall not registered");
         } else {
           const pageChars = Number.isFinite(resolved.resultPackPageChars)