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.
- package/README.en.md +141 -51
- package/README.md +115 -47
- package/dist/admission/usage.js +41 -7
- package/dist/admission/usage.js.map +1 -1
- package/dist/gate/decide.js +33 -2
- package/dist/gate/decide.js.map +1 -1
- package/dist/hooks/llm-stream.js +232 -58
- package/dist/hooks/llm-stream.js.map +1 -1
- package/dist/hooks/post-execute.js +206 -39
- package/dist/hooks/post-execute.js.map +1 -1
- package/dist/hooks/session-state.js +18 -8
- package/dist/hooks/session-state.js.map +1 -1
- package/dist/index.js +601 -72
- package/dist/index.js.map +1 -1
- package/dist/scope/doc.js.map +1 -1
- package/dist/scope/store.js +24 -9
- package/dist/scope/store.js.map +1 -1
- package/dist/tools/boost.js +82 -2
- package/dist/tools/boost.js.map +1 -1
- package/package.json +9 -5
- package/dist/admission/fixed-cost.d.ts +0 -23
- package/dist/admission/ledger.d.ts +0 -113
- package/dist/admission/retrieval.d.ts +0 -65
- package/dist/admission/usage.d.ts +0 -75
- package/dist/config.d.ts +0 -43
- package/dist/gate/binding.d.ts +0 -113
- package/dist/gate/decide.d.ts +0 -82
- package/dist/gate/guard.d.ts +0 -69
- package/dist/gate/invalidate.d.ts +0 -112
- package/dist/gate/plan.d.ts +0 -86
- package/dist/hooks/clock.d.ts +0 -68
- package/dist/hooks/execute.d.ts +0 -79
- package/dist/hooks/llm-stream.d.ts +0 -283
- package/dist/hooks/pending.d.ts +0 -89
- package/dist/hooks/post-execute.d.ts +0 -257
- package/dist/hooks/session-state.d.ts +0 -158
- package/dist/hooks/synthesize.d.ts +0 -74
- package/dist/host/loader.d.ts +0 -23
- package/dist/host/platform.d.ts +0 -18
- package/dist/host/root.d.ts +0 -25
- package/dist/projection/apply.d.ts +0 -174
- package/dist/projection/canonicalise.d.ts +0 -43
- package/dist/projection/counters.d.ts +0 -65
- package/dist/projection/truncate.d.ts +0 -47
- package/dist/prompt/protocol.d.ts +0 -45
- package/dist/receipts/store.d.ts +0 -198
- package/dist/scope/doc.d.ts +0 -117
- package/dist/scope/resolve.d.ts +0 -91
- package/dist/scope/store.d.ts +0 -135
- package/dist/selector/jev.d.ts +0 -93
- package/dist/tools/boost.d.ts +0 -380
- 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.
|
|
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
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
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
|
|
55
|
-
`
|
|
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
|
|
72
|
-
|
|
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.
|
|
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 (
|
|
114
|
-
|
|
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
|
-
|
|
141
|
-
you
|
|
142
|
-
|
|
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
|
|
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**:
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
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**:
|
|
210
|
-
|
|
211
|
-
|
|
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)
|
|
215
|
-
post-hoc detection
|
|
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
|
|
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
|
-
|
|
299
|
-
|
|
300
|
-
`400 + 100 + 50 (head line) +
|
|
301
|
-
about
|
|
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.
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
`
|
|
371
|
-
|
|
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
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
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
|
|
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
|
|