dsh-boost 0.1.0 → 0.1.2

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 (54) hide show
  1. package/README.en.md +184 -70
  2. package/README.md +148 -59
  3. package/dist/gate/decide.js +33 -2
  4. package/dist/gate/decide.js.map +1 -1
  5. package/dist/hooks/llm-stream.js +242 -89
  6. package/dist/hooks/llm-stream.js.map +1 -1
  7. package/dist/hooks/post-execute.js +282 -25
  8. package/dist/hooks/post-execute.js.map +1 -1
  9. package/dist/hooks/session-state.js +18 -8
  10. package/dist/hooks/session-state.js.map +1 -1
  11. package/dist/host/root.js +22 -1
  12. package/dist/host/root.js.map +1 -1
  13. package/dist/index.js +494 -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 +37 -4
  19. package/dist/tools/boost.js.map +1 -1
  20. package/dist/types.d.ts +18 -1
  21. package/dist/types.js.map +1 -1
  22. package/package.json +10 -6
  23. package/dist/admission/fixed-cost.d.ts +0 -23
  24. package/dist/admission/ledger.d.ts +0 -113
  25. package/dist/admission/retrieval.d.ts +0 -65
  26. package/dist/admission/usage.d.ts +0 -75
  27. package/dist/config.d.ts +0 -43
  28. package/dist/gate/binding.d.ts +0 -113
  29. package/dist/gate/decide.d.ts +0 -82
  30. package/dist/gate/guard.d.ts +0 -69
  31. package/dist/gate/invalidate.d.ts +0 -112
  32. package/dist/gate/plan.d.ts +0 -86
  33. package/dist/hooks/clock.d.ts +0 -68
  34. package/dist/hooks/execute.d.ts +0 -79
  35. package/dist/hooks/llm-stream.d.ts +0 -276
  36. package/dist/hooks/pending.d.ts +0 -89
  37. package/dist/hooks/post-execute.d.ts +0 -247
  38. package/dist/hooks/session-state.d.ts +0 -158
  39. package/dist/hooks/synthesize.d.ts +0 -74
  40. package/dist/host/loader.d.ts +0 -23
  41. package/dist/host/platform.d.ts +0 -18
  42. package/dist/host/root.d.ts +0 -18
  43. package/dist/projection/apply.d.ts +0 -174
  44. package/dist/projection/canonicalise.d.ts +0 -43
  45. package/dist/projection/counters.d.ts +0 -65
  46. package/dist/projection/truncate.d.ts +0 -47
  47. package/dist/prompt/protocol.d.ts +0 -45
  48. package/dist/receipts/store.d.ts +0 -198
  49. package/dist/scope/doc.d.ts +0 -117
  50. package/dist/scope/resolve.d.ts +0 -91
  51. package/dist/scope/store.d.ts +0 -135
  52. package/dist/selector/jev.d.ts +0 -93
  53. package/dist/tools/boost.d.ts +0 -367
  54. package/dist/tools/family.d.ts +0 -26
package/README.en.md CHANGED
@@ -4,12 +4,14 @@ Cut DeepSeek Harness (DSH) token usage with **tool-receipt projection** and **de
4
4
  read-only substitution**.
5
5
 
6
6
  > **Status: v1 is implemented.** Projection, substitution, and the control surface are all in
7
- > place; `npm run build` is clean and the full test suite passes.
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
10
 
9
11
  ## What it does
10
12
 
11
13
  DSH replays the whole history on every model request. Across the 300 longest sessions measured
12
- 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.1 stats`
13
15
  banner to stdout, so use `--silent` or `node scripts/session-stats.mjs` for machine-readable
14
16
  output; snapshot at `2026-11-19T03:13:21Z`): 54,141 steps and 54,088 requests,
15
17
  10,575,904,022 raw tokens in total. The mean is 195,340 tokens per step and 195,531 per request
@@ -22,28 +24,44 @@ The plugin does two things:
22
24
  1. **Projection** — before a tool receipt enters the context, keep its head and tail per tool
23
25
  family and replace the middle with a retrievable on-disk handle. The original stays readable;
24
26
  the footer names the path. Projection is deterministic and makes no per-call decision.
25
- 2. **Substitution** — when a repeated read-only call (`read` / `grep` / `glob`) already has
26
- deterministic evidence satisfying its guard, commit it without asking the model for another
27
+ 2. **Substitution** — when a repeated read-only call (`read` / `grep` / `glob`) in a plan already
28
+ has deterministic evidence satisfying its guard, commit it without asking the model for another
27
29
  decision. With several candidates, a single-label selector — one auxiliary request
28
- (`maxTokens` 512 plus its input) — picks one. For the three substituted tools, the plan's
30
+ (`maxTokens` 512 plus its input) — picks one. This is a **narrowing** of original requirement
31
+ 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
34
+ [clarification record](docs/superpowers/clarifications/2026-11-18-dsh-token-efficiency.md)).
35
+ For the three substituted tools, the plan's
29
36
  `$public` argument binding (copying a value from an earlier receipt into a later call's
30
37
  arguments) is effective in practice only for `glob`'s single-token output; `read` and `grep`
31
38
  emit line-numbered or bare-path output that the identifier projection cannot match, so those
32
39
  calls fall back to the model.
33
40
 
34
- The expected v1 range is **3.5% (floor) to 10.0% (ceiling)** of raw `totalTokens`. It was
35
- **estimated offline, ex ante** against a 300-session corpus during design: not a guarantee, and
36
- not a figure the shipped `session-snapshot.json` can recompute (the snapshot stores aggregate
37
- counts only, not the components of the estimate) — **nothing in the deliverable can recompute
38
- it**. Nor can the shadow week turn the range into a measured percentage: the shadow report
39
- outputs four ratios only (see "Shadow week"), with no total-token denominator, and `boost
40
- status` carries absolute values only; replacing the range with measurements needs a denominator
41
- statistic that a later version must add.
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
+
48
+ The **ex-ante estimate** for v1 is **3.5% (lower bound) to 10.0% (ideal upper bound)** of raw
49
+ `totalTokens`; **3.5% is not a floor** — it is the lower bound of an offline estimate against a
50
+ 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.
42
58
 
43
59
  ## Requirements
44
60
 
45
- - Node.js `>=24.9.0` and DSH `0.2.2-rc.4` (an exact pin, not a range; both in `package.json`
46
- `engines`; the Node floor matches the host `@deepseek-ai/dsh@0.2.2-rc.4`).
61
+ - Node.js `>=24.9.0` and DSH `>=0.2.2-rc.4 <0.2.3-0` (a **range**, not an exact pin: the host
62
+ evaluates it with `includePrerelease` semantics and disables the plugin on a miss, while
63
+ `0.2.2-rc.5` is byte-identical to rc.4 in every host package this plugin touches). Both live in
64
+ `package.json` `engines`; the Node floor matches the host `@deepseek-ai/dsh@0.2.2-rc.4`.
47
65
  - **The package declares no peerDependencies**: installing it pulls in no `@deepseek-ai/*`
48
66
  package, and the module loads without any of them; the runtime capabilities (`tokenMeter`,
49
67
  `spillStore`, the estimator, the footer formatter) are provided by the DSH host process, and a
@@ -59,16 +77,28 @@ statistic that a later version must add.
59
77
  directory:
60
78
 
61
79
  ```bash
62
- # install from the registry (0.1.0 is the first release; latest will be 0.1.0)
63
- dsh plugin --profile <name> add dsh-boost@^0.1.0
80
+ # install from the registry: npmjs has latest = 0.1.1 (this repository's
81
+ # .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/
64
83
 
65
84
  # or from a local checkout (build first; dist/ is not committed)
66
85
  npm run build
67
86
  dsh plugin --profile <name> add /absolute/path/to/dsh-boost
68
87
  ```
69
88
 
70
- For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.0`. `dsh plugin` forwards the operation
71
- to pnpm, so pnpm must be on `PATH`.
89
+ For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.1 --registry=https://registry.npmjs.org/`.
90
+ `dsh plugin` forwards the operation to pnpm, so pnpm must be on `PATH`.
91
+
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.
72
102
 
73
103
  The package is ESM (`"type": "module"`) and the `.` entry of `exports` also maps `require` /
74
104
  `default`: on Node >= 24.9, `require('dsh-boost')` loads the very same code as `import`. Nothing
@@ -102,9 +132,13 @@ equivalent. In the conversation, ask the agent to call it, for example:
102
132
 
103
133
  The first `status` should answer `ok: true`, with `data.scope.workspaceIds` empty, `revision` `0`,
104
134
  `shadow` `true`, `projection` `"shadow"`, and `counts` empty (in a fresh session — any earlier tool
105
- call from an out-of-scope session has already recorded `skip:no-scope`). `degraded` containing
106
- `ERR_SCOPE_READ_FAILED` is expected: `scope.json` does not exist yet, so the plugin is on its
107
- fail-closed default. The first successful `scope-set` creates the file.
135
+ call from an out-of-scope session has already recorded `skip:no-scope`). The first `status` does
136
+ **not** report `ERR_SCOPE_READ_FAILED` merely because `scope.json` is missing: a missing file is
137
+ the clean default (`ENOENT` carries no degradation code, `src/scope/store.ts`); on a fresh root
138
+ with the host capabilities in place, `degraded` is simply an empty array. On the `status` read
139
+ path,
140
+ `ERR_SCOPE_READ_FAILED` means the file **exists but cannot be read** (permissions, I/O, a
141
+ directory in its place, …) — not a normal first run; fix it first. The first successful `scope-set` creates the file.
108
142
 
109
143
  Then list the workspace to expose:
110
144
 
@@ -123,10 +157,14 @@ Then list the workspace to expose:
123
157
 
124
158
  - `workspaceIds` are the host's workspace UUIDs, not paths; the host maps the agent's cwd to this
125
159
  id through its workspace registry. **Finding the UUID is itself friction**: either ask the
126
- host / dig through session records, or read `tables.workspaces` (the id ↔ path table) in
127
- `$DSH_HOME/storages/workspace.json` yourself — v1 ships no command that does this for you. If
128
- you cannot find the UUID and this is a single-user machine, `"mode": "global"` widens the
129
- scope to every *defined* workspace; sessions with no workspace stay invisible.
160
+ host / dig through session records, or read `tables.workspaces` (the id ↔ path table) in the
161
+ host's `<hostDshHome>/storages/workspace.json` yourself — v1 ships no command that does this
162
+ for you. The host resolves its home as "a non-empty `$DSH_HOME` (`~` expands) → `~/.dsh`", so
163
+ on a default install the file is `~/.dsh/storages/workspace.json`, **not**
164
+ `$DSH_HOME/storages/workspace.json` (unless `$DSH_HOME` is actually set). Note that
165
+ `config.dshHome` moves only the plugin's `<dshHome>/boost`, never this host file. If you cannot
166
+ find the UUID and this is a single-user machine, `"mode": "global"` widens the scope to every
167
+ *defined* workspace; sessions with no workspace stay invisible.
130
168
  - `baseRevision` is `data.scope.revision` from the status you just read (`0` for the first write).
131
169
  This is compare-and-swap: a stale revision returns `ERR_SCOPE_REVISION_CONFLICT`; read `status`
132
170
  again and retry. When the caller's cancellation signal interrupts the write, the tool returns
@@ -188,7 +226,20 @@ projection priced but never applied — then decide whether to project and subst
188
226
  **"Changes nothing the model sees" would be false**: whenever a workspace is visible the protocol
189
227
  section (379 tokens) is injected into the system prompt, and a multi-candidate plan still makes a
190
228
  **real selector call** (a separate auxiliary model request). By design the shadow week saves
191
- nothing; it produces only the four ratios below. `scope.json` has two independent switches:
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
+ `scope.json` has two independent switches:
192
243
 
193
244
  | Switch | Value | Behaviour |
194
245
  |---|---|---|
@@ -203,16 +254,19 @@ The recommended sequence:
203
254
  1. **Week one**: use `shadow: true` and `projection: 'shadow'` with the `scope-set` above, and work
204
255
  normally.
205
256
  2. **Read the report**: from a repository checkout, run
206
- `node scripts/shadow-report.mjs --dir "${DSH_HOME:-$HOME/.dsh}/boost/receipts"`. The script is
207
- dev-only and is not in the npm tarball. It prints four labels:
257
+ `node scripts/shadow-report.mjs --dir "<root>/receipts"`, where `<root>` is the `root=` printed
258
+ by the assembly log (that is, `<dshHome>/boost`; `dshHome` config wins over `$DSH_HOME`, and
259
+ with neither set it falls back to `~/.dsh`). The script is dev-only and is not in the npm
260
+ tarball. It prints four labels:
208
261
  `saveableRatio` (the share of substitution the v1 whitelist could actually deliver: whitelisted
209
262
  shadow commits over **all** substitution decisions — the denominator is every substitution
210
263
  decision, not just the whitelisted calls; shadow mode records every family, so bash/ssh
211
264
  potential shows up in `byFamily`), `byFamily` (hit rate per candidate family), `candidateRecall`
212
265
  (recall of the candidate set), and `retrievalUpperBound` (retrieval upper bound; structurally
213
266
  `0` during the shadow week because nothing is projected for real).
214
- 3. **Turn on projection**: if the report supports it, keep `shadow: true` and set `projection` to
215
- `'on'`:
267
+ 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'`:
216
270
 
217
271
  ```json
218
272
  { "cmd": "scope-set", "body": { "projection": "on" }, "baseRevision": 1 }
@@ -220,8 +274,9 @@ The recommended sequence:
220
274
 
221
275
  `scope-set` patches only the fields you pass; everything else stays as it was. Receipts now get
222
276
  replaced, while substitution decisions are still recorded only.
223
- 4. **Turn on substitution**: just switch the shadow off — **checking before the switch is a
224
- no-op**: the shadow week never synthesizes a turn, so a `content[].thinking` 400 is
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
279
+ week never synthesizes a turn, so a `content[].thinking` 400 is
225
280
  structurally impossible and a check made before switching it off can only ever read "not
226
281
  seen". After `shadow` becomes `false`, check for that 400 in the **first genuinely
227
282
  substituted round** as described in [`docs/RELEASE.md`](docs/RELEASE.md) §4, and keep
@@ -265,11 +320,11 @@ cap is 256 KiB, so `300000` prevents the family from triggering at all (there is
265
320
  Characters are Unicode code points. Error receipts and receipts above 256 KiB are never projected.
266
321
 
267
322
  The invariant is **not** `triggerChars >= headChars + tailChars + 1`. The real replacement is head
268
- line + head + footer + tail + 3 newlines; the footer is produced by the host's `formatSpillNotice`
269
- and is about 196 characters (68-character locator, 5-digit omitted-byte count, the host's fixed
270
- retrieval hint). With the grep/glob defaults of 400+100:
271
- `400 + 100 + 50 (head line) + 196 (footer) + 3 = 749 > 700`. So a receipt just over 700 — up to
272
- about 749 — is judged cuttable by `truncate`, but `projectApply` assembles a replacement that is
323
+ line + head + footer + tail + 3 newlines; the footer is produced by the host's `formatSpillNotice`.
324
+ With a 68-character locator and the host's fixed 66-character retrieval hint, a 3-digit
325
+ 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).
327
+ So a receipt just over 700 — up to about 743 — is judged cuttable by `truncate`, but `projectApply` assembles a replacement that is
273
328
  not shorter than the original and returns the original. That is a dead band, not a net loss. The
274
329
  runtime `assembled.length >= text.length` check guarantees projection never makes a receipt
275
330
  longer; to remove the dead band, raise `triggerChars` to at least that sum (for example 800 for
@@ -323,24 +378,66 @@ silently.
323
378
 
324
379
  ## State, rollback, and removal
325
380
 
326
- State lives in `$DSH_HOME/boost/` (`$DSH_HOME` falls back to `~/.dsh` when unset):
381
+ State lives in `<dshHome>/boost/`: `dshHome` config **wins over** `$DSH_HOME`, and with neither
382
+ set it falls back to `~/.dsh`; the assembly log prints the resolved `root=` (that is,
383
+ `<dshHome>/boost`).
327
384
 
328
385
  - `scope.json` — the single source of truth for the exposure surface (version 2, with revision).
329
386
  - `scope.lock` — the short-lived write lock, removed after a normal write.
330
- - `receipts/<encoded-session>.jsonl` — append-only receipts. Every line carries metadata, a
331
- preview of the first 256 code points of the receipt (never the full stdout), and **the bound
332
- arguments `args` (model-written, capped to 2048 code points, stored as visibly truncated JSON
333
- with an `args_truncated` flag when oversized — `write` / `edit` arguments can carry whole file
334
- contents and land here too)**. **Only substitution receipts** (`substitute` /
335
- `substitute-settled` / `shadow`) also carry the plan goal (≤256 code points) and guards (≤8,
336
- each ≤300 code points); projection and skip receipts carry `preview` and `args` but no plan
337
- evidence.
387
+ - `receipts/<encoded-session>.jsonl` — append-only receipts. **A receipt is written per
388
+ 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**
395
+ also carry the plan goal (≤256 code points) and guards (≤8, each ≤300 code points):
396
+ `kind:'substitute'`, `kind:'substitute-settled'`, and `kind:'shadow'` with `code:'ok'`.
397
+ `kind:'shadow'` is not substitution-only — projection shadowing also writes `kind:'shadow'`,
398
+ but with `code:'projection-shadow'`, and that is a projection receipt with no plan evidence.
399
+ **Projection receipts** (`kind:'projection'`, `code:'projected'`, and the projection shadow)
400
+ carry `before` / `after` / `saved_projection_tokens` / `unit` / `estimate` / `horizon_steps`;
401
+ without a token meter only `estimate:'unknown'` is written and the three numeric fields are
402
+ omitted entirely. **Retrieval receipts** (`kind:'projection'`, `code:'projection-retrieval'`)
403
+ carry `locator` plus `retrieval_call_tokens` / `retrieval_content_tokens` / `retrieval_tokens`;
404
+ those three are written only when the retrieval was priced, and an unpriced one has
405
+ `estimate:'unknown'` with the fields omitted. `skip` receipts carry only `preview` and `args`
406
+ (`skip:no-scope` carries neither — just the tool name).
407
+
408
+ When the current shard exceeds 8 MiB or 20,000 lines, the next write first rotates it to
409
+ `<encoded-session>.1.jsonl`; only the current shard and its predecessor are kept (an older `.1`
410
+ is overwritten). `boost status` reads `.1` before the current shard. The 256-shard cap counts
411
+ **encoded session names**: a rotated `.1.jsonl` belongs to the same name and takes no extra
412
+ slot, though the scan reads both files under that name.
338
413
 
339
414
  `boost status` replays the projection ledger at each receipt's own `horizon_steps`; a receipt
340
415
  written before that field existed is replayed at the current horizon and counted in
341
416
  `projection_horizon_reestimated`, while `projection_horizon_steps` reports the horizon currently
342
417
  in effect (the minimum over live sessions, falling back to `horizonSteps` when no history exists).
343
418
 
419
+ `status.data` also carries several status and ledger fields that never appear in `degraded`:
420
+
421
+ - `receipts_stopped`: `true` once receipt writes have failed 3 times in a row. Substitution is then
422
+ refused **entirely** (fail closed — no further selector call or step budget is spent), projection
423
+ continues, and every ledger figure is the snapshot from before the writes stopped. The count
424
+ clears and the field returns to `false` after a write succeeds. This is the only place that says
425
+ "receipts have stopped" — there is no `degraded` code for it.
426
+ - `protocol_suppressed`: how many times the protocol section was dropped at assembly (invisible
427
+ workspace, a diagnostic assembly with no agent, and a `complete: true` override). Assembly runs
428
+ per request, so this only counts — it writes no receipt.
429
+ - `projection_locator_evictions`: locators dropped because of the per-session cap (512, oldest
430
+ first); above 0 means the retrieval ledger has losses.
431
+ - `projection_unknown_families`: calls carrying an `mcp__` prefix that reached projection but
432
+ matched no tool family; `projection_unknown_tools` is the retained unmapped tool names with
433
+ 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.
440
+
344
441
  With `projection: 'on'`, the complete original is written to the host spill backend **before** the
345
442
  replacement happens, and the footer locator can be read with `read` / `grep`. Projection never
346
443
  discards the only copy; if the spill write fails, nothing is replaced (the receipt records
@@ -348,9 +445,10 @@ discards the only copy; if the spill write fails, nothing is replaced (the recei
348
445
  `projection-skipped:footer-failed`; a missing footer renderer records
349
446
  `projection-skipped:no-footer`, see "Host dependencies").
350
447
 
351
- Rollback and disablement (the `baseRevision` values below are `3` after the enable path above and
352
- `4` after the first rollback; in practice always use the `data.scope.revision` you just read from
353
- `status`, never copy these):
448
+ Rollback and disablement (the `baseRevision` values below are `3` after the recommended
449
+ "Enable it" + "Shadow week" sequence — enablement ends at `1`, and the two shadow-week steps add
450
+ one each — and `4` after the first rollback; in practice always use the `data.scope.revision` you
451
+ just read from `status`, never copy these):
354
452
 
355
453
  - **Turn both behaviours off** (no projection, no substitution; the protocol section is still
356
454
  injected for every still-visible workspace — the selected ones under `selected`, every defined
@@ -362,10 +460,11 @@ Rollback and disablement (the `baseRevision` values below are `3` after the enab
362
460
  ```
363
461
 
364
462
  - **Go back to fully inert**: set `mode` back to `selected` and empty the list. **Note that
365
- `workspaceIds` matters only in `selected` mode**: `isVisible` is unconditionally true under
366
- `mode:"global"` (`src/scope/doc.ts` — the `global` branch never reads the list), so **while in
367
- `global`, writing only `workspaceIds: []` stops nothing** — projection and substitution keep
368
- running while you believe you have rolled back. Under `selected`, removing one workspace is
463
+ `workspaceIds` matters only in `selected` mode**: `isVisible` is true under `mode:"global"` for
464
+ every **defined** workspace (`src/scope/doc.ts` — the `global` branch never reads the list; a
465
+ session whose `workspaceId` is undefined stays invisible), so **while in `global`, writing only
466
+ `workspaceIds: []` stops nothing** — projection and substitution keep running while you believe
467
+ you have rolled back. Under `selected`, removing one workspace is
369
468
  enough; under `global` you must switch the mode at the same time:
370
469
 
371
470
  ```json
@@ -376,7 +475,7 @@ Rollback and disablement (the `baseRevision` values below are `3` after the enab
376
475
  (only the `boost` tool schema's standing cost remains).
377
476
 
378
477
  - **Uninstall the plugin**: `dsh plugin --profile <name> remove dsh-boost`, then restart DSH.
379
- - Deleting `$DSH_HOME/boost` clears the scope and receipts (back to defaults), but does not delete
478
+ - Deleting `<dshHome>/boost` clears the scope and receipts (back to defaults), but does not delete
380
479
  the original files already written to the host spill backend.
381
480
 
382
481
  ## Host dependencies
@@ -390,11 +489,12 @@ to load. `llm` is soft (only the selector uses it); when absent the selector fal
390
489
  | `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 |
391
490
  | `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` |
392
491
  | `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) |
393
- | `@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) |
492
+ | `@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) |
493
+ | (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 |
394
494
  | `@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` |
395
495
  | `win32` platform | runtime `isPosixOnly()` check | Substitution is refused, projection still works; `status.degraded` reports `ERR_HOST_PLATFORM_UNSUPPORTED` |
396
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 |
397
- | 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 `$DSH_HOME/boost/receipts/`, fix, and re-run `status`, comparing counts |
497
+ | 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 |
398
498
  | 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` |
399
499
  | 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 |
400
500
 
@@ -402,13 +502,13 @@ to load. `llm` is soft (only the selector uses it); when absent the selector fal
402
502
  `ToolRegistrationOptions` since the oldest host line this package declares, so the plugin no
403
503
  longer probes it and registers unconditionally.
404
504
 
405
- Several registration codes are log-only and never enter `status.degraded`: a non-duplicate throw
406
- while registering the protocol section logs `ERR_BOOST_SECTION_REGISTER_FAILED`; `registerHooks`
407
- stops at the first mount, so the substitution, projection, and execute hooks are never registered
408
- and the request path is effectively inert, while the `boost` tool and session events are still
409
- attempted. The host's genuine duplicate-section error logs `ERR_BOOST_ALREADY_MOUNTED` and skips
410
- this mount; a failure to register the `boost` tool itself logs
411
- `ERR_BOOST_TOOL_REGISTER_FAILED`.
505
+ Registration codes come in two kinds. A non-duplicate throw while registering the protocol
506
+ section logs `ERR_BOOST_SECTION_REGISTER_FAILED` (log only). The three event hooks
507
+ (`tools/post-execute`, `llm/stream`, `tools/execute`) are then mounted **independently**: a
508
+ failure in any of them is named and reported through **`ERR_BOOST_PARTIAL_MOUNT`** in
509
+ `status.degraded`, so a partially assembled plugin no longer looks healthy. The host's genuine
510
+ duplicate-section error logs `ERR_BOOST_ALREADY_MOUNTED` and skips this mount; a failure to
511
+ register the `boost` tool itself logs `ERR_BOOST_TOOL_REGISTER_FAILED` (log only).
412
512
 
413
513
  `ERR_HOST_NO_TOKENMETER` and `ERR_HOST_NO_ESTIMATOR` are **two different things**; do not merge
414
514
  them. The first is the host service (`ctx.get('tokenMeter')`) being absent, which refuses
@@ -432,15 +532,26 @@ evidence" degraded path would be unreachable.
432
532
 
433
533
  - Only two things: **replace tool receipts in place** and **substitute read-only calls** (`read` /
434
534
  `grep` / `glob`).
435
- - **No batched tool execution** (no PTC / `run_code`; design N1).
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
539
+ [clarification record](docs/superpowers/clarifications/2026-11-18-dsh-token-efficiency.md);
540
+ design N1).
436
541
  - **No deduplication or merging of tool calls** (design N5) — this was not started at all, and
437
542
  v1 ships **no tool that measures duplicate-call rate**: the "shadow-week duplication
438
543
  statistic" the design reserved as its restart trigger was never delivered; `shadow-report.mjs`
439
544
  does not produce it.
440
545
  - **The shadow week saves nothing by design**: it only records (the protocol section is still
441
546
  injected and the selector is still called); its output is four ratios, not saved tokens.
442
- - **v1 does not judge "better results"**: there is a token ledger and a 20-task regression gate,
547
+ - **v1 does not judge "better results"**: there is a token ledger and a **manual** 20-task
548
+ regression procedure (the task set does not ship with the package; see `docs/RELEASE.md` §3),
443
549
  no quality metric; whether substituted outcomes are better is unjudgeable in v1.
550
+ - **Projection is truncation, not refinement**: it keeps the head and tail and drops the middle;
551
+ the before/after token difference in the ledger measures *shorter*, not *more relevant*. The
552
+ dropped middle may be exactly what the next decision needs — with `projection: 'on'` the
553
+ original can be retrieved through the footer locator, but that costs a tool call, and v1 has
554
+ no metric that separates "refined" from "wrongly cut".
444
555
  - **Installed but not enabled is a small net loss**: the `boost` tool registers as soon as the
445
556
  plugin is assembled, and its schema costs a measured 399 tokens on every request (see the
446
557
  breakdown in "Enable it") while yielding nothing.
@@ -448,9 +559,12 @@ evidence" degraded path would be unreachable.
448
559
  - Does not replace or take over DSH's compaction, pruning, or spill decisions (design N3);
449
560
  projection changes only the model-visible content and keeps the original in the host spill.
450
561
  - No model training or weight changes (N2); no attempt at the paper's 87.93% (N4).
451
- - No 10% promise: 3.5% is the floor and 10% the ideal upper bound; the shadow week tells you
452
- whether to proceed, but it cannot replace the range with a measurement (`shadow-report.mjs`
453
- emits four ratios and no total-token denominator).
562
+ - 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).
454
568
 
455
569
  ## Documentation
456
570
 
@@ -468,7 +582,7 @@ The source and docs live in the repository at
468
582
  | [Design](docs/superpowers/specs/2026-11-18-dsh-token-efficiency-design.md) | Goals, evidence, architecture, contracts, measurement, risks, release shape |
469
583
  | [Host contracts appendix](docs/superpowers/plans/2026-11-18-host-contracts.md) | Interface reference copied line by line from the host sources |
470
584
  | [Three-tier delegation research](docs/research/2026-11-18-three-tier-delegation.md) | 25 primary sources on caching, routing thresholds, compression, and verification |
471
- | [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 |
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 |
472
586
 
473
587
  ## License
474
588