dsh-boost 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.en.md CHANGED
@@ -11,7 +11,7 @@ read-only substitution**.
11
11
  ## What it does
12
12
 
13
13
  DSH replays the whole history on every model request. Across the 300 longest sessions measured
14
- locally (`npm run --silent stats` — without `--silent`, npm prints its `> dsh-boost@0.1.1 stats`
14
+ locally (`npm run --silent stats` — without `--silent`, npm prints its `> dsh-boost@0.1.2 stats`
15
15
  banner to stdout, so use `--silent` or `node scripts/session-stats.mjs` for machine-readable
16
16
  output; snapshot at `2026-11-19T03:13:21Z`): 54,141 steps and 54,088 requests,
17
17
  10,575,904,022 raw tokens in total. The mean is 195,340 tokens per step and 195,531 per request
@@ -50,11 +50,14 @@ The **ex-ante estimate** for v1 is **3.5% (lower bound) to 10.0% (ideal upper bo
50
50
  300-session corpus, and its substitution component (2.70%) is a **ceiling** that must not be
51
51
  counted as a floor. The honest net floor is about **0.4%** (projection gross ~0.8% minus ~0.4%
52
52
  fixed per-request overhead). It is not a guarantee, and not a figure the shipped
53
- `session-snapshot.json` can recompute (the snapshot stores aggregate counts only, not the
54
- components of the estimate) — **nothing in the deliverable can recompute it**. Nor can the shadow
55
- week turn the range into a measured percentage: the shadow report outputs four ratios only (see
56
- "Shadow week"), with no total-token denominator, and `boost status` carries absolute values only;
57
- replacing the range with measurements needs a denominator statistic that a later version must add.
53
+ `session-snapshot.json` can recompute: the snapshot stores per-session aggregates plus each
54
+ session's `requestTokens` / `receiptChars` arrays, `valueTransfer` / `whitelist` counts, and
55
+ its per-family `toolChars` totals, but it has **no per-receipt family bytes** — the projection
56
+ components the estimate needs cannot be assembled from it, so **nothing in the deliverable can
57
+ recompute it**. Nor can the shadow week turn the range into a measured percentage: the shadow
58
+ report outputs four ratios only (see "Shadow week"), with no total-token denominator, and
59
+ `boost status` carries absolute values only; replacing the range with measurements needs a
60
+ denominator statistic that a later version must add.
58
61
 
59
62
  ## Requirements
60
63
 
@@ -77,28 +80,29 @@ replacing the range with measurements needs a denominator statistic that a later
77
80
  directory:
78
81
 
79
82
  ```bash
80
- # install from the registry: npmjs has latest = 0.1.1 (this repository's
83
+ # install from the registry: npmjs has latest = 0.1.2 (this repository's
81
84
  # .npmrc and lockfile are pinned to npmjs too — see below)
82
- dsh plugin --profile <name> add dsh-boost@^0.1.1 --registry=https://registry.npmjs.org/
85
+ dsh plugin --profile <name> add dsh-boost@^0.1.2 --registry=https://registry.npmjs.org/
83
86
 
84
87
  # or from a local checkout (build first; dist/ is not committed)
85
88
  npm run build
86
89
  dsh plugin --profile <name> add /absolute/path/to/dsh-boost
87
90
  ```
88
91
 
89
- For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.1 --registry=https://registry.npmjs.org/`.
92
+ For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.2 --registry=https://registry.npmjs.org/`.
90
93
  `dsh plugin` forwards the operation to pnpm, so pnpm must be on `PATH`.
91
94
 
92
- > **The two registries carry different versions, so `^0.1.0` is not a safe pin.**
93
- > `registry.npmjs.org` has three version records: `0.1.1` (current `latest`), `0.1.0`, and
94
- > `0.0.0-stage`, a placeholder npm creates on a package's first publish. The
95
- > `registry.npmmirror.com` currently has only `0.1.0` (its `latest` is 0.1.0 too) — this
96
- > repository's `.npmrc` and lockfile are pinned to npmjs, but your global npm config may not be.
97
- > The same `^0.1.0` therefore resolves to 0.1.1 on npmjs and to 0.1.0 on
98
- > the mirror — and a mirror user installs a build missing ten of 0.1.1's fixes, several of which
99
- > repair silent failures. Use `dsh-boost@^0.1.1` (or `@latest`), and pass
100
- > `--registry=https://registry.npmjs.org/` explicitly when the registry matters; while the mirror
101
- > has not synced 0.1.1, `@^0.1.1` without that flag fails to resolve.
95
+ > **Both registries now carry 0.1.2, so `^0.1.2` is a safe pin.**
96
+ > `registry.npmjs.org` and `registry.npmmirror.com` each have four version records: `0.1.2` (the
97
+ > current `latest` on both), `0.1.1`, `0.1.0`, and `0.0.0-stage`, the placeholder npm creates on a
98
+ > package's first publish — **do not install `0.0.0-stage`**; it is not a usable build. 0.1.2
99
+ > carries the scope-overwrite fix: corrupt JSON (including a non-object or an array) and an
100
+ > unrecognizable version are no longer silently overwritten with the default document. Use
101
+ > `dsh-boost@^0.1.2` (or `@latest`). This repository's `.npmrc` and lockfile are pinned to npmjs,
102
+ > but **your machine's global npm config** may still point at a mirror that has not synced 0.1.2:
103
+ > that is local configuration, not this repository's state. Pass
104
+ > `--registry=https://registry.npmjs.org/` explicitly when the registry matters; against a lagging
105
+ > mirror, `@^0.1.2` fails to resolve until the sync lands.
102
106
 
103
107
  The package is ESM (`"type": "module"`) and the `.` entry of `exports` also maps `require` /
104
108
  `default`: on Node >= 24.9, `require('dsh-boost')` loads the very same code as `import`. Nothing
@@ -131,8 +135,8 @@ equivalent. In the conversation, ask the agent to call it, for example:
131
135
  > Call the boost tool with `{"cmd":"status"}` and show me the JSON.
132
136
 
133
137
  The first `status` should answer `ok: true`, with `data.scope.workspaceIds` empty, `revision` `0`,
134
- `shadow` `true`, `projection` `"shadow"`, and `counts` empty (in a fresh session — any earlier tool
135
- call from an out-of-scope session has already recorded `skip:no-scope`). The first `status` does
138
+ `shadow` `true`, `projection` `"shadow"`, and `counts` empty (only on a fresh receipt root — `scan()` reads every shard, so earlier out-of-scope
139
+ calls from other sessions in the same DSH home have already recorded `skip:no-scope`). The first `status` does
136
140
  **not** report `ERR_SCOPE_READ_FAILED` merely because `scope.json` is missing: a missing file is
137
141
  the clean default (`ENOENT` carries no degradation code, `src/scope/store.ts`); on a fresh root
138
142
  with the host capabilities in place, `degraded` is simply an empty array. On the `status` read
@@ -184,7 +188,7 @@ After the write, call `status` again. A healthy result looks like this:
184
188
  `"host"` because the token-meter service is present — the two are different things.
185
189
  - `data.counts` usually starts empty — but **control calls count too**: while no workspace is
186
190
  visible, `boost`'s own calls pass the same post-execute scope gate (there is no boost exemption
187
- there; the exemption lives at tool registration), each recording one `skip:no-scope`. It grows
191
+ there; the exemption lives at tool registration), each recording one `skip:no-scope` — except PTC inner calls (`exec.parent` set) and cancelled calls, which return before the scope gate and record nothing. It grows
188
192
  after normal tool calls, for example with `projection-shadow` entries.
189
193
 
190
194
  Excerpt (illustrative values; ledger fields omitted):
@@ -223,10 +227,12 @@ above a workspace is selected, so 778 is the true per-request cost there.
223
227
 
224
228
  The design chose **shadow first**: record for a week — no synthesized turns, no skipped calls,
225
229
  projection priced but never applied — then decide whether to project and substitute for real.
226
- **"Changes nothing the model sees" would be false**: whenever a workspace is visible the protocol
227
- section (379 tokens) is injected into the system prompt, and a multi-candidate plan still makes a
228
- **real selector call** (a separate auxiliary model request). By design the shadow week saves
229
- nothing; it produces only the four ratios below.
230
+ **"Changes nothing the model sees" would be false**: the `boost` tool schema (399 tokens) is
231
+ registered whenever the plugin is assembled, and whenever a workspace is visible the protocol
232
+ section (379 tokens) is also injected into the system prompt — **778 per request** in the
233
+ recommended setup; a multi-candidate plan still makes a **real selector call** (a separate
234
+ auxiliary model request). The shadow week saves no tokens; it produces only the four ratios below.
235
+ Under `selected + []` the protocol section is empty and the fixed cost is still **399**.
230
236
 
231
237
  Of those ratios, `saveableRatio`, `byFamily`, and `candidateRecall` can decide **whether the
232
238
  substitution side is worth turning on**: how many substitution decisions the whitelist could
@@ -237,8 +243,12 @@ a normal release and does not gate on shadow-week savings — and that call was
237
243
  period; they did not rule on whether shadow results should gate a release. They also **cannot measure savings**: the report has no total-token denominator, and
238
244
  `retrievalUpperBound` is structurally `0` during the shadow week (it only counts applied
239
245
  `projection:'on'` retrievals), so it cannot even bound projection's retrieval damage. Projection
240
- is released on the visibility contract (the original stays retrievable through the footer) and
241
- post-hoc detection, not on shadow labels.
246
+ is released on the visibility contract alone (the original stays retrievable through the footer),
247
+ not on shadow labels — and **not on post-hoc detection**: v1 has no mis-truncation detector.
248
+ `src/admission/retrieval.ts` only counts exact-locator retrievals, and design §6.1 itself records
249
+ that the damage metric was never delivered and that retrieval counts are not a damage bound. The
250
+ only guard is that the model can retrieve the original; a retrieval being attempted is a signal,
251
+ not proof that nothing was wrongly cut.
242
252
  `scope.json` has two independent switches:
243
253
 
244
254
  | Switch | Value | Behaviour |
@@ -265,7 +275,8 @@ The recommended sequence:
265
275
  (recall of the candidate set), and `retrievalUpperBound` (retrieval upper bound; structurally
266
276
  `0` during the shadow week because nothing is projected for real).
267
277
  3. **Turn on projection**: projection is not released on shadow labels (its basis is the
268
- visibility contract and post-hoc detection); once the host spill backend is available, keep
278
+ visibility contract — the original stays retrievable through the footer; v1 has no
279
+ mis-truncation detector); once the host spill backend is available, keep
269
280
  `shadow: true` and set `projection` to `'on'`:
270
281
 
271
282
  ```json
@@ -431,12 +442,23 @@ in effect (the minimum over live sessions, falling back to `horizonSteps` when n
431
442
  - `projection_unknown_families`: calls carrying an `mcp__` prefix that reached projection but
432
443
  matched no tool family; `projection_unknown_tools` is the retained unmapped tool names with
433
444
  counts (at most 32), for spotting mapper gaps.
434
- - `hasWorkspaceRegistry`: whether the host currently offers `workspaceRegistry`. The key is
435
- **omitted** when nothing was probed — it is not `false`.
436
- - `saved`: a camelCase ledger object for older consumers (`substitution` / `projectionGross` /
437
- `projectionNet` / `retrievals`), derived from the same aggregation as the top-level snake_case
438
- fields. A projection receipt written before T23b has no `saved_projection_tokens` and is priced
439
- from its legacy `saved` field instead.
445
+ - `hasWorkspaceRegistry`: whether the host **provides** `workspaceRegistry` (also presence). The
446
+ production assembly always supplies the key, so it is **always boolean**: no service is `false` +
447
+ `ERR_HOST_NO_WORKSPACE_REGISTRY`; a service whose `list()` throws is `true` +
448
+ `ERR_HOST_WORKSPACE_REGISTRY_BROKEN`. Both leave every session invisible, but they are fixed
449
+ differently. The key is omitted only when `boost` is constructed directly with no host facts.
450
+ - `hasSpill`: whether the host **provides** a spill backend (presence, not usability). A missing
451
+ service is `false` + `ERR_HOST_NO_SPILL`; a service without `saveText` keeps it **`true`** and puts
452
+ `ERR_HOST_SPILL_UNUSABLE` in `degraded` — the capability fact lives in `degraded`, not in this boolean.
453
+ - `saved`: the camelCase ledger object kept for older consumers (`substitution` /
454
+ `substitutionAvoided` / `projectionGross` / `projectionNet` / `retrievals`), derived from the same
455
+ aggregation as the top-level snake_case fields. Legacy projection receipts (pre-T23b) without
456
+ `saved_projection_tokens` fall back to the receipt's own `saved` field.
457
+ **The two substitution numbers are a range, not the same quantity.** `substitution` takes the
458
+ input of the *next* real request after the skipped one — it includes the substituted call's own
459
+ result, so it is an **upper bound**. `substitutionAvoided` takes the planning request's
460
+ `input + cacheRead + output` — it excludes that result, so it is a **lower bound**. The true
461
+ saving lies between them.
440
462
 
441
463
  With `projection: 'on'`, the complete original is written to the host spill backend **before** the
442
464
  replacement happens, and the footer locator can be read with `read` / `grep`. Projection never
@@ -542,11 +564,15 @@ evidence" degraded path would be unreachable.
542
564
  v1 ships **no tool that measures duplicate-call rate**: the "shadow-week duplication
543
565
  statistic" the design reserved as its restart trigger was never delivered; `shadow-report.mjs`
544
566
  does not produce it.
545
- - **The shadow week saves nothing by design**: it only records (the protocol section is still
546
- injected and the selector is still called); its output is four ratios, not saved tokens.
567
+ - **The shadow week saves no tokens**: it only records (the protocol section is still injected
568
+ and the selector is still called), and the recommended setup still costs 778 per request
569
+ (`selected + []` costs 399); its output is four ratios, not saved tokens.
547
570
  - **v1 does not judge "better results"**: there is a token ledger and a **manual** 20-task
548
571
  regression procedure (the task set does not ship with the package; see `docs/RELEASE.md` §3),
549
- no quality metric; whether substituted outcomes are better is unjudgeable in v1.
572
+ no quality metric; whether substituted outcomes are better is unjudgeable in v1. The procedure
573
+ itself is not fully delivered either: neither the smoke runner (`test/regression/run.mjs`) nor
574
+ the same section's locator-retrieval integrity check exists, and `test/regression/` holds only
575
+ `.gitkeep` — so the "no data loss" invariant in its pass predicate is **unverified** in v1.
550
576
  - **Projection is truncation, not refinement**: it keeps the head and tail and drops the middle;
551
577
  the before/after token difference in the ledger measures *shorter*, not *more relevant*. The
552
578
  dropped middle may be exactly what the next decision needs — with `projection: 'on'` the
@@ -582,7 +608,7 @@ The source and docs live in the repository at
582
608
  | [Design](docs/superpowers/specs/2026-11-18-dsh-token-efficiency-design.md) | Goals, evidence, architecture, contracts, measurement, risks, release shape |
583
609
  | [Host contracts appendix](docs/superpowers/plans/2026-11-18-host-contracts.md) | Interface reference copied line by line from the host sources |
584
610
  | [Three-tier delegation research](docs/research/2026-11-18-three-tier-delegation.md) | 25 primary sources on caching, routing thresholds, compression, and verification |
585
- | [Release acceptance](docs/RELEASE.md) | The one-command `npm run verify:package` acceptance, the zero-peerDependencies state and install spec, the degradation-code matrix, the 20-task regression procedure (manual; the task set does not ship), and the shadow week and stats recompute |
611
+ | [Release acceptance](docs/RELEASE.md) | The one-command `npm run verify:package` acceptance, the zero-peerDependencies state and install spec, the degradation-code matrix, the 20-task regression procedure (manual; the task set, runner, and locator-retrieval integrity check all remain undelivered), and the shadow week and stats recompute |
586
612
 
587
613
  ## License
588
614
 
package/README.md CHANGED
@@ -8,7 +8,7 @@
8
8
  ## 它解决什么
9
9
 
10
10
  DSH 每次模型请求都会回放全部历史。本机 300 个最长会话的实测聚合(`npm run --silent stats`——不带
11
- `--silent` 时 npm 会把 `> dsh-boost@0.1.1 stats` 横幅打进 stdout,机器解析请用 `--silent` 或直接
11
+ `--silent` 时 npm 会把 `> dsh-boost@0.1.2 stats` 横幅打进 stdout,机器解析请用 `--silent` 或直接
12
12
  `node scripts/session-stats.mjs`;快照时刻 `2026-11-19T03:13:21Z`):54,141 步、54,088 个请求,合计 10,575,904,022 raw token。按步均值
13
13
  195,340 token,按请求均值 195,531、中位 187,681;97.01% 的输入是缓存读。工具回执是体积主体
14
14
  (bash 61.75%、read 22.13%、ssh 10.01%),而下一步真正会用到的部分通常远小于回执本身。
@@ -36,7 +36,9 @@ v1 的**事前估算**区间是 **3.5%(下界)– 10.0%(理想上界)**
36
36
  **3.5% 不是保底**——它是设计阶段对一个 300 会话语料做离线估算得到的下界,其中替换账的
37
37
  2.70% 是**上限**,不能算进保底;诚实的净保底只有约 **0.4%**(投影侧毛额约 0.8% 减去每请求
38
38
  固定开销约 0.4%)。这个区间不是保证,也不是从交付的 `session-snapshot.json` 能复算出来的
39
- 数字(快照只存聚合计数,没有估算用的分项)——交付物里**没有任何工具能复算它**。影子周也
39
+ 数字:快照按会话存了聚合计数,也存了每个会话的 `requestTokens` / `receiptChars` 数组、
40
+ `valueTransfer` / `whitelist` 计数,以及该会话按工具族归因的 `toolChars` 字符总量,但
41
+ **没有逐回执的族别字节**,估算所需的投影分项仍然凑不出来——交付物里**没有任何工具能复算它**。影子周也
40
42
  **不能**把这个区间变成实测百分比:影子报告只输出四个比例(见「影子周」一节),没有总 token
41
43
  分母,`boost status` 也只有绝对值;区间要被实测取代,得等后续版本补上分母统计。
42
44
 
@@ -58,26 +60,26 @@ v1 的**事前估算**区间是 **3.5%(下界)– 10.0%(理想上界)**
58
60
  `dsh plugin` 要求指定 profile,剩下的参数原样转发给该 profile 目录里的 pnpm:
59
61
 
60
62
  ```bash
61
- # 从 registry 安装:npmjs 上的 latest 是 0.1.1(本仓库 .npmrc 与 lockfile
63
+ # 从 registry 安装:npmjs 上的 latest 是 0.1.2(本仓库 .npmrc 与 lockfile
62
64
  # 也已钉在 npmjs,见下)
63
- dsh plugin --profile <name> add dsh-boost@^0.1.1 --registry=https://registry.npmjs.org/
65
+ dsh plugin --profile <name> add dsh-boost@^0.1.2 --registry=https://registry.npmjs.org/
64
66
 
65
67
  # 或从本地 checkout 安装(先构建;dist/ 不入库)
66
68
  npm run build
67
69
  dsh plugin --profile <name> add /absolute/path/to/dsh-boost
68
70
  ```
69
71
 
70
- 例如 web profile:`dsh plugin --profile web add dsh-boost@^0.1.1 --registry=https://registry.npmjs.org/`。
72
+ 例如 web profile:`dsh plugin --profile web add dsh-boost@^0.1.2 --registry=https://registry.npmjs.org/`。
71
73
  `dsh plugin` 把操作转发给 pnpm,所以 pnpm 必须在 PATH 上。
72
74
 
73
- > **两个 registry 的版本不同,`^0.1.0` 不是安全的钉法。** `registry.npmjs.org` 上有三条版本记录:
74
- > `0.1.1`(当前 `latest`)、`0.1.0`,以及首次发布时 npm 自动创建的占位版本 `0.0.0-stage`。而
75
- > `registry.npmmirror.com` 目前只有 `0.1.0`(它的 `latest` 也是 0.1.0)——本仓库已把 `.npmrc`
76
- > 与 lockfile 改钉 npmjs,但你机器上的全局 npm 配置可能仍指向镜像。同一个
77
- > `^0.1.0` 在 npmjs 解析到 0.1.1、在镜像解析到 0.1.0——镜像用户会装到缺少 0.1.1 十项修复的
78
- > 构建,其中几项是静默失效修复。请用 `dsh-boost@^0.1.1`(或 `@latest`),并在意 registry 时
79
- > 显式传 `--registry=https://registry.npmjs.org/`;镜像尚未同步 0.1.1 时,不带该 flag 的
80
- > `@^0.1.1` 会解析失败。
75
+ > **两个 registry 现在都到 0.1.2,`^0.1.2` 是安全的钉法。** `registry.npmjs.org` 与
76
+ > `registry.npmmirror.com` 各有四条版本记录:`0.1.2`(两边都是当前 `latest`)、`0.1.1`、
77
+ > `0.1.0`,以及首次发布时 npm 自动创建的占位版本 `0.0.0-stage`——**不要安装 `0.0.0-stage`**,
78
+ > 它不是可用构建。0.1.2 修掉了 scope 文件被静默覆盖的问题:坏 JSON(含非对象或数组)与
79
+ > 无法识别的版本不再被默认文档覆盖。请用 `dsh-boost@^0.1.2`(或 `@latest`)。本仓库已把 `.npmrc`
80
+ > 与 lockfile 钉在 npmjs,但**你机器上的全局 npm 配置**可能仍指向一个尚未同步 0.1.2 的镜像:
81
+ > 那是本机配置,不是本仓库的状态。在意 registry 时显式传
82
+ > `--registry=https://registry.npmjs.org/`;镜像滞后时,`@^0.1.2` 会在同步前解析失败。
81
83
 
82
84
  包是 ESM(`"type": "module"`),`exports` 的 `.` 条目同时映射 `require` / `default`:Node ≥ 24.9
83
85
  下 `require('dsh-boost')` 与 `import` 加载同一份代码,装好的包里**不做任何构建**(`files` 只带
@@ -97,7 +99,7 @@ bundle,patch 的 `insert` 行落在 profile root 上。**装完必须重启 DS
97
99
  ```
98
100
 
99
101
  `workspaceIds` 为空时没有可见工作区:协议段不注入,投影与替换都原样放行,但每个工具调用
100
- 仍会记一条 `skip:no-scope` 收据。`boost` 工具本身是唯一的 scope 豁免,因此没有工作区时仍然
102
+ 仍会记一条 `skip:no-scope` 收据——但 PTC 内层调用(`exec.parent` 存在)与被取消的调用在 scope 门之前就返回,两条都不记。`boost` 工具本身是唯一的 scope 豁免,因此没有工作区时仍然
101
103
  可以调用它来启用。
102
104
 
103
105
  `boost` 是**模型工具,不是 shell 命令**——这个包没有 `bin`,启用全程都要在对话里让模型调用
@@ -106,8 +108,8 @@ bundle,patch 的 `insert` 行落在 profile root 上。**装完必须重启 DS
106
108
  > 调用 boost 工具,参数 `{"cmd":"status"}`,把 JSON 结果给我。
107
109
 
108
110
  首次 `status` 应看到 `ok: true`;`data.scope.workspaceIds` 为空、`revision` 为 `0`,`shadow` 为
109
- `true`、`projection` 为 `"shadow"`,`counts` 为空(**仅限全新会话**——越界会话更早的工具调用
110
- 已经各记过一条 `skip:no-scope`)。首次 `status` 的 `degraded` 里**不会**因为 `scope.json`
111
+ `true`、`projection` 为 `"shadow"`,`counts` 为空(**仅限全新回执根**——`scan()` 读全部分片,同一 DSH home 里别的会话早先的
112
+ 越界调用已经各记过一条 `skip:no-scope`)。首次 `status` 的 `degraded` 里**不会**因为 `scope.json`
111
113
  缺失而出现 `ERR_SCOPE_READ_FAILED`:缺失是干净的默认值(`ENOENT` 不带降级码,
112
114
  `src/scope/store.ts`);全新根目录且宿主能力齐全时,`degraded` 就是空数组。在 `status` 的
113
115
  读取路径上,`ERR_SCOPE_READ_FAILED` 只表示文件**存在但读不出来**(权限、I/O、路径是目录
@@ -187,9 +189,10 @@ scope**:`boost` 工具 schema(399)只要插件装配就常驻——`boost`
187
189
  ## 影子周
188
190
 
189
191
  设计选择**影子优先**:先用一周只记账(不合成回合、不跳过调用,投影只记账不改内容),再决定
190
- 是否真的投影与替换。**「什么都不改」并不成立**:只要有可见工作区,协议段(379 token)就会
191
- 注入系统提示;多候选计划仍会**真实调用一次选择器**(一次独立的辅助模型请求)。影子周按设计
192
- 零节省,它只产出下一节的四个比例。
192
+ 是否真的投影与替换。**「什么都不改」并不成立**:`boost` 工具 schema(399 token)只要插件装配
193
+ 就常驻;只要有可见工作区,协议段(379 token)还会注入系统提示——推荐配置下每请求固定成本
194
+ **778**;多候选计划仍会**真实调用一次选择器**(一次独立的辅助模型请求)。影子周不省任何
195
+ token,它只产出下一节的四个比例;`selected + []` 下协议段为空,固定成本仍有 **399**。
193
196
 
194
197
  其中 `saveableRatio`、`byFamily`、`candidateRecall` 能决定的是**替换侧是否值得打开**:
195
198
  白名单能兑现多少替换决策、命中落在哪些工具族、候选集召回多高——也就是替换打开后会不会
@@ -197,8 +200,10 @@ scope**:`boost` 工具 schema(399)只要插件装配就常驻——`boost`
197
200
  门;这个决定是**实现者在设计阶段做的,不是用户裁决**——用户只接受了为期一周的影子期,没有
198
201
  裁定影子结果是否该当发布门。它们也**不能测出节省**:报告没有总 token 分母,
199
202
  `retrievalUpperBound` 在影子期结构性为 `0`(它只统计 `projection:'on'` 的已应用投影取回),
200
- 连投影的取回损害都约束不了;投影的放行依据是可见性契约(原文可经页脚取回)与事后检测,
201
- 不是影子标签。
203
+ 连投影的取回损害都约束不了。投影的放行依据只有可见性契约(原文可经页脚取回),不是影子
204
+ 标签,也**不是事后检测**:v1 没有误截检测器——`src/admission/retrieval.ts` 只按精确 locator
205
+ 统计取回次数,设计稿 §6.1 也写明损害度量未交付、取回计数不是损害上界。唯一的护栏是模型
206
+ 能取回原文;而「发生过取回」只是信号,不是「没有误截」的证明。
202
207
  `scope.json` 里有两个独立开关:
203
208
 
204
209
  | 开关 | 取值 | 行为 |
@@ -220,8 +225,8 @@ scope**:`boost` 工具 schema(399)只要插件装配就常驻——`boost`
220
225
  是每一次替换决策,不只是白名单调用;影子期全族记账,bash/ssh 的潜力看 `byFamily`)、`byFamily`(按候选工具族的命中率)、
221
226
  `candidateRecall`(候选集召回)、`retrievalUpperBound`(取回率上界;影子期没有真正投影,
222
227
  结构上恒为 `0`)。
223
- 3. **打开投影**:投影的放行不靠影子标签(依据是可见性契约与事后检测),确认宿主 spill
224
- 后端可用后,保持 `shadow: true`,把 `projection` 改成 `'on'`:
228
+ 3. **打开投影**:投影的放行不靠影子标签(依据是可见性契约:原文可经页脚取回;v1 没有
229
+ 误截检测器),确认宿主 spill 后端可用后,保持 `shadow: true`,把 `projection` 改成 `'on'`:
225
230
 
226
231
  ```json
227
232
  { "cmd": "scope-set", "body": { "projection": "on" }, "baseRevision": 1 }
@@ -272,7 +277,7 @@ scope**:`boost` 工具 schema(399)只要插件装配就常驻——`boost`
272
277
  不变量不是 `triggerChars ≥ headChars + tailChars + 1`。真实替换串是 head line + head + 页脚 +
273
278
  tail + 3 个换行;页脚由宿主 `formatSpillNotice` 生成:68 字符 locator 加宿主固定的 66 字符
274
279
  retrieval hint 下,3 位省略字节数是 190 字符,5 位是 192 字符。grep/glob 默认 400+100 时:
275
- `400 + 100 + 50(head line) + 190(页脚) + 3 = 743 > 700`(5 位计数则是 745)。于是刚过 700、
280
+ `400 + 100 + 50(head line) + 190(页脚) + 3 = 743 > 700`(5 位计数时页脚 192、head line 里的数字也各长一位,实测 747–749)。于是刚过 700、
276
281
  约 743 以下的回执会被 `truncate` 判定“可裁”,但 `projectApply` 组装后并不短于原文,直接返回
277
282
  原文——这是死区,不是净亏。运行时的 `assembled.length >= text.length` 检查保证投影绝不会让
278
283
  回执变长;要消除死区,把 `triggerChars` 提到至少这个和(例如 grep/glob 用 800),或缩小窗口。
@@ -366,11 +371,19 @@ horizon 重放,并计入 `projection_horizon_reestimated`;`projection_horizo
366
371
  - `projection_unknown_families`:带 `mcp__` 前缀、进入投影阶段但没有匹配到工具族的调用数;
367
372
  `projection_unknown_tools` 是其中保留的未映射工具名及次数(最多 32 个),用来发现 mapper
368
373
  缺口。
369
- - `hasWorkspaceRegistry`:宿主当前是否提供 `workspaceRegistry`;没有探测到时该键**省略**,
370
- 不是 `false`。
371
- - `saved`:兼容旧消费者的 camelCase 账目对象(`substitution` / `projectionGross` /
372
- `projectionNet` / `retrievals`),与顶层 snake_case 字段由同一次聚合派生。旧投影收据
373
- (pre-T23b)没有 `saved_projection_tokens` 时,按收据里的 legacy `saved` 字段回退计价。
374
+ - `hasWorkspaceRegistry`:宿主是否**提供** `workspaceRegistry`(同样是存在性)。生产装配总是传入
375
+ 这个键,所以它**总是布尔**:宿主没有该服务是 `false` + `ERR_HOST_NO_WORKSPACE_REGISTRY`;服务在但
376
+ `list()` 抛错是 `true` + `ERR_HOST_WORKSPACE_REGISTRY_BROKEN`——两种都让每个会话被判不可见,但
377
+ 修法不同。只有直接构造 `boost` 依赖、完全不给宿主事实时该键才省略(测试场景)。
378
+ - `hasSpill`:宿主是否**提供** spill 后端(存在性,不是可用性)。服务缺失是 `false` +
379
+ `ERR_HOST_NO_SPILL`;服务在但不提供 `saveText` 时它**仍是 `true`**,同时 `degraded` 带
380
+ `ERR_HOST_SPILL_UNUSABLE`——能力事实在 `degraded` 里,不在这个布尔里。
381
+ - `saved`:兼容旧消费者的 camelCase 账目对象(`substitution` / `substitutionAvoided` /
382
+ `projectionGross` / `projectionNet` / `retrievals`),与顶层 snake_case 字段由同一次聚合派生。
383
+ 旧投影收据(pre-T23b)没有 `saved_projection_tokens` 时,按收据里的 legacy `saved` 字段回退计价。
384
+ **两个替换数是一对区间,不是同一个量**:`substitution` 取被跳过请求的**下一**个真实请求的输入
385
+ (含被替换调用自己的结果,所以是**上界**);`substitutionAvoided` 取计划那一次请求的
386
+ `input + cacheRead + output`(不含被替换调用的结果,所以是**下界**)。真实节省落在两者之间。
374
387
 
375
388
  `projection: 'on'` 时,完整原文在替换发生**之前**写入宿主的 spill 后端,页脚 locator 可以用
376
389
  `read` / `grep` 取回。投影不会丢掉唯一副本;spill 写入失败就不替换(收据记
@@ -407,7 +420,7 @@ horizon 重放,并计入 `projection_horizon_reestimated`;`projection_horizo
407
420
 
408
421
  ## 宿主依赖
409
422
 
410
- `inject` 是硬依赖:`tools`、`systemPrompt`——缺任一,插件加载失败。`llm` 是软依赖(只有
423
+ `inject` 是硬依赖:`tools`、`systemPrompt`——缺任一,cordis 让插件停在 pending、不 apply(不是抛错,但对使用者而言效果相同:插件不工作)。`llm` 是软依赖(只有
411
424
  选择器用),缺失时选择器以 `selector-unavailable` 退回,投影与替换的其余部分照常。
412
425
 
413
426
  | 依赖 | 形态 | 缺失时 |
@@ -457,10 +470,12 @@ spill,报它只会制造噪音);但**收据通道**不看当前模式—
457
470
  - **不去重、不合并工具调用**(设计 N5)——这条完全没开工,且 v1 **没有任何工具能测出重复
458
471
  调用率**:设计稿里用来触发重启判定的「影子周重复率统计」没有交付,`shadow-report.mjs`
459
472
  不产出它。
460
- - **影子周按设计零节省**:只记账(协议段照注入、选择器照调用),它的产出是四个比例,
461
- 不是省下的 token。
462
- - **v1 不评判「结果更好」**:只有 token 账目和一套**人工**的 20 任务回退流程(任务集不随包发布,见 `docs/RELEASE.md` §3),没有任何质量指标;「替换后
463
- 结果质量」在 v1 是不可判的。
473
+ - **影子周不省 token**:只记账(协议段照注入、选择器照调用),推荐配置下每请求仍固定花
474
+ 778(`selected + []` 为 399);它的产出是四个比例,不是省下的 token。
475
+ - **v1 不评判「结果更好」**:只有 token 账目和一套**人工**的 20 任务回退流程(任务集不随包发布,
476
+ 见 `docs/RELEASE.md` §3),没有任何质量指标;「替换后结果质量」在 v1 是不可判的。这套流程
477
+ 本身也没交付完整:冒烟 runner(`test/regression/run.mjs`)与同一节的取回完整性检查都未实现,
478
+ `test/regression/` 只有 `.gitkeep`,因此 pass 谓词里的「无数据丢失」不变量在 v1 **未经核实**。
464
479
  - **投影是截断,不是精炼**:它保留头尾、丢掉中段;账本里的 before/after token 差量的是
465
480
  「变短」,不是「变相关」。被丢掉的中段可能正是下一步决策要用的内容——`projection: 'on'`
466
481
  下原文可经页脚 locator 取回,但取回要花一次工具调用,且 v1 没有指标区分「精炼」与
@@ -490,7 +505,7 @@ spill,报它只会制造噪音);但**收据通道**不看当前模式—
490
505
  | [设计稿](docs/superpowers/specs/2026-11-18-dsh-token-efficiency-design.md) | 目标、证据、架构、契约、度量、风险、发布形态 |
491
506
  | [宿主契约附录](docs/superpowers/plans/2026-11-18-host-contracts.md) | 逐条抄自宿主源码的接口准绳 |
492
507
  | [三层委派研究](docs/research/2026-11-18-three-tier-delegation.md) | 缓存、路由阈值、压缩、校验的 25 条一手来源 |
493
- | [发布验收](docs/RELEASE.md) | `npm run verify:package` 一条命令验收、零 peerDependencies 现状与安装规格、降级码矩阵、20 任务回退流程(人工,任务集不随包发布)、影子周与统计复算 |
508
+ | [发布验收](docs/RELEASE.md) | `npm run verify:package` 一条命令验收、零 peerDependencies 现状与安装规格、降级码矩阵、20 任务回退流程(人工;任务集、runner 与取回完整性检查均未交付)、影子周与统计复算 |
494
509
 
495
510
  ## 许可证
496
511
 
@@ -9,6 +9,14 @@
9
9
  * next request is `'unknown'`; an interpolated number would be indistinguishable
10
10
  * from a measurement once written to a receipt.
11
11
  *
12
+ * That next request is not the avoided request: it also carries the executed
13
+ * call and its result, which the avoided request would not have seen. So
14
+ * `saved_input_tokens` is an **upper** estimate. `settle()` therefore also
15
+ * reports `avoided_total_tokens = before.input + before.cacheRead +
16
+ * before.output` — the whole request that produced the plan, which the avoided
17
+ * request would have carried (plus the plan) — as a **lower** estimate. Each
18
+ * side is `'unknown'` from its own sample, never a copy of the other's.
19
+ *
12
20
  * The ledger keeps two request slots plus a mark: `latest`, the first request
13
21
  * after the mark, and the mark itself — which holds the request that preceded
14
22
  * it and the candidate id. No whole-history table (YAGNI). Pure arithmetic: no
@@ -91,12 +99,25 @@ export class UsageLedger {
91
99
  /**
92
100
  * Consume the mark and report the substitution's measured cost.
93
101
  *
94
- * `saved_input_tokens` is the first after-mark request's `input + cacheRead`;
95
- * `output_tokens` is that request's `output`, a third count that is never
96
- * folded into input. Both are `'unknown'` when no usable request arrived after
97
- * the mark — never a copy of the previous request's numbers. `cache_hit_delta`
98
- * is the after-mark hit rate minus the pre-mark hit rate, `null` when either
99
- * side cannot be told (a `null` delta means "cannot tell", not zero).
102
+ * Two estimates of the avoided request, from the same pair of samples:
103
+ *
104
+ * - `saved_input_tokens` is the first after-mark request's `input +
105
+ * cacheRead`. That request is the next real one, so its input also carries
106
+ * the executed call and its result — tokens the avoided request would never
107
+ * have seen. It is therefore the **upper** estimate of the avoided input,
108
+ * and the plugin's headline number.
109
+ * - `avoided_total_tokens` is the pre-mark request's `input + cacheRead +
110
+ * output`: the whole request that produced the plan. The avoided request
111
+ * would have carried that request's context plus the plan, so this is a
112
+ * **lower** estimate of the avoided total. It includes output, hence
113
+ * "total", never "input".
114
+ *
115
+ * Each side is `'unknown'` when its own sample is missing or unusable —
116
+ * never a copy of the other request's numbers. `output_tokens` is the
117
+ * after-mark request's `output`, a third count never folded into either
118
+ * estimate. `cache_hit_delta` is the after-mark hit rate minus the pre-mark
119
+ * hit rate, `null` when either side cannot be told (a `null` delta means
120
+ * "cannot tell", not zero).
100
121
  *
101
122
  * A second `settle()` has nothing left to consume and reports the same
102
123
  * `'unknown'` / `null`.
@@ -108,14 +129,27 @@ export class UsageLedger {
108
129
  this.beforeMark = undefined;
109
130
  this.afterMark = undefined;
110
131
  this.candidateId = undefined;
132
+ // The lower estimate depends only on the pre-mark sample: a settlement
133
+ // with no after-mark request still knows how much that request would have
134
+ // had to replay, and reporting it cannot overstate anything.
135
+ const avoided = before !== undefined && usable(before)
136
+ ? before.input + before.cacheRead + before.output
137
+ : undefined;
138
+ const avoidedTotal = avoided !== undefined && Number.isFinite(avoided) ? avoided : 'unknown';
111
139
  if (after === undefined || !usable(after)) {
112
- return { saved_input_tokens: 'unknown', cache_hit_delta: null, output_tokens: 'unknown' };
140
+ return {
141
+ saved_input_tokens: 'unknown',
142
+ avoided_total_tokens: avoidedTotal,
143
+ cache_hit_delta: null,
144
+ output_tokens: 'unknown',
145
+ };
113
146
  }
114
147
  const afterRate = hitRate(after);
115
148
  const beforeRate = hitRate(before);
116
149
  const delta = afterRate !== null && beforeRate !== null ? afterRate - beforeRate : null;
117
150
  return {
118
151
  saved_input_tokens: after.input + after.cacheRead,
152
+ avoided_total_tokens: avoidedTotal,
119
153
  cache_hit_delta: delta !== null && Number.isFinite(delta) ? delta : null,
120
154
  output_tokens: after.output,
121
155
  };
@@ -1 +1 @@
1
- {"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/admission/usage.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Usage pairing: turn two consecutive model requests into the measured saving\n * of one substitution (design §5.3).\n *\n * When the plugin substitutes a call, the model is not asked for that step, so\n * the next real request replays a shorter history. The saving is therefore\n * measured as the size of that next request — `input + cacheRead`, because the\n * host reports `inputTokens` excluding cache reads — never estimated. A missing\n * next request is `'unknown'`; an interpolated number would be indistinguishable\n * from a measurement once written to a receipt.\n *\n * The ledger keeps two request slots plus a mark: `latest`, the first request\n * after the mark, and the mark itself — which holds the request that preceded\n * it and the candidate id. No whole-history table (YAGNI). Pure arithmetic: no\n * timers, no I/O, no host calls.\n *\n * @module dsh-boost/admission/usage\n */\n\n/** One model request's raw counts, mapped from the `llm/stream` usage chunk. */\nexport interface Usage {\n input: number\n cacheRead: number\n output: number\n}\n\n/**\n * A sample is usable only when all three counts are finite and non-negative\n * and their input total does not overflow. A negative or non-finite count is a\n * protocol violation, and any arithmetic on it would invent `NaN` or\n * `Infinity` — a bogus number no receipt reader could tell from a measurement.\n * An unusable after-mark sample makes the whole settlement unusable; an\n * unusable pre-mark sample only loses the delta.\n */\nfunction usable(u: Usage): boolean {\n return (\n [u.input, u.cacheRead, u.output].every((n) => Number.isFinite(n) && n >= 0) &&\n Number.isFinite(u.input + u.cacheRead)\n )\n}\n\n/**\n * Cache hit rate of one request, `cacheRead / (input + cacheRead)`. `null`\n * when the rate cannot be told: no sample, an unusable sample, or a\n * non-positive denominator. Both sides of the delta go through this one\n * helper so they cannot drift.\n */\nfunction hitRate(u: Usage | undefined): number | null {\n if (u === undefined || !usable(u)) return null\n const denominator = u.input + u.cacheRead\n if (denominator <= 0) return null\n const rate = u.cacheRead / denominator\n return Number.isFinite(rate) ? rate : null\n}\n\n/**\n * Pairs two consecutive model requests around one substitution.\n *\n * The pairing target is the FIRST request after the mark, never the latest:\n * when a caller forgets to settle, a later unrelated request must not be\n * attributed to the substitution. `settle()` consumes the mark and clears the\n * pairing slots; `last()` is a pure reader and survives it.\n */\nexport class UsageLedger {\n private latest: Usage | undefined\n private hasMark = false\n private beforeMark: Usage | undefined\n private afterMark: Usage | undefined\n private candidateId: string | undefined\n\n /**\n * Record one real request. The first request after a mark claims the pairing\n * slot and keeps it; later requests only advance `last()`.\n */\n request(u: Usage): void {\n this.latest = u\n if (this.hasMark && this.afterMark === undefined) this.afterMark = u\n }\n\n /** Most recent request, or `undefined` before the first one. Never consumes. */\n last(): Usage | undefined {\n return this.latest\n }\n\n /**\n * Record that a substitution just happened.\n *\n * `candidateId` is kept only so the caller can pair `settle()` with the right\n * substitution receipt (`pendingCandidateId()`); it never changes the\n * arithmetic. A new mark discards any unconsumed pairing and starts over from\n * the current latest request.\n */\n markSubstituted(candidateId: string): void {\n this.hasMark = true\n this.beforeMark = this.latest\n this.afterMark = undefined\n this.candidateId = candidateId\n }\n\n /** Id of the pending mark, or `undefined` before a mark and after `settle()`. */\n pendingCandidateId(): string | undefined {\n return this.candidateId\n }\n\n /**\n * Consume the mark and report the substitution's measured cost.\n *\n * `saved_input_tokens` is the first after-mark request's `input + cacheRead`;\n * `output_tokens` is that request's `output`, a third count that is never\n * folded into input. Both are `'unknown'` when no usable request arrived after\n * the mark — never a copy of the previous request's numbers. `cache_hit_delta`\n * is the after-mark hit rate minus the pre-mark hit rate, `null` when either\n * side cannot be told (a `null` delta means \"cannot tell\", not zero).\n *\n * A second `settle()` has nothing left to consume and reports the same\n * `'unknown'` / `null`.\n */\n settle(): {\n saved_input_tokens: number | 'unknown'\n cache_hit_delta: number | null\n output_tokens: number | 'unknown'\n } {\n const after = this.hasMark ? this.afterMark : undefined\n const before = this.hasMark ? this.beforeMark : undefined\n this.hasMark = false\n this.beforeMark = undefined\n this.afterMark = undefined\n this.candidateId = undefined\n\n if (after === undefined || !usable(after)) {\n return { saved_input_tokens: 'unknown', cache_hit_delta: null, output_tokens: 'unknown' }\n }\n\n const afterRate = hitRate(after)\n const beforeRate = hitRate(before)\n const delta = afterRate !== null && beforeRate !== null ? afterRate - beforeRate : null\n\n return {\n saved_input_tokens: after.input + after.cacheRead,\n cache_hit_delta: delta !== null && Number.isFinite(delta) ? delta : null,\n output_tokens: after.output,\n }\n }\n}"]}
1
+ {"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/admission/usage.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Usage pairing: turn two consecutive model requests into the measured saving\n * of one substitution (design §5.3).\n *\n * When the plugin substitutes a call, the model is not asked for that step, so\n * the next real request replays a shorter history. The saving is therefore\n * measured as the size of that next request — `input + cacheRead`, because the\n * host reports `inputTokens` excluding cache reads — never estimated. A missing\n * next request is `'unknown'`; an interpolated number would be indistinguishable\n * from a measurement once written to a receipt.\n *\n * That next request is not the avoided request: it also carries the executed\n * call and its result, which the avoided request would not have seen. So\n * `saved_input_tokens` is an **upper** estimate. `settle()` therefore also\n * reports `avoided_total_tokens = before.input + before.cacheRead +\n * before.output` — the whole request that produced the plan, which the avoided\n * request would have carried (plus the plan) — as a **lower** estimate. Each\n * side is `'unknown'` from its own sample, never a copy of the other's.\n *\n * The ledger keeps two request slots plus a mark: `latest`, the first request\n * after the mark, and the mark itself — which holds the request that preceded\n * it and the candidate id. No whole-history table (YAGNI). Pure arithmetic: no\n * timers, no I/O, no host calls.\n *\n * @module dsh-boost/admission/usage\n */\n\n/** One model request's raw counts, mapped from the `llm/stream` usage chunk. */\nexport interface Usage {\n input: number\n cacheRead: number\n output: number\n}\n\n/**\n * A sample is usable only when all three counts are finite and non-negative\n * and their input total does not overflow. A negative or non-finite count is a\n * protocol violation, and any arithmetic on it would invent `NaN` or\n * `Infinity` — a bogus number no receipt reader could tell from a measurement.\n * An unusable after-mark sample makes the whole settlement unusable; an\n * unusable pre-mark sample only loses the delta.\n */\nfunction usable(u: Usage): boolean {\n return (\n [u.input, u.cacheRead, u.output].every((n) => Number.isFinite(n) && n >= 0) &&\n Number.isFinite(u.input + u.cacheRead)\n )\n}\n\n/**\n * Cache hit rate of one request, `cacheRead / (input + cacheRead)`. `null`\n * when the rate cannot be told: no sample, an unusable sample, or a\n * non-positive denominator. Both sides of the delta go through this one\n * helper so they cannot drift.\n */\nfunction hitRate(u: Usage | undefined): number | null {\n if (u === undefined || !usable(u)) return null\n const denominator = u.input + u.cacheRead\n if (denominator <= 0) return null\n const rate = u.cacheRead / denominator\n return Number.isFinite(rate) ? rate : null\n}\n\n/**\n * Pairs two consecutive model requests around one substitution.\n *\n * The pairing target is the FIRST request after the mark, never the latest:\n * when a caller forgets to settle, a later unrelated request must not be\n * attributed to the substitution. `settle()` consumes the mark and clears the\n * pairing slots; `last()` is a pure reader and survives it.\n */\nexport class UsageLedger {\n private latest: Usage | undefined\n private hasMark = false\n private beforeMark: Usage | undefined\n private afterMark: Usage | undefined\n private candidateId: string | undefined\n\n /**\n * Record one real request. The first request after a mark claims the pairing\n * slot and keeps it; later requests only advance `last()`.\n */\n request(u: Usage): void {\n this.latest = u\n if (this.hasMark && this.afterMark === undefined) this.afterMark = u\n }\n\n /** Most recent request, or `undefined` before the first one. Never consumes. */\n last(): Usage | undefined {\n return this.latest\n }\n\n /**\n * Record that a substitution just happened.\n *\n * `candidateId` is kept only so the caller can pair `settle()` with the right\n * substitution receipt (`pendingCandidateId()`); it never changes the\n * arithmetic. A new mark discards any unconsumed pairing and starts over from\n * the current latest request.\n */\n markSubstituted(candidateId: string): void {\n this.hasMark = true\n this.beforeMark = this.latest\n this.afterMark = undefined\n this.candidateId = candidateId\n }\n\n /** Id of the pending mark, or `undefined` before a mark and after `settle()`. */\n pendingCandidateId(): string | undefined {\n return this.candidateId\n }\n\n /**\n * Consume the mark and report the substitution's measured cost.\n *\n * Two estimates of the avoided request, from the same pair of samples:\n *\n * - `saved_input_tokens` is the first after-mark request's `input +\n * cacheRead`. That request is the next real one, so its input also carries\n * the executed call and its result — tokens the avoided request would never\n * have seen. It is therefore the **upper** estimate of the avoided input,\n * and the plugin's headline number.\n * - `avoided_total_tokens` is the pre-mark request's `input + cacheRead +\n * output`: the whole request that produced the plan. The avoided request\n * would have carried that request's context plus the plan, so this is a\n * **lower** estimate of the avoided total. It includes output, hence\n * \"total\", never \"input\".\n *\n * Each side is `'unknown'` when its own sample is missing or unusable —\n * never a copy of the other request's numbers. `output_tokens` is the\n * after-mark request's `output`, a third count never folded into either\n * estimate. `cache_hit_delta` is the after-mark hit rate minus the pre-mark\n * hit rate, `null` when either side cannot be told (a `null` delta means\n * \"cannot tell\", not zero).\n *\n * A second `settle()` has nothing left to consume and reports the same\n * `'unknown'` / `null`.\n */\n settle(): {\n saved_input_tokens: number | 'unknown'\n avoided_total_tokens: number | 'unknown'\n cache_hit_delta: number | null\n output_tokens: number | 'unknown'\n } {\n const after = this.hasMark ? this.afterMark : undefined\n const before = this.hasMark ? this.beforeMark : undefined\n this.hasMark = false\n this.beforeMark = undefined\n this.afterMark = undefined\n this.candidateId = undefined\n\n // The lower estimate depends only on the pre-mark sample: a settlement\n // with no after-mark request still knows how much that request would have\n // had to replay, and reporting it cannot overstate anything.\n const avoided =\n before !== undefined && usable(before)\n ? before.input + before.cacheRead + before.output\n : undefined\n const avoidedTotal =\n avoided !== undefined && Number.isFinite(avoided) ? avoided : ('unknown' as const)\n\n if (after === undefined || !usable(after)) {\n return {\n saved_input_tokens: 'unknown',\n avoided_total_tokens: avoidedTotal,\n cache_hit_delta: null,\n output_tokens: 'unknown',\n }\n }\n\n const afterRate = hitRate(after)\n const beforeRate = hitRate(before)\n const delta = afterRate !== null && beforeRate !== null ? afterRate - beforeRate : null\n\n return {\n saved_input_tokens: after.input + after.cacheRead,\n avoided_total_tokens: avoidedTotal,\n cache_hit_delta: delta !== null && Number.isFinite(delta) ? delta : null,\n output_tokens: after.output,\n }\n }\n}"]}