dsh-boost 0.1.1 → 0.1.2

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.
Files changed (48) hide show
  1. package/README.en.md +97 -33
  2. package/README.md +85 -32
  3. package/dist/gate/decide.js +33 -2
  4. package/dist/gate/decide.js.map +1 -1
  5. package/dist/hooks/llm-stream.js +129 -54
  6. package/dist/hooks/llm-stream.js.map +1 -1
  7. package/dist/hooks/post-execute.js +104 -21
  8. package/dist/hooks/post-execute.js.map +1 -1
  9. package/dist/hooks/session-state.js +18 -8
  10. package/dist/hooks/session-state.js.map +1 -1
  11. package/dist/index.js +371 -67
  12. package/dist/index.js.map +1 -1
  13. package/dist/scope/doc.js.map +1 -1
  14. package/dist/scope/store.js +24 -9
  15. package/dist/scope/store.js.map +1 -1
  16. package/package.json +8 -4
  17. package/dist/admission/fixed-cost.d.ts +0 -23
  18. package/dist/admission/ledger.d.ts +0 -113
  19. package/dist/admission/retrieval.d.ts +0 -65
  20. package/dist/admission/usage.d.ts +0 -75
  21. package/dist/config.d.ts +0 -43
  22. package/dist/gate/binding.d.ts +0 -113
  23. package/dist/gate/decide.d.ts +0 -82
  24. package/dist/gate/guard.d.ts +0 -69
  25. package/dist/gate/invalidate.d.ts +0 -112
  26. package/dist/gate/plan.d.ts +0 -86
  27. package/dist/hooks/clock.d.ts +0 -68
  28. package/dist/hooks/execute.d.ts +0 -79
  29. package/dist/hooks/llm-stream.d.ts +0 -283
  30. package/dist/hooks/pending.d.ts +0 -89
  31. package/dist/hooks/post-execute.d.ts +0 -257
  32. package/dist/hooks/session-state.d.ts +0 -158
  33. package/dist/hooks/synthesize.d.ts +0 -74
  34. package/dist/host/loader.d.ts +0 -23
  35. package/dist/host/platform.d.ts +0 -18
  36. package/dist/host/root.d.ts +0 -25
  37. package/dist/projection/apply.d.ts +0 -174
  38. package/dist/projection/canonicalise.d.ts +0 -43
  39. package/dist/projection/counters.d.ts +0 -65
  40. package/dist/projection/truncate.d.ts +0 -47
  41. package/dist/prompt/protocol.d.ts +0 -45
  42. package/dist/receipts/store.d.ts +0 -198
  43. package/dist/scope/doc.d.ts +0 -117
  44. package/dist/scope/resolve.d.ts +0 -91
  45. package/dist/scope/store.d.ts +0 -135
  46. package/dist/selector/jev.d.ts +0 -93
  47. package/dist/tools/boost.d.ts +0 -380
  48. package/dist/tools/family.d.ts +0 -26
@@ -192,6 +192,20 @@ export function sessionBudget(deps, sessionId) {
192
192
  ? deps.budget
193
193
  : undefined;
194
194
  }
195
+ /**
196
+ * Whether a substitution budget is wired at all.
197
+ *
198
+ * `undefined` from {@link sessionBudget} has two meanings and callers must not
199
+ * conflate them (row 21): with neither `deps.budget` nor a per-session runtime,
200
+ * the embedder never asked for a cap, so the substitution is unconstrained; a
201
+ * wired budget that this session may not borrow is the opposite — the shared
202
+ * instance belongs to another session and the step cannot be paid. Treating the
203
+ * refusal as "no cap" let an unbudgeted substitution through without ever
204
+ * incrementing the live budget.
205
+ */
206
+ export function budgetWired(deps) {
207
+ return deps.budget !== undefined || deps.sessions !== undefined;
208
+ }
195
209
  /** The session's usage ledger; the same precedence as {@link sessionClock}. */
196
210
  export function sessionUsage(deps, sessionId) {
197
211
  try {
@@ -206,13 +220,26 @@ export function sessionUsage(deps, sessionId) {
206
220
  ? deps.usage
207
221
  : undefined;
208
222
  }
209
- /** The session's anchors without ever failing the request. */
223
+ /**
224
+ * The session's anchors, distinguishing a record from a cold store.
225
+ *
226
+ * A substitution is only legitimate against the receipt the model still holds,
227
+ * so every missing answer is a lost anchor (row 28). `post-execute` writes
228
+ * anchors with every commit, so a live queue entry with no record means that
229
+ * write failed; synthesizing then would skip the only verification the design
230
+ * has. A throwing read is equally unverifiable. Both fail closed through the
231
+ * ordinary reset path instead of substituting on unseen evidence.
232
+ */
210
233
  function anchorsOf(deps, sessionId) {
234
+ const store = deps.anchors;
235
+ if (store == null || typeof store.get !== 'function')
236
+ return { kind: 'unreadable' };
211
237
  try {
212
- return deps.anchors?.get(sessionId);
238
+ const anchors = store.get(sessionId);
239
+ return anchors == null ? { kind: 'cold' } : { kind: 'record', anchors };
213
240
  }
214
241
  catch {
215
- return undefined;
242
+ return { kind: 'unreadable' };
216
243
  }
217
244
  }
218
245
  /**
@@ -454,24 +481,30 @@ function carriesAnchor(body, anchor, probe) {
454
481
  * pruner literal means `pruned-reset`, because the pruner is the common case
455
482
  * and it leaves the receipt in place. Only when no anchor was pruned does a
456
483
  * missing carrier mean `compaction-reset` (the history was replaced by a
457
- * summary). No anchors at all is vacuously intact: `post-execute` always writes
458
- * them with a commit, but a missing evidence store must not block substitution
459
- * forever.
484
+ * summary).
460
485
  *
461
- * An empty anchor cannot be located in any message and is skipped; `invalidate`
462
- * treats an empty anchor as a real value, but the stream hook has no receipt
463
- * body to compare it with, and refusing every substitution on one empty tool
464
- * result would be worse than the uncertainty.
486
+ * A missing record, a record with no entries and a record whose shape cannot be
487
+ * read are all unverifiable and therefore `compaction-reset` (row 28): the
488
+ * commit that parked the decision writes anchors, so their absence is a failed
489
+ * write, not a reason to substitute with zero verification. An empty anchor
490
+ * string is a real value the check skips; `invalidate` treats an empty anchor
491
+ * as a real value, and the stream hook has no receipt body to compare it with.
465
492
  */
466
493
  function anchorResetOf(anchors, messages, probe) {
467
494
  if (anchors == null)
468
- return undefined;
469
- const record = anchors.anchors;
495
+ return 'compaction-reset';
496
+ let record;
497
+ try {
498
+ record = anchors.anchors;
499
+ }
500
+ catch {
501
+ return 'compaction-reset';
502
+ }
470
503
  if (typeof record !== 'object' || record === null)
471
- return undefined;
504
+ return 'compaction-reset';
472
505
  const values = Object.values(record);
473
506
  if (values.length === 0)
474
- return undefined;
507
+ return 'compaction-reset';
475
508
  const texts = values.filter((text) => typeof text === 'string' && text.length > 0);
476
509
  if (texts.length === 0) {
477
510
  // An empty anchor is a real value the check skips (it cannot be located in
@@ -495,6 +528,15 @@ function anchorResetOf(anchors, messages, probe) {
495
528
  }
496
529
  return compacted ? 'compaction-reset' : undefined;
497
530
  }
531
+ /** The anchored step id a reset receipt names, never throwing on a foreign shape. */
532
+ function anchorStepIdOf(anchors) {
533
+ try {
534
+ return typeof anchors.stepId === 'string' ? anchors.stepId : 'root';
535
+ }
536
+ catch {
537
+ return 'root';
538
+ }
539
+ }
498
540
  /**
499
541
  * Per-session synthesis history, keyed by `HookDeps` first so two plugin
500
542
  * instances in one process cannot read each other's session. It holds one turn
@@ -554,8 +596,10 @@ function synthesisBlocked(deps, sessionId, entry, turn) {
554
596
  if (current !== undefined && current.callIds.has(entry.callId))
555
597
  return true;
556
598
  const budget = sessionBudget(deps, sessionId);
599
+ // Row 21: a wired budget that was not lent to this session is unpayable, not
600
+ // "no cap". Only a completely unwired budget leaves the step unconstrained.
557
601
  if (budget === undefined)
558
- return false;
602
+ return budgetWired(deps);
559
603
  let spent;
560
604
  try {
561
605
  spent = budget.count();
@@ -594,14 +638,6 @@ function resolveStreamPlan(deps, options) {
594
638
  const entry = peekPending(deps, sessionId);
595
639
  if (entry === undefined)
596
640
  return { kind: 'pass', sessionId };
597
- const turn = clockTurnOf(deps, sessionId);
598
- if (turn === undefined || !sameTurn(entry.turn, turn)) {
599
- return {
600
- kind: 'pass',
601
- sessionId,
602
- abandon: { entry, clearQueue: true, clearAnchors: false },
603
- };
604
- }
605
641
  // A blank call id cannot be dispatched and must not be "repaired" here: the
606
642
  // execute-side tamper check would compare a different id and reject silently.
607
643
  if (typeof entry.callId !== 'string' || entry.callId.trim().length === 0) {
@@ -611,22 +647,29 @@ function resolveStreamPlan(deps, options) {
611
647
  abandon: { entry, clearQueue: true, clearAnchors: false },
612
648
  };
613
649
  }
614
- const anchors = anchorsOf(deps, sessionId);
615
- const reset = anchorResetOf(anchors, options?.messages, anchorProbe(deps));
650
+ const turn = clockTurnOf(deps, sessionId);
651
+ // The reset receipt pairs with the entry's own turn when the clock cannot
652
+ // name a real one; a turn-0 commit still wrote (or failed to write) anchors.
653
+ const resetTurn = turn ?? turnNumberOf(entry.turn);
654
+ // Row 28: anchor evidence is checked before turn validity. A decision whose
655
+ // anchors were never written (the commit's `set` failed), a store that holds
656
+ // no record for a live entry, and a throwing read are all unverifiable;
657
+ // dropping them as an ordinary stale entry would hide the lost evidence.
658
+ // Intact anchors on a stale turn still take the silent abandon below: there
659
+ // the decision is dead by identity, not because its evidence vanished.
660
+ const anchorRead = anchorsOf(deps, sessionId);
661
+ if (anchorRead.kind !== 'record') {
662
+ return resetPlan(sessionId, entry, 'compaction-reset', 'root', resetTurn);
663
+ }
664
+ const reset = anchorResetOf(anchorRead.anchors, options?.messages, anchorProbe(deps));
616
665
  if (reset !== undefined) {
666
+ return resetPlan(sessionId, entry, reset, anchorStepIdOf(anchorRead.anchors), resetTurn);
667
+ }
668
+ if (turn === undefined || !sameTurn(entry.turn, turn)) {
617
669
  return {
618
670
  kind: 'pass',
619
671
  sessionId,
620
- abandon: {
621
- entry,
622
- clearQueue: true,
623
- clearAnchors: true,
624
- reset: {
625
- code: reset,
626
- stepId: typeof anchors?.stepId === 'string' ? anchors.stepId : 'root',
627
- turn: turn,
628
- },
629
- },
672
+ abandon: { entry, clearQueue: true, clearAnchors: false },
630
673
  };
631
674
  }
632
675
  // Re-check the step immediately before synthesizing. The turn/step checks
@@ -644,6 +687,24 @@ function resolveStreamPlan(deps, options) {
644
687
  }
645
688
  return { kind: 'synthesize', sessionId, entry };
646
689
  }
690
+ /**
691
+ * Abandon a decision whose anchored evidence cannot be verified.
692
+ *
693
+ * The reset receipt explains the lost anchor; the queue and anchors go with it,
694
+ * and the usage mark is settled as discarded by `applyAbandon`.
695
+ */
696
+ function resetPlan(sessionId, entry, code, stepId, turn) {
697
+ return {
698
+ kind: 'pass',
699
+ sessionId,
700
+ abandon: {
701
+ entry,
702
+ clearQueue: true,
703
+ clearAnchors: true,
704
+ reset: { code, stepId, turn },
705
+ },
706
+ };
707
+ }
647
708
  /**
648
709
  * A pass plan that abandons the session's pending entry, when one exists.
649
710
  *
@@ -687,30 +748,28 @@ export function settleDiscarded(deps, sessionId) {
687
748
  /**
688
749
  * Plan/guards evidence parked between synthesis and settlement.
689
750
  *
690
- * The settled receipt is written at the first real request after the
691
- * synthesized turn, when the queue entry is already gone; the synth-time
692
- * receipt has it from the entry, this park hands it to the settle. Keyed by
693
- * `HookDeps` first so two plugin instances in one process cannot read each
694
- * other's session, and a `WeakMap` lets the whole map die with the assembly.
751
+ * Keyed by `HookDeps` first so two plugin instances in one process cannot read
752
+ * each other's session, and a `WeakMap` lets the whole map die with the
753
+ * assembly.
695
754
  */
696
755
  const PENDING_EVIDENCE = new WeakMap();
697
- /** Park the evidence for the session's next settlement, replacing any earlier. */
698
- function rememberEvidence(deps, sessionId, evidence) {
756
+ /** Park the fact for the session's next settlement, replacing any earlier. */
757
+ function rememberEvidence(deps, sessionId, fact) {
699
758
  let bySession = PENDING_EVIDENCE.get(deps);
700
759
  if (bySession === undefined) {
701
760
  bySession = new Map();
702
761
  PENDING_EVIDENCE.set(deps, bySession);
703
762
  }
704
- bySession.set(sessionId, evidence);
763
+ bySession.set(sessionId, fact);
705
764
  }
706
- /** Take (and forget) the evidence one settlement consumes. */
765
+ /** Take (and forget) the fact one settlement consumes. */
707
766
  function takeEvidence(deps, sessionId) {
708
767
  const bySession = PENDING_EVIDENCE.get(deps);
709
- const evidence = bySession?.get(sessionId);
768
+ const fact = bySession?.get(sessionId);
710
769
  bySession?.delete(sessionId);
711
- return evidence;
770
+ return fact;
712
771
  }
713
- /** Drop evidence that no settlement will ever consume. */
772
+ /** Drop a fact that no settlement will ever consume. */
714
773
  function forgetEvidence(deps, sessionId) {
715
774
  PENDING_EVIDENCE.get(deps)?.delete(sessionId);
716
775
  }
@@ -759,26 +818,34 @@ async function settlePendingMark(deps, sessionId) {
759
818
  let settled;
760
819
  try {
761
820
  const pending = ledger.pendingCandidateId();
762
- if (typeof pending !== 'string' || pending.length === 0)
821
+ if (typeof pending !== 'string' || pending.length === 0) {
822
+ // A parked fact without a mark can never be settled; drop it rather than
823
+ // let a later, unrelated mark pick up this turn's evidence.
824
+ forgetEvidence(deps, sessionId);
763
825
  return;
826
+ }
764
827
  candidateId = pending;
765
828
  settled = ledger.settle();
766
829
  }
767
830
  catch {
831
+ forgetEvidence(deps, sessionId);
768
832
  return;
769
833
  }
834
+ const fact = takeEvidence(deps, sessionId);
770
835
  await appendReceipt(deps, {
771
836
  version: 1,
772
837
  ts: new Date().toISOString(),
773
838
  sessionId,
774
- turn: clockTurnOf(deps, sessionId) ?? 0,
839
+ // Row 26: the synthesized turn is the substitution's turn; the request that
840
+ // happens to settle it may already be the next one.
841
+ turn: fact?.turn ?? clockTurnOf(deps, sessionId) ?? 0,
775
842
  stepId: 'root',
776
843
  kind: 'substitute-settled',
777
844
  code: 'substitute-settled',
778
845
  candidateId,
779
846
  // G2 applies to the settled line too: the goal and guards are the same
780
847
  // evidence the synth-time line carried, parked when that line was written.
781
- ...(takeEvidence(deps, sessionId) ?? {}),
848
+ ...(fact?.evidence ?? {}),
782
849
  saved_input_tokens: settled.saved_input_tokens,
783
850
  cache_hit_delta: settled.cache_hit_delta,
784
851
  output_tokens: settled.output_tokens,
@@ -918,11 +985,19 @@ async function* synthesizeBranch(deps, sessionId, entry, upstream) {
918
985
  return;
919
986
  }
920
987
  markSubstitutedFor(deps, sessionId, current.candidateId);
921
- // Park the plan evidence for the settled line, which runs at the next real
922
- // request after this entry has left the queue.
988
+ // Park the plan evidence and the synthesis turn for the settled line, which
989
+ // runs at the next real request after this entry has left the queue.
923
990
  const evidence = current.evidence;
924
- if (evidence !== undefined)
925
- rememberEvidence(deps, sessionId, evidence);
991
+ const turn = turnNumberOf(current.turn);
992
+ rememberEvidence(deps, sessionId, {
993
+ turn,
994
+ ...(evidence === undefined ? {} : { evidence }),
995
+ });
996
+ // Row 27: mirror the synthesis fact now, not when `tools/execute` accepts the
997
+ // dispatch. A call denied by `tools/pre-execute` never reaches that hook, and
998
+ // a rollover must still report the model round this turn skipped. The mirror
999
+ // only feeds the settle path; it never claims a measured saving.
1000
+ deps.noteSynthesis?.(sessionId, turn, current.candidateId, evidence);
926
1001
  await appendSubstituteReceipt(deps, sessionId, current);
927
1002
  yield* synthesizeTurn(current);
928
1003
  }