dsh-boost 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.en.md CHANGED
@@ -5,13 +5,14 @@ read-only substitution**.
5
5
 
6
6
  > **Status: v1 is implemented.** Projection, substitution, and the control surface are all in
7
7
  > place; `npm run build` is clean and the full test suite passes. The benefit range is an
8
- > **ex-ante design estimate** (3.5% lower bound / 10.0% ideal upper bound; ~0.4% honest net
9
- > floor); nothing in the deliverable can recompute it — see below.
8
+ > **ex-ante design estimate** (3.5% lower bound / 10.0% ideal upper bound; ~0.4% aggregate net
9
+ > on the 300 longest sessions). Both ends are offline estimates, not per-session floors, and
10
+ > nothing in the deliverable can recompute them — see below.
10
11
 
11
12
  ## What it does
12
13
 
13
14
  DSH replays the whole history on every model request. Across the 300 longest sessions measured
14
- locally (`npm run --silent stats` — without `--silent`, npm prints its `> dsh-boost@0.1.2 stats`
15
+ locally (`npm run --silent stats` — without `--silent`, npm prints its `> dsh-boost@0.1.3 stats`
15
16
  banner to stdout, so use `--silent` or `node scripts/session-stats.mjs` for machine-readable
16
17
  output; snapshot at `2026-11-19T03:13:21Z`): 54,141 steps and 54,088 requests,
17
18
  10,575,904,022 raw tokens in total. The mean is 195,340 tokens per step and 195,531 per request
@@ -29,8 +30,9 @@ The plugin does two things:
29
30
  decision. With several candidates, a single-label selector — one auxiliary request
30
31
  (`maxTokens` 512 plus its input) — picks one. This is a **narrowing** of original requirement
31
32
  2.2: the request asked Jev to score each tool result and decide whether it could feed the next
32
- tool; v1 only picks one of several candidates on the same receipt, with no per-result scoring
33
- (see the 2.2 row and decision 9 in the
33
+ tool; v1 only picks one of several candidates on the same receipt, with no per-result scoring.
34
+ That narrowing is the **implementer's scope decision (E2)**, not a user ruling — **no user
35
+ message ratifies it** (see the 2.2 row and implementer decision E2 in the
34
36
  [clarification record](docs/superpowers/clarifications/2026-11-18-dsh-token-efficiency.md)).
35
37
  For the three substituted tools, the plan's
36
38
  `$public` argument binding (copying a value from an earlier receipt into a later call's
@@ -48,8 +50,11 @@ The plugin does two things:
48
50
  The **ex-ante estimate** for v1 is **3.5% (lower bound) to 10.0% (ideal upper bound)** of raw
49
51
  `totalTokens`; **3.5% is not a floor** — it is the lower bound of an offline estimate against a
50
52
  300-session corpus, and its substitution component (2.70%) is a **ceiling** that must not be
51
- counted as a floor. The honest net floor is about **0.4%** (projection gross ~0.8% minus ~0.4%
52
- fixed per-request overhead). It is not a guarantee, and not a figure the shipped
53
+ 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
53
58
  `session-snapshot.json` can recompute: the snapshot stores per-session aggregates plus each
54
59
  session's `requestTokens` / `receiptChars` arrays, `valueTransfer` / `whitelist` counts, and
55
60
  its per-family `toolChars` totals, but it has **no per-receipt family bytes** — the projection
@@ -80,29 +85,32 @@ denominator statistic that a later version must add.
80
85
  directory:
81
86
 
82
87
  ```bash
83
- # install from the registry: npmjs has latest = 0.1.2 (this repository's
88
+ # install from the registry: npmjs has latest = 0.1.3 (this repository's
84
89
  # .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/
90
+ dsh plugin --profile <name> add dsh-boost@^0.1.3 --registry=https://registry.npmjs.org/
86
91
 
87
92
  # or from a local checkout (build first; dist/ is not committed)
88
93
  npm run build
89
94
  dsh plugin --profile <name> add /absolute/path/to/dsh-boost
90
95
  ```
91
96
 
92
- For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.2 --registry=https://registry.npmjs.org/`.
97
+ For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.3 --registry=https://registry.npmjs.org/`.
93
98
  `dsh plugin` forwards the operation to pnpm, so pnpm must be on `PATH`.
94
99
 
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.
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.
106
114
 
107
115
  The package is ESM (`"type": "module"`) and the `.` entry of `exports` also maps `require` /
108
116
  `default`: on Node >= 24.9, `require('dsh-boost')` loads the very same code as `import`. Nothing
@@ -186,6 +194,10 @@ After the write, call `status` again. A healthy result looks like this:
186
194
  `@deepseek-ai/dsh-token-meter/estimate` is unreachable, `fixedOverheadTokens` is the string
187
195
  `"unknown"` (not 0) and `degraded` carries `ERR_HOST_NO_ESTIMATOR`; `estimate_kind` may still be
188
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.
189
201
  - `data.counts` usually starts empty — but **control calls count too**: while no workspace is
190
202
  visible, `boost`'s own calls pass the same post-execute scope gate (there is no boost exemption
191
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
@@ -234,21 +246,29 @@ recommended setup; a multi-candidate plan still makes a **real selector call** (
234
246
  auxiliary model request). The shadow week saves no tokens; it produces only the four ratios below.
235
247
  Under `selected + []` the protocol section is empty and the fixed cost is still **399**.
236
248
 
237
- Of those ratios, `saveableRatio`, `byFamily`, and `candidateRecall` can decide **whether the
238
- substitution side is worth turning on**: how many substitution decisions the whitelist could
239
- actually deliver, which tool families the hits land in, and how high candidate recall is — that
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
244
- `retrievalUpperBound` is structurally `0` during the shadow week (it only counts applied
245
- `projection:'on'` retrievals), so it cannot even bound projection's retrieval damage. Projection
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.
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
+
252
272
  `scope.json` has two independent switches:
253
273
 
254
274
  | Switch | Value | Behaviour |
@@ -272,12 +292,17 @@ The recommended sequence:
272
292
  shadow commits over **all** substitution decisions — the denominator is every substitution
273
293
  decision, not just the whitelisted calls; shadow mode records every family, so bash/ssh
274
294
  potential shows up in `byFamily`), `byFamily` (hit rate per candidate family), `candidateRecall`
275
- (recall of the candidate set), and `retrievalUpperBound` (retrieval upper bound; structurally
276
- `0` during the shadow week because nothing is projected for real).
295
+ (**commit yield, not candidate-set recall**: `commits / (commits + noCandidate)`; the script
296
+ never compares the candidate set to the model's actual next call, so it answers "how many
297
+ decisions with a candidate committed", not "did the candidate set miss the call the model
298
+ actually made"), and `retrievalUpperBound` (**a lower bound on the observed retrieval rate, not
299
+ an upper bound on retrieval damage**; structurally `0` during the shadow week because nothing
300
+ is projected for real).
277
301
  3. **Turn on projection**: projection is not released on shadow labels (its basis is the
278
302
  visibility contract — the original stays retrievable through the footer; v1 has no
279
- mis-truncation detector); once the host spill backend is available, keep
280
- `shadow: true` and set `projection` to `'on'`:
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'`:
281
306
 
282
307
  ```json
283
308
  { "cmd": "scope-set", "body": { "projection": "on" }, "baseRevision": 1 }
@@ -285,8 +310,8 @@ The recommended sequence:
285
310
 
286
311
  `scope-set` patches only the fields you pass; everything else stays as it was. Receipts now get
287
312
  replaced, while substitution decisions are still recorded only.
288
- 4. **Turn on substitution**: when the shadow report shows acceptable whitelist hits and candidate
289
- recall, just switch the shadow off — **checking before the switch is a no-op**: the shadow
313
+ 4. **Turn on substitution**: when the shadow report shows acceptable whitelist hits and commit
314
+ yield, just switch the shadow off — **checking before the switch is a no-op**: the shadow
290
315
  week never synthesizes a turn, so a `content[].thinking` 400 is
291
316
  structurally impossible and a check made before switching it off can only ever read "not
292
317
  seen". After `shadow` becomes `false`, check for that 400 in the **first genuinely
@@ -321,7 +346,7 @@ cap is 256 KiB, so `300000` prevents the family from triggering at all (there is
321
346
  | `projection.glob.*` | 700 / 400 / 100 | `glob` window |
322
347
  | `projection.bash.*` | 4000 / 2000 / 500 | `bash` window |
323
348
  | `projection.ssh.*` | 2000 / 1200 / 300 | `mcp__ssh__*` (such as `mcp__ssh__execute-command`) window |
324
- | `admission.thresholdTokens` | 1024 | Minimum net saving per candidate before substitution; a single deterministic candidate is exempt |
349
+ | `admission.thresholdTokens` | 1024 | Minimum net saving per candidate before substitution; **a single-step plan is exempt** (`plan.steps.length === 1`, `admittedFor` in `src/hooks/post-execute.ts`) — with one step there is no selector to pay, so the threshold does not apply. It is not "deterministic && the only candidate": a multi-step plan that has one candidate left still has to pass the threshold (`worthSubstituting` in `src/admission/ledger.ts`) |
325
350
  | `selector.maxTokens` | 512 | Output budget for the multi-candidate selector (its input plus output bound is deducted from the saving) |
326
351
  | `stepsPerTurn` | 8 | Maximum substituted steps per turn |
327
352
  | `horizonSteps` | 20 | Remaining-step horizon used when the session average cannot be computed |
@@ -334,7 +359,8 @@ The invariant is **not** `triggerChars >= headChars + tailChars + 1`. The real r
334
359
  line + head + footer + tail + 3 newlines; the footer is produced by the host's `formatSpillNotice`.
335
360
  With a 68-character locator and the host's fixed 66-character retrieval hint, a 3-digit
336
361
  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).
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).
338
364
  So a receipt just over 700 — up to about 743 — is judged cuttable by `truncate`, but `projectApply` assembles a replacement that is
339
365
  not shorter than the original and returns the original. That is a dead band, not a net loss. The
340
366
  runtime `assembled.length >= text.length` check guarantees projection never makes a receipt
@@ -397,12 +423,15 @@ set it falls back to `~/.dsh`; the assembly log prints the resolved `root=` (tha
397
423
  - `scope.lock` — the short-lived write lock, removed after a normal write.
398
424
  - `receipts/<encoded-session>.jsonl` — append-only receipts. **A receipt is written per
399
425
  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**
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**
406
435
  also carry the plan goal (≤256 code points) and guards (≤8, each ≤300 code points):
407
436
  `kind:'substitute'`, `kind:'substitute-settled'`, and `kind:'shadow'` with `code:'ok'`.
408
437
  `kind:'shadow'` is not substitution-only — projection shadowing also writes `kind:'shadow'`,
@@ -414,7 +443,9 @@ set it falls back to `~/.dsh`; the assembly log prints the resolved `root=` (tha
414
443
  carry `locator` plus `retrieval_call_tokens` / `retrieval_content_tokens` / `retrieval_tokens`;
415
444
  those three are written only when the retrieval was priced, and an unpriced one has
416
445
  `estimate:'unknown'` with the fields omitted. `skip` receipts carry only `preview` and `args`
417
- (`skip:no-scope` carries neither — just the tool name).
446
+ (`skip:no-scope` has two paths: the `appendSkipNoScope` branch — no agent, no session id, or an
447
+ inactive session — carries only the tool name; the mid-call live-visibility branch goes through
448
+ `ledgerEntry` and still carries `preview` and `args`).
418
449
 
419
450
  When the current shard exceeds 8 MiB or 20,000 lines, the next write first rotates it to
420
451
  `<encoded-session>.1.jsonl`; only the current shard and its predecessor are kept (an older `.1`
@@ -515,7 +546,7 @@ to load. `llm` is soft (only the selector uses it); when absent the selector fal
515
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 |
516
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` |
517
548
  | `win32` platform | runtime `isPosixOnly()` check | Substitution is refused, projection still works; `status.degraded` reports `ERR_HOST_PLATFORM_UNSUPPORTED` |
518
- | Host version line | startup check of the `@deepseek-ai/dsh-app-boot` version | A version other than `0.2.2-rc.4` logs `ERR_HOST_VERSION_MISMATCH` and loads anyway — advisory only, not a `status.degraded` code. An undeterminable version logs an info line, no code |
549
+ | Host version line | startup check of the `@deepseek-ai/dsh-app-boot` version | A version **outside the `engines.dsh` range** (`>=0.2.2-rc.4 <0.2.3-0`) logs `ERR_HOST_VERSION_MISMATCH` and loads anyway — advisory only, not a `status.degraded` code. A version inside the range but not the verified `0.2.2-rc.4` (such as `rc.5` / `0.2.2`) logs an info line, no code; an undeterminable version or an unparseable range also logs info only |
519
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 |
520
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` |
521
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 |
@@ -554,16 +585,33 @@ evidence" degraded path would be unreachable.
554
585
 
555
586
  - Only two things: **replace tool receipts in place** and **substitute read-only calls** (`read` /
556
587
  `grep` / `glob`).
557
- - **No batched tool execution** (no PTC / `run_code`): this is not a boundary v1 chose for
558
- itself but the **narrowed** form of original requirement 2.1 — the request asked for several
559
- tool calls at once, and the adjudication excluded it explicitly for a later phase (see the
560
- 2.1 row and decision 9 in the
588
+ - **No batched tool execution** (no PTC / `run_code`): this is a **narrowing** of original
589
+ requirement 2.1 and the **implementer's scope decision (E2)**, not a user ruling — **no user
590
+ message ratifies it**. The reason is scope, not "batch dispatch was shown to be worthless":
591
+ 79.8% of steps carry exactly one tool call, but **20.2% are not single-tool steps** — 16.9% carry
592
+ ≥2 calls and 3.3% carry none (`clarifications:17`). The user explicitly asked for batch dispatch,
593
+ and those non-single steps are its surface. PTC is deferred to phase two; the restart condition
594
+ is shadow-week data on the real share and benefit of batched steps, not "79.8% proves batching is
595
+ unnecessary" (see the 2.1 row and E2 in the
561
596
  [clarification record](docs/superpowers/clarifications/2026-11-18-dsh-token-efficiency.md);
562
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).
563
606
  - **No deduplication or merging of tool calls** (design N5) — this was not started at all, and
564
607
  v1 ships **no tool that measures duplicate-call rate**: the "shadow-week duplication
565
608
  statistic" the design reserved as its restart trigger was never delivered; `shadow-report.mjs`
566
609
  does not produce it.
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`).
567
615
  - **The shadow week saves no tokens**: it only records (the protocol section is still injected
568
616
  and the selector is still called), and the recommended setup still costs 778 per request
569
617
  (`selected + []` costs 399); its output is four ratios, not saved tokens.
@@ -586,11 +634,12 @@ evidence" degraded path would be unreachable.
586
634
  projection changes only the model-visible content and keeps the original in the host spill.
587
635
  - No model training or weight changes (N2); no attempt at the paper's 87.93% (N4).
588
636
  - No 10% promise: 3.5% is the **lower bound** of the ex-ante estimate, not a floor; 10% is the
589
- ideal upper bound. The honest net floor is about 0.4% (projection gross ~0.8% minus ~0.4%
590
- fixed per-request overhead). The shadow week only answers whether the substitution side is
591
- worth turning on (candidate coverage and hit rate); it does not decide release, and it cannot
592
- replace the range with a measurement (`shadow-report.mjs` emits four ratios and no total-token
593
- denominator).
637
+ ideal upper bound. Projection's aggregate net across the 300 longest sessions is about 0.4%
638
+ (gross ~0.8% minus ~0.4% fixed per-request overhead); that too is an offline estimate, **not a
639
+ per-session floor** (short sessions can be net negative). The shadow week only gives labels for
640
+ the substitution side (candidate coverage and commit yield); it does not by itself decide
641
+ whether to turn substitution on, does not decide release, and cannot replace the range with a
642
+ measurement (`shadow-report.mjs` emits four ratios and no total-token denominator).
594
643
 
595
644
  ## Documentation
596
645
 
@@ -613,4 +662,6 @@ The source and docs live in the repository at
613
662
  ## License
614
663
 
615
664
  Apache-2.0. The mechanisms are ported from [HarnessMM](https://github.com/YuhuaJiang2002/HarnessMM)
616
- (Apache-2.0); a `NOTICE` ships with the package.
665
+ (Apache-2.0): the flat candidate bank, GDR guard, CCS single-candidate commit, and the closed-set
666
+ selector. **EDG's graph/chain (`predecessor_id`) and the RSI loop were not ported.** A `NOTICE`
667
+ ships with the package.
package/README.md CHANGED
@@ -3,12 +3,13 @@
3
3
  通过**工具回执投影**与**确定性只读替换**降低 DeepSeek Harness(DSH)的 token 消耗。
4
4
 
5
5
  > **状态:v1 已实现。** 投影、替换与控制面均已落地;`npm run build` 干净,测试套件全部通过。
6
- > 收益区间是设计阶段的事前估算(下界 3.5% / 理想上界 10.0%;净保底约 0.4%),交付物**无法复算**——见下。
6
+ > 收益区间是设计阶段的事前估算(下界 3.5% / 理想上界 10.0%;投影侧在 300 个最长会话上的
7
+ > 聚合净额约 0.4%),两端都是离线估算、不是每会话保底,交付物**无法复算**——见下。
7
8
 
8
9
  ## 它解决什么
9
10
 
10
11
  DSH 每次模型请求都会回放全部历史。本机 300 个最长会话的实测聚合(`npm run --silent stats`——不带
11
- `--silent` 时 npm 会把 `> dsh-boost@0.1.2 stats` 横幅打进 stdout,机器解析请用 `--silent` 或直接
12
+ `--silent` 时 npm 会把 `> dsh-boost@0.1.3 stats` 横幅打进 stdout,机器解析请用 `--silent` 或直接
12
13
  `node scripts/session-stats.mjs`;快照时刻 `2026-11-19T03:13:21Z`):54,141 步、54,088 个请求,合计 10,575,904,022 raw token。按步均值
13
14
  195,340 token,按请求均值 195,531、中位 187,681;97.01% 的输入是缓存读。工具回执是体积主体
14
15
  (bash 61.75%、read 22.13%、ssh 10.01%),而下一步真正会用到的部分通常远小于回执本身。
@@ -21,8 +22,9 @@ DSH 每次模型请求都会回放全部历史。本机 300 个最长会话的
21
22
  直接提交,不再向模型要一次决策;多候选时用一个单标签选择器——一次独立的辅助请求
22
23
  (`maxTokens` 512,另加其输入)。这是对原始需求 2.2 的**收窄**:原需求要 Jev 对每个工具
23
24
  结果逐条打分、判断能否交给下一个工具,v1 只做「同一回执上的多个候选里选一个」,不做
24
- 逐条打分(见[澄清记录](docs/superpowers/clarifications/2026-11-18-dsh-token-efficiency.md)
25
- 的 2.2 与「用户裁决」第 9 条)。对替换涉及的三个工具而言,计划里的 `$public` 参数绑定
25
+ 逐条打分。这条收窄是**实现者的范围决定(E2)**,不是用户裁决——澄清记录里**没有用户消息
26
+ 追认它**(见[澄清记录](docs/superpowers/clarifications/2026-11-18-dsh-token-efficiency.md)
27
+ 的 2.2 与「实现者决定」E2)。对替换涉及的三个工具而言,计划里的 `$public` 参数绑定
26
28
  (把上一步回执里的值直接搬进下一步参数)在实践中只对 `glob` 的单 token 输出有效;
27
29
  `read` 与 `grep` 的输出带行号或是裸路径,标识符投影匹配不到,这些调用会退回模型。
28
30
 
@@ -34,8 +36,10 @@ DSH 每次模型请求都会回放全部历史。本机 300 个最长会话的
34
36
 
35
37
  v1 的**事前估算**区间是 **3.5%(下界)– 10.0%(理想上界)**,按 raw `totalTokens` 计;
36
38
  **3.5% 不是保底**——它是设计阶段对一个 300 会话语料做离线估算得到的下界,其中替换账的
37
- 2.70% 是**上限**,不能算进保底;诚实的净保底只有约 **0.4%**(投影侧毛额约 0.8% 减去每请求
38
- 固定开销约 0.4%)。这个区间不是保证,也不是从交付的 `session-snapshot.json` 能复算出来的
39
+ 2.70% 是**上限**,不能算进任何保底。投影侧在 **300 个最长会话**上的**聚合**净额约 **0.4%**
40
+ (毛额约 0.8% 减去每请求固定开销约 0.4%,即 778 / 195,531);它也不是每会话保底——长会话
41
+ 摊薄固定开销,**短会话可能倒亏**,而 `top-300` 里没有 ≤5 步的会话。3.5% 与 0.4% 两端都是
42
+ 离线估算,不是测量。这个区间不是保证,也不是从交付的 `session-snapshot.json` 能复算出来的
39
43
  数字:快照按会话存了聚合计数,也存了每个会话的 `requestTokens` / `receiptChars` 数组、
40
44
  `valueTransfer` / `whitelist` 计数,以及该会话按工具族归因的 `toolChars` 字符总量,但
41
45
  **没有逐回执的族别字节**,估算所需的投影分项仍然凑不出来——交付物里**没有任何工具能复算它**。影子周也
@@ -60,26 +64,29 @@ v1 的**事前估算**区间是 **3.5%(下界)– 10.0%(理想上界)**
60
64
  `dsh plugin` 要求指定 profile,剩下的参数原样转发给该 profile 目录里的 pnpm:
61
65
 
62
66
  ```bash
63
- # 从 registry 安装:npmjs 上的 latest 是 0.1.2(本仓库 .npmrc 与 lockfile
67
+ # 从 registry 安装:npmjs 上的 latest 是 0.1.3(本仓库 .npmrc 与 lockfile
64
68
  # 也已钉在 npmjs,见下)
65
- dsh plugin --profile <name> add dsh-boost@^0.1.2 --registry=https://registry.npmjs.org/
69
+ dsh plugin --profile <name> add dsh-boost@^0.1.3 --registry=https://registry.npmjs.org/
66
70
 
67
71
  # 或从本地 checkout 安装(先构建;dist/ 不入库)
68
72
  npm run build
69
73
  dsh plugin --profile <name> add /absolute/path/to/dsh-boost
70
74
  ```
71
75
 
72
- 例如 web profile:`dsh plugin --profile web add dsh-boost@^0.1.2 --registry=https://registry.npmjs.org/`。
76
+ 例如 web profile:`dsh plugin --profile web add dsh-boost@^0.1.3 --registry=https://registry.npmjs.org/`。
73
77
  `dsh plugin` 把操作转发给 pnpm,所以 pnpm 必须在 PATH 上。
74
78
 
75
- > **两个 registry 现在都到 0.1.2,`^0.1.2` 是安全的钉法。** `registry.npmjs.org` 与
76
- > `registry.npmmirror.com` 各有四条版本记录:`0.1.2`(两边都是当前 `latest`)、`0.1.1`、
77
- > `0.1.0`,以及首次发布时 npm 自动创建的占位版本 `0.0.0-stage`——**不要安装 `0.0.0-stage`**,
78
- > 它不是可用构建。0.1.2 修掉了 scope 文件被静默覆盖的问题:坏 JSON(含非对象或数组)与
79
- > 无法识别的版本不再被默认文档覆盖。请用 `dsh-boost@^0.1.2`(或 `@latest`)。本仓库已把 `.npmrc`
80
- > 与 lockfile 钉在 npmjs,但**你机器上的全局 npm 配置**可能仍指向一个尚未同步 0.1.2 的镜像:
79
+ > **两个 registry 现在都到 0.1.3,`^0.1.3` 是安全的钉法。** `registry.npmjs.org` 与
80
+ > `registry.npmmirror.com` 各有五条版本记录:`0.1.3`(两边都是当前 `latest`)、`0.1.2`、
81
+ > `0.1.1`、`0.1.0`,以及首次发布时 npm 自动创建的占位版本 `0.0.0-stage`——**不要安装
82
+ > `0.0.0-stage`**,它不是可用构建。0.1.3 修掉了「模型看到的正文被外层改写后仍按原始回执
83
+ > 提交替换」的问题,并把节省改报为上下界区间(新增 `avoided_total_tokens`),另加三个宿主
84
+ > 能力降级码与 `status.hasSpill`;0.1.2 修掉了 scope 文件被静默覆盖的问题:坏 JSON(含非对象
85
+ > 或数组)与无法识别的版本不再被默认文档覆盖。请用 `dsh-boost@^0.1.3`(或 `@latest`)——
86
+ > `^0.1.3` 表达的是「至少含 0.1.3 的修复」。本仓库已把 `.npmrc`
87
+ > 与 lockfile 钉在 npmjs,但**你机器上的全局 npm 配置**可能仍指向一个尚未同步 0.1.3 的镜像:
81
88
  > 那是本机配置,不是本仓库的状态。在意 registry 时显式传
82
- > `--registry=https://registry.npmjs.org/`;镜像滞后时,`@^0.1.2` 会在同步前解析失败。
89
+ > `--registry=https://registry.npmjs.org/`;镜像滞后时,`@^0.1.3` 会在同步前解析失败。
83
90
 
84
91
  包是 ESM(`"type": "module"`),`exports` 的 `.` 条目同时映射 `require` / `default`:Node ≥ 24.9
85
92
  下 `require('dsh-boost')` 与 `import` 加载同一份代码,装好的包里**不做任何构建**(`files` 只带
@@ -154,6 +161,9 @@ bundle,patch 的 `insert` 行落在 profile root 上。**装完必须重启 DS
154
161
  `@deepseek-ai/dsh-token-meter/estimate` 不可达,`fixedOverheadTokens` 会是字符串
155
162
  `"unknown"`(不是 0),`degraded` 带 `ERR_HOST_NO_ESTIMATOR`;此时 `estimate_kind` 仍可能是
156
163
  `"host"`,因为 token meter 服务还在——两件事不要混。
164
+ - `data.hasSpill` 为 `true`(宿主**提供** spill 服务的存在性)。它**不表示可用**:服务在但
165
+ 没有 `saveText` 时仍是 `true`,`degraded` 会带 `ERR_HOST_SPILL_UNUSABLE`。打开
166
+ `projection: 'on'` 前要同时看这两个字段;只看 `hasSpill` 会把一个不可用的后端当成可用。
157
167
  - `data.counts` 一开始通常为空——但**控制调用自己也计数**:可见工作区为空时,`boost`
158
168
  自己的调用同样要过 post-execute 的 scope 门(那里没有 boost 豁免,豁免只在工具注册层),
159
169
  每条记一次 `skip:no-scope`。正常工具调用后会累积,例如出现 `projection-shadow` 条目。
@@ -194,16 +204,23 @@ scope**:`boost` 工具 schema(399)只要插件装配就常驻——`boost`
194
204
  **778**;多候选计划仍会**真实调用一次选择器**(一次独立的辅助模型请求)。影子周不省任何
195
205
  token,它只产出下一节的四个比例;`selected + []` 下协议段为空,固定成本仍有 **399**。
196
206
 
197
- 其中 `saveableRatio`、`byFamily`、`candidateRecall` 能决定的是**替换侧是否值得打开**:
198
- 白名单能兑现多少替换决策、命中落在哪些工具族、候选集召回多高——也就是替换打开后会不会
199
- 真的触发、主要落在哪些族。它们**不能决定发布**:v1 按正常版本发布,不把影子期收益当发布
200
- 门;这个决定是**实现者在设计阶段做的,不是用户裁决**——用户只接受了为期一周的影子期,没有
201
- 裁定影子结果是否该当发布门。它们也**不能测出节省**:报告没有总 token 分母,
202
- `retrievalUpperBound` 在影子期结构性为 `0`(它只统计 `projection:'on'` 的已应用投影取回),
203
- 连投影的取回损害都约束不了。投影的放行依据只有可见性契约(原文可经页脚取回),不是影子
204
- 标签,也**不是事后检测**:v1 没有误截检测器——`src/admission/retrieval.ts` 只按精确 locator
205
- 统计取回次数,设计稿 §6.1 也写明损害度量未交付、取回计数不是损害上界。唯一的护栏是模型
206
- 能取回原文;而「发生过取回」只是信号,不是「没有误截」的证明。
207
+ 其中 `saveableRatio`、`byFamily`、`candidateRecall` 提供的是**替换侧的标签,不单独决定
208
+ 是否开启替换**:白名单能兑现多少替换决策、命中落在哪些工具族、提交产出率多高——也就是
209
+ 替换打开后会不会真的触发、主要落在哪些族。报告**没有总 token 分母**,所以这些标签判断不了
210
+ 净收益;它们也**不能决定发布**:v1 按正常版本发布,不把影子期收益当发布门;这个决定是
211
+ **实现者在设计阶段做的,不是用户裁决**——用户只接受了为期一周的影子期,没有裁定影子结果
212
+ 是否该当发布门。它们也**不能测出节省**:`retrievalUpperBound` 在影子期结构性为 `0`(它只
213
+ 统计 `projection:'on'` 的已应用投影取回),连投影的取回损害都约束不了。投影的放行依据只有
214
+ 可见性契约(原文可经页脚取回),不是影子标签,也**不是事后检测**:v1 没有误截检测器——
215
+ `src/admission/retrieval.ts` 只按精确 locator 统计取回次数,设计稿 §6.1 也写明损害度量未
216
+ 交付、取回计数不是损害上界。唯一的护栏是模型能取回原文;而「发生过取回」只是信号,不是
217
+ 「没有误截」的证明。
218
+
219
+ **全零周不能区分两件事。** 如果模型整周没有写 `<CHISEL_PLAN>`,就没有任何决策收据,
220
+ 四个比例全是 `0`;这与「没有可省项」在报告里长得一模一样——报告不测 plan 发射率。看到
221
+ 全零时先查收据里有没有替换决策(`kind:'shadow'` / `kind:'skip'`),不要直接读成
222
+ 「插件没有效果」。
223
+
207
224
  `scope.json` 里有两个独立开关:
208
225
 
209
226
  | 开关 | 取值 | 行为 |
@@ -223,17 +240,21 @@ token,它只产出下一节的四个比例;`selected + []` 下协议段为
223
240
  `~/.dsh`)。这个脚本是 dev-only,不在 npm tarball 里。它输出四个标签:
224
241
  `saveableRatio`(白名单能兑现的替换占比 = `whitelisted` 影子提交 / **全部**替换决策——分母
225
242
  是每一次替换决策,不只是白名单调用;影子期全族记账,bash/ssh 的潜力看 `byFamily`)、`byFamily`(按候选工具族的命中率)、
226
- `candidateRecall`(候选集召回)、`retrievalUpperBound`(取回率上界;影子期没有真正投影,
227
- 结构上恒为 `0`)。
243
+ `candidateRecall`(**提交产出率,不是候选集召回**:`commits / (commits + noCandidate)`;
244
+ 脚本从不拿候选集去比对模型实际的下一调,所以它回答「有候选的决策里多少提交了」,不回答
245
+ 「候选集漏没漏掉模型真正要做的调用」)、`retrievalUpperBound`(**已观测取回率的下界,不是
246
+ 取回损害的上界**;影子期没有真正投影,结构上恒为 `0`)。
228
247
  3. **打开投影**:投影的放行不靠影子标签(依据是可见性契约:原文可经页脚取回;v1 没有
229
- 误截检测器),确认宿主 spill 后端可用后,保持 `shadow: true`,把 `projection` 改成 `'on'`:
248
+ 误截检测器)。先确认 `status.data.hasSpill` 为 `true` **且** `degraded` 不含
249
+ `ERR_HOST_SPILL_UNUSABLE`——前者只证明宿主**提供**服务,后者才说明服务可用;再保持
250
+ `shadow: true`,把 `projection` 改成 `'on'`:
230
251
 
231
252
  ```json
232
253
  { "cmd": "scope-set", "body": { "projection": "on" }, "baseRevision": 1 }
233
254
  ```
234
255
 
235
256
  `scope-set` 只覆盖你传入的字段,其余保持不变。此时回执开始真正被替换,但替换决策仍然只记账。
236
- 4. **再打开替换**:影子报告显示白名单命中与候选召回可接受时,直接把影子关掉——**先检查再关
257
+ 4. **再打开替换**:影子报告显示白名单命中与提交产出率可接受时,直接把影子关掉——**先检查再关
237
258
  是无效顺序**:影子期从不合成回合,`content[].thinking` 的 400 在结构上不可能出现,
238
259
  关影子之前检查它永远只能读到「未见」。
239
260
  把 `shadow` 设为 `false` 之后,按 [docs/RELEASE.md](docs/RELEASE.md) §4 在**第一个真正
@@ -265,7 +286,7 @@ token,它只产出下一节的四个比例;`selected + []` 下协议段为
265
286
  | `projection.glob.*` | 700 / 400 / 100 | `glob` 窗口 |
266
287
  | `projection.bash.*` | 4000 / 2000 / 500 | `bash` 窗口 |
267
288
  | `projection.ssh.*` | 2000 / 1200 / 300 | `mcp__ssh__*`(如 `mcp__ssh__execute-command`)窗口 |
268
- | `admission.thresholdTokens` | 1024 | 每个候选进入替换所需的最小净节省;唯一候选的确定性提交豁免 |
289
+ | `admission.thresholdTokens` | 1024 | 每个候选进入替换所需的最小净节省;**单步计划豁免**(`plan.steps.length === 1`,`src/hooks/post-execute.ts` 的 `admittedFor`)——计划只有一步时没有选择器可付,阈值不适用。不是「确定性 && 唯一候选」:多步计划即使只剩一个候选,仍要过阈值(`src/admission/ledger.ts` 的 `worthSubstituting`) |
269
290
  | `selector.maxTokens` | 512 | 多候选选择器的输出预算(输入 + 输出上界从节省里扣) |
270
291
  | `stepsPerTurn` | 8 | 每个 turn 的替换步数上限 |
271
292
  | `horizonSteps` | 20 | 算不出会话历史均值时的剩余步数 horizon |
@@ -333,8 +354,10 @@ plugin manager 才能把运行中的 entry 认成本包的行、通过 profile p
333
354
  - `scope.json`——暴露面的唯一事实来源(version 2,带 revision)。
334
355
  - `scope.lock`——写路径的短锁,正常写入结束后删除。
335
356
  - `receipts/<encoded-session>.jsonl`——追加式收据。**收据按“决定”写,不是每次调用都写**:
336
- 只有发生投影、替换决策(含 skip)或越界 `skip:no-scope` 时才落一行;一个没有计划的
337
- `write` / `edit` 不产生任何收据,它的参数不会被记录。每行携带元数据、回执前 256 个码点的
357
+ 只有发生投影、替换决策(含 skip)、待发替换因外部改写被放弃(`kind:'reset'`,`code` 为
358
+ `pruned-reset` / `compaction-reset`)或越界 `skip:no-scope` 时才落一行;一个没有计划的
359
+ `write` / `edit` 不产生任何收据,它的参数不会被记录。除 `kind:'reset'` 与
360
+ `appendSkipNoScope` 写出的 `skip:no-scope` 外,每行携带元数据、回执前 256 个码点的
338
361
  preview(不存 stdout 全文)和该调用的绑定参数 `args`(模型所写:超过 2048 个码点时以
339
362
  `args_truncated` 标记的截断 JSON 落盘;嵌套超过 64 层时以 `args_depth_truncated` 标记,
340
363
  并把更深的子树换成 `{ "truncated_depth": 64 }`)。**只有替换类收据**另外携带计划 goal
@@ -348,7 +371,9 @@ plugin manager 才能把运行中的 entry 认成本包的行、通过 profile p
348
371
  (`kind:'projection'`、`code:'projection-retrieval'`)带 `locator` 与
349
372
  `retrieval_call_tokens` / `retrieval_content_tokens` / `retrieval_tokens`;三个取回字段
350
373
  只在这次取回被定价时写入,未定价时 `estimate` 为 `'unknown'`、字段省略。`skip` 收据只有
351
- preview 与 args(`skip:no-scope` 连这两个都没有,只记工具名)。
374
+ preview 与 args(`skip:no-scope` 分两条路径:走 `appendSkipNoScope` 的分支——无 agent、
375
+ 无 session id、会话已不活跃——只记工具名;运行中途可见性翻转的 `ledgerEntry` 分支仍带
376
+ preview 与 args)。
352
377
 
353
378
  当前分片超过 8 MiB 或 20,000 行时,下一次写入前轮转为 `<encoded-session>.1.jsonl`;只保留
354
379
  当前分片和它的前一份(旧的 `.1` 被覆盖)。`boost status` 先读 `.1` 再读当前分片。256 分片
@@ -432,7 +457,7 @@ horizon 重放,并计入 `projection_horizon_reestimated`;`projection_horizo
432
457
  | (spill 后端存在但写失败) | — | 每次 `saveText` 被拒:收据 `projection-skipped:spill-failed`,`status.degraded` 带 **`ERR_HOST_SPILL_FAILING`**。这是**第三种**状态,既不是「没有后端」也不是「没有页脚渲染器」——让操作者去「恢复 spill 包」会把一个已装好却报错的包当成没装 |
433
458
  | `@deepseek-ai/dsh-token-meter/estimate` | 软(动态 import) | 固定开销无法测量,`fixedOverheadTokens` 为 `'unknown'`;`status.degraded` 带 `ERR_HOST_NO_ESTIMATOR` |
434
459
  | `win32` 平台 | 运行时检查 `isPosixOnly()` | 拒绝替换,投影照常;`status.degraded` 带 `ERR_HOST_PLATFORM_UNSUPPORTED` |
435
- | 宿主版本线 | 启动时读 `@deepseek-ai/dsh-app-boot` 的版本 | 不是 `0.2.2-rc.4` 时日志警告 `ERR_HOST_VERSION_MISMATCH`,插件照常加载(advisory,不是 `status.degraded` 码);版本读不到时只记 info,不发码 |
460
+ | 宿主版本线 | 启动时读 `@deepseek-ai/dsh-app-boot` 的版本 | 版本**落在 `engines.dsh` 区间外**(`>=0.2.2-rc.4 <0.2.3-0`)时日志警告 `ERR_HOST_VERSION_MISMATCH`,插件照常加载(advisory,不是 `status.degraded` 码);区间内但不是验证过的 `0.2.2-rc.4`(如 `rc.5` / `0.2.2`)只记 info、不发码;版本读不到或区间无法解析时也只记 info |
436
461
  | 收据分片可读性 | `boost status` 全量扫描(非依赖) | 至少一个收据分片读不出来(EACCES、名为 `x.jsonl` 的目录等)时 `status.degraded` 带 `ERR_RECEIPTS_UNREADABLE`;`status` 仍是**全量聚合**——健康分片照常计数——所以数字可能不完整。查 `<dshHome>/boost/receipts/` 的权限与异常条目,修复后重跑并对比计数 |
437
462
  | 收据分片数量 | `boost status` 全量扫描(非依赖) | 分片超过 256 个时 `status` 只统计按编码名排序的前 256 个,`status.degraded` 带 `ERR_RECEIPTS_TRUNCATED`,所有计数因此是**下界**;分片永不自动删除,可归档/移走旧会话分片后重跑 `status` |
438
463
  | 提示段装配瀑布 | 出站请求探测(非依赖) | 宿主的 `complete: true` 提示段在装配瀑布之后替换了整个系统提示、协议段没有到达请求时,`status.degraded` 带 `ERR_HOST_COMPLETE_SECTION`;受影响请求上替换与投影 fail-closed(工作区明明可见插件却不动作)。找出宿主里覆盖瀑布的 complete 段(通常属于另一个插件)并移除,或接受这些请求上不动作 |
@@ -463,13 +488,25 @@ spill,报它只会制造噪音);但**收据通道**不看当前模式—
463
488
  ## v1 的边界
464
489
 
465
490
  - 只做两件事:**就地替换工具回执**,以及**替换只读调用**(`read` / `grep` / `glob`)。
466
- - **不批量执行工具调用**(没有 PTC / `run_code`):这不是 v1 自行划定的范围,而是原始需求
467
- 2.1 被**收窄**后的结果——原需求要一次调用多个工具,裁决为显式排除、二期再议(见
468
- [澄清记录](docs/superpowers/clarifications/2026-11-18-dsh-token-efficiency.md) 的 2.1 与
469
- 「用户裁决」第 9 条;设计 N1)。
491
+ - **不批量执行工具调用**(没有 PTC / `run_code`):这是原始需求 2.1 的**收窄**,也是**实现者
492
+ 的范围决定(E2)**,不是用户裁决——**没有用户消息追认这条收窄**。收窄的理由是范围,不是
493
+ 「批量派发已被证明没有价值」:每步恰好 1 个工具占 79.8%,但 **20.2% 的步不是单工具步**——
494
+ 16.9% 带 ≥2 个调用、3.3% 零调用(`clarifications:17`);用户明确要求批量派发,非单工具步
495
+ 正是它的作用面。PTC 留二期,重启条件是影子期拿到批量步的真实占比与收益标签,而不是
496
+ 「79.8% 已证明不需要批量」(见[澄清记录](docs/superpowers/clarifications/2026-11-18-dsh-token-efficiency.md)
497
+ 的 2.1 与 E2;设计 N1)。
498
+ - **不回答「工具调用顺序由谁定」**:原始需求 2.3 要求调研组合工具的顺序(Jev 决策还是主模型
499
+ 一开始定好),v1 **没有交付这项调研**——这是开放缺口,**不被 PTC 的推迟覆盖**。v1 的实现是
500
+ 主模型逐步决定下一次调用,Jev 只在已声明候选里选一个、无权加步骤或改序;研究里
501
+ ReWOO / LLMCompiler 的「先声明计划、步骤间不再问模型」证据没有应用到定序权威上,也没有
502
+ 对比实验(`clarifications:19`、设计 §9)。
470
503
  - **不去重、不合并工具调用**(设计 N5)——这条完全没开工,且 v1 **没有任何工具能测出重复
471
504
  调用率**:设计稿里用来触发重启判定的「影子周重复率统计」没有交付,`shadow-report.mjs`
472
505
  不产出它。
506
+ - **HarnessMM 只移植了四件**:扁平候选银行、GDR 守卫、CCS 单候选提交、闭集选择器(Jev)。
507
+ **EDG 的图/链(`predecessor_id`)没有移植**——本插件的计划是扁平、每回执一次性的候选列表,
508
+ 源码里没有 `predecessor_id`;**RSI 循环也没有移植**——v1 是固定策略插件,没有训练/选择
509
+ 生命周期(`clarifications:16`)。
473
510
  - **影子周不省 token**:只记账(协议段照注入、选择器照调用),推荐配置下每请求仍固定花
474
511
  778(`selected + []` 为 399);它的产出是四个比例,不是省下的 token。
475
512
  - **v1 不评判「结果更好」**:只有 token 账目和一套**人工**的 20 任务回退流程(任务集不随包发布,
@@ -486,10 +523,11 @@ spill,报它只会制造噪音);但**收据通道**不看当前模式—
486
523
  - 不替换、也不接管 DSH 的压缩、剪枝与 spill 决策(设计 N3);投影只改模型可见 content,
487
524
  原文仍借宿主 spill 存放。
488
525
  - 不做模型训练或权重改动(N2);不追求论文里的 87.93%(N4)。
489
- - 不承诺 10%:3.5% 是事前估算的**下界**,不是保底;10% 是全程存活的理想上界。净保底约
490
- 0.4%(投影侧毛额约 0.8% 减去每请求固定开销约 0.4%)。影子周只回答替换侧是否值得打开
491
- (候选覆盖与命中),不决定发布,也不能把区间换成实测值(`shadow-report.mjs` 只有四个
492
- 比例,没有总 token 分母)。
526
+ - 不承诺 10%:3.5% 是事前估算的**下界**,不是保底;10% 是全程存活的理想上界。投影侧在
527
+ 300 个最长会话上的聚合净额约 0.4%(毛额约 0.8% 减去每请求固定开销约 0.4%),同样是
528
+ 离线估算,**不是每会话保底**(短会话可能倒亏)。影子周只给替换侧的标签(候选覆盖与提交
529
+ 产出率),不单独决定是否开启替换、也不决定发布,更不能把区间换成实测值
530
+ (`shadow-report.mjs` 只有四个比例,没有总 token 分母)。
493
531
 
494
532
  ## 文档
495
533
 
@@ -509,5 +547,6 @@ spill,报它只会制造噪音);但**收据通道**不看当前模式—
509
547
 
510
548
  ## 许可证
511
549
 
512
- Apache-2.0。机制移植自 [HarnessMM](https://github.com/YuhuaJiang2002/HarnessMM)(Apache-2.0),
513
- 随包分发 `NOTICE`。
550
+ Apache-2.0。机制移植自 [HarnessMM](https://github.com/YuhuaJiang2002/HarnessMM)(Apache-2.0):
551
+ 扁平候选银行、GDR 守卫、CCS 单候选提交与闭集选择器;**EDG 的图/链(`predecessor_id`)与
552
+ RSI 循环没有移植**。随包分发 `NOTICE`。