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