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.
@@ -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
@@ -117,6 +119,9 @@ const SELECTOR_RECEIPT_MAX_CHARS = 1_200;
117
119
  /** Skip reasons that mean the projection machinery degraded, not "nothing to cut". */
118
120
  const PROJECTION_DEGRADATIONS = new Set([
119
121
  'no-spill',
122
+ // `no-owner` is emitted by `projectApply`'s direct-call contract, not by this
123
+ // hook (design §5.4): the hook only calls it once an owner is known. Kept so
124
+ // a future caller cannot silently lose the mapping.
120
125
  'no-owner',
121
126
  'projection-skipped:no-footer',
122
127
  'spill-failed',
@@ -204,10 +209,8 @@ function pendingAnchorsOf(deps, sessionId) {
204
209
  * (`llm/stream`, 23c), where the compared text is the anchored receipt's current
205
210
  * body in the outgoing messages.
206
211
  */
207
- function markerResetOf(pending, receiptText) {
212
+ function markerResetOf(receiptText) {
208
213
  try {
209
- if (pending == null)
210
- return undefined;
211
214
  return looksPruned(receiptText) ? 'pruned-reset' : undefined;
212
215
  }
213
216
  catch {
@@ -613,23 +616,25 @@ async function recordProjectionRetrieval(deps, exec, sessionId, pending, visible
613
616
  // Admission and the decision branch
614
617
  // ---------------------------------------------------------------------------
615
618
  /**
616
- * The conservative saving of skipping one model step: the last real request's
617
- * replayed context (`input + cacheRead`).
619
+ * The saving of skipping one model step: the last real request's `totalTokens`
620
+ * (`input + cacheRead + output`), which is what design §5.3 defines it as.
618
621
  *
619
- * The step that is skipped would have replayed at least this much: the context
620
- * only grows as receipts enter it. A missing ledger or sample is 0, never an
621
- * interpolation, so admission falls back to the model when it cannot measure
622
- * (design §5.3: measured, not estimated).
622
+ * All three parts are skipped when the model does not run: the replayed context
623
+ * is not sent and the response is not generated. The context only grows as
624
+ * receipts enter it, so the last request is a lower bound. A missing ledger or
625
+ * sample is 0, never an interpolation, so admission falls back to the model when
626
+ * it cannot measure (design §5.3: measured, not estimated).
623
627
  */
624
628
  function savedTokensOf(deps, sessionId) {
625
629
  try {
626
630
  const last = sessionUsage(deps, sessionId)?.last();
627
631
  if (last === undefined)
628
632
  return 0;
629
- const { input, cacheRead } = last;
630
- if (!Number.isFinite(input) || !Number.isFinite(cacheRead) || input < 0 || cacheRead < 0)
633
+ const { input, cacheRead, output } = last;
634
+ const parts = [input, cacheRead, output];
635
+ if (parts.some((part) => !Number.isFinite(part) || part < 0))
631
636
  return 0;
632
- const total = input + cacheRead;
637
+ const total = input + cacheRead + output;
633
638
  return Number.isFinite(total) ? total : 0;
634
639
  }
635
640
  catch {
@@ -839,6 +844,10 @@ async function settleRollover(deps, sessionId, turn) {
839
844
  candidateId,
840
845
  ...(dispatched.evidence ?? {}),
841
846
  saved_input_tokens: settled.saved_input_tokens,
847
+ // Row 7: the same pair of samples also yields the lower estimate; the
848
+ // settled line is the only place a measured saving exists, so both numbers
849
+ // travel together.
850
+ avoided_total_tokens: settled.avoided_total_tokens,
842
851
  cache_hit_delta: settled.cache_hit_delta,
843
852
  output_tokens: settled.output_tokens,
844
853
  });
@@ -1113,6 +1122,29 @@ function admissionViewOf(exec) {
1113
1122
  return undefined;
1114
1123
  }
1115
1124
  }
1125
+ /**
1126
+ * The args as they will arrive from the host.
1127
+ *
1128
+ * `JSON.stringify` collapses `-0` to `0` and rewrites non-finite numbers to
1129
+ * `null`, so a pending tree that skipped this round trip would disagree with
1130
+ * its own dispatched call: `sameLiteral` would report tampering and the planned
1131
+ * call would never run (review cod#2).
1132
+ */
1133
+ function jsonNormalise(args) {
1134
+ try {
1135
+ const text = JSON.stringify(args);
1136
+ if (text === undefined)
1137
+ return args;
1138
+ const parsed = JSON.parse(text);
1139
+ if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
1140
+ return parsed;
1141
+ }
1142
+ return args;
1143
+ }
1144
+ catch {
1145
+ return args;
1146
+ }
1147
+ }
1116
1148
  /**
1117
1149
  * The substitution decision and its side effects.
1118
1150
  *
@@ -1196,6 +1228,10 @@ async function decideSubstitution(deps, ctx) {
1196
1228
  });
1197
1229
  }
1198
1230
  catch {
1231
+ // A throwing gate silently disabled substitution for this receipt, so make
1232
+ // it visible in `status.counts` (review row 24). The plan was already
1233
+ // consumed above; nothing can fire later from this failure.
1234
+ await appendReceipt(deps, ledgerEntry(ctx, 'skip', 'substitute-skipped:gate-error', { stepId: 'root' }));
1199
1235
  return;
1200
1236
  }
1201
1237
  // Substitution synthesises a dispatch and expects POSIX process semantics;
@@ -1325,8 +1361,14 @@ async function decideSubstitution(deps, ctx) {
1325
1361
  candidateId,
1326
1362
  // The candidate's tool name identifies the call; the executable args are
1327
1363
  // the *decision's* bound tree, never the plan's `$public` template.
1364
+ //
1365
+ // Normalised through a JSON round trip so the pending tree is byte-for-byte
1366
+ // what the host will hand back. `JSON.stringify` rewrites `-0` to `0` and
1367
+ // `Infinity`/`NaN` to `null`; without this, a legal plan arg of `-0` would
1368
+ // arrive as `0` and `sameLiteral` would report tampering, so the planned
1369
+ // call would never run (review cod#2).
1328
1370
  name: candidate.tool,
1329
- args: boundArgs,
1371
+ args: jsonNormalise(boundArgs),
1330
1372
  turn: ctx.turn,
1331
1373
  step,
1332
1374
  // The plan is one-shot (cleared above), so the evidence must travel with
@@ -1582,6 +1624,13 @@ async function projectDecision(deps, receipt, decision, ctx) {
1582
1624
  before,
1583
1625
  after,
1584
1626
  saved_projection_tokens: before - after,
1627
+ // How much the projection cut, in the units the footer names. Without
1628
+ // it a reader of the ledger cannot tell a 2 KB cut from a 200 KB one
1629
+ // (review cod#3: these fields had no consumer).
1630
+ ...(outcome.omittedBytes === undefined ? {} : { omitted_bytes: outcome.omittedBytes }),
1631
+ ...(outcome.omittedCodePoints === undefined
1632
+ ? {}
1633
+ : { omitted_code_points: outcome.omittedCodePoints }),
1585
1634
  estimate: deps.estimateKind ?? 'unknown',
1586
1635
  }));
1587
1636
  }
@@ -1590,6 +1639,10 @@ async function projectDecision(deps, receipt, decision, ctx) {
1590
1639
  unit: 'raw',
1591
1640
  horizon_steps: projectionHorizonOf(deps, ctx.sessionId),
1592
1641
  ...(ctx.retrievalCall === true ? { call_was_retrieval: true } : {}),
1642
+ ...(outcome.omittedBytes === undefined ? {} : { omitted_bytes: outcome.omittedBytes }),
1643
+ ...(outcome.omittedCodePoints === undefined
1644
+ ? {}
1645
+ : { omitted_code_points: outcome.omittedCodePoints }),
1593
1646
  estimate: 'unknown',
1594
1647
  }));
1595
1648
  }
@@ -1623,15 +1676,45 @@ async function projectDecision(deps, receipt, decision, ctx) {
1623
1676
  * The decision + projection stage.
1624
1677
  *
1625
1678
  * 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.
1679
+ * function: the receipt-visibility gate, then decide, then the
1680
+ * double-projection guard, then project. A shadow substitution does not stop
1681
+ * the projection: the two switches are independent (design §5.2-5), and in
1682
+ * projection-shadow mode the projection writes only its accounting line.
1630
1683
  */
1631
1684
  async function applyDecision(deps, decision, ctx) {
1685
+ // Substitution is only legitimate while the receipt is what the model sees.
1686
+ // `decide` and its guards were evaluated against `ctx.receipt.text`; a
1687
+ // `block`, or an `accept` carrying a replacement `value`, hides that text, so
1688
+ // a commit would dispatch a call whose evidence the model never received
1689
+ // (review row 11). `projectionTargetOf` is the same visibility predicate
1690
+ // projection uses: it rejects `block` and any `accept` with a `value`, and
1691
+ // accepts an `accept` whose content is text (possibly rewritten).
1692
+ //
1693
+ // A hidden receipt still consumes the one-shot plan: the plan was written for
1694
+ // the call that produced it, and keeping it would let it fire against a later
1695
+ // receipt whose text it was not written for.
1696
+ //
1632
1697
  // Projection below runs for a shadow commit too: the decision side never
1633
1698
  // suppresses the projection ledger.
1634
- await decideSubstitution(deps, ctx);
1699
+ const visible = projectionTargetOf(decision, ctx.receipt, ctx.result);
1700
+ if (visible === undefined) {
1701
+ clearPlan(deps, ctx.sessionId);
1702
+ }
1703
+ else if (visible !== ctx.receipt.text) {
1704
+ // An `accept` carrying its own `content` shows the model text the plugin
1705
+ // never canonicalised, so every guard and every literal in the plan was
1706
+ // checked against something else. Projection may still run — it rewrites
1707
+ // the visible text deliberately — but a substitution must not commit on
1708
+ // evidence the model cannot see (review qr5#3).
1709
+ //
1710
+ // No receipt: this is the normal outer-shaper path (`dsh-spill-policy`
1711
+ // appends its footer in every session), not a degradation. A receipt here
1712
+ // would be one line per oversized receipt and would read as a failure.
1713
+ clearPlan(deps, ctx.sessionId);
1714
+ }
1715
+ else {
1716
+ await decideSubstitution(deps, ctx);
1717
+ }
1635
1718
  // Second-projection guard. Two host shapers are outer to this listener:
1636
1719
  //
1637
1720
  // - The spill policy registers with `{ prepend: true }`: it calls `next()`
@@ -1650,8 +1733,23 @@ async function applyDecision(deps, decision, ctx) {
1650
1733
  // to a receipt this listener already clipped. A family the plugin does not
1651
1734
  // project leaves the host shaper untouched.
1652
1735
  //
1653
- // Both the receiver as it arrived and the decision that will enter history
1654
- // are checked (design §5.4).
1736
+ // What these two checks can and cannot catch (review row 25):
1737
+ //
1738
+ // - The first reads `ctx.receipt.text`, captured before this listener
1739
+ // returns. The outer spill policy appends its footer to the decision
1740
+ // *after* this point, so this check can never see the host's own footer.
1741
+ // It can only fire when the tool's output already ends in a spill notice —
1742
+ // for example a `read` of a spill artifact, whose text carries the notice
1743
+ // literally. That is still a receipt that is already a preview, so
1744
+ // refusing to project it again is the intended, if narrow, guard.
1745
+ // - The second sees a replacement an inner listener wrote into the decision.
1746
+ // An outer shaper's footer is invisible to it too.
1747
+ //
1748
+ // Neither check is full double-spill detection: at this point the host's
1749
+ // footer does not exist yet, so projection and the outer spill policy can
1750
+ // both act on one receipt. That is fail-safe, not prevention: the
1751
+ // projection's own footer keeps the original retrievable, and the host's
1752
+ // second notice points at the projected text.
1655
1753
  if (await isAlreadySpilled(deps, ctx.receipt.text))
1656
1754
  return decision;
1657
1755
  const downstreamText = decisionTextOf(decision) ?? ctx.receipt.text;
@@ -1787,7 +1885,7 @@ async function postExecute(deps, state, exec, result, next) {
1787
1885
  // `!= null` rather than `!== undefined`: a foreign store can hand back a
1788
1886
  // null, and dereferencing it would throw out of the hook.
1789
1887
  if (pending != null) {
1790
- const reset = markerResetOf(pending, receipt.text);
1888
+ const reset = markerResetOf(receipt.text);
1791
1889
  if (reset !== undefined) {
1792
1890
  await resetInvalidatedPending(deps, exec, sessionId, turn, pending, reset);
1793
1891
  if (retrieval !== undefined) {