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