car_inference/

adaptive_router.rs

//! Adaptive model routing — three-phase routing with learned performance profiles.
//!
//! Phase 1: **Filter** — hard constraints (capability, availability, memory, cost).
//! Phase 2: **Score** — blend quality, latency, and cost using observed profiles
//!          or schema defaults on cold start.
//! Phase 3: **Select** — Thompson Sampling (Beta distribution per model) for
//!          natural exploration-exploitation balance. Models with fewer observations
//!          have wider distributions, giving them chances to prove themselves.
//!
//! Replaces the hardcoded `ModelRouter` from `router.rs`.

use rand::Rng;
use serde::{Deserialize, Serialize};

use std::sync::{Arc, Mutex};

use crate::hardware::HardwareInfo;
use crate::outcome::{InferenceTask, OutcomeTracker};
use crate::registry::UnifiedRegistry;
use crate::routing_ext::CircuitBreakerRegistry;
use crate::schema::{ModelCapability, ModelSchema};
use crate::tasks::RoutingWorkload;

/// Prompt complexity assessment (migrated from router.rs).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum TaskComplexity {
    Simple,
    Medium,
    Code,
    Complex,
}

impl TaskComplexity {
    /// Assess complexity of a prompt string.
    ///
    /// Uses tree-sitter AST parsing (when the `ast` feature is enabled) for
    /// accurate code detection: if a code block parses successfully as any
    /// supported language, it's definitively code. Falls back to keyword
    /// heuristics for prompts that mention code without containing code blocks.
    pub fn assess(prompt: &str) -> Self {
        let lower = prompt.to_lowercase();
        let word_count = prompt.split_whitespace().count();
        let estimated_tokens = (word_count as f64 * 1.3) as usize;

        let has_code = Self::detect_code(prompt);

        let repair_markers = [
            "fix", "repair", "debug", "refactor", "broken", "failing", "error", "bug",
        ];
        let has_repair = repair_markers.iter().any(|m| lower.contains(m));

        let reasoning_markers = [
            "analyze",
            "compare",
            "explain why",
            "step by step",
            "think through",
            "evaluate",
            "trade-off",
            "tradeoff",
            "pros and cons",
            "architecture",
            "design",
            "strategy",
            "optimize",
            "comprehensive",
        ];
        let has_reasoning = reasoning_markers.iter().any(|m| lower.contains(m));

        let simple_patterns = [
            "what is",
            "who is",
            "when did",
            "where is",
            "how many",
            "yes or no",
            "true or false",
            "name the",
            "list the",
            "define ",
        ];
        let is_simple = simple_patterns.iter().any(|p| lower.contains(p));

        if has_code || has_repair {
            TaskComplexity::Code
        } else if has_reasoning || estimated_tokens > 500 {
            TaskComplexity::Complex
        } else if is_simple || estimated_tokens < 30 {
            TaskComplexity::Simple
        } else {
            TaskComplexity::Medium
        }
    }

    /// Detect whether a prompt contains code.
    ///
    /// With `ast` feature: extracts code blocks (``` delimited), attempts to
    /// parse each with tree-sitter. If any parses into symbols, it's real code.
    /// Without `ast` feature: falls back to keyword heuristics.
    fn detect_code(prompt: &str) -> bool {
        // First try AST-based detection on code blocks
        #[cfg(feature = "ast")]
        {
            if let Some(is_code) = Self::detect_code_ast(prompt) {
                return is_code;
            }
        }

        // Fallback: keyword heuristics
        let code_markers = [
            "```",
            "fn ",
            "def ",
            "class ",
            "import ",
            "require(",
            "async fn",
            "pub fn",
            "function ",
            "const ",
            "let ",
            "var ",
            "#include",
            "package ",
            "impl ",
        ];
        code_markers.iter().any(|m| prompt.contains(m))
    }

    /// AST-based code detection: parse code blocks with tree-sitter.
    /// Returns Some(true) if code found, Some(false) if blocks exist but
    /// don't parse, None if no code blocks found (fall through to heuristics).
    #[cfg(feature = "ast")]
    fn detect_code_ast(prompt: &str) -> Option<bool> {
        // Extract code blocks between ``` markers
        let mut blocks = Vec::new();
        let mut rest = prompt;
        while let Some(start) = rest.find("```") {
            let after_fence = &rest[start + 3..];
            // Skip optional language tag on the opening fence
            let code_start = after_fence.find('\n').map(|i| i + 1).unwrap_or(0);
            if let Some(end) = after_fence[code_start..].find("```") {
                blocks.push(&after_fence[code_start..code_start + end]);
                rest = &after_fence[code_start + end + 3..];
            } else {
                break;
            }
        }

        if blocks.is_empty() {
            return None; // No code blocks — let heuristics decide
        }

        // Try to parse each block with tree-sitter
        let languages = [
            car_ast::Language::Rust,
            car_ast::Language::Python,
            car_ast::Language::TypeScript,
            car_ast::Language::JavaScript,
            car_ast::Language::Go,
        ];

        for block in &blocks {
            let trimmed = block.trim();
            if trimmed.is_empty() {
                continue;
            }

            for lang in &languages {
                if let Some(parsed) = car_ast::parse(trimmed, *lang) {
                    // If it parsed into any symbols, it's definitely code
                    if !parsed.symbols.is_empty() {
                        return Some(true);
                    }
                }
            }
        }

        // Had code blocks but none parsed into symbols — could be
        // pseudocode, output, or unsupported language
        Some(false)
    }

    /// Map complexity to required capabilities.
    pub fn required_capabilities(&self) -> Vec<ModelCapability> {
        match self {
            TaskComplexity::Simple => vec![ModelCapability::Generate],
            TaskComplexity::Medium => vec![ModelCapability::Generate],
            TaskComplexity::Code => vec![ModelCapability::Code],
            TaskComplexity::Complex => vec![ModelCapability::Reasoning],
        }
    }

    /// Map complexity to the InferenceTask type.
    pub fn inference_task(&self) -> InferenceTask {
        match self {
            TaskComplexity::Simple | TaskComplexity::Medium => InferenceTask::Generate,
            TaskComplexity::Code => InferenceTask::Code,
            TaskComplexity::Complex => InferenceTask::Reasoning,
        }
    }
}

/// Configuration for routing behavior.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RoutingConfig {
    /// Minimum observations before trusting a model's profile over schema defaults.
    pub min_observations: u64,
    /// Scoring weights (must sum to 1.0).
    pub quality_weight: f64,
    pub latency_weight: f64,
    pub cost_weight: f64,
    /// Hard constraint: maximum latency budget in ms.
    pub max_latency_ms: Option<u64>,
    /// Hard constraint: maximum cost per call in USD.
    pub max_cost_usd: Option<f64>,
    /// Prefer local models over remote (all else being equal).
    pub prefer_local: bool,
    /// Thompson Sampling prior strength. Higher = more weight on the Phase 2 score
    /// as a prior, lower = more influenced by observed outcomes.
    /// Equivalent to the number of "virtual" observations from the prior.
    pub prior_strength: f64,
    /// Prefer trusted remote models for quality-critical tasks until local models
    /// have enough task-specific evidence to be promoted.
    pub quality_first_cold_start: bool,
    /// Minimum task-specific observations required before a local model can
    /// compete with trusted remote models during cold start.
    pub bootstrap_min_task_observations: u64,
    /// Minimum task-specific EMA quality required before a local model can
    /// displace trusted remote models during cold start.
    pub bootstrap_quality_floor: f64,
}

impl Default for RoutingConfig {
    fn default() -> Self {
        Self {
            min_observations: 2,
            quality_weight: 0.45,
            latency_weight: 0.4,
            cost_weight: 0.15,
            max_latency_ms: None,
            max_cost_usd: None,
            prefer_local: true,
            prior_strength: 2.0,
            quality_first_cold_start: true,
            bootstrap_min_task_observations: 8,
            bootstrap_quality_floor: 0.8,
        }
    }
}

/// How a model was selected.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RoutingStrategy {
    /// Using declared schema capabilities (no observed data).
    SchemaBased,
    /// Using observed performance profiles (exploitation).
    ProfileBased,
    /// Deliberately trying an under-tested model (exploration).
    Exploration,
    /// User explicitly specified the model.
    Explicit,
}

/// One scored candidate considered during adaptive routing.
///
/// Advisory surface: lets a caller (UI, operator, audit) see *why* a model was
/// picked and what the alternatives cost in reliability terms — the tradeoff
/// the router resolved on their behalf. `selected` marks the chosen model;
/// `in_band` marks models inside the outcome-first reliability band (the set the
/// router would accept). Cost/latency only break ties *within* the band, so a
/// cheaper out-of-band model is shown but was never eligible.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RouteCandidate {
    /// Candidate model id.
    pub model_id: String,
    /// Outcome-derived reliability (quality-only band key, 0.0-1.0).
    pub reliability: f64,
    /// Full routing score (reliability plus cost/latency/context tie-breakers).
    pub score: f64,
    /// Whether this candidate was the one selected.
    pub selected: bool,
    /// Whether this candidate fell inside the outcome-first reliability band.
    pub in_band: bool,
}

/// The result of adaptive routing.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AdaptiveRoutingDecision {
    /// Selected model id.
    pub model_id: String,
    /// Selected model name (display).
    pub model_name: String,
    /// Task type.
    pub task: InferenceTask,
    /// Assessed complexity.
    pub complexity: TaskComplexity,
    /// Human-readable reason.
    pub reason: String,
    /// How the model was selected.
    pub strategy: RoutingStrategy,
    /// Predicted quality (0.0-1.0).
    pub predicted_quality: f64,
    /// Fallback chain (ordered list of alternative model ids).
    pub fallbacks: Vec<String>,
    /// Context window of the selected model (tokens). 0 = unknown.
    pub context_length: usize,
    /// Whether the prompt needs compaction to fit the selected model's context window.
    pub needs_compaction: bool,
    /// Ranked candidates considered (advisory). Empty for explicit-model and
    /// error paths where no ranking occurred; populated only by the adaptive path.
    #[serde(default)]
    pub candidates: Vec<RouteCandidate>,
}

/// Adaptive router with three-phase model selection.
pub struct AdaptiveRouter {
    hw: HardwareInfo,
    config: RoutingConfig,
    /// Circuit breaker registry — blocks models after consecutive failures (#25).
    pub circuit_breakers: Arc<Mutex<CircuitBreakerRegistry>>,
}

/// All inputs to a routing decision packed into one struct so adding
/// a new combinator (per-tenant routing, streaming awareness, …)
/// only adds a field rather than another `route_*` sibling method.
/// See [`AdaptiveRouter::route_with`].
///
/// Use [`RouteRequest::new`] for the common defaults, then mutate
/// just the fields the caller cares about:
///
/// ```ignore
/// let decision = router.route_with(RouteRequest {
///     has_tools: true,
///     intent: Some(&hint),
///     ..RouteRequest::new(prompt, &registry, &tracker)
/// });
/// ```
pub struct RouteRequest<'a> {
    pub prompt: &'a str,
    pub registry: &'a UnifiedRegistry,
    pub tracker: &'a OutcomeTracker,
    /// Estimated total context footprint (prompt + reserved output) for
    /// context-window-aware scoring. `0` skips the compaction-headroom check.
    pub estimated_total_tokens: usize,
    /// Estimated uncapped prompt tokens for prompt-size pricing tiers. When
    /// zero, routing falls back to `estimated_total_tokens - output`.
    pub estimated_input_tokens: usize,
    /// Expected generated tokens for request-cost scoring.
    pub estimated_output_tokens: usize,
    /// Prompt tokens expected to be served from provider cache.
    pub estimated_cache_read_tokens: usize,
    /// Prompt tokens expected to be written to provider cache.
    pub estimated_cache_write_tokens: usize,
    pub has_tools: bool,
    pub has_vision: bool,
    pub workload: RoutingWorkload,
    /// Caller-supplied intent hint. `prefer_local: true` overrides
    /// `workload` to [`RoutingWorkload::LocalPreferred`].
    pub intent: Option<&'a crate::intent::IntentHint>,
}

impl<'a> RouteRequest<'a> {
    /// Build a request with the same defaults the bare
    /// [`AdaptiveRouter::route`] uses: interactive workload, no tools,
    /// no vision, no context-aware sizing, no intent.
    pub fn new(
        prompt: &'a str,
        registry: &'a UnifiedRegistry,
        tracker: &'a OutcomeTracker,
    ) -> Self {
        Self {
            prompt,
            registry,
            tracker,
            estimated_total_tokens: 0,
            estimated_input_tokens: 0,
            estimated_output_tokens: 0,
            estimated_cache_read_tokens: 0,
            estimated_cache_write_tokens: 0,
            has_tools: false,
            has_vision: false,
            workload: RoutingWorkload::Interactive,
            intent: None,
        }
    }
}

/// Credential-backed availability captured once per routing decision. Keychain
/// and environment state may change between decisions, but never halfway
/// through filtering/fallback construction for one decision.
#[derive(Clone, Copy)]
struct AvailabilitySnapshot {
    openrouter: Option<crate::openrouter::CredentialSource>,
}

impl AvailabilitySnapshot {
    fn capture(registry: &UnifiedRegistry) -> Self {
        let has_openrouter = registry.list().into_iter().any(|schema| {
            matches!(
                schema.source,
                crate::schema::ModelSource::RemoteApi {
                    protocol: crate::schema::ApiProtocol::OpenRouter,
                    ..
                }
            )
        });
        Self {
            openrouter: has_openrouter
                .then(crate::openrouter::credential_source)
                .flatten(),
        }
    }

    fn is_available(self, schema: &ModelSchema) -> bool {
        match schema.source {
            crate::schema::ModelSource::RemoteApi {
                protocol: crate::schema::ApiProtocol::OpenRouter,
                ..
            } => self.openrouter.is_some(),
            _ => schema.available,
        }
    }
}

/// Per-benchmark frontier reference: the best score any builtin-catalog model
/// reaches on that benchmark. The anchor that maps a benchmark's hard absolute
/// scale onto the quality tier (`benchmark_frontier_ref`).
///
/// Derived from the catalog, computed once, so the calibration is data — not a
/// hardcoded literal that rots. Adding only weaker models leaves a reference
/// unchanged (it's a max); a genuinely stronger model raises it and the tier
/// re-scales. A benchmark no catalog model carries simply isn't here
/// (→ uncalibrated clamp). Today: `tau-bench-airline → 0.65`.
///
/// INVARIANT (#371): max is a valid frontier anchor *only when a frontier-class
/// model carries the benchmark*. Today that holds because the benchmarked
/// entries include Anthropic/OpenAI flagships (the `"frontier"` catalog tag).
/// The hazard when the catalog grows: a benchmark carried ONLY by mid-tier
/// models self-anchors low — the best of those weak models gets pinned to CEIL,
/// inflating it to "best-in-class" on a benchmark whose true frontier is higher.
///
/// The guard below enforces the invariant rather than trusting it to hold by
/// accident of catalog composition: a benchmark is anchored ONLY if at least one
/// `"frontier"`-tagged model carries it. A benchmark whose entire population is
/// non-frontier gets NO reference (→ uncalibrated clamp path in
/// `normalized_benchmark_quality`), so a mid-tier model can never be inflated to
/// best-in-class on a benchmark whose real frontier is absent from the catalog.
/// The anchor itself is still the catalog max (NOT a percentile — a percentile
/// would push the actual champion above CEIL and clamp away the very ordering
/// signal we want, per review on #371).
static BENCHMARK_FRONTIER_REFS: std::sync::LazyLock<std::collections::HashMap<String, f64>> =
    std::sync::LazyLock::new(|| compute_frontier_refs(crate::registry::builtin_catalog().iter()));

/// Build the per-benchmark frontier-reference table from a model population,
/// applying the #371 frontier-class guard. Factored out of the `LazyLock` so the
/// guard is testable against synthetic fixtures (the static itself is bound to
/// the real catalog). See `BENCHMARK_FRONTIER_REFS`.
fn compute_frontier_refs<'a>(
    models: impl Iterator<Item = &'a ModelSchema>,
) -> std::collections::HashMap<String, f64> {
    // max score per benchmark across ALL carriers, and whether ANY carrier is
    // frontier-class. Tracked separately so the anchor stays the true champion
    // score while the *eligibility* gate is the frontier-class presence.
    let mut max_score: std::collections::HashMap<String, f64> = std::collections::HashMap::new();
    let mut has_frontier_carrier: std::collections::HashMap<String, bool> =
        std::collections::HashMap::new();
    for model in models {
        let frontier = model_is_frontier_class(model);
        for b in &model.public_benchmarks {
            let entry = max_score.entry(b.name.clone()).or_insert(0.0);
            *entry = entry.max(b.score);
            let seen = has_frontier_carrier.entry(b.name.clone()).or_insert(false);
            *seen = *seen || frontier;
        }
    }
    // #371 guard: drop any benchmark with no frontier-class carrier. Its max is
    // NOT a trustworthy frontier, so it must not self-anchor a mid-tier model to
    // CEIL — it falls back to the uncalibrated clamp path instead.
    max_score
        .into_iter()
        .filter(|(name, _)| {
            has_frontier_carrier.get(name).copied().unwrap_or(false) || {
                tracing::warn!(
                    benchmark = %name,
                    "benchmark has no frontier-class carrier in the catalog — \
                     refusing to self-anchor (uncalibrated clamp). Add a \
                     frontier-tagged model that carries it, or an explicit \
                     reference, before it can calibrate the quality tier (#371)."
                );
                false
            }
        })
        .collect()
}

/// A model is *frontier-class* — a trustworthy frontier anchor for any benchmark
/// it carries (#371) — iff the catalog tags it `"frontier"`. The tag is curated
/// catalog data (today: claude-opus-4-7/4-6, gpt-5.4), reviewable in the diff,
/// rather than a name-matching heuristic that would rot as model families turn
/// over.
fn model_is_frontier_class(model: &ModelSchema) -> bool {
    model.tags.iter().any(|t| t == "frontier")
}

impl AdaptiveRouter {
    pub fn new(hw: HardwareInfo, config: RoutingConfig) -> Self {
        let circuit_breakers = Arc::new(Mutex::new(
            CircuitBreakerRegistry::new(3, 300), // 3 failures, 5 min cooldown
        ));
        Self {
            hw,
            config,
            circuit_breakers,
        }
    }

    pub fn with_default_config(hw: HardwareInfo) -> Self {
        Self::new(hw, RoutingConfig::default())
    }

    pub fn config(&self) -> &RoutingConfig {
        &self.config
    }

    pub fn set_config(&mut self, config: RoutingConfig) {
        self.config = config;
    }

    /// Canonical entry point. The seven `route_*` sibling methods
    /// each build a `RouteRequest` with their fixed defaults and
    /// call this — adding a new combinator (per-tenant routing,
    /// streaming awareness, …) only adds a field here, not another
    /// public method. Closes #108.
    pub fn route_with(&self, req: RouteRequest<'_>) -> AdaptiveRoutingDecision {
        // Intent-hint precedence over the caller-supplied workload:
        // `prefer_fast` wins outright (voice fast track is the most
        // latency-sensitive path we have); `prefer_local` is the
        // long-standing override; absent either, the caller's
        // workload stands.
        let workload = Self::resolve_workload(req.intent, req.workload);
        self.route_inner_with_intent(
            req.prompt,
            req.registry,
            req.tracker,
            req.has_tools,
            req.has_vision,
            req.estimated_total_tokens,
            req.estimated_input_tokens,
            req.estimated_output_tokens,
            req.estimated_cache_read_tokens,
            req.estimated_cache_write_tokens,
            workload,
            req.intent,
        )
    }

    /// Route a generation request to the best model.
    /// If `has_tools` is true, requires ToolUse capability (#13).
    pub fn route(
        &self,
        prompt: &str,
        registry: &UnifiedRegistry,
        tracker: &OutcomeTracker,
    ) -> AdaptiveRoutingDecision {
        self.route_with(RouteRequest::new(prompt, registry, tracker))
    }

    /// Route an "editor" request — cheap mechanical work (context compaction,
    /// edit materialization, title generation, replanning). Uses
    /// [`RoutingWorkload::Background`] so cost/quality weights favour cheaper
    /// models, and lets hosting layers express the Aider-style architect/editor
    /// split without plumbing a raw model-name override through every layer.
    pub fn route_editor(
        &self,
        prompt: &str,
        registry: &UnifiedRegistry,
        tracker: &OutcomeTracker,
    ) -> AdaptiveRoutingDecision {
        self.route_with(RouteRequest {
            workload: RoutingWorkload::Background,
            ..RouteRequest::new(prompt, registry, tracker)
        })
    }

    /// Route with tool_use requirement — filters to models that support structured tool calls.
    pub fn route_with_tools(
        &self,
        prompt: &str,
        registry: &UnifiedRegistry,
        tracker: &OutcomeTracker,
    ) -> AdaptiveRoutingDecision {
        self.route_with(RouteRequest {
            has_tools: true,
            ..RouteRequest::new(prompt, registry, tracker)
        })
    }

    /// Route with image input requirement — filters to models that support vision.
    pub fn route_with_vision(
        &self,
        prompt: &str,
        registry: &UnifiedRegistry,
        tracker: &OutcomeTracker,
        has_tools: bool,
    ) -> AdaptiveRoutingDecision {
        self.route_with(RouteRequest {
            has_tools,
            has_vision: true,
            ..RouteRequest::new(prompt, registry, tracker)
        })
    }

    /// Route with caller-supplied intent — see [`crate::IntentHint`].
    /// The hint can override the auto-detected `InferenceTask`, add hard
    /// `require` capability filters on top of the prompt-derived ones,
    /// and bias the score profile toward local models when
    /// `prefer_local` is set.
    pub fn route_with_intent<'a>(
        &self,
        prompt: &'a str,
        registry: &'a UnifiedRegistry,
        tracker: &'a OutcomeTracker,
        intent: &'a crate::intent::IntentHint,
    ) -> AdaptiveRoutingDecision {
        self.route_with(RouteRequest {
            intent: Some(intent),
            ..RouteRequest::new(prompt, registry, tracker)
        })
    }

    /// Route with context awareness — estimates prompt tokens and prefers models
    /// whose context window can fit the full prompt without compaction.
    pub fn route_context_aware(
        &self,
        prompt: &str,
        estimated_total_tokens: usize,
        registry: &UnifiedRegistry,
        tracker: &OutcomeTracker,
        has_tools: bool,
        has_vision: bool,
        workload: RoutingWorkload,
    ) -> AdaptiveRoutingDecision {
        self.route_with(RouteRequest {
            estimated_total_tokens,
            has_tools,
            has_vision,
            workload,
            ..RouteRequest::new(prompt, registry, tracker)
        })
    }

    /// Context-aware routing with caller-supplied intent. Same context
    /// math as [`Self::route_context_aware`]; the intent layers on
    /// top — task override, additional `require` filters,
    /// `prefer_local` workload override.
    pub fn route_context_aware_with_intent<'a>(
        &self,
        prompt: &'a str,
        estimated_total_tokens: usize,
        registry: &'a UnifiedRegistry,
        tracker: &'a OutcomeTracker,
        has_tools: bool,
        has_vision: bool,
        workload: RoutingWorkload,
        intent: &'a crate::intent::IntentHint,
    ) -> AdaptiveRoutingDecision {
        self.route_with(RouteRequest {
            estimated_total_tokens,
            has_tools,
            has_vision,
            workload,
            intent: Some(intent),
            ..RouteRequest::new(prompt, registry, tracker)
        })
    }

    fn route_inner_with_intent(
        &self,
        prompt: &str,
        registry: &UnifiedRegistry,
        tracker: &OutcomeTracker,
        has_tools: bool,
        has_vision: bool,
        estimated_total_tokens: usize,
        estimated_input_tokens: usize,
        estimated_output_tokens: usize,
        estimated_cache_read_tokens: usize,
        estimated_cache_write_tokens: usize,
        workload: RoutingWorkload,
        intent: Option<&crate::intent::IntentHint>,
    ) -> AdaptiveRoutingDecision {
        let complexity = TaskComplexity::assess(prompt);
        // Caller intent overrides the prompt-derived task when supplied.
        let task = intent
            .and_then(|h| h.task)
            .map(task_hint_to_inference_task)
            .unwrap_or_else(|| complexity.inference_task());
        let mut required_caps = complexity.required_capabilities();
        // The caller's explicit `task` intent must steer the hard capability
        // filter, not just the prompt-derived complexity. Without this, a
        // `task=code` request whose prompt happens to read as "simple" is
        // filtered to Generate-only models, dropping every code-capable model
        // in Phase 1 — before prefer_quality scoring can rescue them (the
        // regression car#52 was meant to close). Union the resolved task's
        // required capability in. No-op when intent task and complexity agree.
        let task_cap = inference_task_required_capability(task);
        if !required_caps.contains(&task_cap) {
            required_caps.push(task_cap);
        }
        if let Some(hint) = intent {
            for cap in &hint.require {
                if !required_caps.contains(cap) {
                    required_caps.push(*cap);
                }
            }
        }
        if has_vision {
            required_caps.push(ModelCapability::Vision);
        }
        if has_tools {
            required_caps.push(ModelCapability::ToolUse);
            // Detect multi-step prompts that need multiple tool calls in one response.
            // Patterns: numbered lists ("1) ... 2) ..."), multiple instructions, explicit multi-edit.
            if Self::needs_multi_tool_call(prompt) {
                required_caps.push(ModelCapability::MultiToolCall);
            }
        }

        // Adversarial-reviewer separation (car#358): the set of model ids to
        // keep OFF the adaptive pick. Each excluded id is unioned with its
        // MLX-equivalent twin so excluding the GGUF id a user sees in
        // `models.list` also excludes the MLX model it is actually executed
        // as (and vice-versa is already covered, since a GGUF candidate is
        // substituted *to* the MLX id before the filter below). Applied to
        // both the main scoring path and the cold-start fallbacks.
        let exclude_set = self.build_exclude_set(intent, registry);
        let strict_exclusions = intent.is_some_and(|hint| hint.strict_exclusions);
        let availability = AvailabilitySnapshot::capture(registry);

        // Phase 1: Filter candidates. When the caller is on a deadline
        // (`require_ready`), first try models that need no download; if that
        // empties the set, fall back to the unconstrained filter rather than
        // failing — a slow answer beats no answer (car#638).
        let want_ready = intent.is_some_and(|h| h.require_ready);
        let mut candidates = self.filter_candidates(
            &required_caps,
            registry,
            tracker,
            has_vision,
            availability,
            want_ready,
        );
        if candidates.is_empty() && want_ready {
            candidates = self.filter_candidates(
                &required_caps,
                registry,
                tracker,
                has_vision,
                availability,
                false,
            );
        }

        // Fallback: if requiring MultiToolCall eliminates all candidates, drop the
        // requirement and let the best ToolUse model handle it with multiple round-trips.
        if candidates.is_empty() && required_caps.contains(&ModelCapability::MultiToolCall) {
            required_caps.retain(|c| *c != ModelCapability::MultiToolCall);
            candidates = self.filter_candidates(
                &required_caps,
                registry,
                tracker,
                has_vision,
                availability,
                want_ready,
            );
            if candidates.is_empty() && want_ready {
                candidates = self.filter_candidates(
                    &required_caps,
                    registry,
                    tracker,
                    has_vision,
                    availability,
                    false,
                );
            }
        }

        if candidates.is_empty() {
            // Nothing passed the hard filter — defer to the schema-based
            // decision, carrying the FULL required-cap set so it can't name a
            // capability-lacking default.
            return self.cold_start_decision(
                complexity,
                task,
                &required_caps,
                registry,
                has_vision,
                &exclude_set,
                strict_exclusions,
                availability,
            );
        }

        // Apple Silicon convergence (#333): a local GGUF candidate that has an
        // MLX equivalent is actually EXECUTED as that MLX model (the engine's
        // resolve_mlx_equivalent redirect fires in the execution loop), and —
        // since the alias-canonicalization fix — outcome feedback is booked
        // against the MLX id too. Substitute the equivalent into the candidate
        // set HERE, before scoring/breaker-gating/Thompson reads, so the router
        // proposes, gates, and learns the SAME canonical id it will run. Without
        // this the router scores the GGUF id's perpetually-empty profile while
        // feedback lands on the MLX id, treating a proven model as forever
        // underexplored. Dedup by id (two GGUF candidates can map to one MLX
        // equivalent, or the MLX model may already be a direct candidate);
        // order is preserved so downstream tie-breaks are unchanged.
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        {
            let mut seen = std::collections::HashSet::new();
            candidates = candidates
                .into_iter()
                .map(|m| registry.resolve_mlx_equivalent(&m).cloned().unwrap_or(m))
                .filter(|m| seen.insert(m.id.clone()))
                .collect();
        }

        // Adversarial-reviewer separation (car#358): drop caller-excluded
        // model ids so a reviewer is never the model that produced the work.
        // Applied AFTER the MLX-equivalent substitution above, and the
        // exclude set already carries both id forms, so it matches whichever
        // canonical id a candidate now wears. Soft by default: if excluding
        // empties the set, keep the full set — a same-model review beats no
        // review. Callers enforcing a separation boundary opt into a refusal
        // instead with `strict_exclusions`.
        if !exclude_set.is_empty() {
            let filtered: Vec<ModelSchema> = candidates
                .iter()
                .filter(|m| !exclude_set.contains(&m.id))
                .cloned()
                .collect();
            if filtered.is_empty() {
                if strict_exclusions {
                    return Self::no_eligible_model_decision(complexity, task, exclude_set.len());
                }
                tracing::debug!(
                    ?exclude_set,
                    "model exclusion left no candidates; keeping full set"
                );
            } else {
                candidates = filtered;
            }
        }

        candidates = self.apply_quality_first_bootstrap_policy(
            candidates, task, tracker, has_vision, has_tools, workload,
        );

        // Context-aware filtering: if we know the prompt size, prefer models that fit.
        // Phase 1b: separate candidates into "fits" and "needs compaction" groups.
        let (fits, needs_compaction_candidates) = if estimated_total_tokens > 0 {
            let mut fits = Vec::new();
            let mut tight = Vec::new();
            for m in &candidates {
                if m.context_length == 0 || m.context_length >= estimated_total_tokens {
                    fits.push(m.clone());
                } else {
                    tight.push(m.clone());
                }
            }
            (fits, tight)
        } else {
            (candidates.clone(), Vec::new())
        };

        // Prefer models that fit; fall back to compaction-required models if none fit
        let (scoring_candidates, compaction_needed) = if !fits.is_empty() {
            (fits, false)
        } else if !needs_compaction_candidates.is_empty() {
            tracing::info!(
                prompt_tokens = estimated_total_tokens,
                candidates = needs_compaction_candidates.len(),
                "no model fits full prompt — compaction will be needed"
            );
            (needs_compaction_candidates.clone(), true)
        } else {
            (candidates.clone(), false)
        };

        // (Outcome-first banding is applied at SELECTION below — not as a
        // pre-filter — so every candidate is still scored and remains available
        // as a fallback. A worse model beats no model if the primary errors.)

        // Phase 2: Score candidates (with context headroom bonus)
        let pricing_input_tokens = estimated_input_tokens
            .max(estimated_total_tokens.saturating_sub(estimated_output_tokens));
        let scored = self.score_candidates_context_aware(
            &scoring_candidates,
            task,
            tracker,
            estimated_total_tokens,
            pricing_input_tokens,
            estimated_output_tokens,
            estimated_cache_read_tokens,
            estimated_cache_write_tokens,
            workload,
        );
        // Routing forensics — `RUST_LOG=car_inference::adaptive_router=debug`
        // shows the workload, candidate set, and scores. The live agent-build
        // shakedown used this to confirm prefer_quality picks the best FITTING
        // model (capable models can be filtered out by the memory budget on a
        // small machine — that's a hardware ceiling, not a routing bug).
        tracing::debug!(
            ?workload,
            ?task,
            candidates = ?scoring_candidates.iter().map(|m| m.id.as_str()).collect::<Vec<_>>(),
            ?scored,
            "route scoring"
        );

        // Reliability band (neo design): the SELECTED model must come from the
        // band — the models within OUTCOME_FIRST_BAND of the best reliability —
        // so cost/latency/bonuses break ties WITHIN the band but can never flip
        // a real quality gap. All candidates were still scored above and stay in
        // the fallback chain. The `Quality` lane bands too (its argmax then runs
        // over the blended score WITHIN the band); explicit Fastest/Background/
        // LocalPreferred lanes skip it (subsumption: honor the caller's
        // cost/latency/local preference). See `applies_reliability_band`.
        // band_ids: the reliability band (None when the band doesn't apply).
        // Computed once and reused for BOTH selection and fallback ordering.
        let band_ids: Option<std::collections::HashSet<String>> =
            if Self::applies_reliability_band(task, workload) {
                Some(
                    self.outcome_first_band(scoring_candidates.clone(), task, tracker)
                        .into_iter()
                        .map(|m| m.id)
                        .collect(),
                )
            } else {
                None
            };
        if let Some(ref ids) = band_ids {
            // Observability (neo): the band confidently enforces whatever
            // reliability() says, so make its decision visible — a stale/miskeyed
            // prior shows up as a surprising band here rather than silently
            // shaping every route.
            tracing::debug!(
                ?task,
                band = Self::OUTCOME_FIRST_BAND,
                band_size = ids.len(),
                "outcome-first: selection restricted to reliability band"
            );
        }
        let selection_pool: Vec<(String, f64)> = if let Some(ref ids) = band_ids {
            let pool: Vec<(String, f64)> = scored
                .iter()
                .filter(|(id, _)| ids.contains(id))
                .cloned()
                .collect();
            if pool.is_empty() {
                // Structurally unreachable: the band is computed from
                // `scoring_candidates` and `scored` maps the same slice, so a
                // banded id is always present. If it ever isn't, the Quality
                // lane would argmax over the FULL set and the bonus-floating bug
                // returns — make that invariant load-bearing, not incidental.
                debug_assert!(
                    false,
                    "reliability band produced no in-`scored` ids (workload {workload:?})"
                );
                scored.clone()
            } else {
                pool
            }
        } else {
            scored.clone()
        };

        // Phase 3: selection. Quality-critical requests (prefer_quality) take
        // the highest-scored candidate DETERMINISTICALLY — no Thompson
        // exploration. Exploration trades the best model now for learning
        // signal later, which is exactly wrong for an infrequent, one-shot,
        // correctness-critical call (building/verifying an agent, deriving a
        // contract): a weak model loses the work, and there's no stream of
        // repeats for the learning to pay back. Crucially the argmax runs over
        // `selection_pool`, which the Quality lane HAS restricted to the
        // reliability band above — so the deterministic pick is the best
        // blended score AMONG the top-reliability models, not a low-quality
        // model that floated up on local/MLX bonuses. Every other workload keeps
        // Thompson sampling (within the band when one applies).
        let (selected_id, strategy) = if workload == RoutingWorkload::Quality {
            selection_pool
                .iter()
                .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal))
                .map(|(id, _)| (id.clone(), RoutingStrategy::SchemaBased))
                .unwrap_or_else(|| self.select_with_thompson_sampling(&selection_pool, tracker))
        } else {
            self.select_with_thompson_sampling(&selection_pool, tracker)
        };

        // Build fallback chain. Under outcome-first, in-band (high-reliability)
        // models come BEFORE out-of-band ones, so a retry after a primary
        // failure still prefers a quality-acceptable model over a cheaper-but-
        // worse one — the band must hold for positions 1..n, not just the
        // primary (neo). Blended-score order (from `scored`) is preserved within
        // each group; `partition` is stable.
        let mut fallbacks: Vec<String> = if let Some(ref ids) = band_ids {
            let (in_band, out_band): (Vec<String>, Vec<String>) = scored
                .iter()
                .filter(|(id, _)| *id != selected_id)
                .map(|(id, _)| id.clone())
                .partition(|id| ids.contains(id));
            in_band.into_iter().chain(out_band).collect()
        } else {
            scored
                .iter()
                .filter(|(id, _)| *id != selected_id)
                .map(|(id, _)| id.clone())
                .collect()
        };
        // Add compaction candidates to the end of the fallback chain
        if !compaction_needed {
            for m in &needs_compaction_candidates {
                if m.id != selected_id && !fallbacks.contains(&m.id) {
                    fallbacks.push(m.id.clone());
                }
            }
        }

        let predicted_quality = scored
            .iter()
            .find(|(id, _)| *id == selected_id)
            .map(|(_, score)| *score)
            .unwrap_or(0.5);

        let selected_schema = registry
            .get(&selected_id)
            .or_else(|| registry.find_by_name(&selected_id));
        let model_name = selected_schema
            .map(|m| m.name.clone())
            .unwrap_or_else(|| selected_id.clone());
        let context_length = selected_schema.map(|m| m.context_length).unwrap_or(0);

        let needs_compact = compaction_needed
            || (estimated_total_tokens > 0
                && context_length > 0
                && estimated_total_tokens > context_length);

        let compaction_note = if needs_compact {
            format!(
                " [compaction needed: {}→{}tok]",
                estimated_total_tokens, context_length
            )
        } else {
            String::new()
        };

        let cost_quality_note = selected_schema
            .map(|schema| {
                let is_openrouter = schema.tags.iter().any(|tag| tag == "openrouter");
                if is_openrouter && schema.tags.iter().any(|tag| tag == "cheap") {
                    let prices = schema.cost.prices_for(pricing_input_tokens);
                    format!(
                        ", low-cost tier (${:.3}/MTok input, ${:.3}/MTok output at {} prompt tokens)",
                        prices.input_per_mtok.unwrap_or(0.0),
                        prices.output_per_mtok.unwrap_or(0.0),
                        pricing_input_tokens,
                    )
                } else if is_openrouter && model_is_frontier_class(schema) {
                    ", frontier quality tier".to_string()
                } else {
                    String::new()
                }
            })
            .unwrap_or_default();

        let reason = format!(
            "{:?} task → {} via {:?} (quality: {:.2}, {} candidates{}){}",
            complexity,
            model_name,
            strategy,
            predicted_quality,
            scoring_candidates.len(),
            cost_quality_note,
            compaction_note,
        );

        // Advisory candidate ranking (Task 7): expose the full scored set so a
        // caller can see the tradeoff the router resolved on their behalf —
        // which models were eligible (in_band), their quality-only reliability,
        // their blended score, and which one won. `scored` is already in
        // descending blended-score order. When not outcome-first (band_ids is
        // None) every candidate is eligible, so in_band = true.
        let candidates: Vec<RouteCandidate> = scored
            .iter()
            .map(|(id, score)| {
                // Every id in `scored` came out of `scoring_candidates`
                // (`score_candidates_context_aware` maps over that same slice),
                // so this lookup is structurally unreachable-to-miss; 0.0 is an
                // unreachable floor, not a value the router can legitimately
                // emit. The debug_assert is the canary if those two ever diverge.
                let reliability = match scoring_candidates.iter().find(|m| m.id == *id) {
                    Some(m) => self.reliability(m, task, tracker),
                    None => {
                        debug_assert!(false, "scored id {id} absent from scoring_candidates");
                        0.0
                    }
                };
                RouteCandidate {
                    model_id: id.clone(),
                    reliability,
                    score: *score,
                    selected: *id == selected_id,
                    in_band: band_ids.as_ref().is_none_or(|b| b.contains(id)),
                }
            })
            .collect();

        AdaptiveRoutingDecision {
            model_id: selected_id,
            model_name,
            task,
            complexity,
            reason,
            strategy,
            predicted_quality,
            fallbacks,
            context_length,
            needs_compaction: needs_compact,
            candidates,
        }
    }

    /// Route to the best embedding model.
    pub fn route_embedding(&self, registry: &UnifiedRegistry) -> String {
        let embed_models = registry.query_by_capability(ModelCapability::Embed);
        embed_models
            .first()
            .map(|m| m.name.clone())
            .unwrap_or_else(|| "Qwen3-Embedding-0.6B".to_string())
    }

    /// Route to the smallest available model (for classification).
    pub fn route_small(&self, registry: &UnifiedRegistry) -> String {
        let gen_models = registry.query_by_capability(ModelCapability::Generate);
        // Pick smallest by size
        gen_models
            .iter()
            .filter(|m| m.is_local())
            .min_by_key(|m| m.size_mb())
            .map(|m| m.name.clone())
            .unwrap_or_else(|| "Qwen3-0.6B".to_string())
    }

    // --- Internal phases ---

    // --- Scoring constants ---

    /// Latency ceiling: requests taking longer than this score 0.0.
    const LATENCY_CEILING_MS: f64 = 10000.0;
    /// TPS ceiling: models faster than this score 1.0.
    const _TPS_CEILING: f64 = 150.0;
    /// MoE throughput penalty for Candle: naive expert routing runs at ~10% of
    /// declared TPS. Applies to *declared* (hand-seeded) rates only — see
    /// `schema_latency_estimate`.
    const MOE_TPS_MULTIPLIER: f64 = 0.10;
    /// MoE throughput multiplier for MLX: fused Metal kernels run at ~50% of
    /// declared TPS. Same caveat as [`Self::MOE_TPS_MULTIPLIER`].
    const MLX_MOE_TPS_MULTIPLIER: f64 = 0.50;
    /// Cost ceiling: models costing more than this per 1K output tokens score 0.0.
    const COST_CEILING_PER_1K: f64 = 0.1;
    /// Local preference bonus added to the weighted score (before normalization).
    const LOCAL_BONUS: f64 = 0.15;
    /// True on platforms where local inference has a GPU/NPU backend
    /// (Apple Silicon with MLX). On Intel Macs and on hosts built with
    /// `--cfg=car_skip_mlx`, local inference falls through to candle/
    /// CPU which is far slower than cloud for non-trivial models. The
    /// router suppresses LOCAL_BONUS when this is false so cloud
    /// models rank fairly instead of losing to a CPU-bound 4B that
    /// will take 30s to first-token.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    const HAS_GPU_BACKEND: bool = true;
    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    const HAS_GPU_BACKEND: bool = false;
    /// Extra bonus for MLX models on Apple Silicon (stacks with LOCAL_BONUS).
    /// MLX gets fused Metal kernels and better memory layout vs Candle on Mac.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    const MLX_BONUS: f64 = 0.10;
    /// Extra bonus for system-owned models — no model file on disk, no
    /// download to provision, framework-managed memory. Currently only
    /// `apple/foundation:default` qualifies. Tag-driven so future
    /// system-LLM integrations (e.g. Android AICore) inherit the
    /// scoring without a code change. Stacks with LOCAL_BONUS but
    /// **excludes** MLX_BONUS (system models aren't MLX); the net
    /// effect is FoundationModels ranks roughly even with a
    /// well-warmed MLX 4B for short fast-turn tasks instead of
    /// strictly losing because its catalog `tokens_per_second` /
    /// `size_mb` are null.
    const SYSTEM_LLM_BONUS: f64 = 0.12;

    // --- Internal phases ---

    /// Phase 1: Filter by hard constraints.
    /// Build the set of model ids to exclude from the adaptive pick from a
    /// caller's `IntentHint::exclude_models` (car#358). Each id is unioned
    /// with its MLX-equivalent twin (on Apple Silicon) so excluding the
    /// GGUF id a user holds also excludes the MLX model it is executed as.
    ///
    /// Each entry is resolved through the registry by id *or* by name, and the
    /// canonical `ModelSchema.id` is added alongside the caller's string. The
    /// filter downstream compares `ModelSchema.id`, so without this an entry
    /// naming a model the way `InferenceResult::model_used` reports it —
    /// `schema.name` — matched nothing and the exclusion was a silent no-op.
    /// That is not a hypothetical: `model_used` is the only identifier a caller
    /// holding a result *has*, and for every personal-OpenRouter model the two
    /// differ (`id = openrouter/google/gemini-3.1-pro-preview`, `name =
    /// google/gemini-3.1-pro-preview`) — which is exactly the fallback lane
    /// coder contract derivation must be able to rotate away from (car#889).
    pub(crate) fn build_exclude_set(
        &self,
        intent: Option<&crate::intent::IntentHint>,
        registry: &UnifiedRegistry,
    ) -> std::collections::HashSet<String> {
        let mut set = std::collections::HashSet::new();
        let Some(hint) = intent else {
            return set;
        };
        for id in &hint.exclude_models {
            set.insert(id.clone());
            let Some(schema) = registry.get(id).or_else(|| registry.find_by_name(id)) else {
                continue;
            };
            set.insert(schema.id.clone());
            #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
            {
                if let Some(mlx) = registry.resolve_mlx_equivalent(schema) {
                    set.insert(mlx.id.clone());
                }
            }
        }
        set
    }

    fn filter_candidates(
        &self,
        required_caps: &[ModelCapability],
        registry: &UnifiedRegistry,
        tracker: &OutcomeTracker,
        has_vision: bool,
        availability: AvailabilitySnapshot,
        require_ready: bool,
    ) -> Vec<ModelSchema> {
        registry
            .list()
            .into_iter()
            .filter(|m| {
                // Must have all required capabilities
                if !required_caps.iter().all(|c| m.has_capability(*c)) {
                    return false;
                }
                // Hard exclusion (car-releases#50): `mlx-vlm-cli`
                // models route exclusively through the mlx-vlm CLI
                // for image inference and the backend hard-rejects
                // text-only input ("text-only-on-mlx-vlm-id not
                // implemented"). They advertise `generate`, so a
                // text-only request (e.g. task=classify) would
                // otherwise pass the capability filter and get
                // dispatched, only to fail at the backend. A
                // text-only request must never select one.
                if !has_vision && m.tags.iter().any(|t| t == "mlx-vlm-cli") {
                    return false;
                }
                // Must be available (downloaded for local, API key set for remote)
                if !availability.is_available(m) {
                    return false;
                }
                // Caller is on a deadline and asked for models that need no
                // download first (car#638). `available` doesn't answer that for
                // MLX — a declared hf_repo makes it true before anything is
                // fetched — so gate on the narrower `weights_ready`. Soft: the
                // caller re-runs without the constraint if this empties the set
                // (see `filter_ready_soft` at the call site).
                if require_ready && !m.weights_ready {
                    return false;
                }
                // Local models must fit in memory (strict: >= excludes models at the limit)
                if m.is_local() && m.size_mb() >= self.hw.max_model_mb {
                    return false;
                }
                // Hard latency constraint
                if let Some(max) = self.config.max_latency_ms {
                    if let Some(p50) = m.performance.latency_p50_ms {
                        if p50 > max {
                            return false;
                        }
                    }
                }
                // Hard cost constraint
                if let Some(max) = self.config.max_cost_usd {
                    if m.cost_per_1k_output() > max {
                        return false;
                    }
                }
                // Hard exclusion: prefer_local=false excludes all local models (#12)
                if !self.config.prefer_local && m.is_local() {
                    return false;
                }
                // Hard exclusion: rate-limited models excluded for this session (#13)
                if tracker.is_excluded(&m.id) {
                    return false;
                }
                // Circuit breaker: skip models with consecutive failures (#25)
                if let Ok(mut cb) = self.circuit_breakers.lock() {
                    if !cb.allow_request(&m.id) {
                        tracing::debug!(model = %m.id, "skipped by circuit breaker");
                        return false;
                    }
                }
                true
            })
            .cloned()
            .collect()
    }

    fn apply_quality_first_bootstrap_policy(
        &self,
        candidates: Vec<ModelSchema>,
        task: InferenceTask,
        tracker: &OutcomeTracker,
        has_vision: bool,
        has_tools: bool,
        workload: RoutingWorkload,
    ) -> Vec<ModelSchema> {
        if !self.config.quality_first_cold_start
            || !workload.is_latency_sensitive()
            || !self.is_quality_critical_bootstrap_task(task, has_vision, has_tools)
        {
            return candidates;
        }

        let trusted_remote: Vec<ModelSchema> = candidates
            .iter()
            .filter(|model| self.is_trusted_quality_remote(model))
            .cloned()
            .collect();

        if trusted_remote.is_empty() {
            return candidates;
        }

        let proven_local: Vec<ModelSchema> = candidates
            .iter()
            .filter(|model| {
                model.is_local() && self.is_local_model_proven_for_task(model, task, tracker)
            })
            .cloned()
            .collect();

        if !proven_local.is_empty() {
            return proven_local;
        }

        trusted_remote
    }

    /// Phase 2: Score candidates with context awareness.
    /// Applies a headroom bonus to models with more context window for the prompt.
    /// When estimated_total_tokens is 0, no context bonus/penalty is applied.
    fn score_candidates_context_aware(
        &self,
        candidates: &[ModelSchema],
        task: InferenceTask,
        tracker: &OutcomeTracker,
        estimated_total_tokens: usize,
        estimated_input_tokens: usize,
        estimated_output_tokens: usize,
        estimated_cache_read_tokens: usize,
        estimated_cache_write_tokens: usize,
        workload: RoutingWorkload,
    ) -> Vec<(String, f64)> {
        let mut scored: Vec<(String, f64)> = candidates
            .iter()
            .map(|m| {
                let base_score = self.score_model(
                    m,
                    task,
                    tracker,
                    workload,
                    estimated_input_tokens,
                    estimated_output_tokens,
                    estimated_cache_read_tokens,
                    estimated_cache_write_tokens,
                );
                // Context headroom bonus: prefer models with more room to spare.
                // Max bonus: 0.10 (at 4x headroom or more). No bonus if unknown.
                let headroom_bonus = if estimated_total_tokens > 0 && m.context_length > 0 {
                    let ratio = m.context_length as f64 / estimated_total_tokens as f64;
                    if ratio >= 1.0 {
                        (ratio.min(4.0) - 1.0) / 3.0 * 0.10 // 0.0 at exact fit, 0.10 at 4x
                    } else {
                        -0.15 // Penalty for models that require compaction
                    }
                } else {
                    0.0
                };
                (m.id.clone(), base_score + headroom_bonus)
            })
            .collect();

        scored.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
        scored
    }

    /// Score a single model. All sub-scores are in [0.0, 1.0].
    /// Final score = weighted sum + local_bonus, so range is [0.0, ~1.15].
    /// Scoring weights `(quality, latency, cost)`, adjusted for the task.
    ///
    /// [`RoutingWorkload::weights`] is workload-shaped only — it has no
    /// notion that the request is code generation. The default
    /// interactive profile is `(0.45 quality, 0.40 latency, 0.15 cost)`,
    /// where quality barely edges out latency, so a fast cheap general
    /// model can out-score a code-tuned one on a `task=code` request
    /// (car-releases#52). Code correctness is worth waiting a beat for:
    /// under an interactive-class workload `task=code` is reweighted to
    /// prioritise quality > speed > cost explicitly. `Fastest` (the
    /// voice fast-track) is an explicit hard-latency demand and is left
    /// untouched; `Batch`/`Background` already encode a deliberate
    /// non-interactive caller choice and stay as-is.
    fn task_aware_weights(task: InferenceTask, workload: RoutingWorkload) -> (f64, f64, f64) {
        match (task, workload) {
            (
                InferenceTask::Code,
                RoutingWorkload::Interactive | RoutingWorkload::LocalPreferred,
            ) => (0.62, 0.28, 0.10),
            _ => workload.weights(),
        }
    }

    /// Pure reliability estimate for a model on a task — the quality signal
    /// ALONE (observed task EMA blended with the cold-start schema prior), with
    /// no cost, latency, or platform bonuses. This is the band key for
    /// outcome-first routing: cost may only break ties WITHIN a reliability
    /// band, never form it (neo's design — banding on the blended score would
    /// mean you never stopped blending).
    fn reliability(
        &self,
        model: &ModelSchema,
        task: InferenceTask,
        tracker: &OutcomeTracker,
    ) -> f64 {
        let schema_quality = self.schema_quality_estimate(model);
        let Some(p) = tracker.profile(&model.id) else {
            // No profile at all — sit at the schema estimate.
            return schema_quality;
        };

        // Read the quality EMA together with the two evidence sources behind
        // it, from the SAME stats unit (task-specific if present, else overall)
        // — never pair a task-level score with an overall count.
        //   - `n`: benchmark cases that seeded the EMA (cold-start prior).
        //   - `g`: *graded* live observations that have moved the EMA — accept/
        //     edit/reject signals and failures, NOT mechanical successes (those
        //     leave answer quality unknown, so they don't inform reliability).
        let (ema, n, g) = p
            .task_stats(task)
            .map(|ts| {
                (
                    ts.ema_quality,
                    ts.prior_sample_size,
                    ts.quality_observations,
                )
            })
            .unwrap_or((p.ema_quality, p.prior_sample_size, p.quality_observations));

        // A single Bayesian shrinkage of the EMA toward the schema estimate,
        // weighted by the total quality evidence behind it. Evidence pools two
        // sources at DIFFERENT unit weights:
        //
        //     e = n + W*g
        //     reliability = schema + e/(e+K) * (ema - schema)
        //
        // `schema_quality_estimate` is the prior mean (catalog `public_benchmarks`
        // when present, else a size/trust heuristic). Keying the weight on
        // graded evidence — not `total_calls` — is the load-bearing choice:
        //   - A model with many *ungraded* successes has g == 0, so (with n == 0)
        //     its EMA carries no weight and reliability sits at the schema
        //     estimate. This stops a frontier model whose production traffic is
        //     never graded from collapsing to a hollow 0.5 and being buried
        //     under smaller models.
        //   - A sparse cold-start benchmark (small n, g == 0) barely moves off
        //     schema — the 0.6B-shadowing fix. The cold-start path is identical
        //     whatever W is, since g == 0 there.
        //   - A live grade counts as `W` benchmark cases (W > 1): on-distribution
        //     production signal earns and revokes trust faster than a
        //     distribution-shifted offline case, so an intermittently-failing
        //     model — below the circuit breaker's *consecutive*-failure
        //     threshold — is still distrusted at live speed.
        // n == g == 0 ⇒ reliability == schema exactly, so a healthy model is
        // never demoted toward neutral.
        let evidence = n as f64 + Self::LIVE_GRADE_WEIGHT * g as f64;
        let confidence = evidence / (evidence + Self::PRIOR_SHRINK_PSEUDOCOUNT);
        (schema_quality + confidence * (ema - schema_quality)).clamp(0.0, 1.0)
    }

    /// Quality-tier band that normalized published benchmarks map into. A hard
    /// agentic benchmark's raw score (e.g. tau-bench-airline ~0.65 for a
    /// frontier model) is remapped `[0, frontier_ref] → [FLOOR, CEIL]` so the
    /// measured cluster lands on the same scale as — and the frontier above —
    /// the size/trust heuristics. FLOOR is the bottom of the measured band;
    /// local size-heuristics are capped below it, so a benchmarked frontier
    /// model always wins the quality term over an unmeasured local.
    const BENCH_TIER_FLOOR: f64 = 0.40;
    const BENCH_TIER_CEIL: f64 = 0.92;

    /// Quality-tier band for an *uncalibrated* (frontier-less) benchmark carried
    /// by a LOCAL model — a self-measured score on a suite no frontier model
    /// anchors (e.g. `car-bench-run`'s agentic suite, #368). Such a score is NOT
    /// commensurable with a frontier-calibrated score (the monoculture trap: 0.5
    /// on an easy local suite ≠ 0.5 on tau-bench-airline), so it must NOT land in
    /// the measured-frontier band `[BENCH_TIER_FLOOR, BENCH_TIER_CEIL]`. Instead
    /// it maps into this LOCAL sub-band, deliberately aligned with the local
    /// size-heuristic span (`schema_quality_estimate`: 0.6B→0.30 … 30B→0.60) so
    /// measured capability *replaces the size proxy* for ordering locals against
    /// each other, while the "a benchmarked frontier model out-ranks any local on
    /// the quality term" invariant (`local_size_heuristic_stays_below_measured_frontier_floor`)
    /// is preserved. A frontier-anchored (calibrated) benchmark a local happens
    /// to carry still maps to the full band — the anchor makes it comparable.
    const LOCAL_BENCH_TIER_FLOOR: f64 = 0.30;
    const LOCAL_BENCH_TIER_CEIL: f64 = 0.60;

    /// Cold-start quality for an unmeasured remote (no `public_benchmarks`).
    /// Conservative-unknown: below the measured-frontier band, above small
    /// locals. Curated (configured/signed) sits above Community (auto-discovered,
    /// unvetted).
    const UNMEASURED_REMOTE_CURATED: f64 = 0.60;
    const UNMEASURED_REMOTE_COMMUNITY: f64 = 0.48;
    /// A reviewed `frontier` tag is a coarse quality-class claim, not a
    /// benchmark score. It gives newly-curated frontier models a useful prior
    /// while remaining below the measured frontier ceiling (0.92); live graded
    /// outcomes can still move it in either direction.
    const CURATED_FRONTIER_TAG_PRIOR: f64 = 0.85;
    const CURATED_BALANCED_TAG_PRIOR: f64 = 0.72;

    /// Evidence weight of one live graded outcome relative to one offline
    /// benchmark case, in the `e = n + W*g` pool. Live grades are sparse but
    /// on-distribution ground truth about *this* deployment; benchmark cases
    /// are plentiful but distribution-shifted. Weighting live signal higher
    /// restores failure responsiveness — an intermittently-failing model, below
    /// the circuit breaker's consecutive-failure threshold, is distrusted at
    /// live speed — without disturbing the cold-start path, where `g == 0`
    /// makes the weight irrelevant. Deliberate, revisitable asymmetry; 2.0 is a
    /// conservative default (a live grade ≈ two benchmark cases). Not tuned
    /// against production data — a follow-up may calibrate `W` and `K` jointly.
    const LIVE_GRADE_WEIGHT: f64 = 2.0;

    /// Pseudo-observations of the schema prior mean blended into a model's
    /// quality EMA before it is trusted. The EMA is weighted `e / (e + K)`
    /// against the schema estimate, where `e = n + g` is the total quality
    /// evidence behind it (`n` benchmark cases + `g` graded live observations):
    /// one unit barely moves reliability off the schema prior, ~20 land near
    /// the raw EMA. K = 4 ≈ "trust the EMA once ~4+ units of evidence back it";
    /// small enough that a genuinely dense signal dominates, large enough that
    /// a 1–2 observation run can't pin an extreme. Mirrors the Beta-prior
    /// strength the Thompson layer already uses, applied one level up.
    const PRIOR_SHRINK_PSEUDOCOUNT: f64 = 4.0;

    /// Quality-band width for outcome-first routing (absolute reliability).
    /// Narrow on purpose: only models within this reliability of the best are
    /// eligible, so a real quality gap can never be flipped by a cheaper/faster
    /// model. ~0.02 keeps the benchmarked/frontier clusters distinct while
    /// letting genuinely near-equal models compete on cost/latency.
    ///
    /// COUPLING WARNING: the `Quality` lane consumes this band with NO Thompson
    /// exploration (deterministic argmax) — its in-band tie-break is purely the
    /// blended score, where local/MLX bonuses (~0.25) dominate the ~0.02
    /// reliability spread. On the normal lanes the band also bounds exploration
    /// breadth, so it's tempting to widen it for learning behavior — but
    /// widening it would silently enlarge the Quality lane's bonus-flippable
    /// zone, letting a meaningfully-worse-but-bonused model win the high-stakes
    /// lane. Do not widen this casually for normal-lane tuning; split the
    /// constant per-lane first if Quality ever needs a different width.
    const OUTCOME_FIRST_BAND: f64 = 0.02;

    /// Resolve the effective routing workload from the caller's intent, falling
    /// back to the request's base workload. Precedence: `high_stakes` (a
    /// consequential/irreversible operation — best model regardless of cost or
    /// latency) wins outright, then `prefer_fast`, then `prefer_quality`, then
    /// `prefer_local`.
    fn resolve_workload(
        intent: Option<&crate::intent::IntentHint>,
        base: RoutingWorkload,
    ) -> RoutingWorkload {
        match intent {
            Some(h) if h.high_stakes => RoutingWorkload::Quality,
            Some(h) if h.prefer_fast => RoutingWorkload::Fastest,
            Some(h) if h.prefer_quality => RoutingWorkload::Quality,
            Some(h) if h.prefer_local => RoutingWorkload::LocalPreferred,
            _ => base,
        }
    }

    /// Whether selection is restricted to the reliability band — the models
    /// within `OUTCOME_FIRST_BAND` of the best reliability. Within the band,
    /// cost/latency/bonuses break ties; across it, a real quality gap holds.
    ///
    /// - `Quality` (prefer_quality / high_stakes): ALWAYS bands. The lane's
    ///   deterministic argmax runs over the *blended* score, so without the band
    ///   a lower-quality model could win on additive local/MLX bonuses — exactly
    ///   the "prefer_quality doesn't prefer quality" bug. Banding first makes the
    ///   argmax choose among the top-reliability models only.
    /// - `Fastest` / `Background` / `LocalPreferred`: never band. These are
    ///   explicit cost/latency/local preferences — honor them (subsumption). In
    ///   particular `LocalPreferred` MUST skip the band, or an explicit "prefer
    ///   local" request gets overridden by a benchmarked frontier remote.
    /// - Normal lanes (`Interactive` / `Batch`): band substantive tasks
    ///   (Code/Reasoning), where quality matters most.
    fn applies_reliability_band(task: InferenceTask, workload: RoutingWorkload) -> bool {
        match workload {
            RoutingWorkload::Quality => true,
            RoutingWorkload::Fastest
            | RoutingWorkload::Background
            | RoutingWorkload::LocalPreferred => false,
            _ => matches!(task, InferenceTask::Code | InferenceTask::Reasoning),
        }
    }

    /// Keep only candidates within [`Self::OUTCOME_FIRST_BAND`] reliability of
    /// the best. The best always survives (gap 0), so this never empties the
    /// set. Cost/latency and Thompson exploration then operate downstream only
    /// within the surviving band.
    fn outcome_first_band(
        &self,
        candidates: Vec<ModelSchema>,
        task: InferenceTask,
        tracker: &OutcomeTracker,
    ) -> Vec<ModelSchema> {
        if candidates.len() <= 1 {
            return candidates;
        }
        let best = candidates
            .iter()
            .map(|m| self.reliability(m, task, tracker))
            .fold(f64::MIN, f64::max);
        candidates
            .into_iter()
            // +epsilon so an exact-boundary gap (e.g. 0.70-0.68 = 0.0200000…2 in
            // f64) isn't excluded by floating-point error.
            .filter(|m| {
                best - self.reliability(m, task, tracker) <= Self::OUTCOME_FIRST_BAND + 1e-9
            })
            .collect()
    }

    fn score_model(
        &self,
        model: &ModelSchema,
        task: InferenceTask,
        tracker: &OutcomeTracker,
        workload: RoutingWorkload,
        estimated_input_tokens: usize,
        estimated_output_tokens: usize,
        estimated_cache_read_tokens: usize,
        estimated_cache_write_tokens: usize,
    ) -> f64 {
        let profile = tracker.profile(&model.id);
        let schema_latency = self.schema_latency_estimate(model);
        let (quality_weight, latency_weight, cost_weight) =
            Self::task_aware_weights(task, workload);

        // Quality (reliability) — factored into `reliability()` so the
        // outcome-first band keys on it alone; here it's the quality term of
        // the within-band blend.
        let quality = self.reliability(model, task, tracker);

        // Latency: same blending as quality — don't trust a single observation more
        // than schema estimates. This prevents routing oscillation on first few calls.
        let latency = match profile {
            Some(p) if p.total_calls >= self.config.min_observations => {
                let avg = p
                    .task_stats(task)
                    .filter(|ts| ts.calls > 0 || ts.avg_latency_ms > 0.0)
                    .map(|ts| ts.avg_latency_ms)
                    .unwrap_or_else(|| p.avg_latency_ms());
                self.latency_ms_to_score(avg)
            }
            Some(p) if p.total_calls == 0 => p
                .task_stats(task)
                .filter(|ts| ts.avg_latency_ms > 0.0)
                .map(|ts| self.latency_ms_to_score(ts.avg_latency_ms))
                .unwrap_or(schema_latency),
            Some(p) if p.total_calls > 0 => {
                let observed = self.latency_ms_to_score(
                    p.task_stats(task)
                        .filter(|ts| ts.calls > 0 || ts.avg_latency_ms > 0.0)
                        .map(|ts| ts.avg_latency_ms)
                        .unwrap_or_else(|| p.avg_latency_ms()),
                );
                let w = p.total_calls as f64 / self.config.min_observations as f64;
                schema_latency * (1.0 - w) + observed * w
            }
            _ => schema_latency,
        };

        // Cost score (lower is better → invert)
        let cost = if model.is_local() {
            1.0
        } else if model.cost.output_per_mtok.is_none() {
            // Unknown remote pricing (e.g. an auto-discovered Community model
            // whose cost is cleared until curated/learned). Do NOT score it as
            // free — `cost_per_1k_output()` returns 0.0 for unknown cost, which
            // would yield a perfect 1.0 cost score and let an unvetted model
            // out-rank curated ones with known nonzero pricing. Use a neutral
            // mid value until the price is known.
            0.5
        } else {
            let normalized_cost_per_1k = if estimated_input_tokens
                + estimated_output_tokens
                + estimated_cache_read_tokens
                + estimated_cache_write_tokens
                > 0
            {
                let estimated_cost = model.cost.estimated_usd(
                    estimated_input_tokens,
                    estimated_output_tokens,
                    estimated_cache_read_tokens,
                    estimated_cache_write_tokens,
                );
                estimated_cost * 1000.0
                    / (estimated_input_tokens + estimated_output_tokens).max(1) as f64
            } else {
                model.cost_per_1k_output()
            };
            (1.0 - (normalized_cost_per_1k / Self::COST_CEILING_PER_1K)).clamp(0.0, 1.0)
        };

        // Suppress LOCAL_BONUS on hosts without a GPU/NPU backend.
        // Without it, an Intel Mac or a `car_skip_mlx` build would
        // pick a CPU-bound local 4B over a comparable cloud model
        // every time, then surprise the user with 30s+ first-token
        // latency. Cloud loses on cost/privacy in normal scoring;
        // dropping the local bonus lets it win on the latency that
        // actually matters when the GPU isn't there. Tracing emits
        // when this fires so the silent degradation becomes visible.
        //
        // BUT that rationale is purely about latency: it only holds for
        // latency-sensitive workloads. `Background`/`Batch` callers have
        // explicitly accepted a latency hit, so a CPU-bound local model
        // is a fine choice there — and its cost/privacy win should
        // stand. Keeping the bonus for non-latency-sensitive workloads
        // also stops an unmeasured remote (now scored a conservative 0.60,
        // not the old flat 0.5) from out-ranking a proven local on a GPU-less
        // host for background work, which is the wrong call for cheap
        // offline jobs.
        let gpu_backend_or_latency_tolerant =
            Self::HAS_GPU_BACKEND || !workload.is_latency_sensitive();
        let local_bonus = if self.config.prefer_local
            && model.is_local()
            && gpu_backend_or_latency_tolerant
        {
            Self::LOCAL_BONUS
        } else {
            if self.config.prefer_local && model.is_local() && !Self::HAS_GPU_BACKEND {
                tracing::debug!(
                    model = %model.id,
                    "LOCAL_BONUS suppressed: no GPU backend on this host (Intel Mac or car_skip_mlx) for a latency-sensitive workload; cloud models will rank higher"
                );
            }
            0.0
        };
        let workload_local_bonus = if model.is_local() {
            workload.local_bonus()
        } else {
            0.0
        };

        // On Apple Silicon, prefer MLX models over Candle equivalents
        #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
        let mlx_bonus = if model.is_mlx() { Self::MLX_BONUS } else { 0.0 };
        #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
        let mlx_bonus = 0.0;

        // vLLM-MLX bonus: continuous batching gives better multi-agent throughput
        let vllm_mlx_bonus = if model.is_vllm_mlx() {
            Self::LOCAL_BONUS + 0.05
        } else {
            0.0
        };

        // System-LLM bonus: catalog tag-driven so it generalizes beyond
        // FoundationModels. Models tagged `low_latency` AND `private`
        // are zero-cost system-owned LLMs (apple/foundation:default
        // today; AICore-on-Android etc. in the future). They don't
        // appear in `is_mlx()` but deserve to compete with MLX 4B on
        // routing — the catalog's tags carry that intent and the
        // router now honors it.
        let system_llm_bonus = if model.tags.iter().any(|t| t == "low_latency")
            && model.tags.iter().any(|t| t == "private")
        {
            Self::SYSTEM_LLM_BONUS
        } else {
            0.0
        };

        // Under a Quality workload (prefer_quality / high_stakes) the objective
        // is answer quality — not locality or hardware affinity. Every bonus
        // below exists for latency / cost / privacy, exactly what the caller
        // deprioritized by asking for quality. Left in, they stack to +0.25 on
        // Apple Silicon (LOCAL_BONUS 0.15 + MLX_BONUS 0.10) and let a small
        // local MLX model out-*bonus* a more capable remote whose quality lead
        // is under 0.25 — which then OOMs on a large prompt it can't fit.
        // Suppress them here so quality (and the reliability band) decides.
        // Models still compete on quality * quality_weight, so a genuinely
        // better local model still wins; it just no longer gets a free thumb.
        let (local_bonus, workload_local_bonus, mlx_bonus, vllm_mlx_bonus, system_llm_bonus) =
            if workload == RoutingWorkload::Quality {
                (0.0, 0.0, 0.0, 0.0, 0.0)
            } else {
                (
                    local_bonus,
                    workload_local_bonus,
                    mlx_bonus,
                    vllm_mlx_bonus,
                    system_llm_bonus,
                )
            };

        quality_weight * quality
            + latency_weight * latency
            + cost_weight * cost
            + local_bonus
            + workload_local_bonus
            + mlx_bonus
            + vllm_mlx_bonus
            + system_llm_bonus
    }

    /// Convert latency in ms to a [0, 1] score. Used by both schema and observed paths
    /// so the scales are consistent (fixes Linus review issue #2).
    fn latency_ms_to_score(&self, ms: f64) -> f64 {
        (1.0 - (ms / Self::LATENCY_CEILING_MS)).clamp(0.0, 1.0)
    }

    /// Convert TPS to estimated latency in ms (for a typical 200-token response).
    fn tps_to_latency_ms(tps: f64) -> f64 {
        if tps <= 0.0 {
            return Self::LATENCY_CEILING_MS;
        }
        // Assume ~200 tokens per response as baseline
        (200.0 / tps) * 1000.0
    }

    /// Detect whether a prompt likely needs multiple tool calls in a single response.
    /// Looks for numbered lists, multiple explicit instructions, multi-edit patterns.
    fn needs_multi_tool_call(prompt: &str) -> bool {
        let lower = prompt.to_lowercase();

        // Numbered list patterns: "1) ... 2) ..." or "1. ... 2. ..."
        let has_numbered_list = {
            let mut count = 0u32;
            for i in 1..=5u32 {
                if lower.contains(&format!("{}) ", i)) || lower.contains(&format!("{}. ", i)) {
                    count += 1;
                }
            }
            count >= 2
        };

        // Explicit multi-action keywords
        let multi_keywords = [
            "multiple edits",
            "several changes",
            "three changes",
            "two changes",
            "all of the following",
            "each of these",
            "do both",
            "do all",
            "and also",
            "additionally",
            "as well as",
            "then also",
        ];
        let has_multi_keywords = multi_keywords.iter().any(|kw| lower.contains(kw));

        // Bullet point lists with action verbs
        let bullet_actions = lower.matches("- add ").count()
            + lower.matches("- update ").count()
            + lower.matches("- change ").count()
            + lower.matches("- remove ").count()
            + lower.matches("- fix ").count()
            + lower.matches("- edit ").count()
            + lower.matches("- implement ").count()
            + lower.matches("- create ").count();
        let has_bullet_list = bullet_actions >= 2;

        has_numbered_list || has_multi_keywords || has_bullet_list
    }

    /// Schema-based quality estimate (cold start), on a single commensurable
    /// 0..1 "quality tier" scale, in priority order:
    ///
    /// 1. **Published benchmarks**, NORMALIZED onto the tier scale. A raw
    ///    benchmark score is NOT directly comparable to the size/trust
    ///    heuristics: hard agentic benchmarks (tau-bench, SWE-bench) report low
    ///    absolute pass-rates even for frontier models (tau-bench-airline tops
    ///    out ~0.65), so taking the raw average ranked every *measured* model
    ///    below every *unmeasured* local/remote — the exact inversion this
    ///    function exists to prevent. `normalized_benchmark_quality` maps each
    ///    calibrated benchmark's raw score through its frontier reference so
    ///    best-in-class lands near the top of the tier band.
    /// 2. **Unmeasured remotes**: reviewed `frontier` / `balanced` quality-class
    ///    tags provide a coarse prior below the measured-frontier ceiling;
    ///    otherwise conservative-unknown, below measured frontier and above
    ///    small locals. Curated > Community.
    /// 3. **Local models**: a size proxy, CAPPED below the measured-frontier
    ///    floor. We have no evidence a local matches a benchmarked frontier
    ///    model on quality, so an unmeasured local must not out-rank one on the
    ///    quality term — local-first survives via the cost/privacy bonuses in
    ///    `score_model`, not by an inflated quality claim.
    fn schema_quality_estimate(&self, model: &ModelSchema) -> f64 {
        if !model.public_benchmarks.is_empty() {
            return self.normalized_benchmark_quality(model).clamp(0.0, 1.0);
        }
        if model.is_remote() {
            // Conservative-unknown: an UNMEASURED remote's quality is genuinely
            // unknown until it carries real benchmarks or accumulates live
            // outcomes. It sits below the measured-frontier band so ANY model
            // with real benchmarks can rank above it on evidence. Community
            // (auto-discovered, unvetted) is damped further.
            if model.trust_tier == crate::schema::TrustTier::Curated
                && model.tags.iter().any(|tag| tag == "openrouter")
            {
                if model_is_frontier_class(model) {
                    return Self::CURATED_FRONTIER_TAG_PRIOR;
                }
                if model.tags.iter().any(|tag| tag == "balanced") {
                    return Self::CURATED_BALANCED_TAG_PRIOR;
                }
            }
            return match model.trust_tier {
                crate::schema::TrustTier::Community => Self::UNMEASURED_REMOTE_COMMUNITY,
                _ => Self::UNMEASURED_REMOTE_CURATED,
            };
        }
        // Local size proxy, capped below `BENCH_TIER_FLOOR` (the bottom of the
        // measured band) so a benchmarked frontier model always wins the
        // quality term. Ordering by size is preserved.
        match model.size_mb() {
            0 => 0.35,             // unknown local — conservative
            s if s < 1000 => 0.30, // 0.6B
            s if s < 2000 => 0.38, // 1.7B
            s if s < 3000 => 0.45, // 4B
            s if s < 6000 => 0.52, // 8B
            _ => 0.60,             // 30B+: diminishing returns, still < frontier
        }
    }

    /// Average of each published benchmark's score mapped onto the quality-tier
    /// scale. A *calibrated* benchmark (one with a known `frontier_ref`) is
    /// linearly remapped `[0, frontier_ref] → [FLOOR, CEIL]` so best-in-class
    /// lands near CEIL. An *uncalibrated* benchmark (no frontier anchor) is
    /// clamped into a band by model tier: a **remote** model's score clamps into
    /// the measured band `[FLOOR, CEIL]` (frontier-pending — a new benchmark a
    /// frontier model carries before its reference lands); a **local** model's
    /// score clamps into the LOCAL sub-band `[LOCAL_BENCH_TIER_FLOOR,
    /// LOCAL_BENCH_TIER_CEIL]` (a self-measured local suite isn't commensurable
    /// with the frontier scale — see `LOCAL_BENCH_TIER_FLOOR`).
    fn normalized_benchmark_quality(&self, model: &ModelSchema) -> f64 {
        let is_local = model.is_local();
        let n = model.public_benchmarks.len() as f64;
        let sum: f64 = model
            .public_benchmarks
            .iter()
            .map(|b| match Self::benchmark_frontier_ref(&b.name) {
                Some(frontier_ref) => {
                    // #370: a score ABOVE the derived frontier_ref clamps to CEIL
                    // and silently collapses into the top band — two above-frontier
                    // models become one bucket where cost breaks the tie, and the
                    // catalog's champion anchor is now stale. Surface it as a
                    // re-anchor candidate instead of swallowing it. (frontier_ref is
                    // the builtin-catalog max, so this fires only for a model NOT in
                    // that catalog — e.g. a freshly registered model — which is
                    // exactly the case that should prompt a catalog update.)
                    if b.score > frontier_ref {
                        tracing::warn!(
                            model = %model.id,
                            benchmark = %b.name,
                            score = b.score,
                            frontier_ref,
                            "model scores ABOVE the catalog frontier_ref — re-anchor \
                             candidate: update builtin_catalog.json so this benchmark's \
                             champion calibrates the quality tier (#370)"
                        );
                    }
                    let frac = (b.score / frontier_ref).clamp(0.0, 1.0);
                    Self::BENCH_TIER_FLOOR + frac * (Self::BENCH_TIER_CEIL - Self::BENCH_TIER_FLOOR)
                }
                // Uncalibrated benchmark (no frontier_ref): we don't know its
                // scale, so CLAMP into a band rather than pass through raw (a raw
                // hard-benchmark score like SWE-bench ~0.35 could land BELOW the
                // floor and re-invert the scale bug this function fixes). The band
                // depends on the model tier:
                None if is_local => {
                    // LOCAL self-measured (frontier-less) benchmark → the LOCAL
                    // sub-band, NOT the measured-frontier band. A local model's
                    // raw score on an unanchored suite isn't comparable to a
                    // frontier-calibrated score, so it must not be lifted into the
                    // frontier band; instead measured capability replaces the size
                    // proxy WITHIN the local tier (#368). See `LOCAL_BENCH_TIER_FLOOR`.
                    b.score
                        .clamp(Self::LOCAL_BENCH_TIER_FLOOR, Self::LOCAL_BENCH_TIER_CEIL)
                }
                // REMOTE, frontier-pending: a new benchmark a frontier model
                // carries before its catalog reference is added. Clamp into the
                // measured band (the catalog-coverage test guards against a real
                // benchmark silently staying uncalibrated for long).
                None => b.score.clamp(Self::BENCH_TIER_FLOOR, Self::BENCH_TIER_CEIL),
            })
            .sum();
        // NOTE: for a LOCAL model carrying BOTH a calibrated (frontier-anchored,
        // → [0.40,0.92]) and an uncalibrated (→ [0.30,0.60]) benchmark, this mean
        // straddles the two bands — the result is not on a single scale. That's a
        // conservative pull (the local arm only lowers the mean, never inflates
        // it) and doesn't break the frontier-wins invariant; today #368's locals
        // carry only the self-measured suite, so the mean stays single-band.
        sum / n
    }

    /// Raw score a frontier-class model reaches on a known published benchmark
    /// — the reference that calibrates that benchmark's hard absolute scale onto
    /// the quality tier (`[0, frontier_ref] → [FLOOR, CEIL]`, so best-in-class
    /// lands at CEIL). `None` ⇒ the benchmark isn't carried by any catalog model
    /// (or its best score is non-positive) → uncalibrated clamp path.
    ///
    /// DERIVED from the catalog (see `BENCHMARK_FRONTIER_REFS`) rather than
    /// hardcoded: it can't drift out of sync, it auto-anchors when a stronger
    /// model ships, and it auto-calibrates any new benchmark a catalog model
    /// carries — removing the "add a benchmark, forget its reference, silently
    /// mis-rank" footgun the old hardcoded `match` invited.
    fn benchmark_frontier_ref(name: &str) -> Option<f64> {
        BENCHMARK_FRONTIER_REFS
            .get(name)
            .copied()
            .filter(|r| *r > 0.0)
    }

    /// Schema-based latency estimate (cold start).
    ///
    /// Converts declared TPS/p50 to the same ms-based score used by observed data,
    /// so there's no discontinuity when the first observation arrives.
    fn schema_latency_estimate(&self, model: &ModelSchema) -> f64 {
        let is_moe = model.tags.contains(&"moe".to_string());

        if model.is_local() {
            if let Some(tps) = model.performance.tokens_per_second {
                // The MoE discount corrects a *declared* rate — a hand-seeded
                // estimate written as if the model were dense. It must not be
                // applied to a rate that was measured, which already reflects
                // however fast expert routing actually decodes; doing so scores
                // the model at half or a tenth of its observed throughput.
                //
                // `latency_p50_ms` is the marker, and not incidentally:
                // `scripts/bench-consolidate.py` writes a p50 only alongside a
                // real measured `tokens_per_second`, precisely so a throttled
                // run's bogus whole-generation "TTFT" cannot be seeded. A
                // present p50 on a local row therefore means the decode rate
                // beside it came from a benchmark, not from someone's estimate.
                let measured = model.performance.latency_p50_ms.is_some();
                let effective_tps = if is_moe && !measured {
                    let multiplier = if model.is_mlx() {
                        Self::MLX_MOE_TPS_MULTIPLIER
                    } else {
                        Self::MOE_TPS_MULTIPLIER
                    };
                    tps * multiplier
                } else {
                    tps
                };
                let estimated_ms = Self::tps_to_latency_ms(effective_tps);
                return self.latency_ms_to_score(estimated_ms);
            }
            return 0.5; // local, no declared TPS
        }

        // Remote: use declared p50 latency
        if let Some(p50) = model.performance.latency_p50_ms {
            return self.latency_ms_to_score(p50 as f64);
        }
        0.3 // remote, no declared latency
    }

    fn is_quality_critical_bootstrap_task(
        &self,
        task: InferenceTask,
        has_vision: bool,
        has_tools: bool,
    ) -> bool {
        has_vision
            || has_tools
            || matches!(
                task,
                InferenceTask::Generate | InferenceTask::Code | InferenceTask::Reasoning
            )
    }

    fn is_trusted_quality_remote(&self, model: &ModelSchema) -> bool {
        let trusted_provider = matches!(
            model.provider.as_str(),
            "openai" | "anthropic" | "google" | "openrouter"
        );
        model.is_remote()
            && model.trust_tier == crate::schema::TrustTier::Curated
            && (trusted_provider || crate::openrouter::is_managed_gateway_schema(model))
            && !model.has_capability(ModelCapability::SpeechToText)
            && !model.has_capability(ModelCapability::TextToSpeech)
    }

    fn is_local_model_proven_for_task(
        &self,
        model: &ModelSchema,
        task: InferenceTask,
        tracker: &OutcomeTracker,
    ) -> bool {
        let Some(profile) = tracker.profile(&model.id) else {
            return false;
        };
        if let Some(task_stats) = profile.task_stats(task) {
            if task_stats.calls >= self.config.bootstrap_min_task_observations
                && task_stats.ema_quality >= self.config.bootstrap_quality_floor
            {
                return true;
            }
        }

        profile.total_calls >= self.config.bootstrap_min_task_observations
            && profile.ema_quality >= self.config.bootstrap_quality_floor
    }

    /// Phase 3: Thompson Sampling selection.
    ///
    /// Each model gets a Beta(alpha, beta) distribution where:
    /// - alpha = prior_successes + observed_successes
    /// - beta = prior_failures + observed_failures
    ///
    /// The Phase 2 score serves as the prior mean, scaled by `prior_strength`.
    /// Models with few observations have wide distributions (natural exploration).
    /// Models with many observations have tight distributions (exploitation).
    fn select_with_thompson_sampling(
        &self,
        scored: &[(String, f64)],
        tracker: &OutcomeTracker,
    ) -> (String, RoutingStrategy) {
        if scored.is_empty() {
            return (String::new(), RoutingStrategy::SchemaBased);
        }

        let mut rng = rand::rng();
        let mut best_sample = f64::NEG_INFINITY;
        let mut best_id = scored[0].0.clone();
        let mut best_strategy = RoutingStrategy::SchemaBased;

        for (id, phase2_score) in scored {
            let profile = tracker.profile(id);
            let prior = self.config.prior_strength;

            // Convert Phase 2 score (0.0-1.15) to a prior mean in [0, 1]
            let prior_mean = phase2_score.clamp(0.0, 1.0);

            // Prior pseudo-counts from the Phase 2 score
            let prior_alpha = prior * prior_mean;
            let prior_beta = prior * (1.0 - prior_mean);

            // Observed counts
            let (obs_alpha, obs_beta) = match profile {
                Some(p) => (p.success_count as f64, p.fail_count as f64),
                None => (0.0, 0.0),
            };

            // Posterior Beta parameters
            let alpha = (prior_alpha + obs_alpha).max(0.01);
            let beta = (prior_beta + obs_beta).max(0.01);

            // Sample from Beta(alpha, beta) using the Jöhnk algorithm
            let sample = sample_beta(&mut rng, alpha, beta);

            if sample > best_sample {
                best_sample = sample;
                best_id = id.clone();
                best_strategy = match profile {
                    Some(p) if p.total_calls >= self.config.min_observations => {
                        RoutingStrategy::ProfileBased
                    }
                    Some(p) if p.total_calls > 0 => {
                        // Under-tested but has some data — exploration
                        RoutingStrategy::Exploration
                    }
                    _ => RoutingStrategy::SchemaBased,
                };
            }
        }

        (best_id, best_strategy)
    }

    /// Fallback decision when no candidates pass filtering.
    /// Schema-based decision when Phase-1 filtering left no candidate (cold
    /// start, or every capable model gated out by memory/availability).
    ///
    /// `required_caps` is the caller's FULL hard requirement set (prompt
    /// complexity + `intent.require` + tool/vision needs) — the same set
    /// `filter_candidates` enforced. Honoring it here is load-bearing: the
    /// hardcoded complexity→model defaults at the tail can name a model that
    /// lacks a required capability (e.g. `Simple`→`Qwen3-0.6B`, which has no
    /// `Code`), so a `require: [Code]` request that fell through to cold start
    /// used to resolve to a Code-less model — silently violating the hard
    /// filter. We now (1) apply `required_caps` to the trusted-remote branch,
    /// and (2) prefer the best **local** model that both fits memory and
    /// satisfies every required cap before the defaults — which also keeps
    /// work on an eligible local model instead of falling through to a
    /// (possibly unauthenticated) remote default.
    fn cold_start_decision(
        &self,
        complexity: TaskComplexity,
        task: InferenceTask,
        required_caps: &[ModelCapability],
        registry: &UnifiedRegistry,
        has_vision: bool,
        exclude: &std::collections::HashSet<String>,
        strict_exclusions: bool,
        availability: AvailabilitySnapshot,
    ) -> AdaptiveRoutingDecision {
        // car#358: prefer a non-excluded model in every tier. Soft — the tier
        // cascade naturally falls through to the next tier (and ultimately the
        // hardcoded default floor) if exclusion empties a tier, so a reviewer
        // still gets *a* model rather than an error.
        if has_vision {
            if let Some(model) = registry
                .query_by_capability(ModelCapability::Vision)
                .into_iter()
                .filter(|model| !exclude.contains(&model.id))
                .find(|model| {
                    availability.is_available(model) && self.is_trusted_quality_remote(model)
                })
                .or_else(|| {
                    registry
                        .query_by_capability(ModelCapability::Vision)
                        .into_iter()
                        .find(|model| !exclude.contains(&model.id))
                })
            {
                return AdaptiveRoutingDecision {
                    model_id: model.id.clone(),
                    model_name: model.name.clone(),
                    task,
                    complexity,
                    reason: format!(
                        "{:?} task → {} (cold start, vision fallback)",
                        complexity, model.name
                    ),
                    strategy: RoutingStrategy::SchemaBased,
                    predicted_quality: 0.5,
                    fallbacks: vec![],
                    context_length: model.context_length,
                    needs_compaction: false,
                    candidates: vec![],
                };
            }
        }

        if self.config.quality_first_cold_start {
            if let Some(model) = registry
                .list()
                .into_iter()
                .filter(|model| {
                    availability.is_available(model)
                        && !exclude.contains(&model.id)
                        && required_caps.iter().all(|cap| model.has_capability(*cap))
                        && self.is_trusted_quality_remote(model)
                })
                .max_by(|a, b| {
                    self.schema_quality_estimate(a)
                        .partial_cmp(&self.schema_quality_estimate(b))
                        .unwrap_or(std::cmp::Ordering::Equal)
                })
            {
                return AdaptiveRoutingDecision {
                    model_id: model.id.clone(),
                    model_name: model.name.clone(),
                    task,
                    complexity,
                    reason: format!(
                        "{:?} task → {} (quality-first cold start)",
                        complexity, model.name
                    ),
                    strategy: RoutingStrategy::SchemaBased,
                    predicted_quality: self.schema_quality_estimate(model),
                    fallbacks: vec![],
                    context_length: model.context_length,
                    needs_compaction: false,
                    candidates: vec![],
                };
            }
        }

        // Prefer the best LOCAL model that fits memory AND satisfies every
        // required capability, before the hardcoded defaults. This is what
        // makes cold start honor a hard `require: [Code, ToolUse]` instead of
        // naming a capability-lacking complexity default — and keeps work on
        // an eligible local model rather than falling through to a remote that
        // may be unauthenticated. `<` mirrors `filter_candidates`' strict
        // memory gate so the two agree on what "fits".
        if let Some(model) = registry
            .list()
            .into_iter()
            .filter(|model| {
                availability.is_available(model)
                    && !exclude.contains(&model.id)
                    && model.is_local()
                    && model.size_mb() < self.hw.max_model_mb
                    && required_caps.iter().all(|cap| model.has_capability(*cap))
            })
            .max_by(|a, b| {
                self.schema_quality_estimate(a)
                    .partial_cmp(&self.schema_quality_estimate(b))
                    .unwrap_or(std::cmp::Ordering::Equal)
            })
        {
            return AdaptiveRoutingDecision {
                model_id: model.id.clone(),
                model_name: model.name.clone(),
                task,
                complexity,
                reason: format!(
                    "{:?} task → {} (capability-satisfying local cold start)",
                    complexity, model.name
                ),
                strategy: RoutingStrategy::SchemaBased,
                predicted_quality: self.schema_quality_estimate(model),
                fallbacks: vec![],
                context_length: model.context_length,
                needs_compaction: false,
                candidates: vec![],
            };
        }

        // No eligible LOCAL model satisfied the requirement. Before falling to
        // a complexity default that may LACK a required capability, prefer any
        // available model that satisfies every required cap — typically a
        // remote tool-capable model when ToolUse is required but no in-process
        // local backend can execute tool calls (the catalog no longer lets a
        // local model claim ToolUse it can't honor). Trusted-quality remotes
        // sort first, then higher schema quality. This keeps the contract this
        // function's name promises — never name a capability-lacking model when
        // an available satisfying one exists — instead of silently handing back
        // a default the request can't actually use.
        if let Some(model) = registry
            .list()
            .into_iter()
            .filter(|model| {
                availability.is_available(model)
                    && !exclude.contains(&model.id)
                    && required_caps.iter().all(|cap| model.has_capability(*cap))
            })
            .max_by(|a, b| {
                let qa = (
                    self.is_trusted_quality_remote(a),
                    self.schema_quality_estimate(a),
                );
                let qb = (
                    self.is_trusted_quality_remote(b),
                    self.schema_quality_estimate(b),
                );
                qa.partial_cmp(&qb).unwrap_or(std::cmp::Ordering::Equal)
            })
        {
            return AdaptiveRoutingDecision {
                model_id: model.id.clone(),
                model_name: model.name.clone(),
                task,
                complexity,
                reason: format!(
                    "{:?} task → {} (capability-satisfying cold start)",
                    complexity, model.name
                ),
                strategy: RoutingStrategy::SchemaBased,
                predicted_quality: self.schema_quality_estimate(model),
                fallbacks: vec![],
                context_length: model.context_length,
                needs_compaction: false,
                candidates: vec![],
            };
        }

        // A separation boundary cannot fall through to an excluded default.
        // Return an explicit no-route decision; generation turns this into a
        // typed `NoEligibleModel` error before any backend is invoked.
        if strict_exclusions && !exclude.is_empty() {
            return Self::no_eligible_model_decision(complexity, task, exclude.len());
        }

        // Last resort: the old complexity-based defaults. Reached only when NO
        // available model anywhere satisfies `required_caps` — at which point
        // the named default may not satisfy them either, but nothing eligible
        // does, so this is a best-effort handoff (the inference layer surfaces
        // the unmet requirement — e.g. the generate path's tool-capability
        // guard returns UnsupportedMode — rather than the router guessing).
        let model_name = match complexity {
            TaskComplexity::Simple => "Qwen3-0.6B",
            TaskComplexity::Medium => "Qwen3-1.7B",
            TaskComplexity::Code => "Qwen3-4B",
            TaskComplexity::Complex => &self.hw.recommended_model,
        };

        let model_id = registry
            .find_by_name(model_name)
            .map(|m| m.id.clone())
            .unwrap_or_else(|| model_name.to_string());

        let context_length = registry
            .find_by_name(model_name)
            .map(|m| m.context_length)
            .unwrap_or(0);

        AdaptiveRoutingDecision {
            model_id,
            model_name: model_name.to_string(),
            task,
            complexity,
            reason: format!(
                "{:?} task → {} (cold start, no candidates)",
                complexity, model_name
            ),
            strategy: RoutingStrategy::SchemaBased,
            predicted_quality: 0.5,
            fallbacks: vec![],
            context_length,
            needs_compaction: false,
            candidates: vec![],
        }
    }

    fn no_eligible_model_decision(
        complexity: TaskComplexity,
        task: InferenceTask,
        excluded_count: usize,
    ) -> AdaptiveRoutingDecision {
        AdaptiveRoutingDecision {
            model_id: String::new(),
            model_name: String::new(),
            task,
            complexity,
            reason: format!(
                "strict model exclusions left no eligible model ({excluded_count} catalog ids excluded)"
            ),
            strategy: RoutingStrategy::SchemaBased,
            predicted_quality: 0.0,
            fallbacks: vec![],
            context_length: 0,
            needs_compaction: false,
            candidates: vec![],
        }
    }
}

/// Map a caller-supplied [`crate::TaskHint`] to the engine's
/// [`InferenceTask`] enum. The intent surface uses the higher-level
/// hint vocabulary; the router operates on InferenceTask. Every
/// TaskHint variant maps to a distinct InferenceTask — variants that
/// would have silently collapsed to `Generate` were cut from the MVP.
fn task_hint_to_inference_task(hint: crate::intent::TaskHint) -> InferenceTask {
    use crate::intent::TaskHint;
    match hint {
        TaskHint::Chat => InferenceTask::Generate,
        TaskHint::Classify => InferenceTask::Classify,
        TaskHint::Reasoning => InferenceTask::Reasoning,
        TaskHint::Code => InferenceTask::Code,
    }
}

/// Hard capability a model must have to serve a resolved [`InferenceTask`].
///
/// Mirrors `TaskComplexity::required_capabilities` but keyed on the *task* so a
/// caller's explicit `task` intent can gate the candidate filter the same way
/// prompt complexity does. Code/Reasoning gate the specialized tasks; Embed and
/// Classify have dedicated capabilities; Generate is the generative baseline.
fn inference_task_required_capability(task: InferenceTask) -> ModelCapability {
    match task {
        InferenceTask::Generate => ModelCapability::Generate,
        InferenceTask::Code => ModelCapability::Code,
        InferenceTask::Reasoning => ModelCapability::Reasoning,
        InferenceTask::Classify => ModelCapability::Classify,
        InferenceTask::Embed => ModelCapability::Embed,
    }
}

/// Sample from a Beta(alpha, beta) distribution.
///
/// Uses the Gamma distribution method: if X ~ Gamma(alpha, 1) and Y ~ Gamma(beta, 1),
/// then X / (X + Y) ~ Beta(alpha, beta).
///
/// For Gamma sampling, uses Marsaglia and Tsang's method for alpha >= 1,
/// and Ahrens-Dieter for alpha < 1.
fn sample_beta(rng: &mut impl Rng, alpha: f64, beta: f64) -> f64 {
    let x = sample_gamma(rng, alpha);
    let y = sample_gamma(rng, beta);
    if x + y == 0.0 {
        0.5 // degenerate case
    } else {
        x / (x + y)
    }
}

/// Sample from Gamma(shape, 1) using Marsaglia-Tsang for shape >= 1,
/// with Ahrens-Dieter boost for shape < 1.
fn sample_gamma(rng: &mut impl Rng, shape: f64) -> f64 {
    if shape < 1.0 {
        // Ahrens-Dieter: Gamma(a) = Gamma(a+1) * U^(1/a)
        let u: f64 = rng.random();
        return sample_gamma(rng, shape + 1.0) * u.powf(1.0 / shape);
    }

    // Marsaglia-Tsang method for shape >= 1
    let d = shape - 1.0 / 3.0;
    let c = 1.0 / (9.0 * d).sqrt();

    loop {
        let x: f64 = loop {
            let n = sample_standard_normal(rng);
            if 1.0 + c * n > 0.0 {
                break n;
            }
        };

        let v = (1.0 + c * x).powi(3);
        let u: f64 = rng.random();

        if u < 1.0 - 0.0331 * x.powi(4) {
            return d * v;
        }
        if u.ln() < 0.5 * x * x + d * (1.0 - v + v.ln()) {
            return d * v;
        }
    }
}

/// Sample from standard normal N(0,1) using Box-Muller transform.
fn sample_standard_normal(rng: &mut impl Rng) -> f64 {
    let u1: f64 = rng.random();
    let u2: f64 = rng.random();
    (-2.0 * u1.max(1e-300).ln()).sqrt() * (2.0 * std::f64::consts::PI * u2).cos()
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::outcome::InferredOutcome;
    use std::ffi::OsString;

    fn route_model_ids(decision: &AdaptiveRoutingDecision) -> impl Iterator<Item = &str> {
        std::iter::once(decision.model_id.as_str())
            .chain(
                decision
                    .candidates
                    .iter()
                    .map(|candidate| candidate.model_id.as_str()),
            )
            .chain(decision.fallbacks.iter().map(String::as_str))
    }

    struct RestoredEnvironment(Vec<(&'static str, Option<OsString>)>);

    impl RestoredEnvironment {
        fn capture(names: &[&'static str]) -> Self {
            Self(
                names
                    .iter()
                    .map(|name| (*name, std::env::var_os(name)))
                    .collect(),
            )
        }
    }

    impl Drop for RestoredEnvironment {
        fn drop(&mut self) {
            for (name, value) in &self.0 {
                unsafe {
                    match value {
                        Some(value) => std::env::set_var(name, value),
                        None => std::env::remove_var(name),
                    }
                }
            }
        }
    }

    struct TestRegistry {
        registry: UnifiedRegistry,
        // Field drop order is intentional: restore the process environment
        // before releasing the shared mutator lock.
        _restore: RestoredEnvironment,
        _environment: tokio::sync::MutexGuard<'static, ()>,
    }

    impl std::ops::Deref for TestRegistry {
        type Target = UnifiedRegistry;

        fn deref(&self) -> &Self::Target {
            &self.registry
        }
    }

    impl std::ops::DerefMut for TestRegistry {
        fn deref_mut(&mut self) -> &mut Self::Target {
            &mut self.registry
        }
    }

    // The canonical id the router actually proposes/learns for a Qwen3 generate
    // model. On Apple Silicon the GGUF candidate is substituted with its MLX
    // equivalent BEFORE scoring (#333), so outcomes must be seeded against the
    // MLX id the router reads; elsewhere MLX isn't compiled/available so the
    // GGUF id stands. Keeps these routing tests valid on every target.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    const QWEN3_8B_ROUTED_ID: &str = "mlx/qwen3-8b:4bit";
    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    const QWEN3_8B_ROUTED_ID: &str = "qwen/qwen3-8b:q4_k_m";
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    const QWEN3_4B_ROUTED_ID: &str = "mlx/qwen3-4b:4bit";
    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    const QWEN3_4B_ROUTED_ID: &str = "qwen/qwen3-4b:q4_k_m";

    fn test_hw() -> HardwareInfo {
        HardwareInfo {
            os: "macos".into(),
            arch: "aarch64".into(),
            cpu_cores: 10,
            total_ram_mb: 32768,
            gpu_backend: crate::hardware::GpuBackend::Metal,
            gpu_memory_mb: Some(28672),
            gpu_devices: Vec::new(),
            recommended_model: "Qwen3-8B".into(),
            recommended_context: 8192,
            max_model_mb: 18000, // headroom above 30B-A3B's 17000MB
        }
    }

    fn test_registry() -> TestRegistry {
        let environment = crate::openrouter::test_environment_scope();
        let restore = RestoredEnvironment::capture(&["OPENAI_API_KEY", "CAR_SECRETS_FILE_DIR"]);
        let tmp = std::path::PathBuf::from("/tmp/car-test-adaptive-router");
        unsafe {
            std::env::set_var("OPENAI_API_KEY", "test-openai-key");
            // Isolate model availability from the dev machine's real OS keychain:
            // now that availability resolves env-OR-keychain, an empty file
            // backend (debug-only redirect) means only env-set keys resolve, so
            // routing tests don't flip on whatever cloud keys the developer has
            // stored (e.g. a real ANTHROPIC_API_KEY making claude-sonnet win).
            std::env::set_var(
                "CAR_SECRETS_FILE_DIR",
                std::env::temp_dir().join("car-test-adaptive-router-empty-secrets"),
            );
        }
        // Create fake model dirs so the registry marks them as available
        for name in &[
            "Qwen3-0.6B",
            "Qwen3-1.7B",
            "Qwen3-4B",
            "Qwen3-8B",
            "Qwen3-Embedding-0.6B",
        ] {
            let dir = tmp.join(name);
            let _ = std::fs::create_dir_all(&dir);
            let _ = std::fs::write(dir.join("model.gguf"), b"fake");
            let _ = std::fs::write(dir.join("tokenizer.json"), b"{}");
        }
        let mut reg = UnifiedRegistry::new_with_state_root(tmp.clone(), tmp);
        reg.register_project_model(ModelSchema {
            id: "openai/gpt-5.4-mini:latest".into(),
            name: "gpt-5.4-mini".into(),
            provider: "openai".into(),
            family: "gpt-5.4".into(),
            version: "latest".into(),
            capabilities: vec![
                ModelCapability::Generate,
                ModelCapability::Code,
                ModelCapability::Reasoning,
                ModelCapability::ToolUse,
                ModelCapability::MultiToolCall,
                ModelCapability::Vision,
            ],
            context_length: 128_000,
            max_output_tokens: None,
            param_count: "api".into(),
            quantization: None,
            performance: Default::default(),
            cost: Default::default(),
            source: crate::schema::ModelSource::RemoteApi {
                endpoint: "https://api.openai.com/v1".into(),
                api_key_env: "OPENAI_API_KEY".into(),
                api_key_envs: vec![],
                api_version: None,
                protocol: crate::schema::ApiProtocol::OpenAiCompat,
            },
            tags: vec!["trusted-remote".into()],
            supported_params: vec![],
            public_benchmarks: vec![],
            trust_tier: crate::schema::TrustTier::Curated,
            deprecated: false,
            available: true,
            weights_ready: true,
        });
        TestRegistry {
            registry: reg,
            _restore: restore,
            _environment: environment,
        }
    }

    #[test]
    fn openrouter_tags_drive_cost_quality_routing_and_live_availability() {
        let tmp = tempfile::tempdir().unwrap();
        let _credential_scope = crate::openrouter::test_credential_scope();
        crate::openrouter::set_test_credential(Some("test-openrouter-key"));
        let mut registry = UnifiedRegistry::new_empty(tmp.path().to_path_buf());
        for schema in crate::openrouter::curated_schemas()
            .into_iter()
            .filter(|schema| schema.provider == "openrouter")
        {
            registry.register_project_model(schema);
        }
        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prefer_local: false,
                // Make this contract check effectively deterministic: the
                // Thompson posterior is concentrated around the declared
                // cost/quality score while still exercising the real selector.
                prior_strength: 1_000_000.0,
                ..RoutingConfig::default()
            },
        );
        let tracker = OutcomeTracker::new();
        let mut simple_tracker = OutcomeTracker::new();
        let evidenced_cheap = "openrouter/qwen/qwen3-coder-next";
        for _ in 0..8 {
            let trace = simple_tracker.record_start(
                evidenced_cheap,
                InferenceTask::Generate,
                "OpenRouter cheap-model calibration",
            );
            simple_tracker.record_complete(&trace, 100, 10, 10);
            simple_tracker
                .record_inferred_outcome(&trace, InferredOutcome::Accepted { confidence: 1.0 });
        }

        crate::openrouter::reset_credential_source_call_count();
        let simple = router.route_with(RouteRequest {
            workload: RoutingWorkload::Background,
            ..RouteRequest::new("Say hello.", &registry, &simple_tracker)
        });
        assert_eq!(crate::openrouter::credential_source_call_count(), 1);
        let simple_schema = registry.get(&simple.model_id).unwrap();
        assert!(simple_schema.tags.iter().any(|tag| tag == "cheap"));
        assert!(simple.reason.contains("low-cost tier"), "{}", simple.reason);
        assert!(simple
            .candidates
            .iter()
            .any(|candidate| candidate.model_id.starts_with("openrouter/")));

        let quality_intent = crate::intent::IntentHint {
            task: Some(crate::intent::TaskHint::Reasoning),
            prefer_quality: true,
            ..Default::default()
        };
        let complex = router.route_with(RouteRequest {
            intent: Some(&quality_intent),
            ..RouteRequest::new(
                "Analyze this multi-step architecture tradeoff and prove the failure modes.",
                &registry,
                &tracker,
            )
        });
        let complex_schema = registry.get(&complex.model_id).unwrap();
        assert!(complex_schema.tags.iter().any(|tag| tag == "frontier"));
        assert!(
            complex.reason.contains("frontier quality tier"),
            "{}",
            complex.reason
        );

        let vision_intent = crate::intent::IntentHint {
            require: vec![ModelCapability::Vision],
            ..Default::default()
        };
        let vision = router.route_with(RouteRequest {
            intent: Some(&vision_intent),
            ..RouteRequest::new("Inspect this image", &registry, &tracker)
        });
        assert!(vision.candidates.iter().all(|candidate| registry
            .get(&candidate.model_id)
            .is_some_and(|schema| schema.has_capability(ModelCapability::Vision))));

        let failed_model = simple.model_id.clone();
        {
            let mut breakers = router.circuit_breakers.lock().unwrap();
            for _ in 0..3 {
                breakers.record_failure(&failed_model);
            }
        }
        let after_failures = router.route_with(RouteRequest {
            workload: RoutingWorkload::Background,
            ..RouteRequest::new("Say hello.", &registry, &simple_tracker)
        });
        assert_ne!(after_failures.model_id, failed_model);
        assert!(!after_failures
            .candidates
            .iter()
            .any(|candidate| candidate.model_id == failed_model));

        crate::openrouter::set_test_credential(None);
        crate::openrouter::reset_credential_source_call_count();
        let without_key = router.route("Say hello.", &registry, &tracker);
        assert_eq!(crate::openrouter::credential_source_call_count(), 1);
        assert!(!without_key.model_id.starts_with("openrouter/"));
        assert!(!without_key
            .fallbacks
            .iter()
            .any(|model| model.starts_with("openrouter/")));
        assert!(!without_key
            .candidates
            .iter()
            .any(|candidate| candidate.model_id.starts_with("openrouter/")));
    }

    #[tokio::test(flavor = "current_thread")]
    async fn managed_openrouter_aliases_survive_quality_bootstrap_without_a_personal_key() {
        let tmp = tempfile::tempdir().unwrap();
        let _credential_scope = crate::openrouter::test_credential_scope();
        let _environment = crate::openrouter::test_environment_scope_async().await;
        let _restore = RestoredEnvironment::capture(&[
            "CAR_SECRETS_FILE_DIR",
            "CAR_MANAGED_ROUTING_TEST_KEY",
            car_auth::PARSLEE_ACCESS_TOKEN_KEY,
        ]);
        // The assertions below are that the managed `parslee/openrouter/*`
        // aliases stay routable. Both durable session verdicts —
        // `gateway-state.json` (Parslee-ai/car#786) and
        // `parslee-credential-state.json` (Parslee-ai/car#887) — suppress
        // exactly those rows, and they live in the CAR state root, so a live
        // one left there by any other process makes this test fail on a claim
        // it never set. Pin the root and forget the in-process copies
        // (Parslee-ai/car#986).
        let _home = crate::openrouter::StateRootScope::new();
        crate::openrouter::clear_gateway_unconfigured();
        crate::parslee_credential::clear_credential_rejected();
        let secrets_dir = tmp.path().join("secrets");
        unsafe {
            std::env::set_var("CAR_SECRETS_FILE_DIR", &secrets_dir);
            std::env::set_var("CAR_MANAGED_ROUTING_TEST_KEY", "test-peer-key");
            std::env::remove_var(car_auth::PARSLEE_ACCESS_TOKEN_KEY);
        }
        crate::openrouter::set_test_credential(None);

        let mut registry = UnifiedRegistry::new_empty(tmp.path().join("models"));
        for schema in crate::openrouter::curated_schemas() {
            registry.register_project_model(schema);
        }
        let mut bootstrap_peer = remote_model(
            "openai/bootstrap-peer",
            "bootstrap-peer",
            vec![
                ModelCapability::Generate,
                ModelCapability::Code,
                ModelCapability::Reasoning,
            ],
        );
        if let crate::schema::ModelSource::RemoteApi {
            ref mut api_key_env,
            ..
        } = bootstrap_peer.source
        {
            *api_key_env = "CAR_MANAGED_ROUTING_TEST_KEY".into();
        }
        registry.register_project_model(bootstrap_peer);
        let mut unrelated = remote_model(
            "other/unrelated-curated",
            "unrelated-curated",
            vec![
                ModelCapability::Generate,
                ModelCapability::Code,
                ModelCapability::Reasoning,
            ],
        );
        unrelated.provider = "other".into();
        if let crate::schema::ModelSource::RemoteApi {
            ref mut api_key_env,
            ..
        } = unrelated.source
        {
            *api_key_env = "CAR_MANAGED_ROUTING_TEST_KEY".into();
        }
        registry.register_project_model(unrelated);
        // Routing receives the coordinator-owned credential snapshot. Writing
        // a secret-store fixture directly does not publish the passive
        // authority hint and would make this test depend on the developer's
        // ambient sign-in state.
        registry.refresh_routing_availability(Some("https://api.parslee.ai"), false);

        let managed: Vec<_> = registry
            .list()
            .into_iter()
            .filter(|schema| schema.id.starts_with("parslee/openrouter/"))
            .collect();
        assert_eq!(managed.len(), crate::openrouter::curated_model_count());
        assert!(managed.iter().all(|schema| {
            schema.available_now()
                && schema.tags.iter().any(|tag| tag == "openrouter")
                && schema.tags.iter().any(|tag| tag == "managed")
                && schema.cost.input_per_mtok.is_some_and(|price| price > 0.0)
                && schema.cost.output_per_mtok.is_some_and(|price| price > 0.0)
                && schema.has_capability(ModelCapability::Generate)
        }));
        assert!(registry
            .list()
            .into_iter()
            .filter(|schema| schema.id.starts_with("openrouter/"))
            .all(|schema| !schema.available_now()));

        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prefer_local: false,
                prior_strength: 1_000_000.0,
                ..RoutingConfig::default()
            },
        );
        let tracker = OutcomeTracker::new();

        let interactive = router.route("Say hello.", &registry, &tracker);
        assert!(
            interactive
                .candidates
                .iter()
                .any(|candidate| candidate.model_id.starts_with("parslee/openrouter/")),
            "signed-in managed aliases must survive quality-first bootstrap: {interactive:?}"
        );
        assert!(
            interactive
                .fallbacks
                .iter()
                .any(|id| id.starts_with("parslee/openrouter/")),
            "signed-in managed aliases must remain fallback-eligible: {interactive:?}"
        );
        assert!(
            interactive
                .candidates
                .iter()
                .any(|candidate| candidate.model_id == "openai/bootstrap-peer"),
            "adding managed aliases must not remove existing trusted providers: {interactive:?}"
        );
        assert!(
            !interactive
                .candidates
                .iter()
                .any(|candidate| candidate.model_id == "other/unrelated-curated"),
            "managed-alias trust must not broaden the bootstrap to unrelated providers"
        );

        let mut simple_tracker = OutcomeTracker::new();
        let evidenced_cheap = "parslee/openrouter/open-fast";
        for _ in 0..8 {
            let trace = simple_tracker.record_start(
                evidenced_cheap,
                InferenceTask::Generate,
                "managed OpenRouter cheap-model calibration",
            );
            simple_tracker.record_complete(&trace, 100, 10, 10);
            simple_tracker
                .record_inferred_outcome(&trace, InferredOutcome::Accepted { confidence: 1.0 });
        }
        let simple = router.route_with(RouteRequest {
            workload: RoutingWorkload::Background,
            ..RouteRequest::new("Say hello.", &registry, &simple_tracker)
        });
        let simple_schema = registry.get(&simple.model_id).unwrap();
        assert!(
            simple.model_id.starts_with("parslee/openrouter/")
                && simple_schema.tags.iter().any(|tag| tag == "cheap"),
            "simple work should prefer an evidenced cheap managed alias: {simple:?}"
        );
        assert!(simple.reason.contains("low-cost tier"), "{}", simple.reason);

        let quality_intent = crate::intent::IntentHint {
            task: Some(crate::intent::TaskHint::Reasoning),
            prefer_quality: true,
            ..Default::default()
        };
        let complex = router.route_with(RouteRequest {
            intent: Some(&quality_intent),
            ..RouteRequest::new(
                "Analyze this multi-step architecture tradeoff and prove the failure modes.",
                &registry,
                &tracker,
            )
        });
        let complex_schema = registry.get(&complex.model_id).unwrap();
        assert!(
            complex.model_id.starts_with("parslee/openrouter/")
                && complex_schema.tags.iter().any(|tag| tag == "frontier"),
            "complex quality work should escalate to a managed frontier alias: {complex:?}"
        );
        assert!(
            complex.reason.contains("frontier quality tier"),
            "{}",
            complex.reason
        );

        for decision in [&interactive, &simple, &complex] {
            assert!(
                !route_model_ids(decision).any(|id| id.starts_with("openrouter/")),
                "personal OpenRouter rows must stay excluded without a personal key: {decision:?}"
            );
        }

        let spoofed_id = "parslee/openrouter/frontier-general";
        let spoofed_endpoint = "https://attacker.invalid/v1/chat/completions";
        let spoofed_value = serde_json::json!({
            "id": spoofed_id,
            "name": spoofed_id,
            "provider": "parslee",
            "family": "spoof",
            "capabilities": ["generate", "code", "reasoning"],
            "context_length": 1_000_000,
            "performance": {"latency_p50_ms": 1},
            "cost": {"input_per_mtok": 0.0, "output_per_mtok": 0.0},
            "source": {
                "type": "remote_api",
                "endpoint": spoofed_endpoint,
                "api_key_env": "CAR_MANAGED_ROUTING_TEST_KEY",
                "protocol": "open_ai_compat"
            },
            "tags": ["openrouter", "managed", "frontier"],
            "public_benchmarks": [{"name": "attacker-unanchored", "score": 1.0}]
        });
        let omitted_tier: ModelSchema = serde_json::from_value(spoofed_value.clone()).unwrap();
        assert_eq!(
            omitted_tier.trust_tier,
            crate::schema::TrustTier::Curated,
            "the regression must exercise the legacy omitted-tier default"
        );
        let mut direct_spoof_registry =
            UnifiedRegistry::new_empty(tmp.path().join("direct-spoof-models"));
        direct_spoof_registry.register(omitted_tier);
        assert!(
            direct_spoof_registry.get(spoofed_id).is_none(),
            "public registration must reject the reserved managed-alias namespace"
        );
        direct_spoof_registry
            .register_project_model(registry.get("openai/bootstrap-peer").unwrap().clone());
        let direct_spoof_route = router.route(
            "Analyze this architecture and prove the failure modes.",
            &direct_spoof_registry,
            &OutcomeTracker::new(),
        );
        assert!(
            !route_model_ids(&direct_spoof_route).any(|id| id == spoofed_id),
            "a rejected in-memory lookalike must not be routable: {direct_spoof_route:?}"
        );
        std::fs::write(
            tmp.path().join("models.json"),
            serde_json::to_vec_pretty(&vec![spoofed_value]).unwrap(),
        )
        .unwrap();

        let mut reloaded = UnifiedRegistry::new_empty(tmp.path().join("reloaded-models"));
        reloaded.load_user_config().unwrap();
        assert!(
            reloaded.get(spoofed_id).is_none(),
            "persisted user config must reject the reserved managed-alias namespace"
        );
        reloaded.register_project_model(registry.get("openai/bootstrap-peer").unwrap().clone());
        let spoofed_route = router.route(
            "Analyze this architecture and prove the failure modes.",
            &reloaded,
            &OutcomeTracker::new(),
        );
        assert!(
            !route_model_ids(&spoofed_route).any(|id| id == spoofed_id),
            "a rejected persisted lookalike must not be routable: {spoofed_route:?}"
        );

        let discovery_state_root = tmp.path().join("discovery-spoof-root");
        let discovery_models_dir = discovery_state_root.join("models");
        std::fs::create_dir_all(&discovery_models_dir).unwrap();
        let discovery_spoof_id = "openrouter/forged-discovery-cache";
        let mut discovery_spoof = remote_model(
            discovery_spoof_id,
            "forged-discovery-cache",
            vec![
                ModelCapability::Generate,
                ModelCapability::Code,
                ModelCapability::Reasoning,
            ],
        );
        discovery_spoof.provider = "openrouter".into();
        discovery_spoof.tags = vec!["openrouter".into(), "frontier".into()];
        discovery_spoof.trust_tier = crate::schema::TrustTier::Curated;
        discovery_spoof.performance.latency_p50_ms = Some(1);
        discovery_spoof.cost = crate::schema::CostModel::default();
        if let crate::schema::ModelSource::RemoteApi {
            ref mut api_key_env,
            ..
        } = discovery_spoof.source
        {
            *api_key_env = "CAR_MANAGED_ROUTING_TEST_KEY".into();
        }
        crate::discovery::save_cache(
            &crate::discovery::cache_path(&discovery_models_dir),
            &[discovery_spoof],
        )
        .unwrap();

        let mut discovery_registry =
            UnifiedRegistry::new_with_state_root(discovery_state_root, discovery_models_dir);
        discovery_registry
            .register_project_model(registry.get("openai/bootstrap-peer").unwrap().clone());
        assert_eq!(
            discovery_registry
                .get(discovery_spoof_id)
                .unwrap()
                .trust_tier,
            crate::schema::TrustTier::Community,
            "unsigned discovery cache rows must be demoted before registration"
        );
        let discovery_spoof_route = router.route(
            "Analyze this architecture and prove the failure modes.",
            &discovery_registry,
            &OutcomeTracker::new(),
        );
        assert!(
            !discovery_spoof_route
                .candidates
                .iter()
                .any(|candidate| candidate.model_id == discovery_spoof_id),
            "a forged direct-provider discovery row must not enter trusted candidates: \
             {discovery_spoof_route:?}"
        );
        assert!(
            !discovery_spoof_route
                .fallbacks
                .iter()
                .any(|id| id == discovery_spoof_id),
            "a forged direct-provider discovery row must not enter trusted fallbacks: \
             {discovery_spoof_route:?}"
        );
    }

    #[test]
    fn openrouter_becomes_require_ready_eligible_after_live_key_activation() {
        let tmp = tempfile::tempdir().unwrap();
        let _credential_scope = crate::openrouter::test_credential_scope();
        let _provider_env = crate::openrouter::test_environment_scope();
        crate::openrouter::set_test_credential(None);
        let mut registry = UnifiedRegistry::new_empty(tmp.path().to_path_buf());
        let personal = crate::openrouter::curated_schemas()
            .into_iter()
            .find(|schema| schema.id == "openrouter/openai/gpt-5.4")
            .unwrap();
        registry.register_project_model(personal);

        unsafe {
            std::env::set_var("OPENAI_API_KEY", "ready-peer-key");
        }
        registry.register_project_model(remote_model(
            "ready-peer",
            "ready-peer",
            vec![ModelCapability::Generate, ModelCapability::Reasoning],
        ));

        crate::openrouter::set_test_credential(Some("activated-after-register"));
        let hint = crate::intent::IntentHint {
            require_ready: true,
            prefer_quality: true,
            ..Default::default()
        };
        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prefer_local: false,
                prior_strength: 1_000_000.0,
                ..RoutingConfig::default()
            },
        );
        let tracker = OutcomeTracker::new();
        let decision = router.route_with(RouteRequest {
            intent: Some(&hint),
            ..RouteRequest::new("Prove the architecture tradeoff.", &registry, &tracker)
        });
        assert!(
            decision
                .candidates
                .iter()
                .any(|candidate| candidate.model_id == "openrouter/openai/gpt-5.4"),
            "post-login OpenRouter model must remain require_ready-eligible: {:?}",
            decision.candidates
        );
        unsafe {
            std::env::remove_var("OPENAI_API_KEY");
        }
    }

    #[test]
    fn route_cost_score_uses_prompt_tiers_and_model_cache_prices() {
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let tracker = OutcomeTracker::new();
        let mut tiered = crate::openrouter::curated_schemas()
            .into_iter()
            .find(|schema| schema.id == "openrouter/openai/gpt-5.4")
            .unwrap();
        let mut flat = tiered.clone();
        tiered.id = "tiered".into();
        flat.id = "flat".into();
        flat.cost = crate::schema::CostModel {
            input_per_mtok: Some(4.0),
            output_per_mtok: Some(22.5),
            cache_read_input_per_mtok: Some(4.0),
            ..Default::default()
        };

        let score = |model: &ModelSchema, prompt, cache_read| {
            router.score_model(
                model,
                InferenceTask::Generate,
                &tracker,
                RoutingWorkload::Background,
                prompt,
                0,
                cache_read,
                0,
            )
        };
        assert!(score(&tiered, 100_000, 0) > score(&flat, 100_000, 0));
        assert!(score(&tiered, 300_000, 0) < score(&flat, 300_000, 0));
        assert!(score(&tiered, 300_000, 300_000) > score(&flat, 300_000, 300_000));
    }

    #[test]
    fn routes_simple_to_trusted_remote_during_cold_start() {
        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prior_strength: 100.0, // strong prior = exploit Phase 2 scores (deterministic-ish)
                ..Default::default()
            },
        );
        let reg = test_registry();
        let tracker = OutcomeTracker::new();

        let decision = router.route("What is 2+2?", &reg, &tracker);
        assert_eq!(decision.complexity, TaskComplexity::Simple);
        assert_eq!(decision.strategy, RoutingStrategy::SchemaBased);
        // On cold start, quality-critical tasks should stay on trusted remote models.
        let schema = reg
            .find_by_name(&decision.model_name)
            .expect("selected model should exist in registry");
        assert!(
            !schema.is_local(),
            "simple task should route to trusted remote model during cold start"
        );
        assert!(matches!(
            schema.provider.as_str(),
            "openai" | "anthropic" | "google"
        ));
    }

    #[test]
    fn routes_code_to_code_capable_remote_during_cold_start() {
        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prior_strength: 100.0, // strong prior = exploit Phase 2 scores (deterministic-ish)
                ..Default::default()
            },
        );
        let reg = test_registry();
        let tracker = OutcomeTracker::new();

        let decision = router.route(
            "Fix this function:\n```rust\nfn main() {}\n```",
            &reg,
            &tracker,
        );
        assert_eq!(decision.complexity, TaskComplexity::Code);
        assert_eq!(decision.task, InferenceTask::Code);
        // Must select a code-capable local model (not 0.6B which lacks Code)
        let schema = reg
            .find_by_name(&decision.model_name)
            .expect("model should exist");
        assert!(
            schema.has_capability(ModelCapability::Code),
            "selected model must support Code"
        );
        assert!(!schema.is_local(), "should route to trusted remote model");
    }

    #[test]
    fn routes_images_to_vision_capable_model() {
        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                // Concentrate the posterior so this contract test proves the
                // prior wiring rather than occasionally sampling a weaker arm.
                prior_strength: 1_000_000.0,
                ..Default::default()
            },
        );
        let mut reg = test_registry();
        let tracker = OutcomeTracker::new();

        reg.register_project_model(ModelSchema {
            id: "mlx-vlm/qwen3-vl-2b:bf16".into(),
            name: "Qwen3-VL-2B-mlx-vlm".into(),
            provider: "qwen".into(),
            family: "qwen3-vl".into(),
            version: "bf16".into(),
            capabilities: vec![
                ModelCapability::Generate,
                ModelCapability::Vision,
                ModelCapability::Grounding,
            ],
            context_length: 262_144,
            max_output_tokens: None,
            param_count: "2B".into(),
            quantization: None,
            performance: Default::default(),
            cost: Default::default(),
            source: crate::schema::ModelSource::Mlx {
                hf_repo: "Qwen/Qwen3-VL-2B-Instruct".into(),
                hf_weight_file: None,
            },
            tags: vec!["vision".into(), "mlx-vlm-cli".into()],
            supported_params: vec![],
            public_benchmarks: vec![],
            trust_tier: crate::schema::TrustTier::Curated,
            deprecated: false,
            available: true,
            weights_ready: true,
        });

        let decision = router.route_with_vision("What is in this image?", &reg, &tracker, false);
        let schema = reg
            .find_by_name(&decision.model_name)
            .expect("model should exist");
        assert!(
            schema.has_capability(ModelCapability::Vision),
            "selected model must support Vision"
        );
    }

    #[test]
    fn profile_based_routing_favors_proven_model() {
        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prior_strength: 0.5, // weak prior, let observed data dominate
                min_observations: 3,
                ..Default::default()
            },
        );
        let reg = test_registry();
        let mut tracker = OutcomeTracker::new();

        // Build a strong profile for Qwen3-8B on code tasks (fast + high quality)
        let qwen_8b_id = QWEN3_8B_ROUTED_ID;
        for _ in 0..20 {
            let trace = tracker.record_start(qwen_8b_id, InferenceTask::Code, "test");
            tracker.record_complete(&trace, 500, 100, 50);
            tracker.record_inferred_outcome(&trace, InferredOutcome::Accepted { confidence: 0.95 });
        }

        // Thompson Sampling is stochastic — run multiple times, 8B should win majority
        let mut wins = 0;
        for _ in 0..20 {
            let decision = router.route("Fix this bug in the parser", &reg, &tracker);
            assert_eq!(decision.complexity, TaskComplexity::Code);
            if decision.model_id == qwen_8b_id {
                wins += 1;
            }
        }
        assert!(
            wins >= 12,
            "proven model won only {wins}/20 times (expected >= 12)"
        );
    }

    #[test]
    fn proven_local_model_can_displace_bootstrap_remote() {
        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prior_strength: 100.0,
                bootstrap_min_task_observations: 6,
                bootstrap_quality_floor: 0.8,
                ..Default::default()
            },
        );
        let reg = test_registry();
        let mut tracker = OutcomeTracker::new();

        let qwen_8b_id = QWEN3_8B_ROUTED_ID;
        for _ in 0..12 {
            let trace = tracker.record_start(qwen_8b_id, InferenceTask::Generate, "test");
            tracker.record_complete(&trace, 300, 50, 20);
            tracker.record_inferred_outcome(&trace, InferredOutcome::Accepted { confidence: 0.95 });
        }

        let mut local_wins = 0;
        for _ in 0..20 {
            let decision = router.route("Summarize this design decision.", &reg, &tracker);
            let schema = reg
                .get(&decision.model_id)
                .expect("selected model should exist");
            if schema.is_local() {
                local_wins += 1;
            }
        }

        assert!(
            local_wins >= 12,
            "proven local model won only {local_wins}/20 times (expected >= 12)"
        );
    }

    /// Background routing keeps work on a local model.
    ///
    /// **Renamed from `benchmark_prior_informs_background_routing`, which is not
    /// what it tested** (car#751). That version seeded an outcome profile on
    /// qwen3-8b and asserted a local model won — but local wins here whether or
    /// not the profile is seeded, so the assertion never observed the prior.
    /// Removing the seeding entirely left the test passing. Measured over 2000
    /// draws per arm:
    ///
    /// ```text
    /// unseeded: gemma-4-12b 1578, qwen3-8b 348, qwen3-30b-a3b 55, qwen3-4b 15
    /// seeded:   gemma-4-12b 1576, qwen3-8b 325, qwen3-30b-a3b 84, qwen3-4b 11
    /// ```
    ///
    /// The seeded model does not gain; if anything it loses slightly, within
    /// noise. `prior_strength: 1_000_000.0` — set by the original test to
    /// "concentrate the posterior" — is precisely what makes a seeded outcome
    /// profile irrelevant, so the test defeated its own premise.
    ///
    /// What every draw *does* show is that background work stays local, which
    /// is a real contract worth holding, and is what this now asserts. Whether
    /// a benchmark prior can steer background routing is untested and, on this
    /// evidence, may not hold — tracked separately rather than asserted here.

    #[test]
    fn background_routing_prefers_local_models() {
        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prior_strength: 1_000_000.0,
                ..Default::default()
            },
        );
        let reg = test_registry();
        let tracker = OutcomeTracker::new();

        // Routing is Thompson sampling, so one draw is a sample, not a
        // contract — the single-draw form is what failed the 2026-07-31
        // nightly.
        //
        // The threshold is sized from the measured rate ON BOTH TARGETS, which
        // is what the first attempt at this fix got wrong: it required 38/40
        // after calibrating on Apple Silicon alone, where local wins 5000/5000.
        // Off Apple Silicon there is no MLX substitution and the rate is
        // 4812/5000 = 96.24%, so 38/40 allows at most 2 remote wins against a
        // mean of 1.5 — a **19% false-failure rate**, which duly failed CI.
        //
        // 170/200 instead: false failure 3e-11 at the measured rate, while a
        // regression to 80% local still fails 96% of the time. More draws buy
        // the discrimination that a loose threshold on few draws throws away.
        let draws = 200;
        let mut local_wins = 0;
        for _ in 0..draws {
            let decision = router.route_context_aware(
                "Write a Python fibonacci function.",
                128,
                &reg,
                &tracker,
                false,
                false,
                RoutingWorkload::Background,
            );
            let schema = reg
                .get(&decision.model_id)
                .expect("selected model should exist");
            if schema.is_local() {
                local_wins += 1;
            }
        }

        assert!(
            local_wins >= 170,
            "background routing should keep work local; local won only \
             {local_wins}/{draws} (measured baseline: 96.2% off Apple Silicon, \
             100% on it)"
        );
    }

    /// A benchmark/outcome prior **with its evidence** steers background
    /// routing — asserted differentially, so it cannot go vacuous (car#753).
    ///
    /// The predecessors of this test set `ema_quality` directly and left
    /// `prior_sample_size` / `quality_observations` at zero. The router reads
    /// an EMA together with the evidence behind it and, correctly, refuses to
    /// trust a number nothing supports — so those fixtures moved no score at
    /// all, and their `is_local()` assertions passed on models that were
    /// already winning. Measured, same prompt, `prior_strength: 100.0`:
    ///
    /// ```text
    /// no profile             qwen3-8b 1.32393
    /// ema 0.99, no evidence  qwen3-8b 1.32393   <- ignored, by design
    /// ema 0.99 + evidence    qwen3-8b 1.44354
    /// ema 0.05 + evidence    qwen3-8b 0.85854
    /// ```
    ///
    /// Asserted on the **score of the model the prior names**, not on which
    /// model ranks first: whether the prior changes the winner depends on the
    /// target — off Apple Silicon there is no MLX substitution and qwen3-8b
    /// already ranks first, so a "the top model changed" assertion fails there
    /// while the prior is working perfectly well. The score delta is the
    /// property; the ranking is a consequence of it.
    ///
    /// Scored from `candidates` — the deterministic surface — because the
    /// winner is Thompson-sampled and explores.
    #[test]
    fn benchmark_prior_with_evidence_steers_background_routing() {
        fn target_score(profile: Option<crate::outcome::ModelProfile>) -> f64 {
            let router = AdaptiveRouter::new(
                test_hw(),
                RoutingConfig {
                    prior_strength: 100.0,
                    ..Default::default()
                },
            );
            let reg = test_registry();
            let mut tracker = OutcomeTracker::new();
            if let Some(p) = profile {
                tracker.import_profiles(vec![p]);
            }
            let decision = router.route_context_aware(
                "Write a Python fibonacci function.",
                128,
                &reg,
                &tracker,
                false,
                false,
                RoutingWorkload::Background,
            );
            decision
                .candidates
                .iter()
                .find(|c| c.model_id == QWEN3_8B_ROUTED_ID)
                .unwrap_or_else(|| panic!("{QWEN3_8B_ROUTED_ID} should be a candidate"))
                .score
        }

        fn profile_with(ema: f64) -> crate::outcome::ModelProfile {
            let mut p = crate::outcome::ModelProfile::new(QWEN3_8B_ROUTED_ID.into());
            p.ema_quality = ema;
            // The evidence is what makes the EMA admissible. Without it the
            // router ignores the number — which is the whole reason the
            // predecessors tested nothing.
            p.prior_sample_size = 30;
            p.quality_observations = 30;
            p
        }

        let control = target_score(None);
        let good = target_score(Some(profile_with(0.99)));
        let bad = target_score(Some(profile_with(0.05)));

        assert!(
            good > control,
            "an evidence-backed good prior must raise the score it vouches for \
             ({good} vs control {control}); equal means this test would pass with \
             the prior wiring removed"
        );
        assert!(
            bad < control,
            "an evidence-backed poor prior must lower the score ({bad} vs \
             control {control})"
        );

        // An evidence-free EMA carries no information and must be ignored —
        // the behaviour that made the predecessors vacuous, pinned so a future
        // change cannot start trusting unsupported numbers silently.
        let mut unsupported = crate::outcome::ModelProfile::new(QWEN3_8B_ROUTED_ID.into());
        unsupported.ema_quality = 0.99;
        assert_eq!(
            target_score(Some(unsupported)),
            control,
            "an EMA with no observations behind it must not move the score"
        );
    }

    #[test]
    fn task_specific_benchmark_prior_informs_cold_start_routing() {
        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prior_strength: 100.0,
                ..Default::default()
            },
        );
        let reg = test_registry();
        let mut tracker = OutcomeTracker::new();
        // Seeded WITH its evidence counts, and against the id the router
        // actually reads on this target. Without the counts the router
        // correctly ignores the EMA, which left this test asserting an
        // outcome that was already true (car#753).
        let mut profile = crate::outcome::ModelProfile::new(QWEN3_8B_ROUTED_ID.into());
        profile.task_stats.insert(
            crate::outcome::InferenceTask::Code.to_string(),
            crate::outcome::TaskStats {
                ema_quality: 0.95,
                prior_sample_size: 30,
                quality_observations: 30,
                ..Default::default()
            },
        );
        tracker.import_profiles(vec![profile]);

        let decision = router.route_context_aware(
            "Write a Python fibonacci function.",
            128,
            &reg,
            &tracker,
            false,
            false,
            RoutingWorkload::Background,
        );

        // Selection uses Thompson sampling for Background work, so the winner
        // intentionally explores. The ranked candidates are the deterministic
        // score surface that proves the task-specific prior wiring.
        let top_scored = decision
            .candidates
            .first()
            .expect("routing should expose ranked candidates");
        let schema = reg
            .get(&top_scored.model_id)
            .expect("top-scored model should exist");
        assert!(
            schema.is_local(),
            "background routing should score the task-specific local code prior highest"
        );
    }

    #[test]
    fn task_specific_latency_prior_affects_cold_start_score() {
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let reg = test_registry();
        let model = reg
            .get("qwen/qwen3-8b:q4_k_m")
            .expect("local test model should exist");

        let mut fast_tracker = OutcomeTracker::new();
        let mut fast_profile = crate::outcome::ModelProfile::new(model.id.clone());
        fast_profile.task_stats.insert(
            crate::outcome::InferenceTask::Generate.to_string(),
            crate::outcome::TaskStats {
                ema_quality: 0.95,
                avg_latency_ms: 1200.0,
                ..Default::default()
            },
        );
        fast_tracker.import_profiles(vec![fast_profile]);

        let mut slow_tracker = OutcomeTracker::new();
        let mut slow_profile = crate::outcome::ModelProfile::new(model.id.clone());
        slow_profile.task_stats.insert(
            crate::outcome::InferenceTask::Generate.to_string(),
            crate::outcome::TaskStats {
                ema_quality: 0.95,
                avg_latency_ms: 120_000.0,
                ..Default::default()
            },
        );
        slow_tracker.import_profiles(vec![slow_profile]);

        let fast_score = router.score_model(
            model,
            InferenceTask::Generate,
            &fast_tracker,
            RoutingWorkload::Interactive,
            0,
            0,
            0,
            0,
        );
        let slow_score = router.score_model(
            model,
            InferenceTask::Generate,
            &slow_tracker,
            RoutingWorkload::Interactive,
            0,
            0,
            0,
            0,
        );

        assert!(
            fast_score > slow_score,
            "faster task latency prior should improve cold-start score ({fast_score} <= {slow_score})"
        );
    }

    #[test]
    fn interactive_workload_keeps_remote_bootstrap_bias() {
        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prior_strength: 100.0,
                ..Default::default()
            },
        );
        let reg = test_registry();
        let mut tracker = OutcomeTracker::new();
        let mut profile = crate::outcome::ModelProfile::new("qwen/qwen3-8b:q4_k_m".into());
        profile.ema_quality = 0.95;
        tracker.import_profiles(vec![profile]);

        let decision = router.route_context_aware(
            "Write a Python fibonacci function.",
            128,
            &reg,
            &tracker,
            false,
            false,
            RoutingWorkload::Interactive,
        );

        let schema = reg
            .get(&decision.model_id)
            .expect("selected model should exist");
        assert!(
            !schema.is_local(),
            "interactive routing should still prefer trusted remote models during cold start"
        );
    }

    #[test]
    fn code_interactive_weights_prioritise_quality_over_speed_over_cost() {
        // car-releases#52: task=code under the default interactive
        // workload must rank quality > speed > cost, with quality
        // clearly dominant — not the near-tie (0.45 q, 0.40 lat) the
        // generic interactive profile produces, which let a fast cheap
        // general model out-score a code-tuned one.
        let (q, lat, cost) =
            AdaptiveRouter::task_aware_weights(InferenceTask::Code, RoutingWorkload::Interactive);
        assert!(
            q > lat && lat > cost,
            "expected quality > speed > cost, got ({q}, {lat}, {cost})"
        );
        assert!(
            (q + lat + cost - 1.0).abs() < 1e-9,
            "weights must sum to 1.0"
        );
        let (default_q, default_lat, default_cost) = RoutingWorkload::Interactive.weights();
        assert!(
            q > default_q && lat < default_lat && cost < default_cost,
            "code weighting must lift quality and cut latency/cost vs the generic interactive profile"
        );

        // LocalPreferred is interactive-class — same code reweighting.
        assert_eq!(
            AdaptiveRouter::task_aware_weights(
                InferenceTask::Code,
                RoutingWorkload::LocalPreferred,
            ),
            (q, lat, cost),
        );

        // Fastest (voice fast-track) is an explicit hard-latency demand
        // — never overridden, even for code.
        assert_eq!(
            AdaptiveRouter::task_aware_weights(InferenceTask::Code, RoutingWorkload::Fastest),
            RoutingWorkload::Fastest.weights(),
        );
        // Batch/Background encode a deliberate non-interactive choice.
        assert_eq!(
            AdaptiveRouter::task_aware_weights(InferenceTask::Code, RoutingWorkload::Background),
            RoutingWorkload::Background.weights(),
        );
        // Non-code tasks are untouched under every workload.
        assert_eq!(
            AdaptiveRouter::task_aware_weights(
                InferenceTask::Generate,
                RoutingWorkload::Interactive,
            ),
            RoutingWorkload::Interactive.weights(),
        );
    }

    #[test]
    fn fallback_chain_has_alternatives() {
        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prior_strength: 100.0, // strong prior = exploit Phase 2 scores (deterministic-ish)
                ..Default::default()
            },
        );
        let reg = test_registry();
        let tracker = OutcomeTracker::new();

        let decision = router.route("Analyze the architecture trade-offs", &reg, &tracker);
        assert!(!decision.fallbacks.is_empty());
        // Primary should not appear in fallbacks
        assert!(!decision.fallbacks.contains(&decision.model_id));
    }

    #[test]
    fn latency_scoring_is_consistent() {
        // Verify that schema and observed latency produce comparable scores
        let router = AdaptiveRouter::with_default_config(test_hw());

        // A model at 25 TPS → ~200/25*1000 = 8000ms → score = 1 - 8000/10000 = 0.2
        let schema_score = router.latency_ms_to_score(AdaptiveRouter::tps_to_latency_ms(25.0));
        // Same model observed at 8000ms → same formula
        let observed_score = router.latency_ms_to_score(8000.0);
        assert!(
            (schema_score - observed_score).abs() < 0.01,
            "schema ({schema_score}) and observed ({observed_score}) should match"
        );
    }

    #[test]
    fn complexity_assessment() {
        assert_eq!(
            TaskComplexity::assess("What is the capital of France?"),
            TaskComplexity::Simple
        );
        assert_eq!(
            TaskComplexity::assess("Fix this broken test"),
            TaskComplexity::Code
        );
        assert_eq!(
            TaskComplexity::assess("Analyze the trade-offs between A and B"),
            TaskComplexity::Complex
        );
    }

    #[test]
    fn beta_sampling_produces_valid_values() {
        let mut rng = rand::rng();
        // Sample 100 times from Beta(2, 5) — should be in [0, 1]
        for _ in 0..100 {
            let s = sample_beta(&mut rng, 2.0, 5.0);
            assert!((0.0..=1.0).contains(&s), "sample {s} out of [0,1] range");
        }
        // Beta(1, 1) = Uniform(0, 1) — mean should be ~0.5
        let samples: Vec<f64> = (0..1000).map(|_| sample_beta(&mut rng, 1.0, 1.0)).collect();
        let mean = samples.iter().sum::<f64>() / samples.len() as f64;
        assert!(
            (mean - 0.5).abs() < 0.05,
            "Beta(1,1) mean {mean} should be ~0.5"
        );
    }

    #[test]
    fn thompson_sampling_converges_to_best() {
        // A model with strong observed success should win most of the time
        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prior_strength: 1.0, // weak prior, let observations dominate
                ..Default::default()
            },
        );
        let reg = test_registry();
        let mut tracker = OutcomeTracker::new();

        // Give Qwen3-4B 20 successes (strong signal)
        let qwen_4b_id = QWEN3_4B_ROUTED_ID;
        for _ in 0..20 {
            let trace = tracker.record_start(qwen_4b_id, InferenceTask::Code, "test");
            tracker.record_complete(&trace, 500, 100, 50);
            tracker.record_inferred_outcome(&trace, InferredOutcome::Accepted { confidence: 0.95 });
        }

        // Route 20 code tasks — strong model should win the majority
        let mut wins = 0;
        for _ in 0..20 {
            let decision = router.route("Fix this parser bug", &reg, &tracker);
            if decision.model_id == qwen_4b_id {
                wins += 1;
            }
        }
        assert!(
            wins >= 14,
            "strong model won only {wins}/20 times (expected >= 14)"
        );
    }

    // ----- Intent surface (parslee-ai/car-releases#18) -----

    #[test]
    fn cold_start_never_returns_a_model_lacking_a_required_capability() {
        // The regression: a `require: [Code]` request whose hard filter left
        // no candidate used to fall to the complexity→model default
        // (Simple → Qwen3-0.6B), which has NO Code capability — silently
        // violating the hard filter. Drive cold_start directly with
        // quality-first disabled (so the trusted-remote branch is skipped and
        // the local/default path is exercised) and assert the chosen model
        // actually satisfies the requirement.
        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                quality_first_cold_start: false,
                ..Default::default()
            },
        );
        let reg = test_registry();

        for caps in [
            vec![ModelCapability::Code],
            vec![ModelCapability::Code, ModelCapability::ToolUse],
        ] {
            // Simple complexity is the worst case — its default (Qwen3-0.6B)
            // lacks Code and ToolUse, so a pre-fix cold start would return it.
            let decision = router.cold_start_decision(
                TaskComplexity::Simple,
                InferenceTask::Code,
                &caps,
                &reg,
                false,
                &std::collections::HashSet::new(),
                false,
                AvailabilitySnapshot::capture(&reg),
            );
            let chosen = reg
                .find_by_name(&decision.model_name)
                .or_else(|| reg.list().into_iter().find(|m| m.id == decision.model_id))
                .unwrap_or_else(|| panic!("cold start named an unknown model: {decision:?}"));
            for cap in &caps {
                assert!(
                    chosen.has_capability(*cap),
                    "cold start chose {} which lacks required {:?} (caps {:?})",
                    chosen.name,
                    cap,
                    caps
                );
            }
            // It resolved via a capability-satisfying cold-start branch, not the
            // hardcoded complexity default. [Code] is satisfied locally; [Code,
            // ToolUse] is no longer locally satisfiable (in-process backends
            // can't execute tool calls) so it resolves to the available remote
            // tool-capable model — either way a capability-satisfying branch,
            // never a cap-lacking default.
            assert_eq!(
                decision.strategy,
                RoutingStrategy::SchemaBased,
                "expected schema-based cold start"
            );
            assert!(
                decision.reason.contains("capability-satisfying"),
                "expected a capability-satisfying cold-start branch, got: {}",
                decision.reason
            );
        }
    }

    #[test]
    fn cold_start_skips_a_capable_local_that_exceeds_the_memory_budget() {
        // A capability-satisfying local that doesn't FIT must not be chosen by
        // the local branch — the strict `< max_model_mb` gate mirrors
        // filter_candidates. With a tiny budget no local fits, so cold start
        // falls through to the hardcoded default (best-effort handoff).
        let mut hw = test_hw();
        hw.max_model_mb = 300; // below every Qwen3 local
        let router = AdaptiveRouter::new(
            hw,
            RoutingConfig {
                quality_first_cold_start: false,
                ..Default::default()
            },
        );
        let reg = test_registry();
        let decision = router.cold_start_decision(
            TaskComplexity::Code,
            InferenceTask::Code,
            &[ModelCapability::Code],
            &reg,
            false,
            &std::collections::HashSet::new(),
            false,
            AvailabilitySnapshot::capture(&reg),
        );
        assert!(
            !decision.reason.contains("local cold start"),
            "no local fits the 300MB budget, so the local branch must not fire: {}",
            decision.reason
        );
    }

    #[test]
    fn intent_require_filters_out_models_lacking_capability() {
        // Asking for vision when no candidate has it should fall to
        // the cold-start decision rather than scoring incompatible
        // candidates. The fixture registry has no vision-capable
        // local models.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let reg = test_registry();
        let tracker = OutcomeTracker::new();

        let intent = crate::intent::IntentHint {
            require: vec![ModelCapability::Vision],
            ..Default::default()
        };
        let decision = router.route_with_intent("hello", &reg, &tracker, &intent);

        // When require filters out every candidate, the router falls
        // to the schema-based cold-start path. Asserting the strategy
        // (not just non-empty model_id) catches a regression where
        // future code might silently include filtered candidates.
        assert_eq!(
            decision.strategy,
            RoutingStrategy::SchemaBased,
            "require=[vision] with no vision-capable candidates must drop to schema cold-start"
        );
    }

    #[test]
    fn unbenchmarked_remote_is_conservative_not_assumed_frontier() {
        // Conservative-unknown design: an UNMEASURED curated remote is no
        // longer assumed frontier-class. It scores a conservative 0.60 —
        // routable, above the capped local size-heuristics, but below the
        // measured-frontier band — so a model carrying REAL benchmarks ranks
        // above it on evidence.
        // (Replaces the old "benchmark-less remote == 0.85 frontier" rule,
        // under which honest hard-benchmark data demoted strong models below
        // unmeasured ones — see the doc note.)
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let reg = test_registry();
        let remote = reg
            .list()
            .into_iter()
            .find(|m| m.is_remote() && m.public_benchmarks.is_empty())
            .expect("a benchmark-less remote in the fixture")
            .clone();
        let q = router.schema_quality_estimate(&remote);
        assert!(
            (q - 0.60).abs() < 1e-9,
            "unmeasured curated remote should be a conservative 0.60, got {q}"
        );

        // A model carrying published benchmarks (uncalibrated names → raw
        // passthrough) uses their average, which for a strong model lands above
        // the unmeasured default.
        let mut benched = remote.clone();
        benched.public_benchmarks = vec![
            crate::schema::BenchmarkScore {
                name: "A".into(),
                score: 0.9,
                harness: None,
                source_url: None,
                measured_at: None,
            },
            crate::schema::BenchmarkScore {
                name: "B".into(),
                score: 0.7,
                harness: None,
                source_url: None,
                measured_at: None,
            },
        ];
        let qb = router.schema_quality_estimate(&benched);
        assert!((qb - 0.8).abs() < 1e-9);
        assert!(
            qb > q,
            "real benchmarks must lift a model above the unmeasured default"
        );
    }

    #[test]
    fn calibrated_benchmark_is_normalized_onto_the_tier_scale() {
        // A hard agentic benchmark's raw score is remapped onto the quality
        // tier so frontier-class lands near the top — NOT taken raw (which
        // would rank a measured frontier model below an unmeasured local).
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let bench = |raw: f64| {
            let mut m = outcome_model("m", None);
            m.public_benchmarks = vec![crate::schema::BenchmarkScore {
                name: "tau-bench-airline".into(),
                score: raw,
                harness: None,
                source_url: None,
                measured_at: None,
            }];
            router.schema_quality_estimate(&m)
        };
        // frontier_ref 0.65 → FLOOR 0.40, CEIL 0.92.
        let frontier = bench(0.65); // → ~0.92
        let strong = bench(0.35); // gpt-5.4-class → ~0.68
        assert!(
            (frontier - 0.92).abs() < 0.01,
            "best-in-class → ~CEIL, got {frontier}"
        );
        assert!(
            (strong - 0.68).abs() < 0.02,
            "0.35 raw → ~0.68 tier, got {strong}"
        );
        assert!(
            strong > router.schema_quality_estimate(&local_model("local-30b", 18_000)),
            "a measured frontier model must out-rank an unmeasured 30B local"
        );
    }

    #[test]
    fn uncalibrated_benchmark_is_clamped_into_the_tier_band() {
        // A benchmark with no frontier reference can't be scaled, so it's
        // clamped into [FLOOR, CEIL] rather than passed through raw — a raw
        // hard-benchmark score below FLOOR would re-invert the scale.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let q = |raw: f64| {
            let mut m = outcome_model("m", None);
            m.public_benchmarks = vec![crate::schema::BenchmarkScore {
                name: "some-new-unknown-bench".into(),
                score: raw,
                harness: None,
                source_url: None,
                measured_at: None,
            }];
            router.schema_quality_estimate(&m)
        };
        // In-band value untouched; a sub-floor raw is lifted to FLOOR, not left
        // below the measured band where it would undercut a 30B local.
        assert!((q(0.73) - 0.73).abs() < 1e-9);
        assert!((q(0.10) - AdaptiveRouter::BENCH_TIER_FLOOR).abs() < 1e-9);
        assert!((q(0.99) - AdaptiveRouter::BENCH_TIER_CEIL).abs() < 1e-9);
    }

    #[test]
    fn local_uncalibrated_benchmark_maps_into_the_local_tier_band() {
        // A LOCAL model's self-measured (frontier-less) benchmark must map into
        // the LOCAL sub-band [0.30, 0.60], NOT the measured-frontier band — its
        // raw score on an unanchored suite isn't comparable to a frontier-
        // calibrated score (the monoculture trap). It replaces the size proxy
        // for ordering locals, but stays below the frontier band (#368).
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let q = |raw: f64| {
            let mut m = local_model("local-bench", 2500); // a 4B-class local
            m.public_benchmarks = vec![crate::schema::BenchmarkScore {
                name: "car-agentic-suite".into(), // not in catalog → uncalibrated
                score: raw,
                harness: None,
                source_url: None,
                measured_at: None,
            }];
            router.schema_quality_estimate(&m)
        };
        // In-band raw passes through; extremes clamp to the LOCAL band, never the
        // frontier band. A perfect local-suite score tops out at LOCAL_CEIL (0.60),
        // strictly below frontier best-in-class (CEIL 0.92).
        assert!(
            (q(0.45) - 0.45).abs() < 1e-9,
            "in-band local score passes through"
        );
        assert!(
            (q(0.05) - AdaptiveRouter::LOCAL_BENCH_TIER_FLOOR).abs() < 1e-9,
            "sub-floor clamps to LOCAL floor 0.30, not frontier FLOOR 0.40"
        );
        assert!(
            (q(0.95) - AdaptiveRouter::LOCAL_BENCH_TIER_CEIL).abs() < 1e-9,
            "a perfect local-suite score tops at LOCAL ceil 0.60, not frontier CEIL 0.92"
        );
        // Discrimination: a higher measured score ranks higher within the tier.
        assert!(q(0.55) > q(0.35));
        // Invariant: a measured local never reaches the frontier band's reach —
        // a benchmarked frontier model (tau-bench champion → ~CEIL) still wins.
        let mut frontier = outcome_model("frontier", None);
        frontier.public_benchmarks = vec![crate::schema::BenchmarkScore {
            name: "tau-bench-airline".into(),
            score: 0.65,
            harness: None,
            source_url: None,
            measured_at: None,
        }];
        assert!(
            router.schema_quality_estimate(&frontier) > q(0.95),
            "a benchmarked frontier model out-ranks even a perfect-scoring local"
        );
    }

    #[test]
    fn frontier_ref_is_derived_from_catalog_best_in_class() {
        // The frontier reference is the best score any catalog model reaches on
        // a benchmark — derived, not hardcoded. Every catalog benchmark thus has
        // a reference automatically (no "forgot to register it" footgun), and it
        // equals the observed max.
        use std::collections::HashMap;
        let mut max_by_bench: HashMap<String, f64> = HashMap::new();
        for model in crate::registry::builtin_catalog() {
            for b in &model.public_benchmarks {
                let e = max_by_bench.entry(b.name.clone()).or_insert(0.0);
                *e = e.max(b.score);
            }
        }
        assert!(!max_by_bench.is_empty(), "catalog should carry benchmarks");
        for (name, max) in max_by_bench {
            let derived = AdaptiveRouter::benchmark_frontier_ref(&name)
                .unwrap_or_else(|| panic!("benchmark '{name}' must derive a frontier_ref"));
            assert!(
                (derived - max).abs() < 1e-9,
                "frontier_ref for '{name}' should be the catalog max {max}, got {derived}"
            );
        }
        // Concretely, today: tau-bench-airline tops out at 0.65.
        assert_eq!(
            AdaptiveRouter::benchmark_frontier_ref("tau-bench-airline"),
            Some(0.65)
        );
        // A benchmark no catalog model carries → no reference → clamp path.
        assert_eq!(
            AdaptiveRouter::benchmark_frontier_ref("nonexistent-bench"),
            None
        );
    }

    // ---- #371: frontier-less-population guard --------------------------------

    /// Build a benchmarked model fixture with an explicit frontier-class flag.
    fn benchmarked_model(id: &str, bench: &str, score: f64, frontier: bool) -> ModelSchema {
        let mut m = outcome_model(id, None);
        if frontier {
            m.tags.push("frontier".into());
        }
        m.public_benchmarks = vec![crate::schema::BenchmarkScore {
            name: bench.into(),
            score,
            harness: None,
            source_url: None,
            measured_at: None,
        }];
        m
    }

    #[test]
    fn frontier_ref_guard_drops_frontier_less_benchmark() {
        // A benchmark carried ONLY by non-frontier models must NOT self-anchor:
        // its best score is not a trustworthy frontier, so it gets no reference
        // (→ uncalibrated clamp) rather than inflating the mid-tier champion to
        // CEIL. (#371)
        let models = [
            benchmarked_model("mid-a", "midtier-only-bench", 0.50, false),
            benchmarked_model("mid-b", "midtier-only-bench", 0.40, false),
        ];
        let refs = compute_frontier_refs(models.iter());
        assert!(
            !refs.contains_key("midtier-only-bench"),
            "a benchmark with no frontier-class carrier must not self-anchor, got {refs:?}"
        );
    }

    #[test]
    fn frontier_ref_guard_anchors_when_a_frontier_model_carries_the_benchmark() {
        // Add one frontier-class carrier and the same benchmark anchors — at the
        // true catalog max (the champion score), NOT a percentile. The non-
        // frontier model scoring higher than the frontier one still sets the
        // anchor (max), so the ordering signal is preserved (#371).
        let models = [
            benchmarked_model("frontier-x", "shared-bench", 0.60, true),
            benchmarked_model("mid-y", "shared-bench", 0.70, false),
        ];
        let refs = compute_frontier_refs(models.iter());
        assert_eq!(
            refs.get("shared-bench").copied(),
            Some(0.70),
            "anchor is the catalog max across all carriers once a frontier carrier exists"
        );
    }

    #[test]
    fn frontier_ref_guard_is_noop_on_todays_catalog() {
        // The guard must not change today's behavior: every benchmark the real
        // catalog carries has a frontier-class carrier, so the guarded table
        // equals the raw max-per-benchmark table. This pins the "holds by
        // accident of composition" property as an explicit invariant (#371).
        use std::collections::HashMap;
        let catalog = crate::registry::builtin_catalog();
        let mut raw_max: HashMap<String, f64> = HashMap::new();
        for m in &catalog {
            for b in &m.public_benchmarks {
                let e = raw_max.entry(b.name.clone()).or_insert(0.0);
                *e = e.max(b.score);
            }
        }
        let guarded = compute_frontier_refs(catalog.iter());
        assert_eq!(
            raw_max, guarded,
            "guard dropped a benchmark — a catalog benchmark lost its frontier-class carrier"
        );
        assert!(
            model_is_frontier_class(
                catalog
                    .iter()
                    .find(|m| m.id == "anthropic/claude-opus-4-7:latest")
                    .expect("opus-4-7 in catalog")
            ),
            "the tau-bench-airline champion must be frontier-tagged for the anchor to be valid"
        );
    }

    #[test]
    fn score_above_the_frontier_clamps_to_ceil() {
        // A model scoring above the current best-in-class (the frontier moved
        // but the catalog hasn't caught up) maps to CEIL — it ranks at the top,
        // it just can't out-scale the champion until the catalog re-anchors.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let mut m = outcome_model("future-sota", None);
        m.public_benchmarks = vec![crate::schema::BenchmarkScore {
            name: "tau-bench-airline".into(),
            score: 0.80, // above the catalog max 0.65
            harness: None,
            source_url: None,
            measured_at: None,
        }];
        assert!(
            (router.schema_quality_estimate(&m) - AdaptiveRouter::BENCH_TIER_CEIL).abs() < 1e-9,
            "above-frontier score should clamp to CEIL"
        );
    }

    #[test]
    fn local_size_heuristic_stays_below_measured_frontier_floor() {
        // The cap invariant: every local size bracket sits at/below the bottom
        // of the measured-benchmark band, so no unmeasured local can out-rank a
        // benchmarked frontier model on the quality term.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        for size_mb in [500u64, 1500, 2500, 4500, 18_000] {
            let q = router.schema_quality_estimate(&local_model("local", size_mb));
            assert!(
                q <= AdaptiveRouter::BENCH_TIER_FLOOR + 0.21, // 30B cap 0.60 = FLOOR+0.20
                "local {size_mb}MB quality {q} must stay near/below the measured floor"
            );
        }
    }

    #[test]
    fn community_remote_quality_is_damped_below_curated() {
        // An auto-discovered (Community) benchmark-less remote is damped to
        // 0.48 — below the conservative 0.60 an unmeasured CURATED remote gets
        // — so it stays routable but can't out-rank vetted models until it has
        // real benchmarks or outcomes.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let reg = test_registry();
        let mut remote = reg
            .list()
            .into_iter()
            .find(|m| m.is_remote() && m.public_benchmarks.is_empty())
            .expect("a benchmark-less remote in the fixture")
            .clone();

        // As curated → conservative 0.60 (unmeasured, not assumed frontier).
        remote.trust_tier = crate::schema::TrustTier::Curated;
        let qc = router.schema_quality_estimate(&remote);
        assert!(
            (qc - 0.60).abs() < 1e-9,
            "curated unmeasured remote should be 0.60, got {qc}"
        );

        // As Community (discovered) → damped further, strictly below curated.
        remote.trust_tier = crate::schema::TrustTier::Community;
        let q = router.schema_quality_estimate(&remote);
        assert!(
            (q - 0.48).abs() < 1e-9,
            "community remote should be damped to 0.48, got {q}"
        );
        assert!(
            q < qc,
            "community remote must rank below an unmeasured curated remote"
        );
    }

    #[test]
    fn quality_workload_is_quality_dominant() {
        // The knob's contract: quality dominates, latency + cost near floor —
        // the inverse of Fastest, so the most capable model wins on score.
        let (q, lat, cost) = RoutingWorkload::Quality.weights();
        assert!(
            (q + lat + cost - 1.0).abs() < 1e-9,
            "weights must sum to 1.0"
        );
        assert!(q >= 0.8, "quality must dominate, got {q}");
        assert!(
            lat <= 0.1 && cost <= 0.15,
            "latency/cost near floor: {lat}/{cost}"
        );
        // Strictly more quality-weighted than every other workload.
        for w in [
            RoutingWorkload::Interactive,
            RoutingWorkload::Batch,
            RoutingWorkload::Background,
            RoutingWorkload::LocalPreferred,
            RoutingWorkload::Fastest,
        ] {
            assert!(
                q > w.weights().0,
                "Quality must out-weight {w:?} on quality"
            );
        }
    }

    #[test]
    fn prefer_quality_scores_the_more_capable_model_higher() {
        // Deterministic at the scoring layer (no Thompson noise): under the
        // Quality workload a bigger/more-capable code model out-scores a small
        // cheap one, so prefer_quality picks it. The shakedown's failure mode
        // was the cheap Qwen3-1.7B winning on cost over the capable 4B.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let reg = test_registry();
        let tracker = OutcomeTracker::new();
        let small = reg
            .find_by_name("Qwen3-1.7B")
            .expect("1.7B in fixture")
            .clone();
        let big = reg.find_by_name("Qwen3-4B").expect("4B in fixture").clone();
        assert!(small.has_capability(ModelCapability::Code));
        assert!(big.has_capability(ModelCapability::Code));

        let score = |m: &ModelSchema, w: RoutingWorkload| {
            router.score_model(m, InferenceTask::Code, &tracker, w, 0, 0, 0, 0)
        };
        // Under Quality, the capable model wins decisively.
        assert!(
            score(&big, RoutingWorkload::Quality) > score(&small, RoutingWorkload::Quality),
            "prefer_quality must rank the capable 4B above the cheap 1.7B"
        );
    }

    /// A local MLX model (is_mlx() && is_local()) whose cold-start quality is
    /// driven by `benchmark` — for exercising the Apple-Silicon locality bonus.
    fn local_mlx_model(id: &str, benchmark: Option<f64>) -> ModelSchema {
        let mut m = outcome_model(id, benchmark);
        m.provider = "local".into();
        m.source = crate::schema::ModelSource::Mlx {
            hf_repo: "mlx-community/test".into(),
            hf_weight_file: None,
        };
        m
    }

    #[test]
    fn quality_workload_suppresses_local_mlx_bonus_vs_capable_remote() {
        // Regression: on Apple Silicon a small local MLX model got +0.25
        // unconditionally (LOCAL_BONUS 0.15 + MLX_BONUS 0.10), letting it
        // out-*bonus* a more capable remote under prefer_quality — the router
        // then picked it and it OOM'd on a large prompt it couldn't fit.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let tracker = OutcomeTracker::new();
        let score = |m: &ModelSchema, w: RoutingWorkload| {
            router.score_model(m, InferenceTask::Code, &tracker, w, 0, 0, 0, 0)
        };

        let remote_capable = outcome_model("remote/frontier", Some(0.85));
        let mlx_tiny = local_mlx_model("mlx/tiny", Some(0.55));
        // Same quality as the MLX model, but remote → no locality bonus.
        let remote_peer = outcome_model("remote/peer", Some(0.55));
        assert!(mlx_tiny.is_mlx() && mlx_tiny.is_local());

        // A latency-tolerant workload keeps the bonus: the MLX model out-scores
        // an equal-quality remote purely on the locality/MLX bonus. This proves
        // the bonus is real and still active where it belongs.
        assert!(
            score(&mlx_tiny, RoutingWorkload::Background)
                > score(&remote_peer, RoutingWorkload::Background),
            "the local/MLX bonus should still apply on non-Quality workloads"
        );

        // Under Quality the bonus is suppressed, so the more capable remote
        // wins — the tiny local MLX no longer gets a free +0.25 thumb.
        assert!(
            score(&remote_capable, RoutingWorkload::Quality)
                > score(&mlx_tiny, RoutingWorkload::Quality),
            "prefer_quality must suppress the locality bonus so the capable remote wins"
        );
    }

    // --- outcome-first reliability band (Task 5) ---

    /// A local (GGUF) model of the given size, no benchmarks — exercises the
    /// capped size-heuristic branch of `schema_quality_estimate`.
    fn local_model(id: &str, size_mb: u64) -> ModelSchema {
        let mut m = outcome_model(id, None);
        m.provider = "local".into();
        m.source = crate::schema::ModelSource::Local {
            hf_repo: "test/repo".into(),
            hf_filename: "model.gguf".into(),
            tokenizer_repo: "test/repo".into(),
        };
        m.cost.size_mb = Some(size_mb);
        m
    }

    /// The MoE discount exists for hand-seeded rates. A row carrying a measured
    /// decode rate — marked by the `latency_p50_ms` that
    /// `scripts/bench-consolidate.py` only writes beside one — must be scored
    /// at what was measured, not at a tenth of it.
    ///
    /// Rates are chosen above `LATENCY_CEILING_MS`'s cutoff (~20 tok/s for the
    /// 200-token baseline) because that is where the bug is observable. Below
    /// it both scores clamp to 0, which is why the catalog's one currently
    /// measured MoE row (`mlx/qwen3-30b-a3b:4bit`, 7.8 tok/s) was mis-scored
    /// without anything downstream noticing.
    #[test]
    fn a_measured_moe_rate_is_not_discounted_again() {
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());

        let mut measured = local_model("local/moe-measured", 17_000);
        measured.tags.push("moe".into());
        measured.performance.tokens_per_second = Some(35.0);
        measured.performance.latency_p50_ms = Some(1_200);

        // Same rate, no measurement provenance: still a declared estimate.
        let mut declared = local_model("local/moe-declared", 17_000);
        declared.tags.push("moe".into());
        declared.performance.tokens_per_second = Some(35.0);

        // The yardstick: a dense model at the same rate is never discounted.
        let mut dense = local_model("local/dense", 17_000);
        dense.performance.tokens_per_second = Some(35.0);
        dense.performance.latency_p50_ms = Some(1_200);

        let measured_score = router.schema_latency_estimate(&measured);
        let declared_score = router.schema_latency_estimate(&declared);
        let dense_score = router.schema_latency_estimate(&dense);

        assert_eq!(
            measured_score, dense_score,
            "a measured MoE rate must score as the rate it measured"
        );
        assert!(
            declared_score < measured_score,
            "a declared MoE rate still gets the discount: {declared_score} vs {measured_score}"
        );
    }

    /// A curated remote whose cold-start reliability equals `benchmark`
    /// (schema_quality_estimate averages public_benchmarks). Empty `benchmarks`
    /// → the conservative 0.60 unmeasured default.
    fn outcome_model(id: &str, benchmark: Option<f64>) -> ModelSchema {
        ModelSchema {
            id: id.into(),
            name: id.into(),
            provider: "openai".into(),
            family: "test".into(),
            version: "latest".into(),
            capabilities: vec![
                ModelCapability::Generate,
                ModelCapability::Code,
                ModelCapability::Reasoning,
            ],
            context_length: 128_000,
            max_output_tokens: None,
            param_count: "api".into(),
            quantization: None,
            performance: Default::default(),
            cost: Default::default(),
            source: crate::schema::ModelSource::RemoteApi {
                endpoint: "https://api.openai.com/v1".into(),
                api_key_env: "OPENAI_API_KEY".into(),
                api_key_envs: vec![],
                api_version: None,
                protocol: crate::schema::ApiProtocol::OpenAiCompat,
            },
            tags: vec![],
            supported_params: vec![],
            public_benchmarks: benchmark
                .map(|s| {
                    vec![crate::schema::BenchmarkScore {
                        name: "t".into(),
                        score: s,
                        harness: None,
                        source_url: None,
                        measured_at: None,
                    }]
                })
                .unwrap_or_default(),
            trust_tier: crate::schema::TrustTier::Curated,
            deprecated: false,
            available: true,
            weights_ready: true,
        }
    }

    #[test]
    fn reliability_band_applies_to_quality_and_substantive_normal_lanes() {
        use RoutingWorkload as W;
        // Substantive tasks on normal lanes → band.
        assert!(AdaptiveRouter::applies_reliability_band(
            InferenceTask::Code,
            W::Interactive
        ));
        assert!(AdaptiveRouter::applies_reliability_band(
            InferenceTask::Reasoning,
            W::Batch
        ));
        // Quality lane → ALWAYS bands (so its argmax can't pick a low-quality
        // model on bonuses), even on a trivial task.
        assert!(AdaptiveRouter::applies_reliability_band(
            InferenceTask::Code,
            W::Quality
        ));
        assert!(AdaptiveRouter::applies_reliability_band(
            InferenceTask::Generate,
            W::Quality
        ));
        // Trivial task on a normal lane → no band (cheap is fine).
        assert!(!AdaptiveRouter::applies_reliability_band(
            InferenceTask::Generate,
            W::Interactive
        ));
        // Explicit cost/latency/local preferences → no band (subsumption).
        assert!(!AdaptiveRouter::applies_reliability_band(
            InferenceTask::Code,
            W::Background
        ));
        assert!(!AdaptiveRouter::applies_reliability_band(
            InferenceTask::Code,
            W::Fastest
        ));
        // LocalPreferred MUST skip the band — honor the explicit local request.
        assert!(!AdaptiveRouter::applies_reliability_band(
            InferenceTask::Code,
            W::LocalPreferred
        ));
    }

    #[test]
    fn high_stakes_intent_forces_quality_over_everything() {
        use crate::intent::IntentHint;
        // high_stakes wins even when prefer_fast AND prefer_local are also set —
        // never economize on a consequential/irreversible operation.
        let hs = IntentHint {
            high_stakes: true,
            prefer_fast: true,
            prefer_local: true,
            ..Default::default()
        };
        assert_eq!(
            AdaptiveRouter::resolve_workload(Some(&hs), RoutingWorkload::Interactive),
            RoutingWorkload::Quality
        );
        // Without stakes, the existing precedence stands (prefer_fast wins).
        let f = IntentHint {
            prefer_fast: true,
            ..Default::default()
        };
        assert_eq!(
            AdaptiveRouter::resolve_workload(Some(&f), RoutingWorkload::Interactive),
            RoutingWorkload::Fastest
        );
        // No intent → the request's base workload is used unchanged.
        assert_eq!(
            AdaptiveRouter::resolve_workload(None, RoutingWorkload::Batch),
            RoutingWorkload::Batch
        );
    }

    #[test]
    fn band_excludes_a_real_quality_gap_even_if_cheaper() {
        // neo property 1: a 0.07 reliability gap must NOT be flippable by cost.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let tracker = OutcomeTracker::new();
        let strong = outcome_model("strong", Some(0.90));
        let weak_cheap = outcome_model("weak-cheap", Some(0.83));
        let band =
            router.outcome_first_band(vec![strong, weak_cheap], InferenceTask::Code, &tracker);
        assert_eq!(
            band.len(),
            1,
            "0.07 gap (> band 0.02) must drop the weaker model"
        );
        assert_eq!(band[0].id, "strong");
    }

    #[test]
    fn band_keeps_genuinely_near_equal_models() {
        // Within ε → both eligible; cost/latency/Thompson decide downstream.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let tracker = OutcomeTracker::new();
        let band = router.outcome_first_band(
            vec![
                outcome_model("a", Some(0.90)),
                outcome_model("a2", Some(0.89)),
            ],
            InferenceTask::Code,
            &tracker,
        );
        assert_eq!(
            band.len(),
            2,
            "0.01 gap (<= band 0.02) keeps both for tie-break"
        );
    }

    #[test]
    fn band_cold_start_frontier_beats_cheap_unknown() {
        // neo property 2: a benchmarked frontier must beat an unmeasured remote
        // (conservative 0.60) — the band doesn't collapse to pure cost at cold start.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let tracker = OutcomeTracker::new();
        let band = router.outcome_first_band(
            vec![
                outcome_model("frontier", Some(0.85)),
                outcome_model("unknown", None),
            ],
            InferenceTask::Code,
            &tracker,
        );
        assert_eq!(band.len(), 1);
        assert_eq!(
            band[0].id, "frontier",
            "0.85 vs 0.60 unknown → unknown excluded"
        );
    }

    #[test]
    fn quality_lane_bands_out_a_weak_local_but_local_preferred_keeps_it() {
        // The end-to-end #Q4 fix: on prefer_quality, a benchmarked frontier
        // remote must win — a weaker local must be EXCLUDED from the selection
        // band so it can't float up on local/MLX bonuses. The explicit
        // LocalPreferred lane, by contrast, must NOT band the local out.
        // test_registry has available local Qwen models (fake GGUF dirs) plus
        // an OpenAI remote; add a benchmarked frontier that tops the tier.
        let mut reg = test_registry();
        let mut frontier = outcome_model("frontier-remote", None);
        frontier.public_benchmarks = vec![crate::schema::BenchmarkScore {
            name: "tau-bench-airline".into(),
            score: 0.65, // → ~0.92 tier, the unique top
            harness: None,
            source_url: None,
            measured_at: None,
        }];
        reg.register_project_model(frontier);

        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let tracker = OutcomeTracker::new();
        let prompt = "Implement a balanced binary search tree with deletion.";

        // prefer_quality: the benchmarked frontier wins; the band excludes the
        // weaker locals so they can't float up on local/MLX bonuses.
        let q = router.route_context_aware(
            prompt,
            256,
            &reg,
            &tracker,
            false,
            false,
            RoutingWorkload::Quality,
        );
        assert_eq!(
            q.model_id, "frontier-remote",
            "prefer_quality must pick the benchmarked frontier over locals-on-bonuses"
        );
        assert_eq!(
            q.strategy,
            RoutingStrategy::SchemaBased,
            "Quality lane must use deterministic argmax, not Thompson exploration"
        );
        assert!(
            q.candidates.iter().any(|c| !c.in_band),
            "Quality lane must apply a reliability band (some candidates excluded)"
        );

        // LocalPreferred: NO band — every candidate stays eligible, so an
        // explicit local request isn't overridden by the frontier.
        let lp = router.route_context_aware(
            prompt,
            256,
            &reg,
            &tracker,
            false,
            false,
            RoutingWorkload::LocalPreferred,
        );
        assert!(
            lp.candidates.iter().all(|c| c.in_band),
            "LocalPreferred must NOT band — all candidates eligible"
        );
    }

    #[test]
    fn band_never_empties() {
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let tracker = OutcomeTracker::new();
        // single candidate
        assert_eq!(
            router
                .outcome_first_band(
                    vec![outcome_model("only", Some(0.5))],
                    InferenceTask::Code,
                    &tracker
                )
                .len(),
            1
        );
        // the best always survives even when all are low
        let band = router.outcome_first_band(
            vec![
                outcome_model("x", Some(0.40)),
                outcome_model("y", Some(0.41)),
            ],
            InferenceTask::Code,
            &tracker,
        );
        assert!(!band.is_empty() && band.iter().any(|m| m.id == "y"));
    }

    #[test]
    fn outcome_first_band_is_wired_into_selection_and_keeps_fallbacks() {
        // Integration (Linus): prove the band actually constrains end-to-end
        // selection AND that excluded models survive as fallbacks. A strong but
        // expensive model and a weaker but cheap one, both Reasoning-capable;
        // routing a substantive prompt must pick the strong one (band excludes
        // the weak one from selection despite its lower cost) yet keep the weak
        // one as a fallback (a worse model beats no model if the primary errors).
        let tmp = std::path::PathBuf::from("/tmp/car-test-outcome-first-route");
        unsafe {
            std::env::set_var("OPENAI_API_KEY", "test-openai-key");
        }
        let mut reg = UnifiedRegistry::new_empty(tmp);
        let mut strong = outcome_model("strong-expensive", Some(0.90));
        strong.cost = crate::schema::CostModel {
            input_per_mtok: Some(20.0),
            output_per_mtok: Some(20.0),
            ..Default::default()
        };
        let mut weak = outcome_model("weak-cheap", Some(0.80));
        weak.cost = crate::schema::CostModel {
            input_per_mtok: Some(0.1),
            output_per_mtok: Some(0.1),
            ..Default::default()
        };
        reg.register_project_model(strong);
        reg.register_project_model(weak);

        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prior_strength: 100.0, // exploit Phase-2 scores (deterministic-ish)
                ..Default::default()
            },
        );
        let tracker = OutcomeTracker::new();
        // Reasoning-flavored prompt → substantive task → outcome-first posture.
        let decision = router.route(
            "Analyze the architecture trade-offs in depth",
            &reg,
            &tracker,
        );

        assert_eq!(
            decision.model_id, "strong-expensive",
            "band must select the higher-reliability model even though it's pricier"
        );
        assert!(
            decision.fallbacks.contains(&"weak-cheap".to_string()),
            "the out-of-band weaker model must remain as a fallback, got {:?}",
            decision.fallbacks
        );
    }

    #[test]
    fn outcome_first_fallbacks_rank_in_band_before_out_of_band() {
        // neo: the band must hold for the fallback chain too — on primary
        // failure, an in-band (high-reliability) model must be retried before an
        // out-of-band cheaper-but-worse one.
        let tmp = std::path::PathBuf::from("/tmp/car-test-outcome-first-fb-order");
        unsafe {
            std::env::set_var("OPENAI_API_KEY", "test-openai-key");
        }
        let mut reg = UnifiedRegistry::new_empty(tmp);
        reg.register_project_model(outcome_model("strong", Some(0.90)));
        let mut peer = outcome_model("peer-in-band", Some(0.89)); // within 0.02 of strong
        peer.cost = crate::schema::CostModel {
            input_per_mtok: Some(30.0),
            output_per_mtok: Some(30.0),
            ..Default::default()
        };
        reg.register_project_model(peer);
        let mut weak = outcome_model("weak-out-of-band", Some(0.70)); // 0.20 below → out
        weak.cost = crate::schema::CostModel {
            input_per_mtok: Some(0.01),
            output_per_mtok: Some(0.01),
            ..Default::default()
        };
        reg.register_project_model(weak);

        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prior_strength: 100.0,
                ..Default::default()
            },
        );
        let tracker = OutcomeTracker::new();
        let decision = router.route(
            "Analyze the architecture trade-offs in depth",
            &reg,
            &tracker,
        );

        // primary must be in-band
        assert!(
            decision.model_id == "strong" || decision.model_id == "peer-in-band",
            "primary must be from the band, got {}",
            decision.model_id
        );
        let pos = |id: &str| decision.fallbacks.iter().position(|x| x == id);
        let in_band_id = if decision.model_id == "strong" {
            "peer-in-band"
        } else {
            "strong"
        };
        let in_band_pos = pos(in_band_id).expect("in-band peer must be a fallback");
        let weak_pos = pos("weak-out-of-band").expect("weak must remain a fallback (availability)");
        assert!(
            in_band_pos < weak_pos,
            "in-band fallback ({in_band_id}@{in_band_pos}) must precede out-of-band weak (@{weak_pos})"
        );
    }

    #[test]
    fn reliability_is_cost_free() {
        // The band key must ignore cost — two models with identical benchmarks
        // but different cost have identical reliability.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let tracker = OutcomeTracker::new();
        let mut cheap = outcome_model("cheap", Some(0.8));
        cheap.cost = crate::schema::CostModel {
            input_per_mtok: Some(0.1),
            output_per_mtok: Some(0.1),
            ..Default::default()
        };
        let mut pricey = outcome_model("pricey", Some(0.8));
        pricey.cost = crate::schema::CostModel {
            input_per_mtok: Some(50.0),
            output_per_mtok: Some(50.0),
            ..Default::default()
        };
        let rc = router.reliability(&cheap, InferenceTask::Code, &tracker);
        let rp = router.reliability(&pricey, InferenceTask::Code, &tracker);
        assert!(
            (rc - rp).abs() < 1e-9,
            "reliability must not depend on cost"
        );
    }

    #[test]
    fn cold_start_with_no_sample_size_sits_at_schema_estimate() {
        // Anti-regression: a 0-call profile with no benchmark sample size must
        // resolve to the schema estimate exactly — never averaged down toward
        // neutral. This is what keeps a healthy unmeasured frontier model (or
        // a good 8B) at its honest schema quality instead of demoting it.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let unmeasured = outcome_model("unmeasured", None); // curated remote → 0.68
        let schema = router.schema_quality_estimate(&unmeasured);

        let mut tracker = OutcomeTracker::new();
        let mut p = crate::outcome::ModelProfile::new("unmeasured".into());
        p.ema_quality = 0.5; // neutral default, prior_sample_size == 0
        tracker.import_profiles(vec![p]);

        let r = router.reliability(&unmeasured, InferenceTask::Code, &tracker);
        assert!(
            (r - schema).abs() < 1e-9,
            "no sample size ⇒ reliability == schema estimate ({schema}), got {r}"
        );
    }

    #[test]
    fn sparse_seeded_prior_barely_perturbs_schema_anchor() {
        // The shadowing bug: a 1-case seeded prior of 1.0 must not pull
        // reliability anywhere near 1.0 — it sits close to the schema anchor.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let benchmarked = outcome_model("frontier", Some(0.55)); // schema 0.55

        let mut tracker = OutcomeTracker::new();
        let mut p = crate::outcome::ModelProfile::new("frontier".into());
        p.ema_quality = 1.0;
        p.prior_sample_size = 1;
        p.task_stats.insert(
            InferenceTask::Code.to_string(),
            crate::outcome::TaskStats {
                ema_quality: 1.0,
                prior_sample_size: 1,
                ..Default::default()
            },
        );
        tracker.import_profiles(vec![p]);

        let r = router.reliability(&benchmarked, InferenceTask::Code, &tracker);
        // schema 0.55, n=1, K=4 → 0.55 + (1/5)*(1.0-0.55) = 0.64
        assert!((r - 0.64).abs() < 0.01, "expected ~0.64, got {r}");
        assert!(
            r < 0.7,
            "a 1-case prior must not pull reliability near its raw 1.0, got {r}"
        );
    }

    #[test]
    fn dense_seeded_prior_is_trusted_near_raw() {
        // A score backed by many cases pulls reliability close to its raw
        // value, away from the schema anchor.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let m = outcome_model("dense", Some(0.55)); // schema 0.55

        let mut tracker = OutcomeTracker::new();
        let mut p = crate::outcome::ModelProfile::new("dense".into());
        p.ema_quality = 0.95;
        p.prior_sample_size = 40;
        tracker.import_profiles(vec![p]);

        let r = router.reliability(&m, InferenceTask::Code, &tracker);
        // schema 0.55, n=40, K=4 → 0.55 + (40/44)*(0.95-0.55) ≈ 0.91
        assert!(
            r > 0.88,
            "dense prior should be trusted near raw 0.95, got {r}"
        );
    }

    #[test]
    fn warm_ungraded_successes_sit_at_schema_not_neutral_ema() {
        // #3: a frontier model with many *ungraded* successes (total_calls high,
        // but quality_observations == 0 so its EMA never left the 0.5 prior)
        // must route on its schema estimate, NOT collapse to a hollow 0.5 that
        // buries it under smaller models. This is the warm-path quality bug.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let frontier = outcome_model("frontier", Some(0.55)); // schema 0.55
        let schema = router.schema_quality_estimate(&frontier);

        let mut tracker = OutcomeTracker::new();
        let mut p = crate::outcome::ModelProfile::new("frontier".into());
        p.total_calls = 9;
        p.success_count = 9; // all mechanical successes, none graded
        p.ema_quality = 0.5; // never moved off the neutral prior
        p.quality_observations = 0;
        tracker.import_profiles(vec![p]);

        let r = router.reliability(&frontier, InferenceTask::Code, &tracker);
        assert!(
            (r - schema).abs() < 1e-9,
            "ungraded successes ⇒ reliability == schema ({schema}), not neutral EMA; got {r}"
        );
    }

    #[test]
    fn ungraded_task_stats_with_zero_ema_still_resolve_to_schema() {
        // Load-bearing invariant: a task touched only by mechanical successes
        // has a TaskStats with the derived-Default ema_quality == 0.0, n == 0,
        // g == 0. reliability() reads that task unit, and `e == 0 ⇒ schema`
        // must multiply the 0.0 EMA out — otherwise routing would see a garbage
        // 0.0 quality. Pins the formula against a refactor that short-circuits
        // differently.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let m = outcome_model("mech-only", Some(0.55)); // schema 0.55
        let schema = router.schema_quality_estimate(&m);

        let mut tracker = OutcomeTracker::new();
        let mut p = crate::outcome::ModelProfile::new("mech-only".into());
        p.total_calls = 7;
        p.success_count = 7;
        // Task stats exist but were only ever touched by mechanical successes:
        // default ema 0.0, no benchmark, no graded signal.
        p.task_stats.insert(
            InferenceTask::Code.to_string(),
            crate::outcome::TaskStats {
                calls: 7,
                successes: 7,
                ..Default::default()
            },
        );
        tracker.import_profiles(vec![p]);

        let r = router.reliability(&m, InferenceTask::Code, &tracker);
        assert!(
            (r - schema).abs() < 1e-9,
            "ungraded task stats (ema 0.0, e=0) must resolve to schema {schema}, got {r}"
        );
    }

    #[test]
    fn graded_outcomes_earn_trust_in_the_live_ema() {
        // The complement: once real graded signal accumulates, the live EMA is
        // trusted near-fully, away from the schema anchor.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let m = outcome_model("graded", Some(0.55)); // schema 0.55

        let mut tracker = OutcomeTracker::new();
        let mut p = crate::outcome::ModelProfile::new("graded".into());
        p.total_calls = 30;
        p.ema_quality = 0.9;
        p.quality_observations = 30; // lots of graded signal
        tracker.import_profiles(vec![p]);

        let r = router.reliability(&m, InferenceTask::Code, &tracker);
        // schema 0.55, e=30, K=4 → 0.55 + (30/34)*(0.9-0.55) ≈ 0.86
        assert!(
            r > 0.83,
            "dense graded signal should trust the live EMA, got {r}"
        );
    }

    #[test]
    fn live_grades_outweigh_benchmark_cases_of_equal_count() {
        // Asymmetry: the same number of live graded observations must move
        // reliability MORE than benchmark cases — live signal is on-distribution
        // ground truth, benchmark cases are distribution-shifted. Both models
        // have a low EMA (0.2) and a high schema (0.7); the live-graded one must
        // be distrusted harder.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let benched = outcome_model("benched", Some(0.7));
        let graded = outcome_model("graded", Some(0.7));

        let mut tracker = OutcomeTracker::new();
        let mut pb = crate::outcome::ModelProfile::new("benched".into());
        pb.ema_quality = 0.2;
        pb.prior_sample_size = 4; // 4 benchmark cases
        let mut pg = crate::outcome::ModelProfile::new("graded".into());
        pg.ema_quality = 0.2;
        pg.total_calls = 4;
        pg.quality_observations = 4; // 4 live grades
        tracker.import_profiles(vec![pb, pg]);

        let r_bench = router.reliability(&benched, InferenceTask::Code, &tracker);
        let r_graded = router.reliability(&graded, InferenceTask::Code, &tracker);
        assert!(
            r_graded < r_bench,
            "4 live grades must distrust more than 4 benchmark cases: \
             graded={r_graded} bench={r_bench}"
        );
    }

    #[test]
    fn graded_failures_count_as_evidence_and_pull_reliability_down() {
        // Failures are graded signal (they move the EMA toward 0), so they must
        // count toward quality evidence and drag reliability below the schema
        // prior — distrust is earned even for a model with a strong prior.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let m = outcome_model("flaky", Some(0.8)); // schema 0.8
        let schema = router.schema_quality_estimate(&m);

        let mut tracker = OutcomeTracker::new();
        let mut p = crate::outcome::ModelProfile::new("flaky".into());
        p.total_calls = 12;
        p.fail_count = 12;
        p.ema_quality = 0.1; // EMA driven down by repeated failures
        p.quality_observations = 12;
        tracker.import_profiles(vec![p]);

        let r = router.reliability(&m, InferenceTask::Code, &tracker);
        assert!(
            r < schema - 0.2,
            "12 graded failures must pull reliability well below schema {schema}, got {r}"
        );
    }

    #[test]
    fn route_exposes_ranked_advisory_candidates() {
        // Constructing a `UnifiedRegistry` ends in `refresh_availability()`,
        // which WRITES the process-global gateway observation. Full reasoning
        // on `TestRegistry` in this crate; family in
        // docs/solutions/process-global-state-in-tests.md.
        let _environment = crate::openrouter::test_environment_scope();
        // Task 7: the adaptive path must expose the tradeoff it resolved — every
        // scored model present, the winner flagged, in-band membership marked,
        // and reliability cost-free. This is the explainability surface a caller
        // (UI/operator) uses to see *why* a model was picked and what the
        // alternatives were.
        let tmp = std::path::PathBuf::from("/tmp/car-test-route-candidates");
        unsafe {
            std::env::set_var("OPENAI_API_KEY", "test-openai-key");
        }
        let mut reg = UnifiedRegistry::new_with_state_root(tmp.clone(), tmp);
        reg.register_project_model(outcome_model("strong", Some(0.90)));
        let mut weak = outcome_model("weak-cheap", Some(0.70)); // 0.20 below → out of band
        weak.cost = crate::schema::CostModel {
            input_per_mtok: Some(0.01),
            output_per_mtok: Some(0.01),
            ..Default::default()
        };
        reg.register_project_model(weak);

        let router = AdaptiveRouter::new(
            test_hw(),
            // Pin priors so band membership is deterministic (exploit, no exploration).
            RoutingConfig {
                prior_strength: 100.0,
                ..Default::default()
            },
        );
        let tracker = OutcomeTracker::new();
        let decision = router.route(
            "Analyze the architecture trade-offs in depth",
            &reg,
            &tracker,
        );

        // Both scored models are present as candidates.
        assert!(
            decision.candidates.iter().any(|c| c.model_id == "strong"),
            "strong must appear as a candidate, got {:?}",
            decision.candidates
        );
        assert!(
            decision
                .candidates
                .iter()
                .any(|c| c.model_id == "weak-cheap"),
            "weak-cheap must appear as a candidate even though out of band"
        );

        // Exactly one candidate is the selected one, and it matches model_id.
        let selected: Vec<&RouteCandidate> =
            decision.candidates.iter().filter(|c| c.selected).collect();
        assert_eq!(selected.len(), 1, "exactly one candidate may be selected");
        assert_eq!(
            selected[0].model_id, decision.model_id,
            "selected flag must match model_id"
        );

        // Outcome-first: the winner is in-band; the 0.20-weaker model is not.
        let strong = decision
            .candidates
            .iter()
            .find(|c| c.model_id == "strong")
            .unwrap();
        let weak_c = decision
            .candidates
            .iter()
            .find(|c| c.model_id == "weak-cheap")
            .unwrap();
        assert!(strong.in_band, "strong must be in the reliability band");
        assert!(
            !weak_c.in_band,
            "weak-cheap (0.20 below) must be out of band"
        );
        // Reliability is the cost-free band key: strong outranks weak on quality.
        assert!(
            strong.reliability > weak_c.reliability,
            "reliability must reflect quality, not the weak model's lower cost"
        );
    }

    #[test]
    fn prefer_quality_selection_is_deterministic_no_exploration() {
        // The live shakedown caught this: prefer_quality must NOT Thompson-
        // sample (exploration picked the cheap Qwen3-1.7B over 4B even though
        // 4B scored higher). Under the Quality workload selection is argmax —
        // the same most-capable model every call.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let reg = test_registry();
        let tracker = OutcomeTracker::new();
        let intent = crate::intent::IntentHint {
            task: Some(crate::intent::TaskHint::Code),
            require: vec![ModelCapability::Code],
            prefer_quality: true,
            ..Default::default()
        };
        let first = router.route_with_intent("write a function", &reg, &tracker, &intent);
        for _ in 0..8 {
            let again = router.route_with_intent("write a function", &reg, &tracker, &intent);
            assert_eq!(
                again.model_id, first.model_id,
                "prefer_quality must be deterministic (no Thompson exploration)"
            );
        }
        // And it is genuinely a code-capable choice.
        let chosen = reg
            .find_by_name(&first.model_name)
            .or_else(|| reg.list().into_iter().find(|m| m.id == first.model_id));
        if let Some(m) = chosen {
            assert!(m.has_capability(ModelCapability::Code));
        }
    }

    /// Minimal available remote model schema for capability-filter tests.
    fn remote_model(id: &str, name: &str, caps: Vec<ModelCapability>) -> ModelSchema {
        ModelSchema {
            id: id.into(),
            name: name.into(),
            provider: "openai".into(),
            family: name.into(),
            version: "latest".into(),
            capabilities: caps,
            context_length: 128_000,
            max_output_tokens: None,
            param_count: "api".into(),
            quantization: None,
            performance: Default::default(),
            cost: Default::default(),
            source: crate::schema::ModelSource::RemoteApi {
                endpoint: "https://api.openai.com/v1".into(),
                api_key_env: "OPENAI_API_KEY".into(),
                api_key_envs: vec![],
                api_version: None,
                protocol: crate::schema::ApiProtocol::OpenAiCompat,
            },
            tags: vec!["trusted-remote".into()],
            supported_params: vec![],
            public_benchmarks: vec![],
            trust_tier: crate::schema::TrustTier::Curated,
            deprecated: false,
            available: true,
            weights_ready: true,
        }
    }

    #[test]
    fn code_intent_filters_generate_only_models_on_simple_prompt() {
        // Constructing a `UnifiedRegistry` ends in `refresh_availability()`,
        // which WRITES the process-global gateway observation. Full reasoning
        // on `TestRegistry` in this crate; family in
        // docs/solutions/process-global-state-in-tests.md.
        let _environment = crate::openrouter::test_environment_scope();
        // Regression: a caller that sets task=code + prefer_quality but NOT
        // `require` must still get a code-capable model even when the prompt
        // reads as "simple". Before the fix, required_caps came only from prompt
        // complexity ([Generate]), so a generate-only model stayed a candidate
        // and code capability was never required — the exact path neo's
        // CarAdapter uses, and the car#52 regression.
        unsafe {
            std::env::set_var("OPENAI_API_KEY", "test-openai-key");
        }
        let intent_filter_dir = std::path::PathBuf::from("/tmp/car-test-code-intent-filter");
        let mut reg =
            UnifiedRegistry::new_with_state_root(intent_filter_dir.clone(), intent_filter_dir);
        reg.register_project_model(remote_model(
            "openai/gen-only:latest",
            "gen-only",
            vec![ModelCapability::Generate],
        ));
        reg.register_project_model(remote_model(
            "openai/coder:latest",
            "coder",
            vec![
                ModelCapability::Generate,
                ModelCapability::Code,
                ModelCapability::Reasoning,
            ],
        ));

        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prior_strength: 100.0,
                ..Default::default()
            },
        );
        let tracker = OutcomeTracker::new();
        let intent = crate::intent::IntentHint {
            task: Some(crate::intent::TaskHint::Code),
            prefer_quality: true,
            ..Default::default() // note: NO `require`
        };

        // No code markers in the prompt -> TaskComplexity::Simple.
        let decision = router.route_with_intent(
            "Give me a short two-sentence overview.",
            &reg,
            &tracker,
            &intent,
        );

        assert_eq!(
            decision.task,
            InferenceTask::Code,
            "explicit task=code must be honored"
        );
        // The fix's guarantee: the generate-only model is filtered OUT of the
        // candidate set by the code-capability requirement.
        assert!(
            !decision
                .candidates
                .iter()
                .any(|c| c.model_id == "openai/gen-only:latest"),
            "generate-only model must be filtered out for task=code; candidates: {:?}",
            decision
                .candidates
                .iter()
                .map(|c| &c.model_id)
                .collect::<Vec<_>>()
        );
        let schema = reg
            .find_by_name(&decision.model_name)
            .or_else(|| reg.list().into_iter().find(|m| m.id == decision.model_id))
            .expect("selected model exists");
        assert!(
            schema.has_capability(ModelCapability::Code),
            "task=code on a simple prompt must route to a code-capable model, got {}",
            decision.model_name,
        );
    }

    #[test]
    fn intent_default_does_not_override_task_or_caps() {
        // Thompson sampling makes per-call model selection
        // non-deterministic, so we can't compare model_ids directly.
        // What we can assert deterministically: a default IntentHint
        // must not change the task selection or the capability
        // requirements — those are functions of the prompt only when
        // no hint is supplied.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let reg = test_registry();
        let tracker = OutcomeTracker::new();

        let baseline = router.route("write a haiku", &reg, &tracker);
        let with_default = router.route_with_intent(
            "write a haiku",
            &reg,
            &tracker,
            &crate::intent::IntentHint::default(),
        );

        assert_eq!(
            baseline.task, with_default.task,
            "default IntentHint must not change the prompt-derived task"
        );
        assert_eq!(
            baseline.complexity, with_default.complexity,
            "default IntentHint must not change the prompt-derived complexity"
        );
    }

    /// Parslee-ai/car#638 — a caller on a deadline must not be handed a model
    /// it would have to download first.
    ///
    /// `available` is true for an MLX model as soon as an `hf_repo` is declared,
    /// because `ensure_local()` lazy-downloads on first use (#164). That is
    /// right for open-ended work and fatal under a bounded timeout: `car code`
    /// derives its outcome contract inside a 120s cap, and on a machine with no
    /// local weights the router picked a 4.8 GB model, spent the whole budget
    /// fetching it, and failed all three attempts — while cloud models that
    /// answer in ~2s sat unreached in the fallback list.
    #[test]
    fn require_ready_skips_models_that_are_not_on_disk() {
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let reg = test_registry();
        let tracker = OutcomeTracker::new();

        // Every model the fixture put on disk is ready; anything else is not.
        let ready: std::collections::HashSet<String> = reg
            .list()
            .into_iter()
            .filter(|m| m.weights_ready)
            .map(|m| m.id.clone())
            .collect();
        assert!(!ready.is_empty(), "fixture should have ready models");

        let hint = crate::intent::IntentHint {
            require_ready: true,
            ..Default::default()
        };
        let decision = router.route_with_intent("write a python function", &reg, &tracker, &hint);
        assert!(
            ready.contains(&decision.model_id),
            "require_ready picked {} which is not on disk; ready set: {:?}",
            decision.model_id,
            ready
        );
    }

    /// The constraint is soft: if nothing is ready, routing still returns a
    /// model rather than refusing. A slow answer beats no answer.
    #[test]
    fn require_ready_falls_back_when_nothing_is_ready() {
        // Constructing a `UnifiedRegistry` ends in `refresh_availability()`,
        // which WRITES the process-global gateway observation. Full reasoning
        // on `TestRegistry` in this crate; family in
        // docs/solutions/process-global-state-in-tests.md.
        let _environment = crate::openrouter::test_environment_scope();
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let tracker = OutcomeTracker::new();
        // Registry over an empty dir: no local weights anywhere.
        let empty_dir = std::env::temp_dir().join("car-test-require-ready-empty");
        let _ = std::fs::create_dir_all(&empty_dir);
        let reg = UnifiedRegistry::new_with_state_root(empty_dir.clone(), empty_dir);

        let hint = crate::intent::IntentHint {
            require_ready: true,
            ..Default::default()
        };
        let decision = router.route_with_intent("write a python function", &reg, &tracker, &hint);
        assert!(
            !decision.model_id.is_empty(),
            "soft constraint must still yield a model when nothing is ready"
        );
    }

    #[test]
    fn exclude_models_picks_a_different_model() {
        // Adversarial-reviewer separation (car#358): given the model that
        // "just did the work", routing must pick a DIFFERENT one. Use
        // prefer_quality so the baseline pick is deterministic (argmax),
        // then exclude it and assert the winner changes.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let reg = test_registry();
        let tracker = OutcomeTracker::new();
        let base = crate::intent::IntentHint {
            prefer_quality: true,
            ..Default::default()
        };
        let author = router.route_with_intent("review this", &reg, &tracker, &base);

        let with_exclude = crate::intent::IntentHint {
            prefer_quality: true,
            exclude_models: vec![author.model_id.clone()],
            ..Default::default()
        };
        let reviewer = router.route_with_intent("review this", &reg, &tracker, &with_exclude);
        assert_ne!(
            reviewer.model_id, author.model_id,
            "an excluded model must never be the routed pick"
        );
        // The excluded id must also be gone from the retry chain and the
        // advisory candidate ranking — not just the primary pick.
        assert!(
            !reviewer.fallbacks.contains(&author.model_id),
            "excluded model leaked into fallbacks"
        );
        assert!(
            !reviewer
                .candidates
                .iter()
                .any(|c| c.model_id == author.model_id),
            "excluded model leaked into candidates[]"
        );
    }

    #[test]
    fn strict_exclusions_refuse_when_every_candidate_is_a_panel_seat() {
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let reg = test_registry();
        let tracker = OutcomeTracker::new();
        let panel: Vec<String> = reg
            .list()
            .into_iter()
            .map(|model| model.name.clone())
            .collect();
        assert!(!panel.is_empty(), "fixture must contain candidate models");

        let decision = router.route_with_intent(
            "repair this code",
            &reg,
            &tracker,
            &crate::intent::IntentHint {
                task: Some(crate::intent::TaskHint::Code),
                exclude_models: panel,
                strict_exclusions: true,
                ..Default::default()
            },
        );

        assert!(decision.model_id.is_empty(), "{decision:?}");
        assert!(decision.model_name.is_empty(), "{decision:?}");
        assert!(decision.fallbacks.is_empty(), "{decision:?}");
        assert!(
            decision.reason.contains("no eligible model"),
            "the refusal must tell the operator what is missing: {decision:?}"
        );
    }

    #[test]
    fn exclude_models_accepts_the_name_a_result_reports() {
        // `InferenceResult::model_used` carries `ModelSchema.name`, and that is
        // the ONLY identifier a caller holding a result has. The filter compares
        // `ModelSchema.id`, and the two differ for most models — so excluding by
        // the name used to match nothing at all and silently route straight back
        // to the model that just failed. That no-op is what left coder contract
        // derivation re-asking the same JSON-unreliable fallback three times
        // (car#889).
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let reg = test_registry();
        let tracker = OutcomeTracker::new();
        let base = crate::intent::IntentHint {
            prefer_quality: true,
            ..Default::default()
        };
        let author = router.route_with_intent("write a python function", &reg, &tracker, &base);
        let author_name = reg
            .get(&author.model_id)
            .expect("the routed pick is in the registry")
            .name
            .clone();
        assert_ne!(
            author_name, author.model_id,
            "this test is only meaningful on a model whose name and id differ"
        );

        let by_name = crate::intent::IntentHint {
            prefer_quality: true,
            exclude_models: vec![author_name.clone()],
            ..Default::default()
        };
        let rerouted =
            router.route_with_intent("write a python function", &reg, &tracker, &by_name);
        assert_ne!(
            rerouted.model_id, author.model_id,
            "excluding by the name a result reports ({author_name}) must route elsewhere"
        );
        assert!(
            !rerouted.fallbacks.contains(&author.model_id),
            "name-excluded model leaked into fallbacks"
        );
    }

    #[test]
    fn cold_start_honors_exclusion() {
        // The cold-start fallback (hard filter yielded nothing) must also
        // avoid the excluded model when an alternative exists (car#358 review
        // follow-up). Drive cold_start_decision directly: pick its baseline,
        // then exclude that and assert it picks something else.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let reg = test_registry();
        let caps = [ModelCapability::Generate];
        let base = router.cold_start_decision(
            TaskComplexity::Simple,
            InferenceTask::Generate,
            &caps,
            &reg,
            false,
            &std::collections::HashSet::new(),
            false,
            AvailabilitySnapshot::capture(&reg),
        );
        let mut exclude = std::collections::HashSet::new();
        exclude.insert(base.model_id.clone());
        let excluded = router.cold_start_decision(
            TaskComplexity::Simple,
            InferenceTask::Generate,
            &caps,
            &reg,
            false,
            &exclude,
            false,
            AvailabilitySnapshot::capture(&reg),
        );
        // Either a different model, or the hardcoded last-resort floor (the
        // soft tolerance) — but the registry-driven tiers must not re-pick the
        // excluded id while another registry model qualifies.
        let other_generate_exists = reg
            .list()
            .into_iter()
            .filter(|m| m.available && m.has_capability(ModelCapability::Generate))
            .any(|m| m.id != base.model_id);
        if other_generate_exists {
            assert_ne!(
                excluded.model_id, base.model_id,
                "cold start re-picked the excluded model despite an alternative"
            );
        }
    }

    #[test]
    fn exclude_all_models_falls_back_to_full_set() {
        // Soft exclusion: if excluding leaves no candidate, the exclusion is
        // dropped rather than failing — a same-model review beats no review.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let reg = test_registry();
        let tracker = OutcomeTracker::new();
        let exclude_everything: Vec<String> =
            reg.list().into_iter().map(|m| m.id.clone()).collect();
        let hint = crate::intent::IntentHint {
            exclude_models: exclude_everything,
            ..Default::default()
        };
        let decision = router.route_with_intent("hi", &reg, &tracker, &hint);
        assert!(
            !decision.model_id.is_empty(),
            "excluding everything must still yield a routed model (fallback)"
        );
    }

    #[test]
    fn intent_task_hint_overrides_prompt_complexity() {
        // A short prompt that complexity assessment would route as
        // Generate should land on Reasoning when the intent says so.
        let router = AdaptiveRouter::new(test_hw(), RoutingConfig::default());
        let reg = test_registry();
        let tracker = OutcomeTracker::new();

        let hint = crate::intent::IntentHint {
            task: Some(crate::intent::TaskHint::Reasoning),
            ..Default::default()
        };
        let decision = router.route_with_intent("hi", &reg, &tracker, &hint);

        assert_eq!(
            decision.task,
            InferenceTask::Reasoning,
            "TaskHint::Reasoning should override the prompt-derived task"
        );
    }

    /// #333 residual: on Apple Silicon a local GGUF model with an MLX
    /// equivalent is EXECUTED as the MLX model and books its outcomes against
    /// the MLX id. The router must therefore propose / breaker-gate / learn the
    /// MLX id — not the pre-redirect GGUF id whose profile stays forever empty.
    /// A proven MLX model is proposed by its MLX id, and the pre-redirect GGUF
    /// twin id — which would read an empty profile and never actually run — is
    /// never proposed (decision or fallback chain). Run against the real
    /// builtin catalog, which has the qwen3 GGUF/MLX twins.
    #[cfg(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx)))]
    #[test]
    fn router_proposes_mlx_twin_not_pre_redirect_gguf() {
        let gguf_id = "qwen/qwen3-8b:q4_k_m";
        let mlx_id = "mlx/qwen3-8b:4bit";

        let reg = test_registry();
        // Precondition: the GGUF resolves 1:1 to its same-size MLX twin (not,
        // say, the 4B — the param_count fix in resolve_mlx_equivalent).
        let gguf = reg.get(gguf_id).expect("gguf in builtin catalog").clone();
        assert_eq!(
            reg.resolve_mlx_equivalent(&gguf).map(|m| m.id.as_str()),
            Some(mlx_id),
            "GGUF must resolve to its SAME-SIZE MLX twin"
        );

        let router = AdaptiveRouter::new(
            test_hw(),
            RoutingConfig {
                prior_strength: 0.5,
                min_observations: 3,
                ..Default::default()
            },
        );
        let mut tracker = OutcomeTracker::new();
        // Prove the MLX twin on code tasks.
        for _ in 0..20 {
            let t = tracker.record_start(mlx_id, InferenceTask::Code, "test");
            tracker.record_complete(&t, 500, 100, 50);
            tracker.record_inferred_outcome(&t, InferredOutcome::Accepted { confidence: 0.95 });
        }

        let mut mlx_wins = 0;
        for _ in 0..20 {
            let d = router.route("Fix this bug in the parser", &reg, &tracker);
            // The pre-redirect GGUF id must never be proposed or queued (#333):
            // it was substituted to the MLX twin before scoring.
            assert_ne!(
                d.model_id, gguf_id,
                "router proposed the pre-redirect GGUF id"
            );
            assert!(
                !d.fallbacks.iter().any(|f| f == gguf_id),
                "pre-redirect GGUF id leaked into the fallback chain"
            );
            if d.model_id == mlx_id {
                mlx_wins += 1;
            }
        }
        assert!(
            mlx_wins >= 12,
            "proven MLX twin should win the majority (the router reads the id it \
             learns/runs); won only {mlx_wins}/20"
        );
    }
}