dsh-boost 0.1.2 → 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.
@@ -8,16 +8,18 @@
8
8
  * - `tools/post-execute` first gates on the same cached scope judgement the
9
9
  * protocol section reads, then canonicalises the result and runs a
10
10
  * conservative invalidation check. It files the arriving receipt under
11
- * `'root'`, works the substitution decision (`decide` → admission → pending
12
- * queue / shadow receipt / fallback), then the double-projection guard, and
13
- * finally projects the receipt when the scope document asks for it. Order is
14
- * fixed: `next() → scope gate → canonicalise → invalidate → decide →
15
- * (shadow receipt | admit and enqueue | fallback) → double-projection guard →
16
- * projection → return the decision` (plan §Task 23b). A call with no
17
- * `exec.agent` is not the plugin's to inspect: the downstream decision is
18
- * returned untouched and a `skip:no-scope` receipt keeps the pass visible
19
- * (design §5.5). A call carrying `exec.parent` is a PTC inner dispatch and
20
- * returns before any of this: it is not the step's root receipt.
11
+ * `'root'`, then — only when the decision leaves that receipt visible
12
+ * (`projectionTargetOf`) — works the substitution decision (`decide` →
13
+ * admission → pending queue / shadow receipt / fallback), then the
14
+ * double-projection guard, and finally projects the receipt when the scope
15
+ * document asks for it. Order is fixed: `next() → scope gate → canonicalise
16
+ * → invalidate → visibility gate → decide → (shadow receipt | admit and
17
+ * enqueue | fallback) → double-projection guard → projection → return the
18
+ * decision` (plan §Task 23b). A call with no `exec.agent` is not the
19
+ * plugin's to inspect: the downstream decision is returned untouched and a
20
+ * `skip:no-scope` receipt keeps the pass visible (design §5.5). A call
21
+ * carrying `exec.parent` is a PTC inner dispatch and returns before any of
22
+ * this: it is not the step's root receipt.
21
23
  * - `llm/stream` is the model-request waterfall. Its body lives in
22
24
  * `./llm-stream.ts` (Task 23c-1) and is re-exported below: it lets the
23
25
  * plugin's own selector request through untouched, then answers a pending
@@ -839,6 +841,10 @@ async function settleRollover(deps, sessionId, turn) {
839
841
  candidateId,
840
842
  ...(dispatched.evidence ?? {}),
841
843
  saved_input_tokens: settled.saved_input_tokens,
844
+ // Row 7: the same pair of samples also yields the lower estimate; the
845
+ // settled line is the only place a measured saving exists, so both numbers
846
+ // travel together.
847
+ avoided_total_tokens: settled.avoided_total_tokens,
842
848
  cache_hit_delta: settled.cache_hit_delta,
843
849
  output_tokens: settled.output_tokens,
844
850
  });
@@ -1113,6 +1119,29 @@ function admissionViewOf(exec) {
1113
1119
  return undefined;
1114
1120
  }
1115
1121
  }
1122
+ /**
1123
+ * The args as they will arrive from the host.
1124
+ *
1125
+ * `JSON.stringify` collapses `-0` to `0` and rewrites non-finite numbers to
1126
+ * `null`, so a pending tree that skipped this round trip would disagree with
1127
+ * its own dispatched call: `sameLiteral` would report tampering and the planned
1128
+ * call would never run (review cod#2).
1129
+ */
1130
+ function jsonNormalise(args) {
1131
+ try {
1132
+ const text = JSON.stringify(args);
1133
+ if (text === undefined)
1134
+ return args;
1135
+ const parsed = JSON.parse(text);
1136
+ if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
1137
+ return parsed;
1138
+ }
1139
+ return args;
1140
+ }
1141
+ catch {
1142
+ return args;
1143
+ }
1144
+ }
1116
1145
  /**
1117
1146
  * The substitution decision and its side effects.
1118
1147
  *
@@ -1196,6 +1225,10 @@ async function decideSubstitution(deps, ctx) {
1196
1225
  });
1197
1226
  }
1198
1227
  catch {
1228
+ // A throwing gate silently disabled substitution for this receipt, so make
1229
+ // it visible in `status.counts` (review row 24). The plan was already
1230
+ // consumed above; nothing can fire later from this failure.
1231
+ await appendReceipt(deps, ledgerEntry(ctx, 'skip', 'substitute-skipped:gate-error', { stepId: 'root' }));
1199
1232
  return;
1200
1233
  }
1201
1234
  // Substitution synthesises a dispatch and expects POSIX process semantics;
@@ -1325,8 +1358,14 @@ async function decideSubstitution(deps, ctx) {
1325
1358
  candidateId,
1326
1359
  // The candidate's tool name identifies the call; the executable args are
1327
1360
  // the *decision's* bound tree, never the plan's `$public` template.
1361
+ //
1362
+ // Normalised through a JSON round trip so the pending tree is byte-for-byte
1363
+ // what the host will hand back. `JSON.stringify` rewrites `-0` to `0` and
1364
+ // `Infinity`/`NaN` to `null`; without this, a legal plan arg of `-0` would
1365
+ // arrive as `0` and `sameLiteral` would report tampering, so the planned
1366
+ // call would never run (review cod#2).
1328
1367
  name: candidate.tool,
1329
- args: boundArgs,
1368
+ args: jsonNormalise(boundArgs),
1330
1369
  turn: ctx.turn,
1331
1370
  step,
1332
1371
  // The plan is one-shot (cleared above), so the evidence must travel with
@@ -1623,15 +1662,45 @@ async function projectDecision(deps, receipt, decision, ctx) {
1623
1662
  * The decision + projection stage.
1624
1663
  *
1625
1664
  * Both seams live in one place so the listener's order is visible in one
1626
- * function: decide, then the double-projection guard, then project. A shadow
1627
- * substitution does not stop the projection: the two switches are independent
1628
- * (design §5.2-5), and in projection-shadow mode the projection writes only
1629
- * its accounting line.
1665
+ * function: the receipt-visibility gate, then decide, then the
1666
+ * double-projection guard, then project. A shadow substitution does not stop
1667
+ * the projection: the two switches are independent (design §5.2-5), and in
1668
+ * projection-shadow mode the projection writes only its accounting line.
1630
1669
  */
1631
1670
  async function applyDecision(deps, decision, ctx) {
1671
+ // Substitution is only legitimate while the receipt is what the model sees.
1672
+ // `decide` and its guards were evaluated against `ctx.receipt.text`; a
1673
+ // `block`, or an `accept` carrying a replacement `value`, hides that text, so
1674
+ // a commit would dispatch a call whose evidence the model never received
1675
+ // (review row 11). `projectionTargetOf` is the same visibility predicate
1676
+ // projection uses: it rejects `block` and any `accept` with a `value`, and
1677
+ // accepts an `accept` whose content is text (possibly rewritten).
1678
+ //
1679
+ // A hidden receipt still consumes the one-shot plan: the plan was written for
1680
+ // the call that produced it, and keeping it would let it fire against a later
1681
+ // receipt whose text it was not written for.
1682
+ //
1632
1683
  // Projection below runs for a shadow commit too: the decision side never
1633
1684
  // suppresses the projection ledger.
1634
- await decideSubstitution(deps, ctx);
1685
+ const visible = projectionTargetOf(decision, ctx.receipt, ctx.result);
1686
+ if (visible === undefined) {
1687
+ clearPlan(deps, ctx.sessionId);
1688
+ }
1689
+ else if (visible !== ctx.receipt.text) {
1690
+ // An `accept` carrying its own `content` shows the model text the plugin
1691
+ // never canonicalised, so every guard and every literal in the plan was
1692
+ // checked against something else. Projection may still run — it rewrites
1693
+ // the visible text deliberately — but a substitution must not commit on
1694
+ // evidence the model cannot see (review qr5#3).
1695
+ //
1696
+ // No receipt: this is the normal outer-shaper path (`dsh-spill-policy`
1697
+ // appends its footer in every session), not a degradation. A receipt here
1698
+ // would be one line per oversized receipt and would read as a failure.
1699
+ clearPlan(deps, ctx.sessionId);
1700
+ }
1701
+ else {
1702
+ await decideSubstitution(deps, ctx);
1703
+ }
1635
1704
  // Second-projection guard. Two host shapers are outer to this listener:
1636
1705
  //
1637
1706
  // - The spill policy registers with `{ prepend: true }`: it calls `next()`
@@ -1650,8 +1719,23 @@ async function applyDecision(deps, decision, ctx) {
1650
1719
  // to a receipt this listener already clipped. A family the plugin does not
1651
1720
  // project leaves the host shaper untouched.
1652
1721
  //
1653
- // Both the receiver as it arrived and the decision that will enter history
1654
- // are checked (design §5.4).
1722
+ // What these two checks can and cannot catch (review row 25):
1723
+ //
1724
+ // - The first reads `ctx.receipt.text`, captured before this listener
1725
+ // returns. The outer spill policy appends its footer to the decision
1726
+ // *after* this point, so this check can never see the host's own footer.
1727
+ // It can only fire when the tool's output already ends in a spill notice —
1728
+ // for example a `read` of a spill artifact, whose text carries the notice
1729
+ // literally. That is still a receipt that is already a preview, so
1730
+ // refusing to project it again is the intended, if narrow, guard.
1731
+ // - The second sees a replacement an inner listener wrote into the decision.
1732
+ // An outer shaper's footer is invisible to it too.
1733
+ //
1734
+ // Neither check is full double-spill detection: at this point the host's
1735
+ // footer does not exist yet, so projection and the outer spill policy can
1736
+ // both act on one receipt. That is fail-safe, not prevention: the
1737
+ // projection's own footer keeps the original retrievable, and the host's
1738
+ // second notice points at the projected text.
1655
1739
  if (await isAlreadySpilled(deps, ctx.receipt.text))
1656
1740
  return decision;
1657
1741
  const downstreamText = decisionTextOf(decision) ?? ctx.receipt.text;