dsh-boost 0.1.2 → 0.1.4

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
@@ -5,13 +5,14 @@ read-only substitution**.
5
5
 
6
6
  > **Status: v1 is implemented.** Projection, substitution, and the control surface are all in
7
7
  > place; `npm run build` is clean and the full test suite passes. The benefit range is an
8
- > **ex-ante design estimate** (3.5% lower bound / 10.0% ideal upper bound; ~0.4% honest net
9
- > floor); nothing in the deliverable can recompute it — see below.
8
+ > **ex-ante design estimate** (3.5% lower bound / 10.0% ideal upper bound; ~0.4% aggregate net
9
+ > on the 300 longest sessions). Both ends are offline estimates, not per-session floors, and
10
+ > nothing in the deliverable can recompute them — see below.
10
11
 
11
12
  ## What it does
12
13
 
13
14
  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`
15
+ locally (`npm run --silent stats` — without `--silent`, npm prints its `> dsh-boost@0.1.3 stats`
15
16
  banner to stdout, so use `--silent` or `node scripts/session-stats.mjs` for machine-readable
16
17
  output; snapshot at `2026-11-19T03:13:21Z`): 54,141 steps and 54,088 requests,
17
18
  10,575,904,022 raw tokens in total. The mean is 195,340 tokens per step and 195,531 per request
@@ -29,8 +30,9 @@ The plugin does two things:
29
30
  decision. With several candidates, a single-label selector — one auxiliary request
30
31
  (`maxTokens` 512 plus its input) — picks one. This is a **narrowing** of original requirement
31
32
  2.2: the request asked Jev to score each tool result and decide whether it could feed the next
32
- tool; v1 only picks one of several candidates on the same receipt, with no per-result scoring
33
- (see the 2.2 row and decision 9 in the
33
+ tool; v1 only picks one of several candidates on the same receipt, with no per-result scoring.
34
+ That narrowing is the **implementer's scope decision (E2)**, not a user ruling — **no user
35
+ message ratifies it** (see the 2.2 row and implementer decision E2 in the
34
36
  [clarification record](docs/superpowers/clarifications/2026-11-18-dsh-token-efficiency.md)).
35
37
  For the three substituted tools, the plan's
36
38
  `$public` argument binding (copying a value from an earlier receipt into a later call's
@@ -48,13 +50,19 @@ The plugin does two things:
48
50
  The **ex-ante estimate** for v1 is **3.5% (lower bound) to 10.0% (ideal upper bound)** of raw
49
51
  `totalTokens`; **3.5% is not a floor** — it is the lower bound of an offline estimate against a
50
52
  300-session corpus, and its substitution component (2.70%) is a **ceiling** that must not be
51
- counted as a floor. The honest net floor is about **0.4%** (projection gross ~0.8% minus ~0.4%
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
+ counted as any floor. Projection's **aggregate net across the 300 longest sessions** is about
54
+ **0.4%** (gross ~0.8% minus ~0.4% fixed per-request overhead, i.e. 778 / 195,531); that is not a
55
+ per-session floor either — long sessions amortise the fixed overhead, **short sessions can be
56
+ net negative**, and the `top-300` corpus contains no ≤5-step session. Both 3.5% and 0.4% are
57
+ offline estimates, not measurements. It is not a guarantee, and not a figure the shipped
58
+ `session-snapshot.json` can recompute: the snapshot stores per-session aggregates plus each
59
+ session's `requestTokens` / `receiptChars` arrays, `valueTransfer` / `whitelist` counts, and
60
+ its per-family `toolChars` totals, but it has **no per-receipt family bytes** — the projection
61
+ components the estimate needs cannot be assembled from it, so **nothing in the deliverable can
62
+ recompute it**. Nor can the shadow week turn the range into a measured percentage: the shadow
63
+ report outputs four ratios only (see "Shadow week"), with no total-token denominator, and
64
+ `boost status` carries absolute values only; replacing the range with measurements needs a
65
+ denominator statistic that a later version must add.
58
66
 
59
67
  ## Requirements
60
68
 
@@ -77,28 +85,32 @@ replacing the range with measurements needs a denominator statistic that a later
77
85
  directory:
78
86
 
79
87
  ```bash
80
- # install from the registry: npmjs has latest = 0.1.1 (this repository's
88
+ # install from the registry: npmjs has latest = 0.1.3 (this repository's
81
89
  # .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/
90
+ dsh plugin --profile <name> add dsh-boost@^0.1.3 --registry=https://registry.npmjs.org/
83
91
 
84
92
  # or from a local checkout (build first; dist/ is not committed)
85
93
  npm run build
86
94
  dsh plugin --profile <name> add /absolute/path/to/dsh-boost
87
95
  ```
88
96
 
89
- For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.1 --registry=https://registry.npmjs.org/`.
97
+ For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.3 --registry=https://registry.npmjs.org/`.
90
98
  `dsh plugin` forwards the operation to pnpm, so pnpm must be on `PATH`.
91
99
 
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.
100
+ > **Both registries now carry 0.1.3, so `^0.1.3` is a safe pin.**
101
+ > `registry.npmjs.org` and `registry.npmmirror.com` each have five version records: `0.1.3` (the
102
+ > current `latest` on both), `0.1.2`, `0.1.1`, `0.1.0`, and `0.0.0-stage`, the placeholder npm
103
+ > creates on a package's first publish — **do not install `0.0.0-stage`**; it is not a usable
104
+ > build. 0.1.3 stops a substitution from committing on output the model cannot see (an outer
105
+ > shaper rewrote the content) and reports the saving as a range (adding `avoided_total_tokens`),
106
+ > plus three host-capability degradation codes and `status.hasSpill`; 0.1.2 carries the
107
+ > scope-overwrite fix: corrupt JSON (including a non-object or an array) and an unrecognizable
108
+ > version are no longer silently overwritten with the default document. Use `dsh-boost@^0.1.3`
109
+ > (or `@latest`) — `^0.1.3` means "at least 0.1.3's fixes". This repository's `.npmrc` and
110
+ > lockfile are pinned to npmjs, but **your machine's global npm config** may still point at a
111
+ > mirror that has not synced 0.1.3: that is local configuration, not this repository's state.
112
+ > Pass `--registry=https://registry.npmjs.org/` explicitly when the registry matters; against a
113
+ > lagging mirror, `@^0.1.3` fails to resolve until the sync lands.
102
114
 
103
115
  The package is ESM (`"type": "module"`) and the `.` entry of `exports` also maps `require` /
104
116
  `default`: on Node >= 24.9, `require('dsh-boost')` loads the very same code as `import`. Nothing
@@ -131,8 +143,8 @@ equivalent. In the conversation, ask the agent to call it, for example:
131
143
  > Call the boost tool with `{"cmd":"status"}` and show me the JSON.
132
144
 
133
145
  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
146
+ `shadow` `true`, `projection` `"shadow"`, and `counts` empty (only on a fresh receipt root — `scan()` reads every shard, so earlier out-of-scope
147
+ calls from other sessions in the same DSH home have already recorded `skip:no-scope`). The first `status` does
136
148
  **not** report `ERR_SCOPE_READ_FAILED` merely because `scope.json` is missing: a missing file is
137
149
  the clean default (`ENOENT` carries no degradation code, `src/scope/store.ts`); on a fresh root
138
150
  with the host capabilities in place, `degraded` is simply an empty array. On the `status` read
@@ -182,9 +194,13 @@ After the write, call `status` again. A healthy result looks like this:
182
194
  `@deepseek-ai/dsh-token-meter/estimate` is unreachable, `fixedOverheadTokens` is the string
183
195
  `"unknown"` (not 0) and `degraded` carries `ERR_HOST_NO_ESTIMATOR`; `estimate_kind` may still be
184
196
  `"host"` because the token-meter service is present — the two are different things.
197
+ - `data.hasSpill` is `true` when the host **provides** a spill service (presence). It does **not**
198
+ mean the service is usable: a service without `saveText` keeps it `true` while `degraded` carries
199
+ `ERR_HOST_SPILL_UNUSABLE`. Check both before turning `projection: 'on'`; `hasSpill` alone can
200
+ mistake an unusable backend for a working one.
185
201
  - `data.counts` usually starts empty — but **control calls count too**: while no workspace is
186
202
  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
203
+ 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
204
  after normal tool calls, for example with `projection-shadow` entries.
189
205
 
190
206
  Excerpt (illustrative values; ledger fields omitted):
@@ -223,22 +239,36 @@ above a workspace is selected, so 778 is the true per-request cost there.
223
239
 
224
240
  The design chose **shadow first**: record for a week — no synthesized turns, no skipped calls,
225
241
  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
-
231
- Of those ratios, `saveableRatio`, `byFamily`, and `candidateRecall` can decide **whether the
232
- substitution side is worth turning on**: how many substitution decisions the whitelist could
233
- actually deliver, which tool families the hits land in, and how high candidate recall is — that
234
- is, whether substitution would fire at all and where. They **cannot decide release**: v1 ships as
235
- a normal release and does not gate on shadow-week savings — and that call was the
236
- **implementer's** decision during design, not a user ruling. The user accepted a one-week shadow
237
- 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
- `retrievalUpperBound` is structurally `0` during the shadow week (it only counts applied
239
- `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.
242
+ **"Changes nothing the model sees" would be false**: the `boost` tool schema (399 tokens) is
243
+ registered whenever the plugin is assembled, and whenever a workspace is visible the protocol
244
+ section (379 tokens) is also injected into the system prompt — **778 per request** in the
245
+ recommended setup; a multi-candidate plan still makes a **real selector call** (a separate
246
+ auxiliary model request). The shadow week saves no tokens; it produces only the four ratios below.
247
+ Under `selected + []` the protocol section is empty and the fixed cost is still **399**.
248
+
249
+ Of those ratios, `saveableRatio`, `byFamily`, and `candidateRecall` are **labels for the
250
+ substitution side; they do not by themselves decide whether to turn it on**: how many substitution
251
+ decisions the whitelist could actually deliver, which tool families the hits land in, and how high
252
+ the commit yield is — that is, whether substitution would fire at all and where. The report has
253
+ **no total-token denominator**, so these labels cannot judge net benefit. They **cannot decide
254
+ release** either: v1 ships as a normal release and does not gate on shadow-week savings — and that
255
+ call was the **implementer's** decision during design, not a user ruling. The user accepted a
256
+ one-week shadow period; they did not rule on whether shadow results should gate a release. They
257
+ also **cannot measure savings**: `retrievalUpperBound` is structurally `0` during the shadow week
258
+ (it only counts applied `projection:'on'` retrievals), so it cannot even bound projection's
259
+ retrieval damage. Projection is released on the visibility contract alone (the original stays
260
+ retrievable through the footer), not on shadow labels — and **not on post-hoc detection**: v1 has
261
+ no mis-truncation detector. `src/admission/retrieval.ts` only counts exact-locator retrievals, and
262
+ design §6.1 itself records that the damage metric was never delivered and that retrieval counts
263
+ are not a damage bound. The only guard is that the model can retrieve the original; a retrieval
264
+ being attempted is a signal, not proof that nothing was wrongly cut.
265
+
266
+ **An all-zero week cannot distinguish two things.** If the model never writes `<CHISEL_PLAN>`,
267
+ there are no decision receipts at all and all four ratios are `0`; that looks exactly like
268
+ "nothing saveable" — the report does not measure plan emission. When you see all zeros, first
269
+ check whether the receipts contain substitution decisions (`kind:'shadow'` / `kind:'skip'`); do
270
+ not read it directly as "the plugin has no effect".
271
+
242
272
  `scope.json` has two independent switches:
243
273
 
244
274
  | Switch | Value | Behaviour |
@@ -262,11 +292,17 @@ The recommended sequence:
262
292
  shadow commits over **all** substitution decisions — the denominator is every substitution
263
293
  decision, not just the whitelisted calls; shadow mode records every family, so bash/ssh
264
294
  potential shows up in `byFamily`), `byFamily` (hit rate per candidate family), `candidateRecall`
265
- (recall of the candidate set), and `retrievalUpperBound` (retrieval upper bound; structurally
266
- `0` during the shadow week because nothing is projected for real).
295
+ (**commit yield, not candidate-set recall**: `commits / (commits + noCandidate)`; the script
296
+ never compares the candidate set to the model's actual next call, so it answers "how many
297
+ decisions with a candidate committed", not "did the candidate set miss the call the model
298
+ actually made"), and `retrievalUpperBound` (**a lower bound on the observed retrieval rate, not
299
+ an upper bound on retrieval damage**; structurally `0` during the shadow week because nothing
300
+ is projected for real).
267
301
  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
269
- `shadow: true` and set `projection` to `'on'`:
302
+ visibility contract — the original stays retrievable through the footer; v1 has no
303
+ mis-truncation detector). First confirm `status.data.hasSpill` is `true` **and** `degraded`
304
+ does not carry `ERR_HOST_SPILL_UNUSABLE` — the former only proves the host **provides** the
305
+ service, the latter says it is usable; then keep `shadow: true` and set `projection` to `'on'`:
270
306
 
271
307
  ```json
272
308
  { "cmd": "scope-set", "body": { "projection": "on" }, "baseRevision": 1 }
@@ -274,8 +310,8 @@ The recommended sequence:
274
310
 
275
311
  `scope-set` patches only the fields you pass; everything else stays as it was. Receipts now get
276
312
  replaced, while substitution decisions are still recorded only.
277
- 4. **Turn on substitution**: when the shadow report shows acceptable whitelist hits and candidate
278
- recall, just switch the shadow off — **checking before the switch is a no-op**: the shadow
313
+ 4. **Turn on substitution**: when the shadow report shows acceptable whitelist hits and commit
314
+ yield, just switch the shadow off — **checking before the switch is a no-op**: the shadow
279
315
  week never synthesizes a turn, so a `content[].thinking` 400 is
280
316
  structurally impossible and a check made before switching it off can only ever read "not
281
317
  seen". After `shadow` becomes `false`, check for that 400 in the **first genuinely
@@ -310,7 +346,7 @@ cap is 256 KiB, so `300000` prevents the family from triggering at all (there is
310
346
  | `projection.glob.*` | 700 / 400 / 100 | `glob` window |
311
347
  | `projection.bash.*` | 4000 / 2000 / 500 | `bash` window |
312
348
  | `projection.ssh.*` | 2000 / 1200 / 300 | `mcp__ssh__*` (such as `mcp__ssh__execute-command`) window |
313
- | `admission.thresholdTokens` | 1024 | Minimum net saving per candidate before substitution; a single deterministic candidate is exempt |
349
+ | `admission.thresholdTokens` | 1024 | Minimum net saving per candidate before substitution; **a single-step plan is exempt** (`plan.steps.length === 1`, `admittedFor` in `src/hooks/post-execute.ts`) — with one step there is no selector to pay, so the threshold does not apply. It is not "deterministic && the only candidate": a multi-step plan that has one candidate left still has to pass the threshold (`worthSubstituting` in `src/admission/ledger.ts`) |
314
350
  | `selector.maxTokens` | 512 | Output budget for the multi-candidate selector (its input plus output bound is deducted from the saving) |
315
351
  | `stepsPerTurn` | 8 | Maximum substituted steps per turn |
316
352
  | `horizonSteps` | 20 | Remaining-step horizon used when the session average cannot be computed |
@@ -323,7 +359,8 @@ The invariant is **not** `triggerChars >= headChars + tailChars + 1`. The real r
323
359
  line + head + footer + tail + 3 newlines; the footer is produced by the host's `formatSpillNotice`.
324
360
  With a 68-character locator and the host's fixed 66-character retrieval hint, a 3-digit
325
361
  omitted-byte count gives 190 characters and a 5-digit count gives 192. With the grep/glob defaults
326
- of 400+100: `400 + 100 + 50 (head line) + 190 (footer) + 3 = 743 > 700` (745 with a 5-digit count).
362
+ of 400+100: `400 + 100 + 50 (head line) + 190 (footer) + 3 = 743 > 700` (with a 5-digit count the
363
+ footer is 192 and the head line's numbers each gain a digit, measured 747–749).
327
364
  So a receipt just over 700 — up to about 743 — is judged cuttable by `truncate`, but `projectApply` assembles a replacement that is
328
365
  not shorter than the original and returns the original. That is a dead band, not a net loss. The
329
366
  runtime `assembled.length >= text.length` check guarantees projection never makes a receipt
@@ -386,12 +423,15 @@ set it falls back to `~/.dsh`; the assembly log prints the resolved `root=` (tha
386
423
  - `scope.lock` — the short-lived write lock, removed after a normal write.
387
424
  - `receipts/<encoded-session>.jsonl` — append-only receipts. **A receipt is written per
388
425
  decision, not per call**: a line appears only for a projection, a substitution decision
389
- (including skips), or an out-of-scope `skip:no-scope`. A `write` / `edit` with no plan produces
390
- **no receipt at all**, so its arguments are never recorded. Every line carries metadata, a
391
- preview of the first 256 code points of the receipt (never the full stdout), and that call's
392
- bound `args` (model-written: above 2048 code points they are stored as visibly truncated JSON
393
- with an `args_truncated` flag; nesting deeper than 64 levels sets `args_depth_truncated` and
394
- replaces the deeper subtree with `{ "truncated_depth": 64 }`). **Only substitution receipts**
426
+ (including skips), a pending substitution abandoned after an external rewrite (`kind:'reset'`,
427
+ `code` `pruned-reset` / `compaction-reset`), or an out-of-scope `skip:no-scope`. A `write` /
428
+ `edit` with no plan produces **no receipt at all**, so its arguments are never recorded. Except
429
+ for `kind:'reset'` and the `skip:no-scope` written by `appendSkipNoScope`, every line carries
430
+ metadata, a preview of the first 256 code points of the receipt (never the full stdout), and
431
+ that call's bound `args` (model-written: above 2048 code points they are stored as visibly
432
+ truncated JSON with an `args_truncated` flag; nesting deeper than 64 levels sets
433
+ `args_depth_truncated` and replaces the deeper subtree with `{ "truncated_depth": 64 }`).
434
+ **Only substitution receipts**
395
435
  also carry the plan goal (≤256 code points) and guards (≤8, each ≤300 code points):
396
436
  `kind:'substitute'`, `kind:'substitute-settled'`, and `kind:'shadow'` with `code:'ok'`.
397
437
  `kind:'shadow'` is not substitution-only — projection shadowing also writes `kind:'shadow'`,
@@ -403,7 +443,9 @@ set it falls back to `~/.dsh`; the assembly log prints the resolved `root=` (tha
403
443
  carry `locator` plus `retrieval_call_tokens` / `retrieval_content_tokens` / `retrieval_tokens`;
404
444
  those three are written only when the retrieval was priced, and an unpriced one has
405
445
  `estimate:'unknown'` with the fields omitted. `skip` receipts carry only `preview` and `args`
406
- (`skip:no-scope` carries neither — just the tool name).
446
+ (`skip:no-scope` has two paths: the `appendSkipNoScope` branch — no agent, no session id, or an
447
+ inactive session — carries only the tool name; the mid-call live-visibility branch goes through
448
+ `ledgerEntry` and still carries `preview` and `args`).
407
449
 
408
450
  When the current shard exceeds 8 MiB or 20,000 lines, the next write first rotates it to
409
451
  `<encoded-session>.1.jsonl`; only the current shard and its predecessor are kept (an older `.1`
@@ -431,12 +473,23 @@ in effect (the minimum over live sessions, falling back to `horizonSteps` when n
431
473
  - `projection_unknown_families`: calls carrying an `mcp__` prefix that reached projection but
432
474
  matched no tool family; `projection_unknown_tools` is the retained unmapped tool names with
433
475
  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.
476
+ - `hasWorkspaceRegistry`: whether the host **provides** `workspaceRegistry` (also presence). The
477
+ production assembly always supplies the key, so it is **always boolean**: no service is `false` +
478
+ `ERR_HOST_NO_WORKSPACE_REGISTRY`; a service whose `list()` throws is `true` +
479
+ `ERR_HOST_WORKSPACE_REGISTRY_BROKEN`. Both leave every session invisible, but they are fixed
480
+ differently. The key is omitted only when `boost` is constructed directly with no host facts.
481
+ - `hasSpill`: whether the host **provides** a spill backend (presence, not usability). A missing
482
+ service is `false` + `ERR_HOST_NO_SPILL`; a service without `saveText` keeps it **`true`** and puts
483
+ `ERR_HOST_SPILL_UNUSABLE` in `degraded` — the capability fact lives in `degraded`, not in this boolean.
484
+ - `saved`: the camelCase ledger object kept for older consumers (`substitution` /
485
+ `substitutionAvoided` / `projectionGross` / `projectionNet` / `retrievals`), derived from the same
486
+ aggregation as the top-level snake_case fields. Legacy projection receipts (pre-T23b) without
487
+ `saved_projection_tokens` fall back to the receipt's own `saved` field.
488
+ **The two substitution numbers are a range, not the same quantity.** `substitution` takes the
489
+ input of the *next* real request after the skipped one — it includes the substituted call's own
490
+ result, so it is an **upper bound**. `substitutionAvoided` takes the planning request's
491
+ `input + cacheRead + output` — it excludes that result, so it is a **lower bound**. The true
492
+ saving lies between them.
440
493
 
441
494
  With `projection: 'on'`, the complete original is written to the host spill backend **before** the
442
495
  replacement happens, and the footer locator can be read with `read` / `grep`. Projection never
@@ -493,7 +546,7 @@ to load. `llm` is soft (only the selector uses it); when absent the selector fal
493
546
  | (spill backend present but failing) | — | Every `saveText` is rejected: the receipt records `projection-skipped:spill-failed` and `status.degraded` reports **`ERR_HOST_SPILL_FAILING`**. This is a **third** state — neither "no backend" nor "no footer renderer" — and telling an operator to restore the spill package would send them after a package that is installed and failing |
494
547
  | `@deepseek-ai/dsh-token-meter/estimate` | soft (dynamic import) | Fixed overhead cannot be measured, so `fixedOverheadTokens` is `'unknown'`; `status.degraded` reports `ERR_HOST_NO_ESTIMATOR` |
495
548
  | `win32` platform | runtime `isPosixOnly()` check | Substitution is refused, projection still works; `status.degraded` reports `ERR_HOST_PLATFORM_UNSUPPORTED` |
496
- | Host version line | startup check of the `@deepseek-ai/dsh-app-boot` version | A version other than `0.2.2-rc.4` logs `ERR_HOST_VERSION_MISMATCH` and loads anyway — advisory only, not a `status.degraded` code. An undeterminable version logs an info line, no code |
549
+ | Host version line | startup check of the `@deepseek-ai/dsh-app-boot` version | A version **outside the `engines.dsh` range** (`>=0.2.2-rc.4 <0.2.3-0`) logs `ERR_HOST_VERSION_MISMATCH` and loads anyway — advisory only, not a `status.degraded` code. A version inside the range but not the verified `0.2.2-rc.4` (such as `rc.5` / `0.2.2`) logs an info line, no code; an undeterminable version or an unparseable range also logs info only |
497
550
  | Receipt shard readability | `boost status` full scan (not a dependency) | When at least one receipt shard cannot be read (EACCES, a directory named `x.jsonl`, …), `status.degraded` carries `ERR_RECEIPTS_UNREADABLE`; `status` stays a **total over the healthy shards** — they are still counted — so the figures may be incomplete. Check permissions and stray entries in `<dshHome>/boost/receipts/`, fix, and re-run `status`, comparing counts |
498
551
  | Receipt shard count | `boost status` full scan (not a dependency) | When more than 256 shards exist, `status` counts only the first 256 by encoded name and `status.degraded` carries `ERR_RECEIPTS_TRUNCATED`; every count is therefore a **lower bound**. Shards are never pruned automatically; archive or move old session shards and re-run `status` |
499
552
  | Prompt assembly waterfall | outgoing-request probe (not a dependency) | When the host's `complete: true` prompt section replaces the assembled system prompt after the waterfall and the protocol section never reaches the request, `status.degraded` carries `ERR_HOST_COMPLETE_SECTION`; substitution and projection fail closed for the affected requests (the plugin stays inert although the workspace is visible). Find the complete section overriding the waterfall (usually another plugin's) and remove it, or accept the inaction on those requests |
@@ -532,21 +585,42 @@ evidence" degraded path would be unreachable.
532
585
 
533
586
  - Only two things: **replace tool receipts in place** and **substitute read-only calls** (`read` /
534
587
  `grep` / `glob`).
535
- - **No batched tool execution** (no PTC / `run_code`): this is not a boundary v1 chose for
536
- itself but the **narrowed** form of original requirement 2.1 — the request asked for several
537
- tool calls at once, and the adjudication excluded it explicitly for a later phase (see the
538
- 2.1 row and decision 9 in the
588
+ - **No batched tool execution** (no PTC / `run_code`): this is a **narrowing** of original
589
+ requirement 2.1 and the **implementer's scope decision (E2)**, not a user ruling — **no user
590
+ message ratifies it**. The reason is scope, not "batch dispatch was shown to be worthless":
591
+ 79.8% of steps carry exactly one tool call, but **20.2% are not single-tool steps** — 16.9% carry
592
+ ≥2 calls and 3.3% carry none (`clarifications:17`). The user explicitly asked for batch dispatch,
593
+ and those non-single steps are its surface. PTC is deferred to phase two; the restart condition
594
+ is shadow-week data on the real share and benefit of batched steps, not "79.8% proves batching is
595
+ unnecessary" (see the 2.1 row and E2 in the
539
596
  [clarification record](docs/superpowers/clarifications/2026-11-18-dsh-token-efficiency.md);
540
597
  design N1).
598
+ - **Does not answer "who decides tool-call ordering"**: original requirement 2.3 asked for
599
+ research on how a composed tool sequence is ordered (does Jev decide, or does the model fix the
600
+ order up front), and v1 **did not deliver that research** — it is an open gap, **not covered by
601
+ the PTC deferral**. v1's implementation has the model decide the next call step by step; Jev only
602
+ picks one of the declared candidates and cannot add steps or reorder them. The research's
603
+ ReWOO / LLMCompiler evidence for "declare the whole plan, then stop asking the model between
604
+ steps" was never applied to ordering authority, and no comparison experiment exists
605
+ (`clarifications:19`, design §9).
541
606
  - **No deduplication or merging of tool calls** (design N5) — this was not started at all, and
542
607
  v1 ships **no tool that measures duplicate-call rate**: the "shadow-week duplication
543
608
  statistic" the design reserved as its restart trigger was never delivered; `shadow-report.mjs`
544
609
  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.
610
+ - **Only four HarnessMM pieces were ported**: the flat candidate bank, the GDR guard, CCS
611
+ single-candidate commit, and the closed-set selector (Jev). **EDG's graph/chain
612
+ (`predecessor_id`) was not ported** — this plugin's plan is a flat, one-shot-per-receipt
613
+ candidate list, and `predecessor_id` appears nowhere in `src/`; **the RSI loop was not ported**
614
+ either — v1 is a fixed-policy plugin with no training/selection lifecycle (`clarifications:16`).
615
+ - **The shadow week saves no tokens**: it only records (the protocol section is still injected
616
+ and the selector is still called), and the recommended setup still costs 778 per request
617
+ (`selected + []` costs 399); its output is four ratios, not saved tokens.
547
618
  - **v1 does not judge "better results"**: there is a token ledger and a **manual** 20-task
548
619
  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.
620
+ no quality metric; whether substituted outcomes are better is unjudgeable in v1. The procedure
621
+ itself is not fully delivered either: neither the smoke runner (`test/regression/run.mjs`) nor
622
+ the same section's locator-retrieval integrity check exists, and `test/regression/` holds only
623
+ `.gitkeep` — so the "no data loss" invariant in its pass predicate is **unverified** in v1.
550
624
  - **Projection is truncation, not refinement**: it keeps the head and tail and drops the middle;
551
625
  the before/after token difference in the ledger measures *shorter*, not *more relevant*. The
552
626
  dropped middle may be exactly what the next decision needs — with `projection: 'on'` the
@@ -560,11 +634,12 @@ evidence" degraded path would be unreachable.
560
634
  projection changes only the model-visible content and keeps the original in the host spill.
561
635
  - No model training or weight changes (N2); no attempt at the paper's 87.93% (N4).
562
636
  - No 10% promise: 3.5% is the **lower bound** of the ex-ante estimate, not a floor; 10% is the
563
- ideal upper bound. The honest net floor is about 0.4% (projection gross ~0.8% minus ~0.4%
564
- fixed per-request overhead). The shadow week only answers whether the substitution side is
565
- worth turning on (candidate coverage and hit rate); it does not decide release, and it cannot
566
- replace the range with a measurement (`shadow-report.mjs` emits four ratios and no total-token
567
- denominator).
637
+ ideal upper bound. Projection's aggregate net across the 300 longest sessions is about 0.4%
638
+ (gross ~0.8% minus ~0.4% fixed per-request overhead); that too is an offline estimate, **not a
639
+ per-session floor** (short sessions can be net negative). The shadow week only gives labels for
640
+ the substitution side (candidate coverage and commit yield); it does not by itself decide
641
+ whether to turn substitution on, does not decide release, and cannot replace the range with a
642
+ measurement (`shadow-report.mjs` emits four ratios and no total-token denominator).
568
643
 
569
644
  ## Documentation
570
645
 
@@ -582,9 +657,11 @@ The source and docs live in the repository at
582
657
  | [Design](docs/superpowers/specs/2026-11-18-dsh-token-efficiency-design.md) | Goals, evidence, architecture, contracts, measurement, risks, release shape |
583
658
  | [Host contracts appendix](docs/superpowers/plans/2026-11-18-host-contracts.md) | Interface reference copied line by line from the host sources |
584
659
  | [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 |
660
+ | [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
661
 
587
662
  ## License
588
663
 
589
664
  Apache-2.0. The mechanisms are ported from [HarnessMM](https://github.com/YuhuaJiang2002/HarnessMM)
590
- (Apache-2.0); a `NOTICE` ships with the package.
665
+ (Apache-2.0): the flat candidate bank, GDR guard, CCS single-candidate commit, and the closed-set
666
+ selector. **EDG's graph/chain (`predecessor_id`) and the RSI loop were not ported.** A `NOTICE`
667
+ ships with the package.