Skip to main content

firstpass_core/
config.rs

1//! Routing configuration (SPEC §8.4) — declarative, agent-first.
2//!
3//! Config is the policy an operator (or agent) hands Firstpass: an ordered list of routes,
4//! each matching a slice of traffic to a mode, a model ladder, and gates; plus budget caps
5//! and escalation rules. The first matching route wins, so specific routes go first and a
6//! bare `match = {}` catch-all goes last.
7
8use crate::error::{Error, Result};
9use crate::features::{Features, TaskKind};
10use serde::{Deserialize, Serialize};
11use std::time::Duration;
12
13/// Serving mode for a route (SPEC glossary).
14#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
15#[serde(rename_all = "lowercase")]
16pub enum Mode {
17    /// Gate before serving; escalate on fail. The output is proven before the caller sees it.
18    Enforce,
19    /// Serve immediately, gate asynchronously — verdicts feed learning only. Zero added latency,
20    /// zero risk; the default for onboarding unfamiliar traffic.
21    Observe,
22}
23
24/// Named routing-mode presets: coherent (accuracy/cost/latency) constraint bundles layered
25/// on top of the existing escalation knobs. A mode is a **resolver** over existing config,
26/// not a new engine — it overrides only the knobs it has an opinion on; everything else
27/// comes from the route/global config unchanged.
28///
29/// `Balanced` (the default) is a strict no-op: with no mode set anywhere, behaviour is
30/// byte-identical to existing behaviour. All other modes are opt-in overlays.
31///
32/// Set per-request via the `x-firstpass-mode` header, per-route via `routing_mode = "..."`,
33/// or globally via the `FIRSTPASS_MODE_PROFILE` env var.
34#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
35#[serde(rename_all = "lowercase")]
36pub enum RoutingMode {
37    /// Forward without routing or gating; verdicts are asynchronous learning signals only.
38    /// Maps to the existing observe passthrough path. Zero added latency, zero quality proof.
39    Observe,
40    /// Prefer cheapest start; no speculative prefetch.
41    /// Tradeoff: lowest token spend; can serve lower quality on hard or heavy traffic.
42    Cost,
43    /// Today's default — bandit start, configured thresholds, configured speculation.
44    /// **This preset is a strict no-op: byte-identical to existing behaviour when applied.**
45    #[default]
46    Balanced,
47    /// One extra escalation rung allowed; serial (no speculative prefetch waste).
48    /// Tradeoff: higher quality ceiling at higher cost; still bounded by gate verification.
49    Quality,
50    /// `speculation = 1` always: always prefetch one rung ahead to cut p95 latency.
51    /// Tradeoff: pays 1 wasted speculative call when the cheap rung passes.
52    Latency,
53    /// Start at the top (most expensive) ladder rung; verification as insurance.
54    /// Tradeoff: highest quality, highest cost per call; bandit is bypassed; savings are minimal.
55    Max,
56}
57
58impl RoutingMode {
59    /// Lowercase string name, for use in headers and trace fields.
60    #[must_use]
61    pub fn as_str(self) -> &'static str {
62        match self {
63            Self::Observe => "observe",
64            Self::Cost => "cost",
65            Self::Balanced => "balanced",
66            Self::Quality => "quality",
67            Self::Latency => "latency",
68            Self::Max => "max",
69        }
70    }
71
72    /// All named modes in display order, for discovery surfaces (capabilities, MCP, CLI).
73    pub const ALL: &'static [Self] = &[
74        Self::Observe,
75        Self::Cost,
76        Self::Balanced,
77        Self::Quality,
78        Self::Latency,
79        Self::Max,
80    ];
81
82    /// The knob overrides this mode applies on top of the route/global escalation config.
83    /// `None` fields are left unchanged — modes only override where they have an opinion.
84    ///
85    /// **`Balanced` returns all `None`/`false`: it is a strict no-op by invariant.**
86    #[must_use]
87    pub fn preset(self) -> ModePreset {
88        match self {
89            // Observe: handled as a passthrough redirect before EnforceCtx; preset is unused.
90            Self::Observe => ModePreset {
91                speculation: None,
92                max_rungs_delta: None,
93                start_at_top: false,
94                description: "shadow mode: forward without gating; verdicts are async learning signals only",
95                tradeoff: "zero added latency, zero quality proof; use to observe before enforcing",
96            },
97            // Cost: kill speculative spend; let the bandit start cheap.
98            Self::Cost => ModePreset {
99                speculation: Some(0),
100                max_rungs_delta: None,
101                start_at_top: false,
102                description: "no speculative prefetch; bandit start on cheapest rung",
103                tradeoff: "lowest token spend; can serve lower quality on hard or heavy traffic",
104            },
105            // Balanced: all None — strict no-op so existing behaviour is preserved.
106            Self::Balanced => ModePreset {
107                speculation: None,
108                max_rungs_delta: None,
109                start_at_top: false,
110                description: "bandit start, configured thresholds and speculation (default — no behavioral change)",
111                tradeoff: "today's tuned balance; add a mode only when you need a different point",
112            },
113            // Quality: one more rung; no speculative waste.
114            Self::Quality => ModePreset {
115                speculation: Some(0),
116                max_rungs_delta: Some(1),
117                start_at_top: false,
118                description: "one extra escalation rung; serial (no speculative waste)",
119                tradeoff: "higher quality ceiling at higher cost; still bounded by gate verification",
120            },
121            // Latency: speculation=1 always; pay 1 wasted call to cut p95.
122            Self::Latency => ModePreset {
123                speculation: Some(1),
124                max_rungs_delta: None,
125                start_at_top: false,
126                description: "speculation=1: always prefetch one rung ahead to cut p95 latency",
127                tradeoff: "pays 1 wasted speculative call when cheap rung passes; speculation_band is overridden",
128            },
129            // Max: jump to top rung immediately; verification as insurance.
130            Self::Max => ModePreset {
131                speculation: Some(0),
132                max_rungs_delta: None,
133                start_at_top: true,
134                description: "start at the top (most expensive) ladder rung; verification as insurance",
135                tradeoff: "highest quality, highest cost per call; bandit bypassed; savings minimal",
136            },
137        }
138    }
139}
140
141/// Knob overrides a [`RoutingMode`] applies on top of the route/global escalation config.
142/// Only non-`None` fields override; absent fields leave the config value unchanged.
143///
144/// `Balanced` returns all `None`/`false` — it is a strict no-op.
145#[derive(Debug, Clone, Copy)]
146pub struct ModePreset {
147    /// Override for `escalation.speculation`. `None` = no override (config value unchanged).
148    pub speculation: Option<u32>,
149    /// Additive delta applied to `max_rungs_per_request`. `None` = no change.
150    /// Applied as `(current + delta).max(1)`.
151    pub max_rungs_delta: Option<i32>,
152    /// When `true`, start at the last ladder rung (top quality), bypassing the bandit.
153    pub start_at_top: bool,
154    /// One-line description of what this mode targets.
155    pub description: &'static str,
156    /// Honest tradeoff: what you gain and what you give up.
157    pub tradeoff: &'static str,
158}
159
160/// Top-level configuration document.
161#[derive(Debug, Clone, Default, Deserialize)]
162#[serde(deny_unknown_fields)]
163pub struct Config {
164    /// Ordered routes; first match wins.
165    #[serde(rename = "route", default)]
166    pub routes: Vec<Route>,
167    /// Spend caps.
168    #[serde(default)]
169    pub budget: Budget,
170    /// Escalation limits and promotion rules.
171    #[serde(default)]
172    pub escalation: Escalation,
173    /// Served-failure guardrail (ADR 0009 D3). Absent (the default) means nothing watches the
174    /// served-failure rate and behaviour is byte-identical to before.
175    #[serde(default)]
176    pub guardrail: Option<crate::guardrail::Guardrail>,
177    /// Seconds a demoted route stays demoted before the guardrail will consider it again.
178    /// Deliberately long: re-promoting on one good window makes routing flap, and every flap is
179    /// a visible behaviour change for real users.
180    #[serde(default = "default_guardrail_cooldown")]
181    pub guardrail_cooldown_secs: i64,
182    /// User-defined subprocess gates (SPEC §8.1), referenced by `id` from a route's `gates` /
183    /// `deferred_gates`. Declared as `[[gate]]` sections in TOML.
184    #[serde(rename = "gate", default)]
185    pub gate_defs: Vec<GateDef>,
186    /// Per-deployment price overrides, replacing the built-in defaults for the named models.
187    /// List prices drift and enterprise contracts differ — savings math is only honest when the
188    /// operator can pin THEIR prices. Declared as `[[price]]` sections in TOML.
189    #[serde(rename = "price", default)]
190    pub price_defs: Vec<PriceDef>,
191    /// Extra model providers a ladder can route to, beyond the built-in `anthropic` / `openai`.
192    /// Any OpenAI-compatible endpoint (Groq, Together, Fireworks, DeepSeek, Mistral, xAI,
193    /// OpenRouter, Ollama, vLLM, Azure, …) is one `[[provider]]` entry — no rebuild. Declared as
194    /// `[[provider]]` sections; a ladder rung is then `<id>/<model>`.
195    #[serde(rename = "provider", default)]
196    pub providers: Vec<ProviderDef>,
197}
198
199/// The wire API a provider speaks. `anthropic` = Messages API; `openai` = Chat Completions API
200/// (the de-facto standard that nearly every hosted and open-source model host implements);
201/// `gemini` = Google's Generative Language API (`generateContent`).
202#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
203#[serde(rename_all = "lowercase")]
204pub enum Dialect {
205    /// Anthropic Messages API (`POST /v1/messages`).
206    Anthropic,
207    /// OpenAI Chat Completions API (`POST /v1/chat/completions`).
208    Openai,
209    /// Google Gemini Generative Language API (`POST /v1beta/models/<model>:generateContent`),
210    /// authenticated with an API key in the `x-goog-api-key` header.
211    Gemini,
212}
213
214/// How a provider call is credentialed — orthogonal to [`Dialect`] (ADR 0006): dialect shapes the
215/// request/response body, auth scheme shapes how the request is signed/credentialed. Default
216/// (`api_key_env` / BYOK header) is unchanged for every existing `[[provider]]` entry.
217#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize)]
218#[serde(rename_all = "snake_case")]
219pub enum AuthScheme {
220    /// API key in a header (`x-api-key`, `Authorization: Bearer`, or `x-goog-api-key`) — today's
221    /// behavior for `anthropic` / `openai` / `gemini`.
222    #[default]
223    ApiKey,
224    /// AWS SigV4 request signing (Bedrock) — credentials from `AWS_ACCESS_KEY_ID` /
225    /// `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`, region-scoped.
226    AwsSigv4,
227    /// GCP OAuth2 bearer token (Vertex AI) — minted and cached by `gcp_auth` from
228    /// `GOOGLE_APPLICATION_CREDENTIALS` or the ambient environment.
229    GcpOauth,
230}
231
232/// A model provider a ladder can route to. Declared as `[[provider]]` in TOML; referenced from a
233/// ladder as `<id>/<model>` (e.g. `groq/llama-3.3-70b-versatile`).
234#[derive(Debug, Clone, Deserialize)]
235#[serde(deny_unknown_fields)]
236pub struct ProviderDef {
237    /// Ladder prefix for this provider, e.g. `"groq"`. Overrides a built-in of the same id.
238    pub id: String,
239    /// Which wire API it speaks.
240    pub dialect: Dialect,
241    /// Base URL, e.g. `"https://api.groq.com/openai"` or `"http://localhost:11434"` for Ollama.
242    /// Unused for `aws_sigv4/gcp_oauth` auth (those construct the URL from `region`/`project`).
243    #[serde(default)]
244    pub base_url: String,
245    /// Env var the API key is read from at call time, e.g. `"GROQ_API_KEY"`. Omit for a keyless
246    /// endpoint (local Ollama / vLLM). Per-request BYOK headers still apply to the built-in
247    /// `anthropic` / `openai` providers.
248    #[serde(default)]
249    pub api_key_env: Option<String>,
250    /// How this provider's requests are credentialed. `api_key` (default) is byte-identical to
251    /// today; `aws_sigv4` / `gcp_oauth` are the Bedrock/Vertex auth schemes (ADR 0006).
252    #[serde(default)]
253    pub auth: AuthScheme,
254    /// Cloud region, e.g. `"us-east-1"` — required for `aws_sigv4` (Bedrock) and `gcp_oauth`
255    /// (Vertex).
256    #[serde(default)]
257    pub region: Option<String>,
258    /// GCP project id — required for `gcp_oauth` (Vertex).
259    #[serde(default)]
260    pub project: Option<String>,
261}
262
263/// A per-deployment price override for one model (`provider/model`), USD per 1M tokens.
264#[derive(Debug, Clone, Deserialize)]
265#[serde(deny_unknown_fields)]
266pub struct PriceDef {
267    /// The ladder id this price applies to, e.g. `"anthropic/claude-haiku-4-5"`.
268    pub model: String,
269    /// USD per 1M input (prompt) tokens.
270    pub input_per_mtok: f64,
271    /// USD per 1M output (completion) tokens.
272    pub output_per_mtok: f64,
273}
274
275/// A user-defined gate (SPEC §8.1). Exactly one kind per definition:
276/// - **subprocess** (`cmd`): any executable that reads the candidate as JSON on **stdin** (never
277///   argv — injection-resistant) and emits `{"verdict":"pass|fail|abstain", ...}` on stdout.
278/// - **judge** (`judge`): a native LLM-judge gate that grades the candidate against a rubric.
279/// - **consistency** (`consistency`): a self-consistency uncertainty gate that scores the
280///   candidate by agreement with k fresh samples of the same model (Wang et al. 2022).
281/// - **schema** (`schema`): validates the candidate (parsed as JSON) against a JSON-Schema
282///   subset (top-level `type` / `required` / per-property `type`).
283/// - **decision** (`decision`): a cheap external decision-model verifier (TypeSafe's Jev) that
284///   answers a single yes/no "does this response satisfy the request?" question. **Unmeasured**:
285///   its precision/recall against real failures has not been benchmarked.
286#[derive(Debug, Clone, Deserialize)]
287#[serde(deny_unknown_fields)]
288pub struct GateDef {
289    /// The id a route references this gate by (must be unique and not shadow a built-in gate id).
290    pub id: String,
291    /// Subprocess command: program first, then its args — e.g. `["pytest", "-q"]`. Set this **or**
292    /// `judge` / `consistency` / `schema` / `decision`, not both.
293    #[serde(default)]
294    pub cmd: Vec<String>,
295    /// Hard timeout in milliseconds for a subprocess gate; it abstains (`timeout`) if the process
296    /// runs longer.
297    #[serde(default = "default_gate_timeout_ms")]
298    pub timeout_ms: u64,
299    /// LLM-judge configuration. Set this **or** `cmd` / `consistency` / `schema` / `decision`,
300    /// not both.
301    #[serde(default)]
302    pub judge: Option<JudgeDef>,
303    /// Self-consistency configuration. Set this **or** `cmd` / `judge` / `schema` / `decision`,
304    /// not both.
305    #[serde(default)]
306    pub consistency: Option<ConsistencyDef>,
307    /// JSON-Schema (subset) the candidate must satisfy. Set this **or** `cmd` / `judge` /
308    /// `consistency` / `decision`, not both.
309    #[serde(default)]
310    pub schema: Option<serde_json::Value>,
311    /// TypeSafe Jev decision-model configuration. Set this **or** `cmd` / `judge` / `consistency`
312    /// / `schema`, not both.
313    #[serde(default)]
314    pub decision: Option<DecisionDef>,
315    /// What an **abstain** from this gate means for serving (§7.2). `fail_open` (default): an
316    /// abstaining gate never blocks serving — availability over strictness, today's behavior.
317    /// `fail_closed`: an abstain blocks serving exactly like a `Fail` — strictness over
318    /// availability, for gates whose silence must never be mistaken for approval.
319    #[serde(default)]
320    pub on_abstain: AbstainPolicy,
321}
322
323/// Per-gate abstain policy (§7.2): what happens to serving when the gate can't produce a verdict.
324#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)]
325#[serde(rename_all = "snake_case")]
326pub enum AbstainPolicy {
327    /// An abstain never blocks serving (the historical behavior).
328    #[default]
329    FailOpen,
330    /// An abstain blocks serving exactly like a `Fail`.
331    FailClosed,
332}
333
334/// Configuration for a native LLM-judge gate (SPEC §8.3): a separate model grades the candidate
335/// against a rubric. The runner enforces maker ≠ checker (a model never grades its own output) and
336/// treats the candidate as data, not instructions.
337#[derive(Debug, Clone, Deserialize)]
338#[serde(deny_unknown_fields)]
339pub struct JudgeDef {
340    /// The judge model, as `provider/model` (must differ from the candidate's model at runtime).
341    pub model: String,
342    /// Pass iff the judge's score ≥ this threshold, in `[0, 1]`.
343    #[serde(default = "default_judge_threshold")]
344    pub threshold: f64,
345    /// What "good" means for this route — handed to the judge as the grading rubric.
346    #[serde(default)]
347    pub rubric: Option<String>,
348}
349
350/// Configuration for a self-consistency uncertainty gate: resample the original request `k` times
351/// on the same model and score the candidate by agreement with the fresh samples.
352///
353/// Research basis: Wang et al. 2022 (self-consistency) and Farquhar et al., *Nature* 2024
354/// (semantic entropy). Answers a model reliably reproduces are far likelier correct; disagreement
355/// flags hallucination. This produces a continuous confidence score the conformal threshold
356/// machinery can calibrate.
357///
358/// **maker == checker is intentional** — unlike a judge gate, self-consistency is definitionally
359/// self-referential. This is the mechanism, not a bug.
360#[derive(Debug, Clone, Deserialize)]
361#[serde(deny_unknown_fields)]
362pub struct ConsistencyDef {
363    /// The model used for resampling, as `provider/model`. May equal the candidate's model —
364    /// self-consistency is self-referential by design.
365    pub model: String,
366    /// Number of resample calls. Must be in `[2, 8]`; defaults to `3`.
367    #[serde(default = "default_consistency_k")]
368    pub k: u32,
369    /// Pass iff the mean agreement score ≥ this threshold, in `[0, 1]`.
370    pub threshold: f64,
371}
372
373/// Configuration for a TypeSafe Jev decision-model gate: a cheap (~$0.042/M input tokens) external
374/// verifier, orders of magnitude cheaper than a frontier LLM-judge call. It asks Jev's
375/// `POST {base_url}/v1/systemone` a single `noul` (probability-of-yes) question — "does this
376/// response fully and correctly satisfy this request?" — and passes iff `P(yes) >= threshold`.
377///
378/// The request and candidate response are carried only inside the `state` payload, as DATA — never
379/// interpolated into `instructions` — so a candidate that tries to talk the verifier into a pass
380/// cannot reach the instruction the model actually follows.
381///
382/// **Unmeasured**: this gate's precision/recall against real failures has not been benchmarked.
383/// Treat it as an unvalidated cheap pre-filter, not a drop-in replacement for `judge`.
384#[derive(Debug, Clone, Deserialize)]
385#[serde(deny_unknown_fields)]
386pub struct DecisionDef {
387    /// Decision-model provider. Only `"typesafe"` is built in today; validated by
388    /// [`Config::parse`].
389    pub provider: String,
390    /// Model name passed to the provider's API.
391    #[serde(default = "default_decision_model")]
392    pub model: String,
393    /// Env var naming the API key. Read once at gate-build time; never logged, never put on the
394    /// trace.
395    #[serde(default = "default_decision_api_key_env")]
396    pub api_key_env: String,
397    /// Provider API base URL.
398    #[serde(default = "default_decision_base_url")]
399    pub base_url: String,
400    /// Hard timeout for the decision call. A timeout, transport error, non-2xx response, or a
401    /// reply this gate cannot parse all ABSTAIN (fail-safe) — never a fabricated `Pass`.
402    #[serde(default = "default_decision_timeout_ms")]
403    pub timeout_ms: u64,
404    /// Pass iff `P(yes) >= threshold`. Must be in the open interval `(0, 1)`; validated by
405    /// [`Config::parse`].
406    #[serde(default = "default_decision_threshold")]
407    pub threshold: f64,
408    /// Override the default yes/no verification question. `None` (default) uses a generic
409    /// "does the response satisfy the request" instruction.
410    #[serde(default)]
411    pub instructions: Option<String>,
412}
413
414/// Default subprocess-gate timeout: 30s. Long enough for a test suite, short enough to bound the
415/// enforce-path tail.
416fn default_gate_timeout_ms() -> u64 {
417    30_000
418}
419
420/// Default judge pass threshold.
421fn default_judge_threshold() -> f64 {
422    0.7
423}
424
425/// Default self-consistency k (resample count).
426fn default_consistency_k() -> u32 {
427    3
428}
429
430fn default_decision_model() -> String {
431    "jev-latest".to_owned()
432}
433
434fn default_decision_api_key_env() -> String {
435    "TYPESAFE_API_KEY".to_owned()
436}
437
438fn default_decision_base_url() -> String {
439    "https://api.typesafe.ai".to_owned()
440}
441
442fn default_decision_timeout_ms() -> u64 {
443    1_000
444}
445
446fn default_decision_threshold() -> f64 {
447    0.5
448}
449
450/// One routing rule.
451#[derive(Debug, Clone, Deserialize)]
452#[serde(deny_unknown_fields)]
453pub struct Route {
454    /// The traffic this route claims. An empty match (`{}`) matches everything.
455    #[serde(rename = "match", default)]
456    pub match_: Match,
457    /// Serving mode.
458    pub mode: Mode,
459    /// Model ladder, cheapest first, as `provider/model` strings.
460    #[serde(default)]
461    pub ladder: Vec<String>,
462    /// Inline gates run before serving (enforce mode).
463    #[serde(default)]
464    pub gates: Vec<String>,
465    /// Gates run asynchronously after serving; their verdicts attach to the trace as a
466    /// learning signal and never block the response.
467    #[serde(default)]
468    pub deferred_gates: Vec<String>,
469    /// Per-route routing-mode preset. Overrides `FIRSTPASS_MODE_PROFILE`; overridden by the
470    /// per-request `x-firstpass-mode` header. Absent (default `None`) falls through to the
471    /// global default, then `Balanced` — byte-identical to existing behaviour.
472    #[serde(default)]
473    pub routing_mode: Option<RoutingMode>,
474    /// Percentage rollout (ADR 0009 D1): enforce only a slice of this route's matched traffic,
475    /// held constant per session so a conversation never flips arm mid-thread. Absent (the
476    /// default) enforces all matched traffic — byte-identical to existing behaviour.
477    #[serde(default)]
478    pub rollout: Option<crate::rollout::Rollout>,
479    /// Shadow scoring (ADR 0009 D2): on a sample of *observed* requests, run the ladder off the
480    /// hot path and record what would have been served and what it would have cost. Absent (the
481    /// default) leaves observe exactly as it was. Makes real model calls when enabled, which is
482    /// why `max_usd_per_day` is required rather than defaulted.
483    #[serde(default)]
484    pub shadow: Option<crate::rollout::Shadow>,
485    /// Certified model selection (ADR 0014): serve a randomized fraction of *sessions* from a
486    /// challenger ladder, collect task outcomes through the feedback API, and let a sequential
487    /// non-inferiority test decide certified / halted / undecided. Requires `mode = "enforce"`.
488    /// Absent (the default) leaves the route exactly as it was.
489    #[serde(default)]
490    pub challenger: Option<crate::rollout::Challenger>,
491}
492
493/// Predicate over a request's [`Features`]. Every present field is an AND-constraint; absent
494/// fields are wildcards.
495#[derive(Debug, Clone, Default, Deserialize)]
496#[serde(deny_unknown_fields)]
497pub struct Match {
498    /// Require a specific calling agent.
499    #[serde(default)]
500    pub agent: Option<String>,
501    /// Require the subagent to be one of these (or this one, if a bare string).
502    #[serde(default)]
503    pub subagent: Option<StringOrVec>,
504    /// Require a specific task kind.
505    #[serde(default)]
506    pub task_kind: Option<TaskKind>,
507    /// Require the language to be one of these (or this one, if a bare string).
508    #[serde(default)]
509    pub language: Option<StringOrVec>,
510}
511
512impl Match {
513    /// Whether `f` satisfies every present constraint.
514    #[must_use]
515    pub fn matches(&self, f: &Features) -> bool {
516        if let Some(agent) = &self.agent
517            && f.agent.as_deref() != Some(agent.as_str())
518        {
519            return false;
520        }
521        if let Some(subs) = &self.subagent {
522            match &f.subagent {
523                Some(s) if subs.contains(s) => {}
524                _ => return false,
525            }
526        }
527        if let Some(tk) = self.task_kind
528            && f.task_kind != tk
529        {
530            return false;
531        }
532        if let Some(langs) = &self.language {
533            match &f.language {
534                Some(l) if langs.contains(l) => {}
535                _ => return false,
536            }
537        }
538        true
539    }
540}
541
542/// A field that accepts either a single string or a list of strings in TOML/JSON.
543#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
544#[serde(untagged)]
545pub enum StringOrVec {
546    /// A single value.
547    One(String),
548    /// A set of values.
549    Many(Vec<String>),
550}
551
552impl StringOrVec {
553    /// Whether `needle` is contained in this value.
554    #[must_use]
555    pub fn contains(&self, needle: &str) -> bool {
556        match self {
557            StringOrVec::One(s) => s == needle,
558            StringOrVec::Many(v) => v.iter().any(|s| s == needle),
559        }
560    }
561}
562
563/// What to do when a spend cap is hit (SPEC §8.4 — never brick the customer).
564#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
565#[serde(rename_all = "snake_case")]
566pub enum OnExhausted {
567    /// Serve the best attempt seen so far (default).
568    #[default]
569    ServeBestAttempt,
570    /// Return a structured error instead of serving.
571    Error,
572}
573
574/// Spend caps. `None` means "no cap".
575#[derive(Debug, Clone, Default, Deserialize)]
576#[serde(deny_unknown_fields)]
577pub struct Budget {
578    /// Max USD per single request (across all rungs + gates).
579    #[serde(default)]
580    pub per_request_usd: Option<f64>,
581    /// Max USD per session.
582    #[serde(default)]
583    pub per_session_usd: Option<f64>,
584    /// Max USD per day.
585    #[serde(default)]
586    pub per_day_usd: Option<f64>,
587    /// Behaviour when a cap is reached.
588    #[serde(default)]
589    pub on_exhausted: OnExhausted,
590}
591
592/// Escalation limits and session-level promotion.
593#[derive(Debug, Clone, Deserialize)]
594#[serde(deny_unknown_fields)]
595pub struct Escalation {
596    /// Hard ceiling on rungs climbed within one request.
597    #[serde(default = "default_max_rungs")]
598    pub max_rungs_per_request: u32,
599    /// Optionally start higher for the rest of a session that keeps failing.
600    #[serde(default)]
601    pub session_promotion: Option<SessionPromotion>,
602    /// Prefetch depth: fire this many rungs ahead concurrently to trade wasted spend for latency.
603    /// `0` (default) is serial — one call at a time. The served result is identical either way.
604    #[serde(default)]
605    pub speculation: u32,
606    /// Calibrated conformal serve threshold: a rung is served iff its aggregate gate score is
607    /// `>=` this value (SPEC §10.1). `None` (default) keeps the original rule — serve iff the
608    /// aggregate gate verdict is `Pass` — byte-identical to today.
609    #[serde(default)]
610    pub serve_threshold: Option<f64>,
611    /// Online/adaptive conformal (Gibbs-Candès ACI): when set, the serve threshold is tracked
612    /// **live** from deferred feedback instead of held fixed, so served-failure stays at target under
613    /// distribution shift. `None` (default) uses the fixed `serve_threshold` above — byte-identical.
614    #[serde(default)]
615    pub adaptive: Option<AdaptiveConfig>,
616    /// Anytime-valid risk control (ADR 0011). Takes precedence over `adaptive` once it certifies.
617    #[serde(default)]
618    pub eprocess: Option<EProcessConfig>,
619    /// Route tool-calling / multimodal requests through enforce (ADR 0005). **Default `true`**:
620    /// agent traffic — the target workload — is gated out of the box. A per-request fidelity
621    /// guard still applies: structured content only routes when every ladder rung's provider
622    /// carries it verbatim (Anthropic-dialect today); otherwise the request falls back to
623    /// transparent observe passthrough rather than risking corruption. Set `false` to restore
624    /// the pre-ADR-0005 behavior (structured requests always pass through un-gated).
625    #[serde(default = "default_enforce_structured")]
626    pub enforce_structured: bool,
627    /// UCB1 start-rung bandit: learn which rung to START the ladder on per request context, to
628    /// cut expected cost by skipping rungs that almost always fail for this context. `None`
629    /// (default) starts every request at rung 0 — byte-identical to today. Prediction may only
630    /// choose where the ladder STARTS; gating, escalation, and serving are untouched.
631    #[serde(default)]
632    pub bandit: Option<BanditConfig>,
633    /// Last-resort context condensing. `None` (default) = a conversation that overflows every
634    /// rung's context window fails, which is today's behaviour.
635    ///
636    /// Deliberately not a general trimming knob: condensing routinely would mean the gate verifies
637    /// an answer produced from a prompt the client never sent, and the receipt would attest to a
638    /// decision about a different question than the one asked. This fires only once the ladder is
639    /// exhausted, where the choice is no longer "faithful vs degraded" but "degraded vs failed".
640    #[serde(default)]
641    pub condense: Option<CondenseConfig>,
642    /// Insert Anthropic prompt-cache breakpoints on the stable prefix (system + tools).
643    /// `false` (default) = today's behaviour: whatever the caller sent, unchanged.
644    ///
645    /// Opt-in because it is a bet on your traffic, not a free optimisation. A cache write costs
646    /// 1.25x base input and a read 0.1x, so roughly one reuse of the prefix covers the premium and
647    /// everything after it saves heavily. A long agent session with a fixed system prompt and tool
648    /// set reuses constantly; single-shot traffic never does, and pays a 25% surcharge on the
649    /// prefix for nothing.
650    #[serde(default)]
651    pub prompt_cache: bool,
652    /// Replay a previously **verified** answer for an identical prompt, skipping the ladder
653    /// entirely. `None` (default) = every request runs the ladder, byte-identical to today.
654    ///
655    /// Unlike an ordinary response cache, an entry is written only when the receipt shows the
656    /// request was served on a passing verdict — so a hit cannot serve something that was never
657    /// proven. The receipt records `served_from: cache` and `cache_source`, naming the decision
658    /// whose gate passed.
659    #[serde(default)]
660    pub verified_cache: Option<VerifiedCacheConfig>,
661    /// Speculative-deferral band: when set (and the bandit has a warm gate-pass estimate for
662    /// the chosen start rung), speculative prefetch fires **only** when that estimate falls
663    /// inside `[low, high]` — the marginal zone where the next rung is *probably but not
664    /// certainly* needed, which is where parallel spend buys the most latency (speculative
665    /// cascades). Outside the band (confident pass or confident fail-through) requests run
666    /// serial and the speculative tokens are saved. `None` (default) = `speculation` applies
667    /// unconditionally, byte-identical to today. No bandit / cold context ⇒ band inapplicable
668    /// ⇒ configured `speculation` applies.
669    #[serde(default)]
670    pub speculation_band: Option<[f64; 2]>,
671    /// Epsilon-greedy start-rung exploration: randomise a fraction of start-rung choices and
672    /// record propensities so IPS/SNIPS off-policy estimates are valid. `None` (default) →
673    /// deterministic policy — byte-identical to today. See [`ExplorationConfig`].
674    #[serde(default)]
675    pub exploration: Option<ExplorationConfig>,
676    /// Shadow probe (ADR 0008 Phase 1): measure the k-sample gate-pass-count signal on a
677    /// sampled fraction of enforce requests without changing serving or the served cost.
678    /// `None` (default) = off = zero extra provider calls = byte-identical to today.
679    #[serde(default)]
680    pub probe: Option<ProbeConfig>,
681    /// Per-query gate-pass predictor (ADR 0008 Phase 2): a learned `P(gate-pass | rung,
682    /// features)` model, trained online from receipts and recorded on the receipt in shadow.
683    /// `None` (default) = off = byte-identical to today (no predictor, no `predicted_pass`).
684    #[serde(default)]
685    pub predictor: Option<PredictorConfig>,
686    /// Verified predictive routing: an optional pre-generation decision-model **prior** over
687    /// which ladder rung is the least capable one that fully handles this request, fed into the
688    /// existing start-rung expected-cost argmin as `P(pass | rung)`. `None` (default) = off =
689    /// byte-identical to today — no extra call, no `decision_prior` on the trace. The gate still
690    /// verifies every output regardless of the prior; a failed rung is never served.
691    #[serde(default)]
692    pub prior: Option<PriorConfig>,
693    /// Elastic verification (ADR 0008 Phase 3): skip the named expensive gates on a serve when the
694    /// cheap **visible** gate score clears the conformally-calibrated threshold λ. `None` (default)
695    /// runs every gate on every serve — byte-identical to today's uniform verification. See
696    /// [`ElasticConfig`].
697    #[serde(default)]
698    pub elastic: Option<ElasticConfig>,
699}
700
701/// Per-query gate-pass predictor configuration (ADR 0008 Phase 2). The model is an online
702/// logistic regression (`firstpass_core::predictor::PassPredictor`) trained from the trace
703/// store. Its prediction is recorded on the receipt in **shadow** — it does not change routing
704/// in this phase; whether it is good enough to act on is decided offline (`firstpass
705/// predictor-eval`).
706#[derive(Debug, Clone, Copy, Deserialize)]
707#[serde(deny_unknown_fields)]
708pub struct PredictorConfig {
709    /// SGD learning rate, in `(0, 1]`. Validated by [`Config::parse`].
710    #[serde(default = "default_predictor_lr")]
711    pub lr: f64,
712    /// L2 shrinkage on the weights (bias excluded), `>= 0`. Validated by [`Config::parse`].
713    #[serde(default = "default_predictor_l2")]
714    pub l2: f64,
715}
716
717fn default_predictor_lr() -> f64 {
718    0.05
719}
720
721fn default_predictor_l2() -> f64 {
722    1e-4
723}
724
725/// Verified predictive routing config: a pre-generation decision-model **prior** (TypeSafe's
726/// Jev today — `provider` is a discriminator on purpose, so a future second provider is an
727/// additive match arm, not a breaking rename) that answers, per query, "which is the least
728/// capable ladder rung that fully and correctly handles this?" The answer's probabilities become
729/// a `P(pass | rung)` prior fed into the existing start-rung expected-cost argmin
730/// ([`crate::prior::cumulative_pass`]).
731///
732/// This is a PRIOR, not a verifier: the enforce gate still runs on every served attempt exactly
733/// as before. A confident prior can only change *where the ladder starts*, never whether a
734/// failing output is served. `None` (default) = off = byte-identical to today.
735#[derive(Debug, Clone, Deserialize)]
736#[serde(deny_unknown_fields)]
737pub struct PriorConfig {
738    /// Decision-model provider. Only `"typesafe"` is built in today; validated by
739    /// [`Config::parse`].
740    pub provider: String,
741    /// Model name passed to the provider's API.
742    #[serde(default = "default_prior_model")]
743    pub model: String,
744    /// Env var naming the API key. Read once at startup; never logged, never put on the trace.
745    #[serde(default = "default_prior_api_key_env")]
746    pub api_key_env: String,
747    /// Provider API base URL.
748    #[serde(default = "default_prior_base_url")]
749    pub base_url: String,
750    /// Hard timeout for the prior call. A timeout or any other error fails open (no prior for
751    /// this request, `decision_prior` absent, start rung falls back to the prior-free choice) —
752    /// this is a cost hint, never a serving dependency.
753    #[serde(default = "default_prior_timeout_ms")]
754    pub timeout_ms: u64,
755    /// Beta pseudo-count weight: how many observations the prior is worth relative to the
756    /// bandit's own learned counts at a context. Higher = the prior dominates longer before
757    /// real data overrides it. Must be finite and `> 0`; validated by [`Config::parse`].
758    #[serde(default = "default_prior_strength")]
759    pub strength: f64,
760    /// Ladder rung names, in the same order as the route's `ladder`, used as the choice
761    /// question's criteria labels (`r0`, `r1`, ... map to `rungs[0]`, `rungs[1]`, ...). Must be
762    /// non-empty and match the length of every enforce route's ladder; validated by
763    /// [`Config::parse`].
764    pub rungs: Vec<String>,
765}
766
767fn default_prior_model() -> String {
768    "jev-latest".to_owned()
769}
770
771fn default_prior_api_key_env() -> String {
772    "TYPESAFE_API_KEY".to_owned()
773}
774
775fn default_prior_base_url() -> String {
776    "https://api.typesafe.ai".to_owned()
777}
778
779fn default_prior_timeout_ms() -> u64 {
780    150
781}
782
783fn default_prior_strength() -> f64 {
784    10.0
785}
786
787/// Config for anytime-valid risk control ([`crate::eprocess::EProcessRiskControl`], ADR 0011).
788///
789/// Opt-in and additive. Absent, the router behaves exactly as before. Present, the certified
790/// threshold takes precedence over `[escalation.adaptive]` **once something is certified** — before
791/// that it contributes nothing, because a controller that has proven nothing must not hand out a
792/// number.
793#[derive(Debug, Clone, Deserialize)]
794#[serde(deny_unknown_fields)]
795pub struct EProcessConfig {
796    /// Target served-failure rate the bound holds to.
797    pub alpha: f64,
798    /// Family-wise error budget, across every grid threshold and every round jointly.
799    pub delta: f64,
800    /// Betting fraction. Clamped internally so a large value cannot annihilate a threshold.
801    #[serde(default = "default_bet")]
802    pub bet: f64,
803    /// Candidate thresholds. Kept small on purpose: the Bonferroni crossing level is `n/delta`, so
804    /// evidence required per threshold grows linearly in grid size.
805    #[serde(default = "default_grid")]
806    pub grid: Vec<f64>,
807}
808
809fn default_bet() -> f64 {
810    0.5
811}
812
813/// A 21-point grid over `[0,1]`. Fine enough to pick a useful threshold, coarse enough that the
814/// Bonferroni correction stays affordable.
815fn default_grid() -> Vec<f64> {
816    (0..=20).map(|i| f64::from(i) / 20.0).collect()
817}
818
819/// Config for online/adaptive conformal serving ([`crate::conformal::AdaptiveConformal`]).
820#[derive(Debug, Clone, Deserialize)]
821#[serde(deny_unknown_fields)]
822pub struct AdaptiveConfig {
823    /// Target served-failure rate the online loop holds to.
824    pub alpha: f64,
825    /// Step size (default 0.02) — larger tracks shift faster but noisier.
826    #[serde(default = "default_adaptive_gamma")]
827    pub gamma: f64,
828}
829
830fn default_adaptive_gamma() -> f64 {
831    0.02
832}
833
834/// Epsilon-greedy start-rung exploration: a fraction `epsilon` of requests start at a
835/// uniformly-random rung so that propensities are logged and IPS/SNIPS off-policy estimates
836/// are valid (Horvitz-Thompson 1952; SNIPS: Swaminathan & Joachims 2015). The bandit still
837/// observes all gate verdicts — including from exploration draws — so learning is uninterrupted.
838///
839/// Every request under this policy records `policy.propensity` in the trace: the probability the
840/// logging policy had of choosing the start rung it actually chose. Old traces (before this field
841/// was added) serialize byte-identically (propensity is omitted when `None`).
842///
843/// Absent (default) → deterministic policy — no exploration, no propensity recorded,
844/// byte-identical to today.
845#[derive(Debug, Clone, Deserialize)]
846#[serde(deny_unknown_fields)]
847pub struct ExplorationConfig {
848    /// Fraction of requests routed to a uniformly-random start rung instead of the greedy
849    /// choice. Must be finite and in `(0, 0.5]`; validated by [`Config::parse`].
850    /// A small `epsilon` (0.05–0.1) is usually enough: it keeps learning alive and makes
851    /// IPS/SNIPS estimates valid at low cost in exploration waste.
852    pub epsilon: f64,
853}
854
855/// Shadow-probe configuration (ADR 0008 Phase 1): measure the validated k-sample
856/// gate-pass-count signal on a sampled fraction of requests WITHOUT changing serving.
857///
858/// **Cost caveat**: `sample_rate × k` extra model calls (at the `start_rung` model) per
859/// sampled request — measurement only, nothing served changes. Default absent = off = zero
860/// extra provider calls, byte-identical to today. Enable only when you want to collect the
861/// regime signal for offline analysis.
862#[derive(Debug, Clone, Copy, Deserialize)]
863#[serde(deny_unknown_fields)]
864pub struct ProbeConfig {
865    /// Number of parallel probe samples per request. Must be in `[2, 8]`; validated by
866    /// [`Config::parse`]. Each sample is one model call at the `start_rung` model.
867    pub k: u32,
868    /// Fraction of requests that trigger the probe, in `[0, 1]`. `0.0` = never; `1.0` = always.
869    /// Must be finite; validated by [`Config::parse`].
870    pub sample_rate: f64,
871}
872
873/// Elastic-verification serving config (ADR 0008 Phase 3). When present, the gates named in
874/// `expensive_gates` are treated as *skippable*: a rung serves without running them when the
875/// **visible** (cheap, always-run) gate score is `>= lambda` — the elastic three-regime rule,
876/// validated offline (`firstpass-bench --elastic`, artifact `docs/benchmarks/elastic-validation.txt`).
877///
878/// The load-bearing invariant (ADR 0008): the un-verified serves carry the *same* distribution-free
879/// served-failure bound as the verified ones **only when `lambda` was conformally calibrated on
880/// representative data and the workload has not drifted**. `lambda` is therefore operator-supplied
881/// from a calibration run — obtain it from `firstpass calibrate` / the offline `--elastic` harness,
882/// never hand-tuned. `alpha`/`delta`/`calibration_id` are recorded verbatim on every skip receipt so
883/// an auditor can check the bound held against realized deferred outcomes.
884///
885/// Default-off: absent config = today's uniform cascade, byte-identical. Applies to the serial
886/// engine only; if `speculation > 0` is also configured the expensive gates still run (conservative
887/// — running more gates never weakens the bound).
888#[derive(Debug, Clone, Deserialize, PartialEq)]
889#[serde(deny_unknown_fields)]
890pub struct ElasticConfig {
891    /// Gate ids that may be skipped when the visible signal clears `lambda`. Ids **not** listed
892    /// here are "visible" (cheap, e.g. `non-empty`/`json-valid`/`schema`) and always run — they are
893    /// the probe signal. Must be non-empty; validated by [`Config::parse`].
894    pub expensive_gates: Vec<String>,
895    /// Calibrated skip threshold λ: serve without the expensive gates iff the visible gate score is
896    /// `>= lambda`. Must be finite and in `[0, 1]`; validated by [`Config::parse`].
897    pub lambda: f64,
898    /// Target served-failure rate α the λ was calibrated at. Recorded on every skip receipt for
899    /// audit; not enforced per-request (the calibration already baked it into λ).
900    #[serde(default)]
901    pub alpha: Option<f64>,
902    /// Confidence level (1−δ) the λ was calibrated at. Recorded on every skip receipt for audit.
903    #[serde(default)]
904    pub delta: Option<f64>,
905    /// Provenance id of the calibration run that produced λ. Recorded on every skip receipt so the
906    /// skip traces back to the exact conformal calibration that authorized it.
907    #[serde(default)]
908    pub calibration_id: Option<String>,
909}
910
911/// Last-resort context condensing (§8.4). See [`Escalation::condense`].
912#[derive(Debug, Clone, Deserialize)]
913#[serde(deny_unknown_fields)]
914pub struct CondenseConfig {
915    /// Opening turns to keep — usually where the task definition lives.
916    #[serde(default = "default_condense_keep_head")]
917    pub keep_head: usize,
918    /// Closing turns to keep — the live thread.
919    #[serde(default = "default_condense_keep_tail")]
920    pub keep_tail: usize,
921}
922
923const fn default_condense_keep_head() -> usize {
924    2
925}
926
927const fn default_condense_keep_tail() -> usize {
928    6
929}
930
931/// Verified-response cache (§8.4). See [`Escalation::verified_cache`].
932#[derive(Debug, Clone, Deserialize)]
933#[serde(deny_unknown_fields)]
934pub struct VerifiedCacheConfig {
935    /// How long a proven answer stays replayable.
936    ///
937    /// A proof has a shelf life: the model, the gate, and the world all move. Short by default
938    /// because replaying a stale answer confidently is worse than paying to re-derive it.
939    #[serde(default = "default_cache_ttl_secs")]
940    pub ttl_secs: u64,
941    /// Hard cap on entries; oldest evicted first. In-process store only — a Redis-backed cache is
942    /// bounded by its TTL and the server's own eviction policy.
943    #[serde(default = "default_cache_max_entries")]
944    pub max_entries: usize,
945    /// Redis URL for a **shared** cache across replicas. Absent (default) = in-process only.
946    ///
947    /// Without it the cache is per-replica: behind N instances the same answer is cached N times
948    /// over, the hit rate drops roughly by N, and — the part that matters — a retraction only
949    /// reaches the replica that received the feedback, leaving the other N-1 serving an answer
950    /// that has been disproven.
951    ///
952    /// Requires the `redis-cache` build feature. Configuring a URL without it is rejected at
953    /// startup rather than silently ignored: a cache that quietly stays per-replica looks
954    /// identical to one that is working.
955    #[serde(default)]
956    pub redis_url: Option<String>,
957}
958
959const fn default_cache_ttl_secs() -> u64 {
960    15 * 60
961}
962
963const fn default_cache_max_entries() -> usize {
964    10_000
965}
966
967/// Config for the UCB1 start-rung bandit (`firstpass_proxy::bandit::StartRungBandit`).
968///
969/// Absent (`None`) → start every request at rung 0 (byte-identical to today).
970#[derive(Debug, Clone, Deserialize)]
971#[serde(deny_unknown_fields)]
972pub struct BanditConfig {
973    /// Minimum total gate-verdict observations in a context bucket before the bandit's
974    /// prediction kicks in. Below this, every request starts at rung 0 (cold-start safety).
975    #[serde(default = "default_bandit_min_observations")]
976    pub min_observations: usize,
977    /// UCB1 exploration constant `c` (Auer et al. 2002). Higher values explore more; 1.0 is the
978    /// theoretical default. Must be finite and `>= 0`; validated by [`Config::parse`].
979    #[serde(default = "default_bandit_exploration")]
980    pub exploration: f64,
981    /// Selection algorithm. `"ucb1"` (default) is deterministic and auditable; `"thompson"`
982    /// samples Beta posteriors — stochastic by nature, so every decision logs a non-degenerate
983    /// propensity (clean IPS/SNIPS/DR off-policy estimates without the epsilon overlay) and
984    /// pairs with `discount` for non-stationary traffic.
985    #[serde(default)]
986    pub algorithm: BanditAlgorithm,
987    /// Per-observation multiplicative decay of a context's counts, in `(0, 1]`. `1.0`
988    /// (default) = no forgetting. `0.99` adapts to model churn / workload drift at the cost
989    /// of a slightly noisier estimate. Validated by [`Config::parse`].
990    #[serde(default = "default_bandit_discount")]
991    pub discount: f64,
992}
993
994/// Start-rung bandit selection algorithm.
995#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize)]
996#[serde(rename_all = "lowercase")]
997pub enum BanditAlgorithm {
998    /// Deterministic UCB1 (Auer et al. 2002).
999    #[default]
1000    Ucb1,
1001    /// Thompson sampling with Beta posteriors (Chapelle & Li 2011).
1002    Thompson,
1003}
1004
1005fn default_bandit_discount() -> f64 {
1006    1.0
1007}
1008
1009fn default_bandit_min_observations() -> usize {
1010    50
1011}
1012
1013fn default_bandit_exploration() -> f64 {
1014    1.0
1015}
1016
1017const fn default_max_rungs() -> u32 {
1018    3
1019}
1020
1021/// Structured (tools/images) enforce is on by default — the fidelity guard in the proxy keeps
1022/// it safe (verbatim-carry rungs only).
1023fn default_enforce_structured() -> bool {
1024    true
1025}
1026
1027impl Default for Escalation {
1028    fn default() -> Self {
1029        Self {
1030            max_rungs_per_request: default_max_rungs(),
1031            session_promotion: None,
1032            speculation: 0,
1033            serve_threshold: None,
1034            adaptive: None,
1035            eprocess: None,
1036            enforce_structured: default_enforce_structured(),
1037            speculation_band: None,
1038            bandit: None,
1039            condense: None,
1040            prompt_cache: false,
1041            verified_cache: None,
1042            exploration: None,
1043            probe: None,
1044            predictor: None,
1045            prior: None,
1046            elastic: None,
1047        }
1048    }
1049}
1050
1051/// "After N failures within a window, promote this session's starting rung."
1052#[derive(Debug, Clone, Deserialize)]
1053#[serde(deny_unknown_fields)]
1054pub struct SessionPromotion {
1055    /// Failure count that triggers promotion.
1056    pub after_failures: u32,
1057    /// Sliding window, e.g. `"30m"`. Also the idle TTL: a session untouched for this long forgets
1058    /// its promotion, so a reused session id never inherits a stale rung.
1059    pub window: String,
1060    /// Re-probe one rung below the promotion every `probe_every` turns.
1061    ///
1062    /// Without this, promotion is a **ratchet**: a session that escalates once stays expensive for
1063    /// its whole life, so every later turn — including the trivial ones — pays the higher rung.
1064    /// The periodic probe is the only way a promotion comes back down. `1` re-probes every turn
1065    /// (promotion effectively off); large values approach a permanent ratchet.
1066    #[serde(default = "default_promotion_probe_every")]
1067    pub probe_every: u32,
1068    /// Hard cap on tracked sessions; oldest evicted first. A routing optimisation must never be
1069    /// able to exhaust memory on a proxy under load. In-process only — a Redis-backed store is
1070    /// bounded by its TTL and the server's own eviction policy, and a per-replica cap on a shared
1071    /// store would have each replica evicting the others' sessions.
1072    #[serde(default = "default_promotion_max_sessions")]
1073    pub max_sessions: usize,
1074    /// Redis URL for promotion state shared across replicas. Absent (default) = in-process only.
1075    ///
1076    /// Without it, promotion fragments behind a load balancer: a session that escalated on one
1077    /// replica starts cold on the next, so the escalation tax this exists to remove is paid again
1078    /// on roughly (N-1)/N of turns — configured, reporting nothing wrong, doing a fraction of its
1079    /// job. Requires the `redis-cache` build feature.
1080    #[serde(default)]
1081    pub redis_url: Option<String>,
1082}
1083
1084const fn default_promotion_probe_every() -> u32 {
1085    // Every 5th turn probes one rung down: quick enough to recover from an over-promotion, rare
1086    // enough that the escalation tax is still mostly avoided.
1087    5
1088}
1089
1090const fn default_promotion_max_sessions() -> usize {
1091    10_000
1092}
1093
1094impl SessionPromotion {
1095    /// Parse [`SessionPromotion::window`] into a [`Duration`].
1096    ///
1097    /// # Errors
1098    /// Returns [`Error::BadDuration`] if the window is not `<int><unit>` with unit in `s`/`m`/`h`/`d`.
1099    pub fn window_duration(&self) -> Result<Duration> {
1100        parse_window(&self.window)
1101    }
1102}
1103
1104/// Parse a compact duration like `30m`, `2h`, `90s`, `1d`.
1105fn parse_window(s: &str) -> Result<Duration> {
1106    let s = s.trim();
1107    let split = s
1108        .find(|c: char| c.is_ascii_alphabetic())
1109        .ok_or_else(|| Error::BadDuration(s.to_owned()))?;
1110    let (num, unit) = s.split_at(split);
1111    let n: u64 = num
1112        .trim()
1113        .parse()
1114        .map_err(|_| Error::BadDuration(s.to_owned()))?;
1115    let secs = match unit {
1116        "s" => n,
1117        "m" => n.saturating_mul(60),
1118        "h" => n.saturating_mul(3600),
1119        "d" => n.saturating_mul(86_400),
1120        _ => return Err(Error::BadDuration(s.to_owned())),
1121    };
1122    Ok(Duration::from_secs(secs))
1123}
1124
1125/// A parsed `provider/model` reference.
1126#[derive(Debug, Clone, PartialEq, Eq)]
1127pub struct ModelRef {
1128    /// Provider segment, e.g. `anthropic`.
1129    pub provider: String,
1130    /// Model segment, e.g. `claude-haiku-4-5`.
1131    pub model: String,
1132}
1133
1134impl ModelRef {
1135    /// Parse a `provider/model` string.
1136    ///
1137    /// # Errors
1138    /// Returns [`Error::BadModelRef`] if the input is not exactly one `provider/model` pair.
1139    pub fn parse(s: &str) -> Result<Self> {
1140        match s.split_once('/') {
1141            Some((p, m)) if !p.is_empty() && !m.is_empty() && !m.contains('/') => Ok(Self {
1142                provider: p.to_owned(),
1143                model: m.to_owned(),
1144            }),
1145            _ => Err(Error::BadModelRef(s.to_owned())),
1146        }
1147    }
1148}
1149
1150const fn default_guardrail_cooldown() -> i64 {
1151    3_600
1152}
1153
1154impl Config {
1155    /// Parse a TOML configuration document.
1156    ///
1157    /// # Errors
1158    /// Returns [`Error::Config`] on invalid TOML or unknown fields, or [`Error::InvalidConfig`] on
1159    /// an invalid gate definition (not exactly one of `cmd`/`judge`, a judge threshold outside
1160    /// `[0,1]`, or a duplicate/blank `id`).
1161    pub fn parse(toml_str: &str) -> Result<Self> {
1162        let config: Self = toml::from_str(toml_str)?;
1163        // A nonsensical rollout percent must fail loudly at parse: silently clamping it would
1164        // ramp a different amount of traffic than the operator asked for, and they would only
1165        // notice via a savings figure that never moved.
1166        for (i, route) in config.routes.iter().enumerate() {
1167            if let Some(r) = &route.rollout {
1168                r.validate()
1169                    .map_err(|e| Error::InvalidConfig(format!("route[{i}]: {e}")))?;
1170            }
1171            if let Some(sh) = &route.shadow {
1172                sh.validate()
1173                    .map_err(|e| Error::InvalidConfig(format!("route[{i}]: {e}")))?;
1174            }
1175            if let Some(ch) = &route.challenger {
1176                ch.validate()
1177                    .map_err(|e| Error::InvalidConfig(format!("route[{i}]: {e}")))?;
1178                if route.mode != Mode::Enforce {
1179                    return Err(Error::InvalidConfig(format!(
1180                        "route[{i}]: route.challenger requires mode = \"enforce\" — a challenger \
1181                         is served through the enforce path, and observe never runs a ladder"
1182                    )));
1183                }
1184                if ch.ladder == route.ladder {
1185                    return Err(Error::InvalidConfig(format!(
1186                        "route[{i}]: route.challenger.ladder is identical to the route ladder — \
1187                         both arms would serve the same models and the experiment could prove nothing"
1188                    )));
1189                }
1190                if ch.is_paired() {
1191                    // A pass-everything gate makes gate-pass non-inferiority meaningless (finding 1
1192                    // of ADR 0014): if every response passes, the challenger always "wins" and the
1193                    // test certifies nothing useful. Require at least one gate beyond `non-empty`.
1194                    let has_meaningful_gate = route.gates.iter().any(|g| g != "non-empty");
1195                    if !has_meaningful_gate {
1196                        return Err(Error::InvalidConfig(format!(
1197                            "route[{i}]: paired challenger mode requires at least one gate other \
1198                             than `non-empty` (e.g. `json-valid`, a judge, or a test gate) — \
1199                             a pass-everything gate makes gate-pass non-inferiority meaningless"
1200                        )));
1201                    }
1202                }
1203            }
1204        }
1205        if let Some(g) = &config.guardrail {
1206            g.validate().map_err(Error::InvalidConfig)?;
1207        }
1208        if let Some(p) = &config.escalation.session_promotion {
1209            // `window` is also the idle TTL, so an unparseable one would silently disable expiry.
1210            p.window_duration()?;
1211            // probe_every = 0 would make promotion one-way: a session that escalated once stays on
1212            // the expensive rung for its whole life, including the trivial turns at the end. That
1213            // is a cost regression an operator would only find in a bill, so it is rejected here
1214            // rather than quietly coerced to something they did not ask for.
1215            if p.probe_every == 0 {
1216                return Err(Error::InvalidConfig(
1217                    "[escalation.session_promotion] probe_every must be >= 1. It is how a promoted \
1218                     session ever returns to a cheaper rung; 0 would pin it permanently."
1219                        .to_owned(),
1220                ));
1221            }
1222            if p.max_sessions == 0 {
1223                return Err(Error::InvalidConfig(
1224                    "[escalation.session_promotion] max_sessions must be >= 1".to_owned(),
1225                ));
1226            }
1227        }
1228        let mut seen = std::collections::HashSet::new();
1229        for def in &config.gate_defs {
1230            if def.id.trim().is_empty() {
1231                return Err(Error::InvalidConfig("gate id must not be empty".to_owned()));
1232            }
1233            // Exactly one kind: `cmd`, `judge`, `consistency`, `schema`, or `decision` — never
1234            // more, never none.
1235            let kinds_set = [
1236                !def.cmd.is_empty(),
1237                def.judge.is_some(),
1238                def.consistency.is_some(),
1239                def.schema.is_some(),
1240                def.decision.is_some(),
1241            ]
1242            .iter()
1243            .filter(|&&b| b)
1244            .count();
1245            if kinds_set != 1 {
1246                return Err(Error::InvalidConfig(format!(
1247                    "gate {:?} must set exactly one of `cmd`, `judge`, `consistency`, `schema`, \
1248                     or `decision`",
1249                    def.id
1250                )));
1251            }
1252            if let Some(judge) = &def.judge
1253                && !(0.0..=1.0).contains(&judge.threshold)
1254            {
1255                return Err(Error::InvalidConfig(format!(
1256                    "gate {:?} judge threshold {} is outside [0, 1]",
1257                    def.id, judge.threshold
1258                )));
1259            }
1260            if let Some(c) = &def.consistency {
1261                if !(2..=8).contains(&c.k) {
1262                    return Err(Error::InvalidConfig(format!(
1263                        "gate {:?} consistency k {} is outside [2, 8]",
1264                        def.id, c.k
1265                    )));
1266                }
1267                if !(0.0..=1.0).contains(&c.threshold) {
1268                    return Err(Error::InvalidConfig(format!(
1269                        "gate {:?} consistency threshold {} is outside [0, 1]",
1270                        def.id, c.threshold
1271                    )));
1272                }
1273            }
1274            if let Some(d) = &def.decision {
1275                if d.provider != "typesafe" {
1276                    return Err(Error::InvalidConfig(format!(
1277                        "gate {:?} decision provider {:?} is not supported — only \"typesafe\" \
1278                         is built in",
1279                        def.id, d.provider
1280                    )));
1281                }
1282                if !(d.threshold.is_finite() && d.threshold > 0.0 && d.threshold < 1.0) {
1283                    return Err(Error::InvalidConfig(format!(
1284                        "gate {:?} decision threshold {} must be finite and in (0, 1)",
1285                        def.id, d.threshold
1286                    )));
1287                }
1288                if d.timeout_ms == 0 {
1289                    return Err(Error::InvalidConfig(format!(
1290                        "gate {:?} decision timeout_ms must be >= 1",
1291                        def.id
1292                    )));
1293                }
1294            }
1295            if !seen.insert(def.id.as_str()) {
1296                return Err(Error::InvalidConfig(format!(
1297                    "duplicate gate id {:?}",
1298                    def.id
1299                )));
1300            }
1301        }
1302        for price in &config.price_defs {
1303            if price.model.trim().is_empty() {
1304                return Err(Error::InvalidConfig(
1305                    "price model must not be empty".to_owned(),
1306                ));
1307            }
1308            let ok = |v: f64| v.is_finite() && v >= 0.0;
1309            if !ok(price.input_per_mtok) || !ok(price.output_per_mtok) {
1310                return Err(Error::InvalidConfig(format!(
1311                    "price for {:?} must be finite and >= 0",
1312                    price.model
1313                )));
1314            }
1315        }
1316        config.validate_ladders_are_priced()?;
1317        config.validate_challenger_ladders()?;
1318        if let Some(b) = &config.escalation.bandit {
1319            if !b.exploration.is_finite() || b.exploration < 0.0 {
1320                return Err(Error::InvalidConfig(format!(
1321                    "bandit.exploration must be finite and >= 0, got {}",
1322                    b.exploration
1323                )));
1324            }
1325            if !b.discount.is_finite() || b.discount <= 0.0 || b.discount > 1.0 {
1326                return Err(Error::InvalidConfig(format!(
1327                    "bandit.discount must be in (0, 1], got {}",
1328                    b.discount
1329                )));
1330            }
1331        }
1332        if let Some([lo, hi]) = config.escalation.speculation_band {
1333            let ok = |v: f64| v.is_finite() && (0.0..=1.0).contains(&v);
1334            if !ok(lo) || !ok(hi) || lo > hi {
1335                return Err(Error::InvalidConfig(format!(
1336                    "escalation.speculation_band must satisfy 0 <= low <= high <= 1, got [{lo}, {hi}]"
1337                )));
1338            }
1339        }
1340        // An out-of-range e-process grid must be REJECTED, not silently filtered.
1341        // `EProcessRiskControl::new` drops non-finite entries so a bad grid cannot panic, but
1342        // dropping is the wrong contract for config: an operator who writes a grid of `[2.0, 3.0]`
1343        // gets an empty grid, which certifies nothing, and the report then reads "no threshold
1344        // certified" — indistinguishable from insufficient data. Same failure shape as the
1345        // Bonferroni collapse in ADR 0011, arriving through a typo instead. Flagged in review.
1346        if let Some(ep) = &config.escalation.eprocess {
1347            if !ep.alpha.is_finite() || ep.alpha <= 0.0 || ep.alpha >= 1.0 {
1348                return Err(Error::InvalidConfig(format!(
1349                    "escalation.eprocess.alpha must be finite and in (0, 1), got {}",
1350                    ep.alpha
1351                )));
1352            }
1353            if !ep.delta.is_finite() || ep.delta <= 0.0 || ep.delta >= 1.0 {
1354                return Err(Error::InvalidConfig(format!(
1355                    "escalation.eprocess.delta must be finite and in (0, 1), got {}",
1356                    ep.delta
1357                )));
1358            }
1359            // `bet` completes the set. The runtime clamps it to a safe range so it cannot
1360            // annihilate a threshold, but clamping is not validation: `bet = 0.0` clamps to 0.0,
1361            // the betting factor becomes exactly 1 on every update, the e-value never moves, and
1362            // NOTHING can ever certify. Silent and permanent — the same "reads as insufficient
1363            // data" failure as an empty grid. I validated alpha, delta and grid and left this one,
1364            // which review caught.
1365            if !ep.bet.is_finite() || ep.bet <= 0.0 || ep.bet > 1.0 {
1366                return Err(Error::InvalidConfig(format!(
1367                    "escalation.eprocess.bet must be finite and in (0, 1], got {}",
1368                    ep.bet
1369                )));
1370            }
1371            if ep.grid.is_empty() {
1372                return Err(Error::InvalidConfig(
1373                    "escalation.eprocess.grid must not be empty — an empty grid certifies nothing"
1374                        .to_owned(),
1375                ));
1376            }
1377            if let Some(bad) = ep
1378                .grid
1379                .iter()
1380                .find(|g| !g.is_finite() || **g < 0.0 || **g > 1.0)
1381            {
1382                return Err(Error::InvalidConfig(format!(
1383                    "escalation.eprocess.grid values must be finite and in [0, 1], got {bad}"
1384                )));
1385            }
1386        }
1387        if let Some(exp) = &config.escalation.exploration
1388            && (!exp.epsilon.is_finite() || exp.epsilon <= 0.0 || exp.epsilon > 0.5)
1389        {
1390            return Err(Error::InvalidConfig(format!(
1391                "escalation.exploration.epsilon must be finite and in (0, 0.5], got {}",
1392                exp.epsilon
1393            )));
1394        }
1395        if let Some(probe) = &config.escalation.probe {
1396            if !(2..=8).contains(&probe.k) {
1397                return Err(Error::InvalidConfig(format!(
1398                    "escalation.probe.k must be in [2, 8], got {}",
1399                    probe.k
1400                )));
1401            }
1402            if !probe.sample_rate.is_finite() || !(0.0..=1.0).contains(&probe.sample_rate) {
1403                return Err(Error::InvalidConfig(format!(
1404                    "escalation.probe.sample_rate must be finite and in [0, 1], got {}",
1405                    probe.sample_rate
1406                )));
1407            }
1408        }
1409        if let Some(pred) = &config.escalation.predictor {
1410            if !pred.lr.is_finite() || !(0.0..=1.0).contains(&pred.lr) || pred.lr == 0.0 {
1411                return Err(Error::InvalidConfig(format!(
1412                    "escalation.predictor.lr must be finite and in (0, 1], got {}",
1413                    pred.lr
1414                )));
1415            }
1416            if !pred.l2.is_finite() || pred.l2 < 0.0 {
1417                return Err(Error::InvalidConfig(format!(
1418                    "escalation.predictor.l2 must be finite and >= 0, got {}",
1419                    pred.l2
1420                )));
1421            }
1422        }
1423        if let Some(prior) = &config.escalation.prior {
1424            if prior.provider != "typesafe" {
1425                return Err(Error::InvalidConfig(format!(
1426                    "escalation.prior.provider {:?} is not supported — only \"typesafe\" is \
1427                     built in",
1428                    prior.provider
1429                )));
1430            }
1431            if !prior.strength.is_finite() || prior.strength <= 0.0 {
1432                return Err(Error::InvalidConfig(format!(
1433                    "escalation.prior.strength must be finite and > 0, got {}",
1434                    prior.strength
1435                )));
1436            }
1437            if prior.timeout_ms == 0 {
1438                return Err(Error::InvalidConfig(
1439                    "escalation.prior.timeout_ms must be >= 1".to_owned(),
1440                ));
1441            }
1442            if prior.rungs.is_empty() {
1443                return Err(Error::InvalidConfig(
1444                    "escalation.prior.rungs must not be empty".to_owned(),
1445                ));
1446            }
1447            // A prior with the wrong arity can't be mapped onto the ladder it is meant to score,
1448            // so it is rejected at parse rather than silently truncated/padded at request time.
1449            for (i, route) in config.routes.iter().enumerate() {
1450                if route.mode == Mode::Enforce && prior.rungs.len() != route.ladder.len() {
1451                    return Err(Error::InvalidConfig(format!(
1452                        "escalation.prior.rungs has {} entries but route[{i}]'s enforce ladder \
1453                         has {} — they must match 1:1",
1454                        prior.rungs.len(),
1455                        route.ladder.len()
1456                    )));
1457                }
1458            }
1459        }
1460        if let Some(elastic) = &config.escalation.elastic {
1461            if elastic.expensive_gates.is_empty() {
1462                return Err(Error::InvalidConfig(
1463                    "escalation.elastic.expensive_gates must name at least one gate to skip".into(),
1464                ));
1465            }
1466            if !elastic.lambda.is_finite() || !(0.0..=1.0).contains(&elastic.lambda) {
1467                return Err(Error::InvalidConfig(format!(
1468                    "escalation.elastic.lambda must be finite and in [0, 1], got {}",
1469                    elastic.lambda
1470                )));
1471            }
1472        }
1473        Ok(config)
1474    }
1475
1476    /// The first route whose match claims `f`, or `None` if no route matches.
1477    #[must_use]
1478    pub fn route_for(&self, f: &Features) -> Option<&Route> {
1479        self.routes.iter().find(|r| r.match_.matches(f))
1480    }
1481
1482    /// The effective price table: built-in defaults with this config's `[[price]]` blocks applied.
1483    #[must_use]
1484    pub fn price_table(&self) -> crate::cost::PriceTable {
1485        self.price_defs
1486            .iter()
1487            .fold(crate::cost::PriceTable::defaults(), |table, p| {
1488                table.with_override(
1489                    p.model.clone(),
1490                    crate::cost::ModelPrice {
1491                        input_per_mtok: p.input_per_mtok,
1492                        output_per_mtok: p.output_per_mtok,
1493                    },
1494                )
1495            })
1496    }
1497
1498    /// Every challenger rung must be a well-formed `provider/model` whose provider resolves
1499    /// (built-in `anthropic` / `openai`, or a `[[provider]]` block) and whose price is known, for
1500    /// the same reason route rungs must be priced: an unpriced rung would record $0.00 receipts
1501    /// and make the experiment's cost comparison — the whole point of adopting a challenger —
1502    /// meaningless.
1503    fn validate_challenger_ladders(&self) -> Result<()> {
1504        let prices = self.price_table();
1505        for (i, route) in self.routes.iter().enumerate() {
1506            let Some(ch) = &route.challenger else {
1507                continue;
1508            };
1509            for rung in &ch.ladder {
1510                let m = ModelRef::parse(rung).map_err(|_| {
1511                    Error::InvalidConfig(format!(
1512                        "route[{i}] challenger rung {rung:?} is not a `provider/model` string"
1513                    ))
1514                })?;
1515                let builtin = matches!(m.provider.as_str(), "anthropic" | "openai");
1516                if !builtin && !self.providers.iter().any(|p| p.id == m.provider) {
1517                    return Err(Error::InvalidConfig(format!(
1518                        "route[{i}] challenger rung {rung:?}: provider {:?} is not built in \
1519                         (only `anthropic` and `openai` are) and has no `[[provider]]` block",
1520                        m.provider
1521                    )));
1522                }
1523                if prices.get(rung).is_none() {
1524                    return Err(Error::InvalidConfig(format!(
1525                        "route[{i}] challenger rung {rung:?} has no price. Declare it:\n\n\
1526                         [[price]]\nmodel = {rung:?}\ninput_per_mtok = 0.0\noutput_per_mtok = 0.0\n\n\
1527                         (0.0 is correct only for a model you host yourself)"
1528                    )));
1529                }
1530            }
1531        }
1532        Ok(())
1533    }
1534
1535    /// Every ladder rung must resolve to a price.
1536    ///
1537    /// An unpriced rung is not a missing number, it is a **fabricated one**: the router falls
1538    /// back to `$0.00` for that call, so the receipt reports a spend nobody measured and a
1539    /// `[budget]` cap fed by that total can never trip. The built-in table only knows the
1540    /// first-party models, so this is precisely the bring-your-own-provider path.
1541    ///
1542    /// A genuinely free rung (a local model you host) is still legal — declare it as an
1543    /// explicit `[[price]]` of `0`, so the receipt's `$0.00` is a stated fact rather than a
1544    /// silent fallback.
1545    fn validate_ladders_are_priced(&self) -> Result<()> {
1546        let prices = self.price_table();
1547        for (i, route) in self.routes.iter().enumerate() {
1548            for rung in &route.ladder {
1549                if prices.get(rung).is_none() {
1550                    return Err(Error::InvalidConfig(format!(
1551                        "route[{i}] ladder rung {rung:?} has no price, so its cost would be \
1552                         recorded as $0.00 and any [budget] cap would never trip. Declare it:\n\n\
1553                         [[price]]\nmodel = {rung:?}\ninput_per_mtok = 0.0\noutput_per_mtok = 0.0\n\n\
1554                         (use the real per-1M-token prices; 0.0 is correct only for a model you \
1555                         host yourself)"
1556                    )));
1557                }
1558            }
1559        }
1560        Ok(())
1561    }
1562}
1563
1564#[cfg(test)]
1565mod tests {
1566    use super::*;
1567    use crate::features::Features;
1568
1569    const SPEC_CONFIG: &str = r#"
1570[[route]]
1571match = { agent = "claude-code", subagent = ["test-runner", "explore"] }
1572mode  = "enforce"
1573ladder = ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-5"]
1574gates  = ["schema", "judge-diff"]
1575
1576[[route]]
1577match = { task_kind = "code_edit" }
1578mode  = "enforce"
1579ladder = ["anthropic/claude-sonnet-5", "anthropic/claude-opus-4-8"]
1580gates  = ["patch-applies", "lint-diff", "judge-diff"]
1581deferred_gates = ["compiles", "tests"]
1582
1583[[route]]
1584match = {}
1585mode  = "observe"
1586ladder = ["anthropic/claude-opus-4-8"]
1587
1588[budget]
1589per_request_usd = 0.50
1590per_session_usd = 10.00
1591per_day_usd     = 250.00
1592on_exhausted    = "serve_best_attempt"
1593
1594[escalation]
1595max_rungs_per_request = 3
1596session_promotion = { after_failures = 3, window = "30m" }
1597"#;
1598
1599    #[test]
1600    fn parses_the_spec_example() {
1601        let c = Config::parse(SPEC_CONFIG).unwrap();
1602        assert_eq!(c.routes.len(), 3);
1603        assert_eq!(c.routes[0].mode, Mode::Enforce);
1604        assert_eq!(
1605            c.routes[0].ladder,
1606            ["anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-5"]
1607        );
1608        assert_eq!(c.routes[1].deferred_gates, ["compiles", "tests"]);
1609        assert_eq!(c.budget.per_request_usd, Some(0.50));
1610        assert_eq!(c.budget.on_exhausted, OnExhausted::ServeBestAttempt);
1611        assert_eq!(c.escalation.max_rungs_per_request, 3);
1612        let sp = c.escalation.session_promotion.as_ref().unwrap();
1613        assert_eq!(sp.after_failures, 3);
1614        assert_eq!(sp.window_duration().unwrap(), Duration::from_secs(1800));
1615    }
1616
1617    #[test]
1618    fn first_matching_route_wins() {
1619        let c = Config::parse(SPEC_CONFIG).unwrap();
1620
1621        // claude-code / test-runner -> route 0
1622        let mut f = Features::new(TaskKind::Explore);
1623        f.agent = Some("claude-code".into());
1624        f.subagent = Some("test-runner".into());
1625        let r = c.route_for(&f).unwrap();
1626        assert_eq!(r.ladder[0], "anthropic/claude-haiku-4-5");
1627
1628        // a code_edit with no agent -> route 1 (route 0's agent constraint fails)
1629        let f2 = Features::new(TaskKind::CodeEdit);
1630        let r2 = c.route_for(&f2).unwrap();
1631        assert_eq!(r2.gates, ["patch-applies", "lint-diff", "judge-diff"]);
1632
1633        // anything else -> catch-all observe route
1634        let f3 = Features::new(TaskKind::Chat);
1635        let r3 = c.route_for(&f3).unwrap();
1636        assert_eq!(r3.mode, Mode::Observe);
1637    }
1638
1639    #[test]
1640    fn shipped_example_config_parses() {
1641        // The repo ships `firstpass.example.toml` for users to copy. If it drifts
1642        // from the schema, this fails in CI rather than at a user's first run.
1643        let toml = include_str!("../../../firstpass.example.toml");
1644        let c = Config::parse(toml).expect("firstpass.example.toml must parse");
1645        assert_eq!(c.routes.len(), 3);
1646        assert_eq!(c.routes[0].mode, Mode::Enforce);
1647    }
1648
1649    #[test]
1650    fn parses_gate_definitions() {
1651        let toml = r#"
1652[[route]]
1653match = {}
1654mode  = "enforce"
1655ladder = ["anthropic/claude-haiku-4-5"]
1656gates  = ["my-tests"]
1657
1658[[gate]]
1659id  = "my-tests"
1660cmd = ["pytest", "-q"]
1661
1662[[gate]]
1663id         = "judge"
1664cmd        = ["bash", "-c", "./judge.sh"]
1665timeout_ms = 60000
1666"#;
1667        let c = Config::parse(toml).unwrap();
1668        assert_eq!(c.gate_defs.len(), 2);
1669        assert_eq!(c.gate_defs[0].id, "my-tests");
1670        assert_eq!(c.gate_defs[0].cmd, ["pytest", "-q"]);
1671        assert_eq!(c.gate_defs[0].timeout_ms, 30_000, "default timeout applies");
1672        assert_eq!(c.gate_defs[1].timeout_ms, 60_000);
1673    }
1674
1675    #[test]
1676    fn rejects_invalid_gate_definitions() {
1677        let empty_cmd = "[[gate]]\nid = \"g\"\ncmd = []\n";
1678        assert!(matches!(
1679            Config::parse(empty_cmd),
1680            Err(Error::InvalidConfig(_))
1681        ));
1682
1683        let dup = "[[gate]]\nid = \"g\"\ncmd = [\"a\"]\n[[gate]]\nid = \"g\"\ncmd = [\"b\"]\n";
1684        assert!(matches!(Config::parse(dup), Err(Error::InvalidConfig(_))));
1685    }
1686
1687    #[test]
1688    fn parses_consistency_gate_definition() {
1689        let toml = r#"
1690[[gate]]
1691id          = "uncertainty"
1692consistency = { model = "anthropic/claude-haiku-4-5", k = 5, threshold = 0.6 }
1693"#;
1694        let c = Config::parse(toml).unwrap();
1695        assert_eq!(c.gate_defs.len(), 1);
1696        let cons = c.gate_defs[0].consistency.as_ref().unwrap();
1697        assert_eq!(cons.model, "anthropic/claude-haiku-4-5");
1698        assert_eq!(cons.k, 5);
1699        assert!((cons.threshold - 0.6).abs() < 1e-9);
1700    }
1701
1702    #[test]
1703    fn consistency_k_defaults_to_3() {
1704        let toml = "[[gate]]\nid = \"u\"\nconsistency = { model = \"anthropic/claude-haiku-4-5\", threshold = 0.7 }\n";
1705        let c = Config::parse(toml).unwrap();
1706        assert_eq!(c.gate_defs[0].consistency.as_ref().unwrap().k, 3);
1707    }
1708
1709    #[test]
1710    fn rejects_exactly_one_of_violations_for_consistency() {
1711        // cmd + consistency — two kinds set
1712        let both = "[[gate]]\nid = \"g\"\ncmd = [\"x\"]\nconsistency = { model = \"a/b\", threshold = 0.5 }\n";
1713        assert!(matches!(Config::parse(both), Err(Error::InvalidConfig(_))));
1714
1715        // consistency k out of bounds
1716        let bad_k =
1717            "[[gate]]\nid = \"g\"\nconsistency = { model = \"a/b\", k = 1, threshold = 0.5 }\n";
1718        assert!(matches!(Config::parse(bad_k), Err(Error::InvalidConfig(_))));
1719
1720        let bad_k2 =
1721            "[[gate]]\nid = \"g\"\nconsistency = { model = \"a/b\", k = 9, threshold = 0.5 }\n";
1722        assert!(matches!(
1723            Config::parse(bad_k2),
1724            Err(Error::InvalidConfig(_))
1725        ));
1726
1727        // consistency threshold out of bounds
1728        let bad_thresh =
1729            "[[gate]]\nid = \"g\"\nconsistency = { model = \"a/b\", threshold = 1.1 }\n";
1730        assert!(matches!(
1731            Config::parse(bad_thresh),
1732            Err(Error::InvalidConfig(_))
1733        ));
1734    }
1735
1736    #[test]
1737    fn parses_adaptive_conformal_config() {
1738        let c = Config::parse("[escalation.adaptive]\nalpha = 0.1\n").unwrap();
1739        let a = c
1740            .escalation
1741            .adaptive
1742            .expect("[escalation.adaptive] should parse");
1743        assert!((a.alpha - 0.1).abs() < 1e-9);
1744        assert!((a.gamma - 0.02).abs() < 1e-9, "gamma defaults to 0.02");
1745        // Absent => None (fixed-threshold serving, default byte-identical behavior).
1746        assert!(Config::parse("").unwrap().escalation.adaptive.is_none());
1747    }
1748
1749    #[test]
1750    fn parses_provider_entries_and_ladders_can_reference_them() {
1751        let c = Config::parse(
1752            r#"
1753[[provider]]
1754id = "groq"
1755dialect = "openai"
1756base_url = "https://api.groq.com/openai"
1757api_key_env = "GROQ_API_KEY"
1758
1759[[provider]]
1760id = "ollama"
1761dialect = "openai"
1762base_url = "http://localhost:11434"
1763
1764# A bring-your-own provider has no built-in price, so the ladder must declare one or the
1765# receipt would report $0.00 for every Groq call.
1766[[price]]
1767model = "groq/llama-3.3-70b-versatile"
1768input_per_mtok = 0.59
1769output_per_mtok = 0.79
1770
1771[[route]]
1772match = {}
1773mode = "enforce"
1774ladder = ["groq/llama-3.3-70b-versatile", "anthropic/claude-sonnet-5"]
1775"#,
1776        )
1777        .unwrap();
1778        assert_eq!(c.providers.len(), 2);
1779        let groq = &c.providers[0];
1780        assert_eq!(groq.id, "groq");
1781        assert_eq!(groq.dialect, Dialect::Openai);
1782        assert_eq!(groq.base_url, "https://api.groq.com/openai");
1783        assert_eq!(groq.api_key_env.as_deref(), Some("GROQ_API_KEY"));
1784        // A keyless local endpoint (Ollama) parses with no api_key_env.
1785        assert_eq!(c.providers[1].id, "ollama");
1786        assert!(c.providers[1].api_key_env.is_none());
1787        // Absent => no extra providers (built-ins only).
1788        assert!(Config::parse("").unwrap().providers.is_empty());
1789    }
1790
1791    #[test]
1792    fn parses_aws_sigv4_provider_and_defaults_auth_to_api_key() {
1793        let c = Config::parse(
1794            r#"
1795[[provider]]
1796id = "bedrock"
1797dialect = "anthropic"
1798auth = "aws_sigv4"
1799region = "us-east-1"
1800"#,
1801        )
1802        .unwrap();
1803        let bedrock = &c.providers[0];
1804        assert_eq!(bedrock.auth, AuthScheme::AwsSigv4);
1805        assert_eq!(bedrock.region.as_deref(), Some("us-east-1"));
1806        assert!(bedrock.project.is_none());
1807
1808        // Omitting `auth` on an existing provider entry defaults to ApiKey (I1: no behavior
1809        // change for today's `[[provider]]` entries).
1810        let c2 = Config::parse(
1811            r#"
1812[[provider]]
1813id = "groq"
1814dialect = "openai"
1815base_url = "https://api.groq.com/openai"
1816"#,
1817        )
1818        .unwrap();
1819        assert_eq!(c2.providers[0].auth, AuthScheme::ApiKey);
1820    }
1821
1822    #[test]
1823    fn all_documented_provider_shapes_parse() {
1824        // The exact `[[provider]]` shapes shown in the README / usage page / firstpass.example.toml.
1825        // This is the guard that the documented provider instructions stay valid — one entry per
1826        // dialect/auth combination we tell users to write.
1827        let c = Config::parse(
1828            r#"
1829[[provider]]
1830id = "groq"
1831dialect = "openai"
1832base_url = "https://api.groq.com/openai"
1833api_key_env = "GROQ_API_KEY"
1834
1835[[provider]]
1836id = "ollama"
1837dialect = "openai"
1838base_url = "http://localhost:11434"
1839
1840[[provider]]
1841id = "gemini"
1842dialect = "gemini"
1843base_url = "https://generativelanguage.googleapis.com"
1844api_key_env = "GEMINI_API_KEY"
1845
1846[[provider]]
1847id = "bedrock"
1848dialect = "anthropic"
1849auth = "aws_sigv4"
1850region = "us-east-1"
1851
1852[[provider]]
1853id = "vertex"
1854dialect = "anthropic"
1855auth = "gcp_oauth"
1856region = "us-east5"
1857project = "my-gcp-project"
1858"#,
1859        )
1860        .expect("every documented provider shape must parse");
1861        assert_eq!(c.providers.len(), 5);
1862
1863        let gemini = c.providers.iter().find(|p| p.id == "gemini").unwrap();
1864        assert_eq!(gemini.dialect, Dialect::Gemini);
1865        assert_eq!(gemini.auth, AuthScheme::ApiKey);
1866
1867        let vertex = c.providers.iter().find(|p| p.id == "vertex").unwrap();
1868        assert_eq!(vertex.auth, AuthScheme::GcpOauth);
1869        assert_eq!(vertex.region.as_deref(), Some("us-east5"));
1870        assert_eq!(vertex.project.as_deref(), Some("my-gcp-project"));
1871    }
1872
1873    #[test]
1874    fn empty_match_is_wildcard() {
1875        let m = Match::default();
1876        assert!(m.matches(&Features::new(TaskKind::Other)));
1877    }
1878
1879    #[test]
1880    fn subagent_list_membership() {
1881        let c = Config::parse(SPEC_CONFIG).unwrap();
1882        let route0 = &c.routes[0];
1883        let mut f = Features::new(TaskKind::Other);
1884        f.agent = Some("claude-code".into());
1885        f.subagent = Some("docs-writer".into()); // not in [test-runner, explore]
1886        assert!(!route0.match_.matches(&f));
1887        f.subagent = Some("explore".into());
1888        assert!(route0.match_.matches(&f));
1889    }
1890
1891    #[test]
1892    fn model_ref_parsing() {
1893        let m = ModelRef::parse("anthropic/claude-haiku-4-5").unwrap();
1894        assert_eq!(m.provider, "anthropic");
1895        assert_eq!(m.model, "claude-haiku-4-5");
1896        assert!(ModelRef::parse("no-slash").is_err());
1897        assert!(ModelRef::parse("/model").is_err());
1898        assert!(ModelRef::parse("a/b/c").is_err());
1899    }
1900
1901    #[test]
1902    fn window_parsing_units_and_errors() {
1903        assert_eq!(parse_window("90s").unwrap(), Duration::from_secs(90));
1904        assert_eq!(parse_window("30m").unwrap(), Duration::from_secs(1800));
1905        assert_eq!(parse_window("2h").unwrap(), Duration::from_secs(7200));
1906        assert_eq!(parse_window("1d").unwrap(), Duration::from_secs(86_400));
1907        assert!(parse_window("30x").is_err());
1908        assert!(parse_window("abc").is_err());
1909    }
1910
1911    #[test]
1912    fn empty_config_defaults() {
1913        let c = Config::parse("").unwrap();
1914        assert!(c.routes.is_empty());
1915        assert_eq!(c.escalation.max_rungs_per_request, 3);
1916        assert_eq!(c.budget.on_exhausted, OnExhausted::ServeBestAttempt);
1917    }
1918
1919    // ── ExplorationConfig parse / validation ──────────────────────────────────
1920
1921    #[test]
1922    fn parses_exploration_config() {
1923        let c = Config::parse("[escalation.exploration]\nepsilon = 0.1\n").unwrap();
1924        let exp = c
1925            .escalation
1926            .exploration
1927            .expect("[escalation.exploration] should parse");
1928        assert!((exp.epsilon - 0.1).abs() < 1e-12);
1929        // Absent => None (deterministic policy, byte-identical behavior).
1930        assert!(Config::parse("").unwrap().escalation.exploration.is_none());
1931    }
1932
1933    /// An out-of-range e-process grid must be REJECTED at parse, not silently filtered.
1934    ///
1935    /// `EProcessRiskControl::new` drops non-finite entries so a bad grid cannot panic — correct for
1936    /// a library, wrong for config. An operator who writes `grid = [2.0, 3.0]` would otherwise get
1937    /// an empty grid, certify nothing, and read "no threshold certified" in the report:
1938    /// indistinguishable from insufficient data. The same silent-collapse shape as the Bonferroni
1939    /// failure in ADR 0011, arriving through a typo. Flagged in review.
1940    #[test]
1941    fn an_out_of_range_eprocess_grid_is_rejected_not_filtered() {
1942        let good = "[escalation.eprocess]\nalpha = 0.1\ndelta = 0.05\ngrid = [0.0, 0.5, 1.0]\n";
1943        assert!(Config::parse(good).is_ok(), "a valid grid must parse");
1944
1945        for bad in [
1946            "[escalation.eprocess]\nalpha = 0.1\ndelta = 0.05\ngrid = [2.0]\n",
1947            "[escalation.eprocess]\nalpha = 0.1\ndelta = 0.05\ngrid = [-0.5, 0.5]\n",
1948            "[escalation.eprocess]\nalpha = 0.1\ndelta = 0.05\ngrid = []\n",
1949        ] {
1950            assert!(
1951                matches!(Config::parse(bad), Err(Error::InvalidConfig(_))),
1952                "must reject: {bad}"
1953            );
1954        }
1955    }
1956
1957    /// `alpha` and `delta` are probabilities. Zero or one makes the guarantee vacuous or
1958    /// unreachable — `delta = 0` in particular means the crossing level is infinite and nothing can
1959    /// ever certify, which is a silent no-op rather than an error at runtime.
1960    #[test]
1961    fn degenerate_eprocess_alpha_or_delta_is_rejected() {
1962        for bad in [
1963            "[escalation.eprocess]\nalpha = 0.0\ndelta = 0.05\n",
1964            "[escalation.eprocess]\nalpha = 1.0\ndelta = 0.05\n",
1965            "[escalation.eprocess]\nalpha = 0.1\ndelta = 0.0\n",
1966            "[escalation.eprocess]\nalpha = 0.1\ndelta = 1.0\n",
1967            // bet = 0 clamps to 0 at runtime: the betting factor is always 1, the e-value never
1968            // moves, and nothing can ever certify. Silent, permanent, and indistinguishable from
1969            // insufficient data.
1970            "[escalation.eprocess]\nalpha = 0.1\ndelta = 0.05\nbet = 0.0\n",
1971            "[escalation.eprocess]\nalpha = 0.1\ndelta = 0.05\nbet = 1.5\n",
1972        ] {
1973            assert!(
1974                matches!(Config::parse(bad), Err(Error::InvalidConfig(_))),
1975                "must reject: {bad}"
1976            );
1977        }
1978    }
1979
1980    #[test]
1981    fn exploration_epsilon_boundary_valid() {
1982        // Upper bound 0.5 is allowed.
1983        let c = Config::parse("[escalation.exploration]\nepsilon = 0.5\n").unwrap();
1984        assert!((c.escalation.exploration.unwrap().epsilon - 0.5).abs() < 1e-12);
1985    }
1986
1987    #[test]
1988    fn exploration_epsilon_above_half_rejected() {
1989        let bad = "[escalation.exploration]\nepsilon = 0.51\n";
1990        assert!(
1991            matches!(Config::parse(bad), Err(Error::InvalidConfig(_))),
1992            "epsilon > 0.5 must be rejected"
1993        );
1994    }
1995
1996    #[test]
1997    fn exploration_epsilon_zero_rejected() {
1998        let bad = "[escalation.exploration]\nepsilon = 0.0\n";
1999        assert!(
2000            matches!(Config::parse(bad), Err(Error::InvalidConfig(_))),
2001            "epsilon = 0 must be rejected (must be strictly positive)"
2002        );
2003    }
2004
2005    #[test]
2006    fn exploration_epsilon_negative_rejected() {
2007        let bad = "[escalation.exploration]\nepsilon = -0.1\n";
2008        assert!(
2009            matches!(Config::parse(bad), Err(Error::InvalidConfig(_))),
2010            "epsilon < 0 must be rejected"
2011        );
2012    }
2013
2014    #[test]
2015    fn gate_def_schema_and_on_abstain_parse() {
2016        let toml = r#"
2017[[route]]
2018match = {}
2019mode = "enforce"
2020ladder = ["anthropic/claude-haiku-4-5"]
2021gates = ["extract-shape"]
2022
2023[[gate]]
2024id = "extract-shape"
2025schema = { type = "object", required = ["name"] }
2026on_abstain = "fail_closed"
2027"#;
2028        let config = Config::parse(toml).expect("schema gate def must parse");
2029        let def = &config.gate_defs[0];
2030        assert_eq!(def.id, "extract-shape");
2031        let schema = def.schema.as_ref().expect("schema captured");
2032        assert_eq!(schema["type"], "object");
2033        assert_eq!(def.on_abstain, AbstainPolicy::FailClosed);
2034    }
2035
2036    #[test]
2037    fn gate_def_on_abstain_defaults_fail_open() {
2038        let toml = r#"
2039[[route]]
2040match = {}
2041mode = "enforce"
2042ladder = ["anthropic/claude-haiku-4-5"]
2043
2044[[gate]]
2045id = "tests"
2046cmd = ["true"]
2047"#;
2048        let config = Config::parse(toml).expect("parse");
2049        assert_eq!(config.gate_defs[0].on_abstain, AbstainPolicy::FailOpen);
2050    }
2051
2052    #[test]
2053    fn gate_def_rejects_schema_plus_cmd() {
2054        let toml = r#"
2055[[route]]
2056match = {}
2057mode = "enforce"
2058ladder = ["anthropic/claude-haiku-4-5"]
2059
2060[[gate]]
2061id = "both"
2062cmd = ["true"]
2063schema = { type = "object" }
2064"#;
2065        let err = Config::parse(toml).unwrap_err();
2066        assert!(
2067            err.to_string().contains("exactly one"),
2068            "two kinds must be rejected: {err}"
2069        );
2070    }
2071
2072    #[test]
2073    fn gate_def_decision_parses_with_defaults() {
2074        let toml = r#"
2075[[route]]
2076match = {}
2077mode = "enforce"
2078ladder = ["anthropic/claude-haiku-4-5"]
2079gates = ["verify"]
2080
2081[[gate]]
2082id = "verify"
2083decision = { provider = "typesafe" }
2084"#;
2085        let config = Config::parse(toml).expect("decision gate def must parse");
2086        let def = &config.gate_defs[0];
2087        let d = def.decision.as_ref().expect("decision captured");
2088        assert_eq!(d.provider, "typesafe");
2089        assert_eq!(d.model, "jev-latest");
2090        assert_eq!(d.api_key_env, "TYPESAFE_API_KEY");
2091        assert_eq!(d.base_url, "https://api.typesafe.ai");
2092        assert_eq!(d.timeout_ms, 1_000);
2093        assert!((d.threshold - 0.5).abs() < 1e-12);
2094        assert!(d.instructions.is_none());
2095    }
2096
2097    #[test]
2098    fn gate_def_decision_overrides_every_field() {
2099        let toml = r#"
2100[[route]]
2101match = {}
2102mode = "enforce"
2103ladder = ["anthropic/claude-haiku-4-5"]
2104gates = ["verify"]
2105
2106[[gate]]
2107id = "verify"
2108decision = { provider = "typesafe", model = "jev-mini", api_key_env = "MY_KEY", base_url = "https://example.test", timeout_ms = 250, threshold = 0.9, instructions = "be strict" }
2109"#;
2110        let config = Config::parse(toml).expect("parse");
2111        let d = config.gate_defs[0].decision.as_ref().unwrap();
2112        assert_eq!(d.model, "jev-mini");
2113        assert_eq!(d.api_key_env, "MY_KEY");
2114        assert_eq!(d.base_url, "https://example.test");
2115        assert_eq!(d.timeout_ms, 250);
2116        assert!((d.threshold - 0.9).abs() < 1e-12);
2117        assert_eq!(d.instructions.as_deref(), Some("be strict"));
2118    }
2119
2120    #[test]
2121    fn gate_def_rejects_decision_plus_judge() {
2122        let toml = r#"
2123[[route]]
2124match = {}
2125mode = "enforce"
2126ladder = ["anthropic/claude-haiku-4-5"]
2127
2128[[gate]]
2129id = "both"
2130decision = { provider = "typesafe" }
2131judge = { model = "anthropic/claude-opus-4-8" }
2132"#;
2133        let err = Config::parse(toml).unwrap_err();
2134        assert!(
2135            err.to_string().contains("exactly one"),
2136            "two kinds must be rejected: {err}"
2137        );
2138    }
2139
2140    #[test]
2141    fn gate_def_rejects_unsupported_decision_provider() {
2142        let toml = r#"
2143[[route]]
2144match = {}
2145mode = "enforce"
2146ladder = ["anthropic/claude-haiku-4-5"]
2147
2148[[gate]]
2149id = "verify"
2150decision = { provider = "acme" }
2151"#;
2152        let err = Config::parse(toml).unwrap_err();
2153        assert!(
2154            matches!(err, Error::InvalidConfig(_)),
2155            "unsupported provider must be rejected: {err}"
2156        );
2157    }
2158
2159    #[test]
2160    fn gate_def_rejects_decision_threshold_outside_open_interval() {
2161        for bad in ["0.0", "1.0", "1.5", "-0.1"] {
2162            let toml = format!(
2163                r#"
2164[[route]]
2165match = {{}}
2166mode = "enforce"
2167ladder = ["anthropic/claude-haiku-4-5"]
2168
2169[[gate]]
2170id = "verify"
2171decision = {{ provider = "typesafe", threshold = {bad} }}
2172"#
2173            );
2174            assert!(
2175                matches!(Config::parse(&toml), Err(Error::InvalidConfig(_))),
2176                "threshold {bad} outside (0,1) must be rejected"
2177            );
2178        }
2179    }
2180
2181    #[test]
2182    fn gate_def_rejects_decision_zero_timeout() {
2183        let toml = r#"
2184[[route]]
2185match = {}
2186mode = "enforce"
2187ladder = ["anthropic/claude-haiku-4-5"]
2188
2189[[gate]]
2190id = "verify"
2191decision = { provider = "typesafe", timeout_ms = 0 }
2192"#;
2193        assert!(matches!(Config::parse(toml), Err(Error::InvalidConfig(_))));
2194    }
2195
2196    #[test]
2197    fn price_overrides_parse_and_validate() {
2198        let toml = r#"
2199[[route]]
2200match = {}
2201mode = "observe"
2202ladder = ["anthropic/claude-haiku-4-5"]
2203
2204[[price]]
2205model = "anthropic/claude-haiku-4-5"
2206input_per_mtok = 0.8
2207output_per_mtok = 4.0
2208"#;
2209        let config = Config::parse(toml).expect("price override must parse");
2210        assert_eq!(config.price_defs[0].model, "anthropic/claude-haiku-4-5");
2211        assert!((config.price_defs[0].input_per_mtok - 0.8).abs() < 1e-12);
2212
2213        let bad = toml.replace("input_per_mtok = 0.8", "input_per_mtok = -1.0");
2214        assert!(Config::parse(&bad).is_err(), "negative price rejected");
2215    }
2216
2217    // ── RoutingMode / ModePreset ──────────────────────────────────────────────
2218
2219    /// The Balanced preset must be a strict no-op: all overrides None/false.
2220    /// This is the invariant that guarantees byte-identical behaviour when no mode is set.
2221    #[test]
2222    fn balanced_preset_is_strict_noop() {
2223        let p = RoutingMode::Balanced.preset();
2224        assert!(
2225            p.speculation.is_none(),
2226            "Balanced must not override speculation"
2227        );
2228        assert!(
2229            p.max_rungs_delta.is_none(),
2230            "Balanced must not override max_rungs"
2231        );
2232        assert!(!p.start_at_top, "Balanced must not set start_at_top");
2233    }
2234
2235    #[test]
2236    fn cost_preset_disables_speculation() {
2237        let p = RoutingMode::Cost.preset();
2238        assert_eq!(p.speculation, Some(0));
2239        assert!(p.max_rungs_delta.is_none());
2240        assert!(!p.start_at_top);
2241    }
2242
2243    #[test]
2244    fn quality_preset_bumps_max_rungs_and_disables_speculation() {
2245        let p = RoutingMode::Quality.preset();
2246        assert_eq!(p.max_rungs_delta, Some(1));
2247        assert_eq!(p.speculation, Some(0));
2248        assert!(!p.start_at_top);
2249    }
2250
2251    #[test]
2252    fn latency_preset_enables_speculation() {
2253        let p = RoutingMode::Latency.preset();
2254        assert_eq!(p.speculation, Some(1));
2255        assert!(p.max_rungs_delta.is_none());
2256        assert!(!p.start_at_top);
2257    }
2258
2259    #[test]
2260    fn max_preset_sets_start_at_top_and_disables_speculation() {
2261        let p = RoutingMode::Max.preset();
2262        assert!(p.start_at_top);
2263        assert_eq!(p.speculation, Some(0));
2264        assert!(p.max_rungs_delta.is_none());
2265    }
2266
2267    #[test]
2268    fn routing_mode_as_str_roundtrips() {
2269        for mode in RoutingMode::ALL {
2270            let s = mode.as_str();
2271            let back: RoutingMode = serde_json::from_str(&format!("\"{s}\"")).unwrap();
2272            assert_eq!(*mode, back, "as_str/serde roundtrip for {s}");
2273        }
2274    }
2275
2276    #[test]
2277    fn routing_mode_defaults_to_balanced() {
2278        assert_eq!(RoutingMode::default(), RoutingMode::Balanced);
2279    }
2280
2281    #[test]
2282    fn route_routing_mode_parses_and_defaults_to_none() {
2283        // Absent → None (byte-identical, no behavioral change).
2284        let no_mode = Config::parse(
2285            "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\"]\n",
2286        )
2287        .unwrap();
2288        assert_eq!(no_mode.routes[0].routing_mode, None);
2289
2290        // Explicit cost mode.
2291        let with_mode = Config::parse(
2292            "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\"]\nrouting_mode = \"cost\"\n",
2293        )
2294        .unwrap();
2295        assert_eq!(with_mode.routes[0].routing_mode, Some(RoutingMode::Cost));
2296    }
2297
2298    #[test]
2299    fn all_routing_modes_have_non_empty_description_and_tradeoff() {
2300        for mode in RoutingMode::ALL {
2301            let p = mode.preset();
2302            assert!(
2303                !p.description.is_empty(),
2304                "mode {} has empty description",
2305                mode.as_str()
2306            );
2307            assert!(
2308                !p.tradeoff.is_empty(),
2309                "mode {} has empty tradeoff",
2310                mode.as_str()
2311            );
2312        }
2313    }
2314
2315    #[test]
2316    fn bandit_thompson_and_band_parse_and_validate() {
2317        let toml = r#"
2318[[route]]
2319match = {}
2320mode = "enforce"
2321ladder = ["anthropic/claude-haiku-4-5"]
2322
2323[escalation]
2324speculation = 1
2325speculation_band = [0.3, 0.7]
2326
2327[escalation.bandit]
2328algorithm = "thompson"
2329discount = 0.98
2330"#;
2331        let config = Config::parse(toml).expect("thompson + band must parse");
2332        let b = config.escalation.bandit.as_ref().unwrap();
2333        assert_eq!(b.algorithm, BanditAlgorithm::Thompson);
2334        assert!((b.discount - 0.98).abs() < 1e-12);
2335        assert_eq!(config.escalation.speculation_band, Some([0.3, 0.7]));
2336
2337        // Defaults: ucb1, discount 1.0, no band.
2338        let plain = Config::parse(
2339            "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\"]\n[escalation.bandit]\n",
2340        )
2341        .unwrap();
2342        let b = plain.escalation.bandit.as_ref().unwrap();
2343        assert_eq!(b.algorithm, BanditAlgorithm::Ucb1);
2344        assert!((b.discount - 1.0).abs() < 1e-12);
2345
2346        // Bad discount and bad band are rejected.
2347        assert!(Config::parse(&toml.replace("discount = 0.98", "discount = 0.0")).is_err());
2348        assert!(
2349            Config::parse(&toml.replace(
2350                "speculation_band = [0.3, 0.7]",
2351                "speculation_band = [0.9, 0.2]"
2352            ))
2353            .is_err()
2354        );
2355    }
2356
2357    // ── ProbeConfig parse / validation ───────────────────────────────────────
2358
2359    #[test]
2360    fn probe_absent_defaults_to_none() {
2361        // Default off = byte-identical to today.
2362        let c = Config::parse("").unwrap();
2363        assert!(c.escalation.probe.is_none());
2364    }
2365
2366    #[test]
2367    fn parses_valid_probe_config() {
2368        let c = Config::parse("[escalation.probe]\nk = 5\nsample_rate = 0.1\n").unwrap();
2369        let p = c.escalation.probe.expect("[escalation.probe] should parse");
2370        assert_eq!(p.k, 5);
2371        assert!((p.sample_rate - 0.1).abs() < 1e-12);
2372    }
2373
2374    #[test]
2375    fn probe_sample_rate_boundaries_accepted() {
2376        // 0.0 (never probe) and 1.0 (always probe) are both valid.
2377        let c0 = Config::parse("[escalation.probe]\nk = 2\nsample_rate = 0.0\n").unwrap();
2378        assert!((c0.escalation.probe.unwrap().sample_rate - 0.0).abs() < 1e-12);
2379        let c1 = Config::parse("[escalation.probe]\nk = 8\nsample_rate = 1.0\n").unwrap();
2380        assert!((c1.escalation.probe.unwrap().sample_rate - 1.0).abs() < 1e-12);
2381    }
2382
2383    #[test]
2384    fn probe_rejects_k_below_2() {
2385        let bad = "[escalation.probe]\nk = 1\nsample_rate = 0.5\n";
2386        assert!(
2387            matches!(Config::parse(bad), Err(Error::InvalidConfig(_))),
2388            "k=1 must be rejected"
2389        );
2390    }
2391
2392    #[test]
2393    fn probe_rejects_k_above_8() {
2394        let bad = "[escalation.probe]\nk = 9\nsample_rate = 0.5\n";
2395        assert!(
2396            matches!(Config::parse(bad), Err(Error::InvalidConfig(_))),
2397            "k=9 must be rejected"
2398        );
2399    }
2400
2401    #[test]
2402    fn probe_rejects_sample_rate_above_1() {
2403        let bad = "[escalation.probe]\nk = 5\nsample_rate = 1.5\n";
2404        assert!(
2405            matches!(Config::parse(bad), Err(Error::InvalidConfig(_))),
2406            "sample_rate=1.5 must be rejected"
2407        );
2408    }
2409
2410    #[test]
2411    fn probe_rejects_negative_sample_rate() {
2412        let bad = "[escalation.probe]\nk = 5\nsample_rate = -0.1\n";
2413        assert!(
2414            matches!(Config::parse(bad), Err(Error::InvalidConfig(_))),
2415            "negative sample_rate must be rejected"
2416        );
2417    }
2418
2419    #[test]
2420    fn predictor_config_parses_and_validates() {
2421        let base = "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\"]\n[escalation.predictor]\nlr = 0.05\nl2 = 0.001\n";
2422        let cfg = Config::parse(base).expect("valid predictor must parse");
2423        let pred = cfg.escalation.predictor.unwrap();
2424        assert!((pred.lr - 0.05).abs() < 1e-12 && (pred.l2 - 0.001).abs() < 1e-12);
2425        // defaults when omitted
2426        let d = Config::parse("[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\"]\n[escalation.predictor]\n").unwrap();
2427        assert!(d.escalation.predictor.is_some());
2428        // bad lr / l2 rejected
2429        assert!(Config::parse(&base.replace("lr = 0.05", "lr = 0.0")).is_err());
2430        assert!(Config::parse(&base.replace("lr = 0.05", "lr = 1.5")).is_err());
2431        assert!(Config::parse(&base.replace("l2 = 0.001", "l2 = -1.0")).is_err());
2432    }
2433
2434    #[test]
2435    fn prior_config_parses_and_validates() {
2436        let base = "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\", \"anthropic/claude-sonnet-5\"]\n[escalation.prior]\nprovider = \"typesafe\"\nrungs = [\"cheap\", \"strong\"]\n";
2437        let cfg = Config::parse(base).expect("valid prior must parse");
2438        let prior = cfg.escalation.prior.unwrap();
2439        assert_eq!(prior.model, "jev-latest");
2440        assert_eq!(prior.api_key_env, "TYPESAFE_API_KEY");
2441        assert_eq!(prior.base_url, "https://api.typesafe.ai");
2442        assert_eq!(prior.timeout_ms, 150);
2443        assert!((prior.strength - 10.0).abs() < 1e-12);
2444        assert_eq!(prior.rungs, vec!["cheap".to_owned(), "strong".to_owned()]);
2445    }
2446
2447    #[test]
2448    fn prior_config_overrides_all_defaults() {
2449        let cfg = Config::parse(
2450            "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\"]\n\
2451             [escalation.prior]\nprovider = \"typesafe\"\nmodel = \"jev-2\"\n\
2452             api_key_env = \"MY_KEY\"\nbase_url = \"https://example.test\"\ntimeout_ms = 500\n\
2453             strength = 5.0\nrungs = [\"cheap\"]\n",
2454        )
2455        .unwrap();
2456        let prior = cfg.escalation.prior.unwrap();
2457        assert_eq!(prior.model, "jev-2");
2458        assert_eq!(prior.api_key_env, "MY_KEY");
2459        assert_eq!(prior.base_url, "https://example.test");
2460        assert_eq!(prior.timeout_ms, 500);
2461        assert!((prior.strength - 5.0).abs() < 1e-12);
2462    }
2463
2464    #[test]
2465    fn prior_rejects_unsupported_provider() {
2466        let bad = "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\"]\n[escalation.prior]\nprovider = \"openai\"\nrungs = [\"cheap\"]\n";
2467        assert!(
2468            matches!(Config::parse(bad), Err(Error::InvalidConfig(_))),
2469            "unsupported provider must be rejected"
2470        );
2471    }
2472
2473    #[test]
2474    fn prior_rejects_non_positive_strength() {
2475        let base = "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\"]\n[escalation.prior]\nprovider = \"typesafe\"\nrungs = [\"cheap\"]\nstrength = ";
2476        assert!(matches!(
2477            Config::parse(&format!("{base}0.0\n")),
2478            Err(Error::InvalidConfig(_))
2479        ));
2480        assert!(matches!(
2481            Config::parse(&format!("{base}-1.0\n")),
2482            Err(Error::InvalidConfig(_))
2483        ));
2484    }
2485
2486    #[test]
2487    fn prior_rejects_zero_timeout() {
2488        let bad = "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\"]\n[escalation.prior]\nprovider = \"typesafe\"\nrungs = [\"cheap\"]\ntimeout_ms = 0\n";
2489        assert!(matches!(Config::parse(bad), Err(Error::InvalidConfig(_))));
2490    }
2491
2492    #[test]
2493    fn prior_rejects_empty_rungs() {
2494        let bad = "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\"]\n[escalation.prior]\nprovider = \"typesafe\"\nrungs = []\n";
2495        assert!(matches!(Config::parse(bad), Err(Error::InvalidConfig(_))));
2496    }
2497
2498    #[test]
2499    fn prior_rejects_rung_count_mismatch_with_enforce_ladder() {
2500        // Ladder has 2 rungs, prior names only 1 -> reject.
2501        let bad = "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\", \"anthropic/claude-sonnet-5\"]\n[escalation.prior]\nprovider = \"typesafe\"\nrungs = [\"only-one\"]\n";
2502        let err = Config::parse(bad).expect_err("rung count mismatch must be rejected");
2503        assert!(matches!(err, Error::InvalidConfig(_)));
2504    }
2505
2506    #[test]
2507    fn prior_ignores_rung_count_mismatch_on_observe_only_routes() {
2508        // An observe-mode route's ladder isn't enforced, so a mismatched prior there is harmless.
2509        let cfg = Config::parse(
2510            "[[route]]\nmatch = {}\nmode = \"observe\"\nladder = [\"anthropic/claude-haiku-4-5\", \"anthropic/claude-sonnet-5\"]\n\
2511             [escalation.prior]\nprovider = \"typesafe\"\nrungs = [\"only-one\"]\n",
2512        )
2513        .expect("observe-only ladder mismatch must not be rejected");
2514        assert_eq!(cfg.escalation.prior.unwrap().rungs.len(), 1);
2515    }
2516
2517    #[test]
2518    fn prior_absent_by_default() {
2519        let cfg = Config::parse(
2520            "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\"]\n",
2521        )
2522        .unwrap();
2523        assert!(cfg.escalation.prior.is_none());
2524    }
2525
2526    /// An unpriced ladder rung must be rejected at parse. The router prices a call with
2527    /// `cost_usd(..).unwrap_or(0.0)`, so accepting one would put a spend nobody measured into a
2528    /// tamper-evident receipt and leave every `[budget]` cap permanently un-trippable — the two
2529    /// failures this product can least afford.
2530    #[test]
2531    fn unpriced_ladder_rung_is_rejected_and_an_explicit_price_fixes_it() {
2532        let unpriced =
2533            "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"ollama/qwen2.5-coder:7b\"]\n";
2534        let err = Config::parse(unpriced).expect_err("an unpriced rung must not parse");
2535        let msg = err.to_string();
2536        assert!(
2537            msg.contains("ollama/qwen2.5-coder:7b") && msg.contains("[[price]]"),
2538            "the error must name the rung and the fix, got: {msg}"
2539        );
2540
2541        // A self-hosted model really is free — but it has to SAY so.
2542        let declared = format!(
2543            "[[price]]\nmodel = \"ollama/qwen2.5-coder:7b\"\ninput_per_mtok = 0.0\noutput_per_mtok = 0.0\n{unpriced}"
2544        );
2545        let cfg = Config::parse(&declared).expect("an explicit zero price is legal");
2546        assert_eq!(
2547            cfg.price_table()
2548                .get("ollama/qwen2.5-coder:7b")
2549                .unwrap()
2550                .input_per_mtok,
2551            0.0
2552        );
2553
2554        // The built-in first-party models still need no ceremony.
2555        assert!(
2556            Config::parse("[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\"]\n").is_ok()
2557        );
2558    }
2559
2560    /// Shadow is off unless asked for, and a nonsensical setting must fail loudly at parse rather
2561    /// than being clamped — a silently-corrected ceiling would spend a different amount than the
2562    /// operator authorised.
2563    #[test]
2564    fn shadow_config_parses_and_validates() {
2565        let base = "[[route]]\nmatch = {}\nmode = \"observe\"\nladder = [\"anthropic/claude-haiku-4-5\"]\n";
2566        let none = Config::parse(base).unwrap();
2567        assert!(
2568            none.routes[0].shadow.is_none(),
2569            "shadow must be off by default"
2570        );
2571
2572        let ok = Config::parse(&format!(
2573            "{base}[route.shadow]\nsample_rate = 0.25\nmax_usd_per_day = 5.0\n"
2574        ))
2575        .unwrap();
2576        let sh = ok.routes[0].shadow.expect("shadow parsed");
2577        assert!((sh.sample_rate - 0.25).abs() < f64::EPSILON);
2578        assert!((sh.max_usd_per_day - 5.0).abs() < f64::EPSILON);
2579
2580        for bad in [
2581            "sample_rate = 1.5\nmax_usd_per_day = 5.0",
2582            "sample_rate = -0.1\nmax_usd_per_day = 5.0",
2583            "sample_rate = 0.1\nmax_usd_per_day = -1.0",
2584        ] {
2585            assert!(
2586                Config::parse(&format!("{base}[route.shadow]\n{bad}\n")).is_err(),
2587                "invalid shadow config accepted: {bad}"
2588            );
2589        }
2590    }
2591
2592    /// Same for rollout: absent by default, invalid percent rejected at parse.
2593    #[test]
2594    fn rollout_config_parses_and_validates() {
2595        let base = "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-haiku-4-5\"]\n";
2596        assert!(Config::parse(base).unwrap().routes[0].rollout.is_none());
2597        let ok = Config::parse(&format!(
2598            "{base}[route.rollout]\npercent = 5.0\nkey = \"session\"\n"
2599        ))
2600        .unwrap();
2601        assert!((ok.routes[0].rollout.unwrap().percent - 5.0).abs() < f64::EPSILON);
2602        assert!(Config::parse(&format!("{base}[route.rollout]\npercent = 140.0\n")).is_err());
2603    }
2604
2605    /// `[route.challenger]` (ADR 0014): one accept and every rejection the brief names.
2606    #[test]
2607    fn challenger_config_parses_and_rejects_incoherent_setups() {
2608        let route =
2609            "[[route]]\nmatch = {}\nmode = \"enforce\"\nladder = [\"anthropic/claude-sonnet-5\"]\n";
2610        let obs =
2611            "[[route]]\nmatch = {}\nmode = \"observe\"\nladder = [\"anthropic/claude-sonnet-5\"]\n";
2612        let ch = |body: &str| format!("{route}[route.challenger]\n{body}\n");
2613
2614        assert!(Config::parse(route).unwrap().routes[0].challenger.is_none());
2615        let ok = Config::parse(&ch(
2616            "ladder = [\"anthropic/claude-haiku-4-5\"]\npercent = 10.0",
2617        ))
2618        .unwrap();
2619        let c = ok.routes[0].challenger.as_ref().expect("parsed");
2620        assert!((c.margin - crate::select::DEFAULT_MARGIN).abs() < f64::EPSILON);
2621        assert!((c.alpha - crate::select::DEFAULT_ALPHA).abs() < f64::EPSILON);
2622
2623        let bad: &[(&str, String)] = &[
2624            ("empty ladder", ch("ladder = []\npercent = 10.0")),
2625            (
2626                "percent 0",
2627                ch("ladder = [\"anthropic/claude-haiku-4-5\"]\npercent = 0.0"),
2628            ),
2629            (
2630                "percent 100 (no control arm)",
2631                ch("ladder = [\"anthropic/claude-haiku-4-5\"]\npercent = 100.0"),
2632            ),
2633            (
2634                "percent > 100",
2635                ch("ladder = [\"anthropic/claude-haiku-4-5\"]\npercent = 101.0"),
2636            ),
2637            (
2638                "margin 0",
2639                ch("ladder = [\"anthropic/claude-haiku-4-5\"]\npercent = 10.0\nmargin = 0.0"),
2640            ),
2641            (
2642                "alpha 0.5",
2643                ch("ladder = [\"anthropic/claude-haiku-4-5\"]\npercent = 10.0\nalpha = 0.5"),
2644            ),
2645            (
2646                "unknown key",
2647                ch(
2648                    "ladder = [\"anthropic/claude-haiku-4-5\"]\npercent = 10.0\nmax_escalations = 3",
2649                ),
2650            ),
2651            (
2652                "same ladder as the route",
2653                ch("ladder = [\"anthropic/claude-sonnet-5\"]\npercent = 10.0"),
2654            ),
2655            (
2656                "unpriced rung",
2657                ch("ladder = [\"anthropic/not-a-priced-model\"]\npercent = 10.0"),
2658            ),
2659            (
2660                "unresolvable provider",
2661                format!(
2662                    "{route}[route.challenger]\nladder = [\"groq/llama\"]\npercent = 10.0\n\
2663                     [[price]]\nmodel = \"groq/llama\"\ninput_per_mtok = 0.1\noutput_per_mtok = 0.1\n"
2664                ),
2665            ),
2666            ("malformed rung", ch("ladder = [\"haiku\"]\npercent = 10.0")),
2667            (
2668                "observe route",
2669                format!(
2670                    "{obs}[route.challenger]\nladder = [\"anthropic/claude-haiku-4-5\"]\npercent = 10.0\n"
2671                ),
2672            ),
2673        ];
2674        for (why, toml) in bad {
2675            assert!(Config::parse(toml).is_err(), "accepted: {why}");
2676        }
2677
2678        // A declared provider + price makes a custom rung acceptable.
2679        assert!(
2680            Config::parse(&format!(
2681                "{route}[route.challenger]\nladder = [\"groq/llama\"]\npercent = 10.0\n\
2682                 [[provider]]\nid = \"groq\"\ndialect = \"openai\"\nbase_url = \"https://api.groq.com/openai\"\n\
2683                 [[price]]\nmodel = \"groq/llama\"\ninput_per_mtok = 0.1\noutput_per_mtok = 0.1\n"
2684            ))
2685            .is_ok()
2686        );
2687
2688        // Paired mode: valid when the route has a meaningful gate, invalid without one.
2689        let gated = "[[route]]\nmatch = {}\nmode = \"enforce\"\n\
2690                     ladder = [\"anthropic/claude-sonnet-5\"]\ngates = [\"json-valid\"]\n";
2691        let paired_ok = format!(
2692            "{gated}[route.challenger]\nladder = [\"anthropic/claude-haiku-4-5\"]\n\
2693             mode = \"paired\"\nmax_usd_per_day = 5.0\n"
2694        );
2695        assert!(
2696            Config::parse(&paired_ok).is_ok(),
2697            "paired with json-valid gate"
2698        );
2699
2700        // Paired mode rejected on non-empty-only route.
2701        let no_gate = "[[route]]\nmatch = {}\nmode = \"enforce\"\n\
2702                       ladder = [\"anthropic/claude-sonnet-5\"]\n";
2703        let paired_no_gate = format!(
2704            "{no_gate}[route.challenger]\nladder = [\"anthropic/claude-haiku-4-5\"]\n\
2705             mode = \"paired\"\nmax_usd_per_day = 5.0\n"
2706        );
2707        assert!(
2708            Config::parse(&paired_no_gate).is_err(),
2709            "paired requires meaningful gate"
2710        );
2711
2712        // Paired mode with only non-empty gate also rejected.
2713        let only_nonempty = "[[route]]\nmatch = {}\nmode = \"enforce\"\n\
2714                             ladder = [\"anthropic/claude-sonnet-5\"]\ngates = [\"non-empty\"]\n";
2715        let paired_nonempty = format!(
2716            "{only_nonempty}[route.challenger]\nladder = [\"anthropic/claude-haiku-4-5\"]\n\
2717             mode = \"paired\"\nmax_usd_per_day = 5.0\n"
2718        );
2719        assert!(
2720            Config::parse(&paired_nonempty).is_err(),
2721            "paired with only non-empty gate rejected"
2722        );
2723
2724        // Paired mode missing max_usd_per_day.
2725        let paired_no_ceiling = format!(
2726            "{gated}[route.challenger]\nladder = [\"anthropic/claude-haiku-4-5\"]\n\
2727             mode = \"paired\"\n"
2728        );
2729        assert!(
2730            Config::parse(&paired_no_ceiling).is_err(),
2731            "paired without max_usd_per_day"
2732        );
2733    }
2734}