@crewhaus/runtime-core 0.5.7 → 0.6.0

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.
@@ -0,0 +1,43 @@
1
+ /**
2
+ * 0.6.0 §7.9 — latency hygiene for the pool reward.
3
+ *
4
+ * The reward's latency term (`RouteObservation.latencyMs`) was measured as
5
+ * `now - t0Model` at the streaming fold, which spans every tool the
6
+ * streaming executor ran MID-STREAM (a tool dispatches the moment its
7
+ * `input_json` closes, while the model is still generating, and the drain
8
+ * after `message_stop` waits for the stragglers). A tool-heavy cheap arm was
9
+ * therefore penalised for latency it did not cause — and the learned policy
10
+ * learned the wrong thing from it. The non-streaming path never had the
11
+ * problem: tools run after the fold there.
12
+ *
13
+ * `createSpanUnionTracker` accumulates the UNION of overlapping spans (not
14
+ * their sum — up to `maxConcurrentTools` tools run at once, and summing would
15
+ * over-subtract), so `modelLatencyMs = wall - toolBusyMs` is the model's own
16
+ * time. Wall time is untouched: `model_response.durationMs` and `turn_end`
17
+ * keep measuring the turn the user waited for.
18
+ *
19
+ * Pure and clock-injectable so the union semantics are unit-tested with a
20
+ * fake clock — the runtime never asserts wall-clock timing.
21
+ */
22
+ export type SpanUnionTracker = {
23
+ /** A span opened (a `runTool` dispatch started). */
24
+ readonly enter: () => void;
25
+ /** A span closed (that dispatch settled — success, error or abort alike). */
26
+ readonly exit: () => void;
27
+ /** Total time, in ms, during which AT LEAST ONE span was open. */
28
+ readonly busyMs: () => number;
29
+ };
30
+ /**
31
+ * Track the union of concurrent spans against `now` (defaults to
32
+ * `performance.now`). `busyMs()` may be read while spans are still open — it
33
+ * then includes the in-progress stretch up to `now()`.
34
+ */
35
+ export declare function createSpanUnionTracker(now?: () => number): SpanUnionTracker;
36
+ /**
37
+ * The model's own latency for a streamed call: the wall span from request
38
+ * open (`t0Model`) to the fold (`nowMs`), minus the tool-busy union. Clamped
39
+ * at 0 so a tool span that (through clock skew) outlives the wall span can
40
+ * never yield a negative latency — which would be read as "infinitely fast"
41
+ * by the reward.
42
+ */
43
+ export declare function modelLatencyMs(t0Model: number, nowMs: number, toolBusyMs: number): number;
@@ -0,0 +1,61 @@
1
+ /**
2
+ * 0.6.0 §7.9 — latency hygiene for the pool reward.
3
+ *
4
+ * The reward's latency term (`RouteObservation.latencyMs`) was measured as
5
+ * `now - t0Model` at the streaming fold, which spans every tool the
6
+ * streaming executor ran MID-STREAM (a tool dispatches the moment its
7
+ * `input_json` closes, while the model is still generating, and the drain
8
+ * after `message_stop` waits for the stragglers). A tool-heavy cheap arm was
9
+ * therefore penalised for latency it did not cause — and the learned policy
10
+ * learned the wrong thing from it. The non-streaming path never had the
11
+ * problem: tools run after the fold there.
12
+ *
13
+ * `createSpanUnionTracker` accumulates the UNION of overlapping spans (not
14
+ * their sum — up to `maxConcurrentTools` tools run at once, and summing would
15
+ * over-subtract), so `modelLatencyMs = wall - toolBusyMs` is the model's own
16
+ * time. Wall time is untouched: `model_response.durationMs` and `turn_end`
17
+ * keep measuring the turn the user waited for.
18
+ *
19
+ * Pure and clock-injectable so the union semantics are unit-tested with a
20
+ * fake clock — the runtime never asserts wall-clock timing.
21
+ */
22
+ /**
23
+ * Track the union of concurrent spans against `now` (defaults to
24
+ * `performance.now`). `busyMs()` may be read while spans are still open — it
25
+ * then includes the in-progress stretch up to `now()`.
26
+ */
27
+ export function createSpanUnionTracker(now = () => performance.now()) {
28
+ let open = 0;
29
+ let openedAt;
30
+ let settled = 0;
31
+ return {
32
+ enter() {
33
+ if (open === 0)
34
+ openedAt = now();
35
+ open += 1;
36
+ },
37
+ exit() {
38
+ if (open === 0)
39
+ return; // tolerate an unmatched exit rather than go negative
40
+ open -= 1;
41
+ if (open === 0 && openedAt !== undefined) {
42
+ settled += Math.max(0, now() - openedAt);
43
+ openedAt = undefined;
44
+ }
45
+ },
46
+ busyMs() {
47
+ const live = open > 0 && openedAt !== undefined ? Math.max(0, now() - openedAt) : 0;
48
+ return settled + live;
49
+ },
50
+ };
51
+ }
52
+ /**
53
+ * The model's own latency for a streamed call: the wall span from request
54
+ * open (`t0Model`) to the fold (`nowMs`), minus the tool-busy union. Clamped
55
+ * at 0 so a tool span that (through clock skew) outlives the wall span can
56
+ * never yield a negative latency — which would be read as "infinitely fast"
57
+ * by the reward.
58
+ */
59
+ export function modelLatencyMs(t0Model, nowMs, toolBusyMs) {
60
+ return Math.max(0, nowMs - t0Model - Math.max(0, toolBusyMs));
61
+ }
@@ -168,9 +168,18 @@ export type AttachedAdvisorPersistence = {
168
168
  * `event-log` append path the run already writes its transcript with:
169
169
  *
170
170
  * error_recovered → `recovery` { errorName, action, depth }
171
- * tool_call_end → `tool_stats` { toolName, durationMs, isError }
171
+ * tool_call_end → `tool_stats` { toolName, durationMs, isError, profile? }
172
172
  * permission_decision → `permission` { toolName, decision, askOutcome }
173
- * model_response → `model_meta` { stopReason, model }
173
+ * model_response → `model_meta` { stopReason, model, role?, profile?,
174
+ * usage, durationMs, turnNumber }
175
+ *
176
+ * 0.6.0 (design §8.4) — `model_meta` carries exact per-turn attribution
177
+ * (`usage`, whole-ms `durationMs`, the envelope `turnNumber`, and the
178
+ * `role` / `profile` the response was published with) so `watchme report`'s
179
+ * `attributeModels` can be `exact` from the session log alone, without the
180
+ * opt-in `CREWHAUS_WATCHME` sidecar. `role`/`profile` are written only when
181
+ * the response carries them (absent role ⇒ primary), and readers that
182
+ * predate the enrichment keep reading `stopReason`/`model` unchanged.
174
183
  *
175
184
  * Unlike the other `attach*IfEnvSet` subscribers this one is DEFAULT-ON:
176
185
  * the lines are tiny (see the granularity note on the `tool_stats` kind in
@@ -212,6 +221,42 @@ export type AttachedMcpStatsPersistence = {
212
221
  * persistence hiccup must not abort a turn.
213
222
  */
214
223
  export declare function attachMcpStatsPersistence(bus: TraceEventBus, eventLog: EventLog, runContext: RunContext, env?: NodeJS.ProcessEnv): AttachedMcpStatsPersistence | undefined;
224
+ export type AttachedRoutingPersistence = {
225
+ unsubscribe: Unsubscribe;
226
+ };
227
+ /**
228
+ * 0.6.0 (design §8.1) — mirror the routing decisions that were trace-bus-only
229
+ * in 0.5.x into the session JSONL, as the durable event-log kinds of the same
230
+ * name, so `crewhaus route explain`, `sessions tail`, Hangar's session gutter
231
+ * and `--resume` read them offline:
232
+ *
233
+ * model_failover → `model_failover` { turnNumber, from, to, reason }
234
+ * model_stage → `model_stage` { turnNumber, stage, strategy, role, model, profile?, outcome, cause?, costUsdMicros? }
235
+ * model_directive → `model_directive` { turnNumber, source, requested, resolved?, accepted, reason? }
236
+ * judge_verdict → `judge_verdict` { turnNumber, stepOrNode, verdict, score, rationale?, judgeModel?, panel?, costUsdMicros? }
237
+ *
238
+ * A bus subscriber rather than a `logEvent` at each publish site because two
239
+ * of these are published OUTSIDE runtime-core: the failover chain in
240
+ * `@crewhaus/model-router` (which has no event log) and the `kind: judge`
241
+ * gate helpers emitted into workflow/graph bundles. `model_tier_route` is
242
+ * the exception — its only publisher is runtime-core's own tier branch, which
243
+ * writes the durable line directly beside the publish, exactly as
244
+ * `model_route` does.
245
+ *
246
+ * UNGATED, like the `model_route` line and unlike the advisor mirrors: these
247
+ * records are what replay reads (`--resume` reconstructs a directive pin from
248
+ * `model_directive`; `route explain` reconstructs a turn's stages), so an env
249
+ * flag that dropped them would make replay diverge from the run. The lines
250
+ * are small and fire once per decision, not per token. `append()` failures
251
+ * are logged, never thrown — a persistence hiccup must not abort a turn.
252
+ */
253
+ export type RoutingPersistedKind = "model_failover" | "model_stage" | "model_directive" | "judge_verdict";
254
+ export declare function attachRoutingPersistence(bus: TraceEventBus, eventLog: EventLog, runContext: RunContext, opts?: {
255
+ /** 0.6.0 PR 9c — persist only these kinds (a host's between-loop sink
256
+ * passes `["judge_verdict"]` so it never duplicates the lines the live
257
+ * loop's own subscriber writes). Absent → every routing kind. */
258
+ readonly kinds?: ReadonlyArray<RoutingPersistedKind>;
259
+ }): AttachedRoutingPersistence;
215
260
  export declare const WATCHME_MIRRORED_KINDS: ReadonlySet<string>;
216
261
  export type AttachedWatchmeCapture = {
217
262
  unsubscribe(): void;
@@ -363,9 +363,18 @@ const CLEAN_STOP_REASONS = new Set(["end_turn", "tool_use", "stop_sequence"]);
363
363
  * `event-log` append path the run already writes its transcript with:
364
364
  *
365
365
  * error_recovered → `recovery` { errorName, action, depth }
366
- * tool_call_end → `tool_stats` { toolName, durationMs, isError }
366
+ * tool_call_end → `tool_stats` { toolName, durationMs, isError, profile? }
367
367
  * permission_decision → `permission` { toolName, decision, askOutcome }
368
- * model_response → `model_meta` { stopReason, model }
368
+ * model_response → `model_meta` { stopReason, model, role?, profile?,
369
+ * usage, durationMs, turnNumber }
370
+ *
371
+ * 0.6.0 (design §8.4) — `model_meta` carries exact per-turn attribution
372
+ * (`usage`, whole-ms `durationMs`, the envelope `turnNumber`, and the
373
+ * `role` / `profile` the response was published with) so `watchme report`'s
374
+ * `attributeModels` can be `exact` from the session log alone, without the
375
+ * opt-in `CREWHAUS_WATCHME` sidecar. `role`/`profile` are written only when
376
+ * the response carries them (absent role ⇒ primary), and readers that
377
+ * predate the enrichment keep reading `stopReason`/`model` unchanged.
369
378
  *
370
379
  * Unlike the other `attach*IfEnvSet` subscribers this one is DEFAULT-ON:
371
380
  * the lines are tiny (see the granularity note on the `tool_stats` kind in
@@ -427,6 +436,9 @@ export function attachAdvisorPersistence(bus, eventLog, runContext, env = proces
427
436
  // without adding advisory signal.
428
437
  durationMs: Math.round(event.durationMs),
429
438
  isError: event.isError,
439
+ // 0.6.0 §5.6 — the serving profile, so `tools audit` can group
440
+ // failures by profile; absent (byte-identical) on a single-model run.
441
+ ...(event.profile !== undefined ? { profile: event.profile } : {}),
430
442
  });
431
443
  return;
432
444
  }
@@ -452,7 +464,17 @@ export function attachAdvisorPersistence(bus, eventLog, runContext, env = proces
452
464
  responses += 1;
453
465
  if (!CLEAN_STOP_REASONS.has(event.stopReason))
454
466
  anomalousStops += 1;
455
- persist("model_meta", { stopReason: event.stopReason, model: event.model });
467
+ persist("model_meta", {
468
+ stopReason: event.stopReason,
469
+ model: event.model,
470
+ ...(event.role !== undefined ? { role: event.role } : {}),
471
+ ...(event.profile !== undefined ? { profile: event.profile } : {}),
472
+ usage: event.usage,
473
+ // Whole milliseconds — performance.now() floats add line bytes
474
+ // without adding attribution signal.
475
+ durationMs: Math.round(event.durationMs),
476
+ turnNumber: event.turnNumber,
477
+ });
456
478
  return;
457
479
  }
458
480
  case "compaction_fired": {
@@ -533,6 +555,77 @@ export function attachMcpStatsPersistence(bus, eventLog, runContext, env = proce
533
555
  });
534
556
  return { unsubscribe };
535
557
  }
558
+ export function attachRoutingPersistence(bus, eventLog, runContext, opts = {}) {
559
+ const persist = (kind, payload) => {
560
+ void eventLog.append({ kind, payload }).catch((err) => {
561
+ runContext.logger.error("routing_event.persist_failed", {
562
+ kind,
563
+ message: err instanceof Error ? err.message : String(err),
564
+ });
565
+ });
566
+ };
567
+ const wanted = opts.kinds;
568
+ const unsubscribe = bus.subscribe((event) => {
569
+ if (wanted !== undefined && !wanted.includes(event.kind))
570
+ return;
571
+ switch (event.kind) {
572
+ case "model_failover": {
573
+ const e = event;
574
+ persist("model_failover", {
575
+ turnNumber: e.turnNumber,
576
+ from: e.from,
577
+ to: e.to,
578
+ reason: e.reason,
579
+ });
580
+ return;
581
+ }
582
+ case "model_stage": {
583
+ const e = event;
584
+ persist("model_stage", {
585
+ turnNumber: e.turnNumber,
586
+ stage: e.stage,
587
+ strategy: e.strategy,
588
+ role: e.role,
589
+ model: e.model,
590
+ ...(e.profile !== undefined ? { profile: e.profile } : {}),
591
+ outcome: e.outcome,
592
+ ...(e.cause !== undefined ? { cause: e.cause } : {}),
593
+ ...(e.costUsdMicros !== undefined ? { costUsdMicros: e.costUsdMicros } : {}),
594
+ });
595
+ return;
596
+ }
597
+ case "model_directive": {
598
+ const e = event;
599
+ persist("model_directive", {
600
+ turnNumber: e.turnNumber,
601
+ source: e.source,
602
+ requested: e.requested,
603
+ ...(e.resolved !== undefined ? { resolved: e.resolved } : {}),
604
+ accepted: e.accepted,
605
+ ...(e.reason !== undefined ? { reason: e.reason } : {}),
606
+ });
607
+ return;
608
+ }
609
+ case "judge_verdict": {
610
+ const e = event;
611
+ persist("judge_verdict", {
612
+ turnNumber: e.turnNumber,
613
+ stepOrNode: e.stepOrNode,
614
+ verdict: e.verdict,
615
+ score: e.score,
616
+ ...(e.rationale !== undefined ? { rationale: e.rationale } : {}),
617
+ ...(e.judgeModel !== undefined ? { judgeModel: e.judgeModel } : {}),
618
+ ...(e.panel !== undefined ? { panel: e.panel } : {}),
619
+ ...(e.costUsdMicros !== undefined ? { costUsdMicros: e.costUsdMicros } : {}),
620
+ });
621
+ return;
622
+ }
623
+ default:
624
+ return;
625
+ }
626
+ });
627
+ return { unsubscribe };
628
+ }
536
629
  // -------- "watch me" live capture tap (design/watch-me.md §6.1) --------
537
630
  /**
538
631
  * Reconciliation with the SHIPPED G26 `observability:` block (watch-me §4.5 —
@@ -589,6 +682,14 @@ const WATCHME_MIRRORED_KIND_RECORD = {
589
682
  model_meta: true,
590
683
  mcp_stats: true,
591
684
  model_route: true,
685
+ // 0.6.0 (design §8.1) — the routing decisions made durable in this release:
686
+ // the tier twin of model_route (written beside its publish) and the four
687
+ // kinds `attachRoutingPersistence` mirrors from the bus.
688
+ model_tier_route: true,
689
+ model_failover: true,
690
+ model_stage: true,
691
+ model_directive: true,
692
+ judge_verdict: true,
592
693
  wiki_write: true,
593
694
  plan_update: true,
594
695
  goal_update: true,
@@ -0,0 +1,149 @@
1
+ /**
2
+ * 0.6.0 §7.2 / §7.11 — the `preRoute` decision phase: what runs BEFORE the
3
+ * synchronous `PolicyRouter.route()` call on every pooled model call and
4
+ * produces the `RouteHint` the router consumes. Pure over its context (the
5
+ * one `await` is the opt-in classifier call the loop injects), so every
6
+ * decision replays exactly from the persisted `model_route` line.
7
+ *
8
+ * Order — forced → directive → rules → classifier → policy over `eligible[]`
9
+ * (plan §7.2; the forced lane comes FIRST so a `/model` pin can never disarm
10
+ * a budget degrade or an escalation):
11
+ *
12
+ * 1. eligibility (N1) — the turn's requirement vector (image blocks in the
13
+ * transcript, tools in play, the context size, a matched rule's
14
+ * `requires`) intersected with each candidate's features / declared
15
+ * `requires` / breaker state / `enabled` / remaining per-profile cost
16
+ * cap → `eligible[]`, persisted;
17
+ * 2. forced — a budget degrade or the escalation latch names the arm
18
+ * (substituted by the loop; the hint records the lane). The forced arm
19
+ * is run through the SAME requirement check: an ineligible degrade rung
20
+ * gives way to the cheapest eligible roster arm, an ineligible
21
+ * escalation target to the strongest eligible one (§7.11: ineligible
22
+ * rather than a request-time error), and when nothing eligible remains
23
+ * the forced arm stands with `no-eligible-candidate` recorded;
24
+ * 3. directive — the session's `/model` pin, when it is on the roster AND
25
+ * eligible this turn (an ineligible pin is noted and skipped);
26
+ * 4. rules — first-match `model_pool.rules[]`; `use: <tag|arm>` forces that
27
+ * arm, `use: { requires }` narrows `eligible[]` and picks the cheapest
28
+ * survivor; the `ruleId` is persisted;
29
+ * 5. classifier — `policy: classifier` runs the injected enum-constrained
30
+ * label call; any failure falls back to the heuristic policy with the
31
+ * reason `classifier failed`;
32
+ * 6. otherwise the hint only carries `eligible[]` and the policy decides.
33
+ *
34
+ * Also here: the SYNTHETIC-message marker. runtime-core pushes five kinds of
35
+ * non-human `role: "user"` messages onto the transcript (the grader-rationale
36
+ * correction, the continue nudge, the tombstone retry, loop-detection
37
+ * notices, the resume/toolset marker); they are `synthetic: true` in the
38
+ * event log and marked in memory here so `latestHumanUserMessage` — the
39
+ * text the rules and the classifier read — never sees them (a `/model fast`
40
+ * echoed inside a judge's rationale must not steer routing, §7.2.1).
41
+ * Directives themselves are parsed at the typed INPUT seams (the REPL input,
42
+ * the single-turn seed), never from the transcript.
43
+ */
44
+ import type Anthropic from "@anthropic-ai/sdk";
45
+ import { type EligibilityCandidate, type EligibilityExclusionReason, type RouteHint, type RouteRule, type RouteSignals, type RuleSkip, type TurnRequirement } from "@crewhaus/model-plan";
46
+ /** Mark a runtime-injected `role: "user"` message as NOT human input. Returns it. */
47
+ export declare function markSynthetic<T extends Anthropic.MessageParam>(message: T): T;
48
+ /** Was this message injected by the runtime (or replayed from a `synthetic: true` log line)? */
49
+ export declare function isSyntheticMessage(message: Anthropic.MessageParam): boolean;
50
+ /** The text blocks of a message joined by newlines (`""` for a tool-result-only message). */
51
+ export declare function messageText(message: Anthropic.MessageParam): string;
52
+ /** Does the message carry an image block (directly, not inside a tool_result)? */
53
+ export declare function messageHasImages(message: Anthropic.MessageParam): boolean;
54
+ /**
55
+ * The latest HUMAN user message: the last `role: "user"` entry that is not
56
+ * synthetic and carries human words or an image (a bare tool-result tail is
57
+ * skipped). `undefined` when none exists.
58
+ */
59
+ export declare function latestHumanUserMessage(messages: ReadonlyArray<Anthropic.MessageParam>): Anthropic.MessageParam | undefined;
60
+ /**
61
+ * The request-local copy of a user message with its `/model …` token
62
+ * removed: a string message becomes `rest`; a block message keeps every
63
+ * non-text block and replaces its text with `rest` (dropping the text block
64
+ * when `rest` is empty and other blocks remain). The PERSISTED transcript
65
+ * keeps the token — only the request copy is stripped (§7.2.1).
66
+ */
67
+ export declare function stripDirectiveFromMessage(message: Anthropic.MessageParam, rest: string): Anthropic.MessageParam;
68
+ /** One roster arm as `preRoute` sees it: the eligibility inputs plus its routing identity. */
69
+ export type PreRouteArm = EligibilityCandidate & {
70
+ readonly armId: string;
71
+ readonly modelString: string;
72
+ readonly tags: readonly string[];
73
+ };
74
+ /** The forced lane's input: a budget degrade or the escalation latch. */
75
+ export type PreRouteForced = {
76
+ /** The forced arm's id when it is on the roster (a non-roster degrade rung has none). */
77
+ readonly armId?: string;
78
+ /**
79
+ * The eligibility inputs of a degrade rung that sits OFF the roster (a
80
+ * roster arm is checked through `roster`). Absent → the rung's
81
+ * eligibility is unknown and it is served as-is.
82
+ */
83
+ readonly candidate?: EligibilityCandidate;
84
+ readonly lane: "budget" | "escalation";
85
+ readonly reason: string;
86
+ };
87
+ export type PreRouteClassifierVerdict = {
88
+ /** One of the pool's declared tags. */
89
+ readonly label: string;
90
+ /** Wire model id of the classifier call. */
91
+ readonly model?: string;
92
+ readonly costUsdMicros?: number;
93
+ };
94
+ export type PreRouteContext = {
95
+ /** The pool's enabled candidates, declared order. */
96
+ readonly roster: readonly PreRouteArm[];
97
+ readonly signals: RouteSignals;
98
+ /** The turn's requirement vector (N1). */
99
+ readonly turn: TurnRequirement;
100
+ readonly policy: "static" | "heuristic" | "learned" | "classifier";
101
+ readonly forced?: PreRouteForced;
102
+ /** The run's `/model` pin (already roster-validated); honoured only when eligible. */
103
+ readonly pin?: string;
104
+ readonly rules?: readonly RouteRule[];
105
+ /**
106
+ * The injected classifier call (`policy: classifier` only) — resolves to
107
+ * the label, throws on any failure. Absent → "no classifier wired".
108
+ */
109
+ readonly classifier?: () => Promise<PreRouteClassifierVerdict>;
110
+ /** The classifier's declared labels — the closed vocabulary a verdict must come from. */
111
+ readonly classifierLabels?: readonly string[];
112
+ /** Set by the loop when the classifier must not run (e.g. `judge_share_exhausted`). */
113
+ readonly classifierSkipReason?: string;
114
+ /** `model_pool.routing.strongTag` (default `strong`) — for the rule/classifier tag lookup. */
115
+ readonly strongTag?: string;
116
+ };
117
+ export type PreRouteResult = {
118
+ readonly hint: RouteHint;
119
+ /** Eligible arm ids, declared order (the hint's `eligible`, after any rule narrowing). */
120
+ readonly eligible: readonly string[];
121
+ readonly excluded: ReadonlyArray<{
122
+ readonly armId: string;
123
+ readonly reason: EligibilityExclusionReason;
124
+ }>;
125
+ /** The first-match rule that steered the turn, when one did. */
126
+ readonly ruleId?: string;
127
+ readonly skippedRules: readonly RuleSkip[];
128
+ readonly classifierVerdict?: PreRouteClassifierVerdict;
129
+ /**
130
+ * Set when the forced lane's arm was INELIGIBLE this turn (§7.11): `served`
131
+ * names the eligible roster arm substituted for it — the cheapest for a
132
+ * budget degrade, the strongest for an escalation — and is absent when no
133
+ * eligible arm remained (the loop then keeps the forced arm, records
134
+ * `no-eligible-candidate` and warns).
135
+ */
136
+ readonly forcedIneligible?: {
137
+ readonly armId: string;
138
+ readonly reason: string;
139
+ readonly served?: string;
140
+ };
141
+ /**
142
+ * Human-readable notes for the decision's `reason` — a pin that sat out,
143
+ * a rule whose target was ineligible, a classifier failure. Never user text.
144
+ */
145
+ readonly notes: readonly string[];
146
+ };
147
+ export declare function preRoute(ctx: PreRouteContext): Promise<PreRouteResult>;
148
+ /** Render a hint's evidence as `k=v` pairs for the persisted `hint.evidence` string. */
149
+ export declare function describeHintEvidence(evidence: Readonly<Record<string, unknown>>): string;