dsh-boost 0.1.1 → 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.
Files changed (52) hide show
  1. package/README.en.md +141 -51
  2. package/README.md +115 -47
  3. package/dist/admission/usage.js +41 -7
  4. package/dist/admission/usage.js.map +1 -1
  5. package/dist/gate/decide.js +33 -2
  6. package/dist/gate/decide.js.map +1 -1
  7. package/dist/hooks/llm-stream.js +232 -58
  8. package/dist/hooks/llm-stream.js.map +1 -1
  9. package/dist/hooks/post-execute.js +206 -39
  10. package/dist/hooks/post-execute.js.map +1 -1
  11. package/dist/hooks/session-state.js +18 -8
  12. package/dist/hooks/session-state.js.map +1 -1
  13. package/dist/index.js +601 -72
  14. package/dist/index.js.map +1 -1
  15. package/dist/scope/doc.js.map +1 -1
  16. package/dist/scope/store.js +24 -9
  17. package/dist/scope/store.js.map +1 -1
  18. package/dist/tools/boost.js +82 -2
  19. package/dist/tools/boost.js.map +1 -1
  20. package/package.json +9 -5
  21. package/dist/admission/fixed-cost.d.ts +0 -23
  22. package/dist/admission/ledger.d.ts +0 -113
  23. package/dist/admission/retrieval.d.ts +0 -65
  24. package/dist/admission/usage.d.ts +0 -75
  25. package/dist/config.d.ts +0 -43
  26. package/dist/gate/binding.d.ts +0 -113
  27. package/dist/gate/decide.d.ts +0 -82
  28. package/dist/gate/guard.d.ts +0 -69
  29. package/dist/gate/invalidate.d.ts +0 -112
  30. package/dist/gate/plan.d.ts +0 -86
  31. package/dist/hooks/clock.d.ts +0 -68
  32. package/dist/hooks/execute.d.ts +0 -79
  33. package/dist/hooks/llm-stream.d.ts +0 -283
  34. package/dist/hooks/pending.d.ts +0 -89
  35. package/dist/hooks/post-execute.d.ts +0 -257
  36. package/dist/hooks/session-state.d.ts +0 -158
  37. package/dist/hooks/synthesize.d.ts +0 -74
  38. package/dist/host/loader.d.ts +0 -23
  39. package/dist/host/platform.d.ts +0 -18
  40. package/dist/host/root.d.ts +0 -25
  41. package/dist/projection/apply.d.ts +0 -174
  42. package/dist/projection/canonicalise.d.ts +0 -43
  43. package/dist/projection/counters.d.ts +0 -65
  44. package/dist/projection/truncate.d.ts +0 -47
  45. package/dist/prompt/protocol.d.ts +0 -45
  46. package/dist/receipts/store.d.ts +0 -198
  47. package/dist/scope/doc.d.ts +0 -117
  48. package/dist/scope/resolve.d.ts +0 -91
  49. package/dist/scope/store.d.ts +0 -135
  50. package/dist/selector/jev.d.ts +0 -93
  51. package/dist/tools/boost.d.ts +0 -380
  52. package/dist/tools/family.d.ts +0 -26
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.0 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
@@ -38,21 +38,33 @@ The plugin does two things:
38
38
  emit line-numbered or bare-path output that the identifier projection cannot match, so those
39
39
  calls fall back to the model.
40
40
 
41
+ The multi-candidate selector **does not read a separate model configuration**: it reuses the
42
+ **boundary request's** `provider` / `model` / `reasoningEffort` (`rememberRoute` in
43
+ `src/index.ts`, fed mainly by `agent/pre-step`'s `modelSelection`, with the `agent/request`
44
+ resolution only as a fallback), so it is not necessarily a cheap model. To move it, either
45
+ change the model on the boundary session (the host routes per agent) or leave the plan with a
46
+ single candidate (one candidate never calls the selector).
47
+
41
48
  The **ex-ante estimate** for v1 is **3.5% (lower bound) to 10.0% (ideal upper bound)** of raw
42
49
  `totalTokens`; **3.5% is not a floor** — it is the lower bound of an offline estimate against a
43
50
  300-session corpus, and its substitution component (2.70%) is a **ceiling** that must not be
44
51
  counted as a floor. The honest net floor is about **0.4%** (projection gross ~0.8% minus ~0.4%
45
52
  fixed per-request overhead). It is not a guarantee, and not a figure the shipped
46
- `session-snapshot.json` can recompute (the snapshot stores aggregate counts only, not the
47
- components of the estimate) — **nothing in the deliverable can recompute it**. Nor can the shadow
48
- week turn the range into a measured percentage: the shadow report outputs four ratios only (see
49
- "Shadow week"), with no total-token denominator, and `boost status` carries absolute values only;
50
- 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.
51
61
 
52
62
  ## Requirements
53
63
 
54
- - Node.js `>=24.9.0` and DSH `0.2.2-rc.4` (an exact pin, not a range; both in `package.json`
55
- `engines`; the Node floor matches the host `@deepseek-ai/dsh@0.2.2-rc.4`).
64
+ - Node.js `>=24.9.0` and DSH `>=0.2.2-rc.4 <0.2.3-0` (a **range**, not an exact pin: the host
65
+ evaluates it with `includePrerelease` semantics and disables the plugin on a miss, while
66
+ `0.2.2-rc.5` is byte-identical to rc.4 in every host package this plugin touches). Both live in
67
+ `package.json` `engines`; the Node floor matches the host `@deepseek-ai/dsh@0.2.2-rc.4`.
56
68
  - **The package declares no peerDependencies**: installing it pulls in no `@deepseek-ai/*`
57
69
  package, and the module loads without any of them; the runtime capabilities (`tokenMeter`,
58
70
  `spillStore`, the estimator, the footer formatter) are provided by the DSH host process, and a
@@ -68,16 +80,29 @@ replacing the range with measurements needs a denominator statistic that a later
68
80
  directory:
69
81
 
70
82
  ```bash
71
- # install from the registry (0.1.0 is the first release and is latest)
72
- dsh plugin --profile <name> add dsh-boost@^0.1.0
83
+ # install from the registry: npmjs has latest = 0.1.2 (this repository's
84
+ # .npmrc and lockfile are pinned to npmjs too — see below)
85
+ dsh plugin --profile <name> add dsh-boost@^0.1.2 --registry=https://registry.npmjs.org/
73
86
 
74
87
  # or from a local checkout (build first; dist/ is not committed)
75
88
  npm run build
76
89
  dsh plugin --profile <name> add /absolute/path/to/dsh-boost
77
90
  ```
78
91
 
79
- For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.0`. `dsh plugin` forwards the operation
80
- to pnpm, so pnpm must be on `PATH`.
92
+ For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.2 --registry=https://registry.npmjs.org/`.
93
+ `dsh plugin` forwards the operation to pnpm, so pnpm must be on `PATH`.
94
+
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.
81
106
 
82
107
  The package is ESM (`"type": "module"`) and the `.` entry of `exports` also maps `require` /
83
108
  `default`: on Node >= 24.9, `require('dsh-boost')` loads the very same code as `import`. Nothing
@@ -110,8 +135,8 @@ equivalent. In the conversation, ask the agent to call it, for example:
110
135
  > Call the boost tool with `{"cmd":"status"}` and show me the JSON.
111
136
 
112
137
  The first `status` should answer `ok: true`, with `data.scope.workspaceIds` empty, `revision` `0`,
113
- `shadow` `true`, `projection` `"shadow"`, and `counts` empty (in a fresh session — any earlier tool
114
- 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
115
140
  **not** report `ERR_SCOPE_READ_FAILED` merely because `scope.json` is missing: a missing file is
116
141
  the clean default (`ENOENT` carries no degradation code, `src/scope/store.ts`); on a fresh root
117
142
  with the host capabilities in place, `degraded` is simply an empty array. On the `status` read
@@ -136,10 +161,14 @@ Then list the workspace to expose:
136
161
 
137
162
  - `workspaceIds` are the host's workspace UUIDs, not paths; the host maps the agent's cwd to this
138
163
  id through its workspace registry. **Finding the UUID is itself friction**: either ask the
139
- host / dig through session records, or read `tables.workspaces` (the id ↔ path table) in
140
- `$DSH_HOME/storages/workspace.json` yourself — v1 ships no command that does this for you. If
141
- you cannot find the UUID and this is a single-user machine, `"mode": "global"` widens the
142
- scope to every *defined* workspace; sessions with no workspace stay invisible.
164
+ host / dig through session records, or read `tables.workspaces` (the id ↔ path table) in the
165
+ host's `<hostDshHome>/storages/workspace.json` yourself — v1 ships no command that does this
166
+ for you. The host resolves its home as "a non-empty `$DSH_HOME` (`~` expands) → `~/.dsh`", so
167
+ on a default install the file is `~/.dsh/storages/workspace.json`, **not**
168
+ `$DSH_HOME/storages/workspace.json` (unless `$DSH_HOME` is actually set). Note that
169
+ `config.dshHome` moves only the plugin's `<dshHome>/boost`, never this host file. If you cannot
170
+ find the UUID and this is a single-user machine, `"mode": "global"` widens the scope to every
171
+ *defined* workspace; sessions with no workspace stay invisible.
143
172
  - `baseRevision` is `data.scope.revision` from the status you just read (`0` for the first write).
144
173
  This is compare-and-swap: a stale revision returns `ERR_SCOPE_REVISION_CONFLICT`; read `status`
145
174
  again and retry. When the caller's cancellation signal interrupts the write, the tool returns
@@ -159,7 +188,7 @@ After the write, call `status` again. A healthy result looks like this:
159
188
  `"host"` because the token-meter service is present — the two are different things.
160
189
  - `data.counts` usually starts empty — but **control calls count too**: while no workspace is
161
190
  visible, `boost`'s own calls pass the same post-execute scope gate (there is no boost exemption
162
- 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
163
192
  after normal tool calls, for example with `projection-shadow` entries.
164
193
 
165
194
  Excerpt (illustrative values; ledger fields omitted):
@@ -198,21 +227,28 @@ above a workspace is selected, so 778 is the true per-request cost there.
198
227
 
199
228
  The design chose **shadow first**: record for a week — no synthesized turns, no skipped calls,
200
229
  projection priced but never applied — then decide whether to project and substitute for real.
201
- **"Changes nothing the model sees" would be false**: whenever a workspace is visible the protocol
202
- section (379 tokens) is injected into the system prompt, and a multi-candidate plan still makes a
203
- **real selector call** (a separate auxiliary model request). By design the shadow week saves
204
- 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**.
205
236
 
206
237
  Of those ratios, `saveableRatio`, `byFamily`, and `candidateRecall` can decide **whether the
207
238
  substitution side is worth turning on**: how many substitution decisions the whitelist could
208
239
  actually deliver, which tool families the hits land in, and how high candidate recall is — that
209
- is, whether substitution would fire at all and where. They **cannot decide release**: that
210
- decision was fixed during design; v1 ships as a normal release and does not gate on shadow-week
211
- savings. They also **cannot measure savings**: the report has no total-token denominator, and
240
+ is, whether substitution would fire at all and where. They **cannot decide release**: v1 ships as
241
+ a normal release and does not gate on shadow-week savings — and that call was the
242
+ **implementer's** decision during design, not a user ruling. The user accepted a one-week shadow
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
212
244
  `retrievalUpperBound` is structurally `0` during the shadow week (it only counts applied
213
245
  `projection:'on'` retrievals), so it cannot even bound projection's retrieval damage. Projection
214
- is released on the visibility contract (the original stays retrievable through the footer) and
215
- 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.
216
252
  `scope.json` has two independent switches:
217
253
 
218
254
  | Switch | Value | Behaviour |
@@ -239,7 +275,8 @@ The recommended sequence:
239
275
  (recall of the candidate set), and `retrievalUpperBound` (retrieval upper bound; structurally
240
276
  `0` during the shadow week because nothing is projected for real).
241
277
  3. **Turn on projection**: projection is not released on shadow labels (its basis is the
242
- 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
243
280
  `shadow: true` and set `projection` to `'on'`:
244
281
 
245
282
  ```json
@@ -294,11 +331,11 @@ cap is 256 KiB, so `300000` prevents the family from triggering at all (there is
294
331
  Characters are Unicode code points. Error receipts and receipts above 256 KiB are never projected.
295
332
 
296
333
  The invariant is **not** `triggerChars >= headChars + tailChars + 1`. The real replacement is head
297
- line + head + footer + tail + 3 newlines; the footer is produced by the host's `formatSpillNotice`
298
- and is about 196 characters (68-character locator, 5-digit omitted-byte count, the host's fixed
299
- retrieval hint). With the grep/glob defaults of 400+100:
300
- `400 + 100 + 50 (head line) + 196 (footer) + 3 = 749 > 700`. So a receipt just over 700 — up to
301
- about 749 — is judged cuttable by `truncate`, but `projectApply` assembles a replacement that is
334
+ line + head + footer + tail + 3 newlines; the footer is produced by the host's `formatSpillNotice`.
335
+ With a 68-character locator and the host's fixed 66-character retrieval hint, a 3-digit
336
+ omitted-byte count gives 190 characters and a 5-digit count gives 192. With the grep/glob defaults
337
+ of 400+100: `400 + 100 + 50 (head line) + 190 (footer) + 3 = 743 > 700` (745 with a 5-digit count).
338
+ So a receipt just over 700 — up to about 743 — is judged cuttable by `truncate`, but `projectApply` assembles a replacement that is
302
339
  not shorter than the original and returns the original. That is a dead band, not a net loss. The
303
340
  runtime `assembled.length >= text.length` check guarantees projection never makes a receipt
304
341
  longer; to remove the dead band, raise `triggerChars` to at least that sum (for example 800 for
@@ -358,23 +395,71 @@ set it falls back to `~/.dsh`; the assembly log prints the resolved `root=` (tha
358
395
 
359
396
  - `scope.json` — the single source of truth for the exposure surface (version 2, with revision).
360
397
  - `scope.lock` — the short-lived write lock, removed after a normal write.
361
- - `receipts/<encoded-session>.jsonl` — append-only receipts. Every line carries metadata, a
362
- preview of the first 256 code points of the receipt (never the full stdout), and **the bound
363
- arguments `args` (model-written: above 2048 code points they are stored as visibly truncated
364
- JSON with an `args_truncated` flag; nesting deeper than 64 levels sets `args_depth_truncated`
365
- and replaces the deeper subtree with `{ "truncated_depth": 64 }` — `write` / `edit` arguments
366
- can carry whole file contents and land here too)**. **Only substitution receipts** also carry
367
- the plan goal (≤256 code points) and guards (≤8, each ≤300 code points): `kind:'substitute'`,
368
- `kind:'substitute-settled'`, and `kind:'shadow'` with `code:'ok'`. `kind:'shadow'` is not
369
- substitution-only — projection shadowing also writes `kind:'shadow'`, but with
370
- `code:'projection-shadow'`, and that is a projection receipt with no plan evidence; projection
371
- and skip receipts carry `preview` and `args` only.
398
+ - `receipts/<encoded-session>.jsonl` — append-only receipts. **A receipt is written per
399
+ decision, not per call**: a line appears only for a projection, a substitution decision
400
+ (including skips), or an out-of-scope `skip:no-scope`. A `write` / `edit` with no plan produces
401
+ **no receipt at all**, so its arguments are never recorded. Every line carries metadata, a
402
+ preview of the first 256 code points of the receipt (never the full stdout), and that call's
403
+ bound `args` (model-written: above 2048 code points they are stored as visibly truncated JSON
404
+ with an `args_truncated` flag; nesting deeper than 64 levels sets `args_depth_truncated` and
405
+ replaces the deeper subtree with `{ "truncated_depth": 64 }`). **Only substitution receipts**
406
+ also carry the plan goal (≤256 code points) and guards (≤8, each ≤300 code points):
407
+ `kind:'substitute'`, `kind:'substitute-settled'`, and `kind:'shadow'` with `code:'ok'`.
408
+ `kind:'shadow'` is not substitution-only — projection shadowing also writes `kind:'shadow'`,
409
+ but with `code:'projection-shadow'`, and that is a projection receipt with no plan evidence.
410
+ **Projection receipts** (`kind:'projection'`, `code:'projected'`, and the projection shadow)
411
+ carry `before` / `after` / `saved_projection_tokens` / `unit` / `estimate` / `horizon_steps`;
412
+ without a token meter only `estimate:'unknown'` is written and the three numeric fields are
413
+ omitted entirely. **Retrieval receipts** (`kind:'projection'`, `code:'projection-retrieval'`)
414
+ carry `locator` plus `retrieval_call_tokens` / `retrieval_content_tokens` / `retrieval_tokens`;
415
+ those three are written only when the retrieval was priced, and an unpriced one has
416
+ `estimate:'unknown'` with the fields omitted. `skip` receipts carry only `preview` and `args`
417
+ (`skip:no-scope` carries neither — just the tool name).
418
+
419
+ When the current shard exceeds 8 MiB or 20,000 lines, the next write first rotates it to
420
+ `<encoded-session>.1.jsonl`; only the current shard and its predecessor are kept (an older `.1`
421
+ is overwritten). `boost status` reads `.1` before the current shard. The 256-shard cap counts
422
+ **encoded session names**: a rotated `.1.jsonl` belongs to the same name and takes no extra
423
+ slot, though the scan reads both files under that name.
372
424
 
373
425
  `boost status` replays the projection ledger at each receipt's own `horizon_steps`; a receipt
374
426
  written before that field existed is replayed at the current horizon and counted in
375
427
  `projection_horizon_reestimated`, while `projection_horizon_steps` reports the horizon currently
376
428
  in effect (the minimum over live sessions, falling back to `horizonSteps` when no history exists).
377
429
 
430
+ `status.data` also carries several status and ledger fields that never appear in `degraded`:
431
+
432
+ - `receipts_stopped`: `true` once receipt writes have failed 3 times in a row. Substitution is then
433
+ refused **entirely** (fail closed — no further selector call or step budget is spent), projection
434
+ continues, and every ledger figure is the snapshot from before the writes stopped. The count
435
+ clears and the field returns to `false` after a write succeeds. This is the only place that says
436
+ "receipts have stopped" — there is no `degraded` code for it.
437
+ - `protocol_suppressed`: how many times the protocol section was dropped at assembly (invisible
438
+ workspace, a diagnostic assembly with no agent, and a `complete: true` override). Assembly runs
439
+ per request, so this only counts — it writes no receipt.
440
+ - `projection_locator_evictions`: locators dropped because of the per-session cap (512, oldest
441
+ first); above 0 means the retrieval ledger has losses.
442
+ - `projection_unknown_families`: calls carrying an `mcp__` prefix that reached projection but
443
+ matched no tool family; `projection_unknown_tools` is the retained unmapped tool names with
444
+ counts (at most 32), for spotting mapper gaps.
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.
462
+
378
463
  With `projection: 'on'`, the complete original is written to the host spill backend **before** the
379
464
  replacement happens, and the footer locator can be read with `read` / `grep`. Projection never
380
465
  discards the only copy; if the spill write fails, nothing is replaced (the receipt records
@@ -426,7 +511,7 @@ to load. `llm` is soft (only the selector uses it); when absent the selector fal
426
511
  | `workspaceRegistry` | soft (`ctx.get('workspaceRegistry')`) | **The workspace is invisible**: a cwd can never map to a workspace id, so everything fails closed as invisible — no protocol section, projection and substitution all skipped, only `skip:no-scope` receipts accumulating; `status.degraded` reports `ERR_HOST_NO_WORKSPACE_REGISTRY`. This is the host-capability explanation **when a workspace should be visible**, not the only explanation for "installed but nothing happens": the shipped default `selected + []` is inert by design and reports no error; a missing token meter also refuses real substitution; a `complete: true` section also suppresses the protocol |
427
512
  | `tokenMeter` | soft (`ctx.get('tokenMeter')`) | Substitution is refused; projection keeps working and its accounting records `unknown` (never a fabricated number); `status.degraded` reports `ERR_HOST_NO_TOKENMETER` |
428
513
  | `spillStore` | soft (`ctx.get('spillStore')`) | With `projection: 'on'`, an over-limit receipt is not projected (evidence preserved) and the receipt records `projection-skipped:no-spill`; `status.degraded` reports `ERR_HOST_NO_SPILL` (the live probe only in on mode; a historical receipt reports it in any mode) |
429
- | `@deepseek-ai/dsh-spill-policy/notice` | soft (dynamic import) | The spill backend exists but the footer renderer `formatSpillNotice` cannot be loaded/is absent: apply-mode projection cannot build its footer and skips every receipt (`projection-skipped:no-footer`); `status.degraded` reports `ERR_HOST_NO_SPILL_NOTICE`. This is a different absence from `ERR_HOST_NO_SPILL` (no spill backend at all) |
514
+ | `@deepseek-ai/dsh-spill-policy/notice` | soft (dynamic import) | The spill backend exists but the footer renderer `formatSpillNotice` cannot be loaded/is absent: apply-mode projection cannot build its footer and skips every receipt (`projection-skipped:no-footer`; a throw while rendering records `projection-skipped:footer-failed`); `status.degraded` reports `ERR_HOST_NO_SPILL_NOTICE`. This is a different absence from `ERR_HOST_NO_SPILL` (no spill backend at all) |
430
515
  | (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 |
431
516
  | `@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` |
432
517
  | `win32` platform | runtime `isPosixOnly()` check | Substitution is refused, projection still works; `status.degraded` reports `ERR_HOST_PLATFORM_UNSUPPORTED` |
@@ -479,10 +564,15 @@ evidence" degraded path would be unreachable.
479
564
  v1 ships **no tool that measures duplicate-call rate**: the "shadow-week duplication
480
565
  statistic" the design reserved as its restart trigger was never delivered; `shadow-report.mjs`
481
566
  does not produce it.
482
- - **The shadow week saves nothing by design**: it only records (the protocol section is still
483
- injected and the selector is still called); its output is four ratios, not saved tokens.
484
- - **v1 does not judge "better results"**: there is a token ledger and a 20-task regression gate,
485
- no quality metric; whether substituted outcomes are better is unjudgeable in v1.
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.
570
+ - **v1 does not judge "better results"**: there is a token ledger and a **manual** 20-task
571
+ regression procedure (the task set does not ship with the package; see `docs/RELEASE.md` §3),
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.
486
576
  - **Projection is truncation, not refinement**: it keeps the head and tail and drops the middle;
487
577
  the before/after token difference in the ledger measures *shorter*, not *more relevant*. The
488
578
  dropped middle may be exactly what the next decision needs — with `projection: 'on'` the
@@ -518,7 +608,7 @@ The source and docs live in the repository at
518
608
  | [Design](docs/superpowers/specs/2026-11-18-dsh-token-efficiency-design.md) | Goals, evidence, architecture, contracts, measurement, risks, release shape |
519
609
  | [Host contracts appendix](docs/superpowers/plans/2026-11-18-host-contracts.md) | Interface reference copied line by line from the host sources |
520
610
  | [Three-tier delegation research](docs/research/2026-11-18-three-tier-delegation.md) | 25 primary sources on caching, routing thresholds, compression, and verification |
521
- | [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 gate, 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 |
522
612
 
523
613
  ## License
524
614