car-inference 0.47.0

//! Model schema — declarative metadata for models, analogous to ToolSchema for tools.
//!
//! Every model (local GGUF, remote API, Ollama) is described by a `ModelSchema`
//! that declares identity, capabilities, constraints, cost, and source.
//! The router uses this schema for initial routing; observed outcomes refine it.

use serde::{Deserialize, Serialize};

/// What a model can do.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ModelCapability {
    /// Text completion / chat generation
    Generate,
    /// Vector embeddings
    Embed,
    /// Cross-encoder relevance scoring (query + document → relevance
    /// score). Qwen3-Reranker is the canonical local implementation.
    Rerank,
    /// Label assignment / classification
    Classify,
    /// Code generation, repair, refactoring
    Code,
    /// Chain-of-thought, planning, analysis
    Reasoning,
    /// Text condensation
    Summarize,
    /// Function/tool calling
    ToolUse,
    /// Multiple tool calls in a single response (parallel tool execution)
    MultiToolCall,
    /// Vision / image understanding
    Vision,
    /// Video understanding (multi-frame sampling + temporal tokens).
    /// Distinct from `Vision` so routing can prefer video-trained
    /// models when the caller attaches a video content block.
    VideoUnderstanding,
    /// Audio understanding (speech + non-speech audio as an input to
    /// a chat/reasoning model). Distinct from `SpeechToText` which is
    /// the transcription-only task. Gemma 4 E2B/E4B and Gemini do
    /// this; Qwen2.5-VL does not.
    AudioUnderstanding,
    /// Visual grounding — structured object-localization output
    /// (bounding boxes keyed to object labels) in addition to text.
    Grounding,
    /// Speech recognition / transcription
    SpeechToText,
    /// Speech synthesis / text-to-speech
    TextToSpeech,
    /// Image generation
    ImageGeneration,
    /// Video generation
    VideoGeneration,
}

/// How much the project vouches for a model. Gates automatic upgrades and
/// is surfaced in recommendation rationale. Closed enum — a new tier is a
/// deliberate FFI-visible change, never a silent string fallback.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum TrustTier {
    /// Vetted by the project — the built-in catalog and verified upgrades.
    /// Eligible for background auto-apply when the user opts in.
    #[default]
    Curated,
    /// User-registered or upstream-discovered, not project-vetted. Always
    /// notify-only; never auto-applied regardless of update policy.
    Community,
}

/// How to access the model.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ModelSource {
    /// Local GGUF file via Candle backend.
    Local {
        hf_repo: String,
        hf_filename: String,
        tokenizer_repo: String,
    },
    /// Remote API endpoint (OpenAI-compatible, Anthropic, etc.)
    RemoteApi {
        endpoint: String,
        /// Environment variable name containing the API key (never the key itself).
        /// The env var value may contain comma-separated keys for load balancing.
        api_key_env: String,
        /// Additional environment variable names for load balancing across multiple keys.
        /// Each env var may also contain comma-separated keys.
        #[serde(default)]
        api_key_envs: Vec<String>,
        #[serde(default)]
        api_version: Option<String>,
        protocol: ApiProtocol,
    },
    /// Ollama local server.
    Ollama {
        model_tag: String,
        #[serde(default = "default_ollama_host")]
        host: String,
    },
    /// Local MLX model via mlx-rs backend (Apple Silicon, safetensors format).
    /// Models from mlx-community on HuggingFace.
    Mlx {
        /// HuggingFace repo (e.g., "mlx-community/Qwen3-4B-4bit").
        hf_repo: String,
        /// Optional specific weight filename. If None, auto-discovers safetensors files.
        #[serde(default)]
        hf_weight_file: Option<String>,
    },
    /// Local whisper.cpp speech-to-text model — a ggml `.bin` from the
    /// `ggerganov/whisper.cpp` HF repo, run in-process via the shared
    /// `car-whisper` crate. Cross-platform (Windows/Linux/macOS): this is the
    /// on-device STT path where MLX isn't available. Cached at
    /// `~/.tokhn/whisper/ggml-<model>.bin`.
    WhisperCpp {
        /// whisper.cpp model id — the suffix of `ggml-<model>.bin`
        /// (e.g. `"large-v3-turbo-q5_0"`).
        model: String,
    },
    /// Windows OS text-to-speech via `Windows.Media.SpeechSynthesis` (WinRT),
    /// run in-process. The catalog-side analog of the `car-voice`
    /// `TtsProvider::WindowsSpeech` live path and the parity counterpart of
    /// Apple's OS synthesizer — free, on-device, no model download, no MLX.
    /// Windows-only; availability is `false` on every other target (like
    /// `AppleFoundationModels`).
    WindowsSpeech {},
    /// Local vLLM-MLX server (Apple Silicon, OpenAI-compatible API).
    /// Routes through RemoteBackend with OpenAI protocol handler.
    VllmMlx {
        /// Server endpoint (e.g., "http://localhost:8000").
        endpoint: String,
        /// The model name as known to vLLM-MLX (e.g., "mlx-community/Qwen3-4B-4bit").
        model_name: String,
    },
    /// Apple's on-device system model via the FoundationModels framework
    /// (macOS 26+, Apple Silicon). Inference happens in-process through a
    /// Swift shim — there is no HTTP, no API key, and no model file: the
    /// OS owns the weights. Availability is checked at runtime via
    /// `@available(macOS 26.0, *)`; on older macOS or non-Apple-Silicon
    /// hosts the backend reports `UnsupportedMode` and the router falls
    /// through to the next candidate.
    AppleFoundationModels {
        /// Optional Apple use-case hint passed through to
        /// `LanguageModelSession`. Apple's framework tunes its prompt and
        /// safety scaffolding per use case (e.g. "general", "summarize").
        /// `None` uses the default.
        #[serde(default)]
        use_case: Option<String>,
    },
    /// Proprietary provider with custom auth and protocol.
    ///
    /// For vendor-specific APIs that aren't generic OpenAI-compatible endpoints.
    /// Parslee is the first proprietary provider — custom auth (OAuth2),
    /// custom response format, multi-provider routing built into the API.
    Proprietary {
        /// Provider identifier (e.g., "parslee").
        provider: String,
        /// Base URL for the API.
        endpoint: String,
        /// Auth configuration.
        auth: ProprietaryAuth,
        /// Custom protocol details.
        protocol: ProprietaryProtocol,
    },
    /// Inference is delegated to a host-registered runner. CAR does
    /// not own the wire format — the runner (typically a JS / Python
    /// host) translates the `GenerateRequest` to its provider's API,
    /// streams chunks back through the runner's event callback, and
    /// returns the final aggregated result.
    ///
    /// Closes Parslee-ai/car-releases#24. Use this when the host
    /// already has an SDK relationship with a provider (Anthropic,
    /// OpenAI, GitHub Models, Vercel AI SDK) and wants CAR to sit in
    /// the lifecycle / policy / replay path without learning every
    /// provider's wire format.
    ///
    /// Routing requires that a runner has been registered via
    /// [`crate::set_inference_runner`] (or its FFI equivalent —
    /// `registerInferenceRunner` on JS, `register_inference_runner`
    /// on Python, the `InferenceRunner` foreign trait on UniFFI,
    /// `inference.register_runner` on the WebSocket protocol).
    /// Without a runner, dispatch fails with `InferenceFailed`.
    Delegated {
        /// Opaque hint passed through to the runner — typically the
        /// provider id (`"anthropic"`, `"openai"`, `"vercel-ai-sdk"`)
        /// so a multi-provider runner can dispatch internally. CAR
        /// does not interpret this string.
        #[serde(default)]
        hint: Option<String>,
    },
}

/// Authentication method for proprietary providers.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ProprietaryAuth {
    /// OAuth2 PKCE flow (e.g., Azure AD for Parslee).
    OAuth2Pkce {
        authority: String,
        client_id: String,
        scopes: Vec<String>,
    },
    /// Static API key from environment variable.
    ApiKeyEnv { env_var: String },
    /// Bearer token from environment variable.
    BearerTokenEnv { env_var: String },
}

/// Protocol configuration for proprietary providers.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProprietaryProtocol {
    /// Chat/completion endpoint path (appended to base URL).
    #[serde(default = "default_chat_path")]
    pub chat_path: String,
    /// Content type for requests.
    #[serde(default = "default_content_type")]
    pub content_type: String,
    /// Whether the API streams responses via SSE.
    #[serde(default)]
    pub streaming: bool,
    /// Custom headers to include in every request.
    #[serde(default)]
    pub extra_headers: std::collections::HashMap<String, String>,
}

impl Default for ProprietaryProtocol {
    fn default() -> Self {
        Self {
            chat_path: default_chat_path(),
            content_type: default_content_type(),
            streaming: false,
            extra_headers: std::collections::HashMap::new(),
        }
    }
}

fn default_chat_path() -> String {
    "/chat".to_string()
}

fn default_content_type() -> String {
    "application/json".to_string()
}

fn default_ollama_host() -> String {
    "http://localhost:11434".to_string()
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ApiProtocol {
    OpenAiCompat,
    /// OpenRouter's OpenAI-compatible Chat Completions surface. Distinct so
    /// credential precedence and error translation stay provider-specific.
    OpenRouter,
    /// OpenAI Responses API (/v1/responses) — works with all OpenAI models including codex.
    OpenAiResponses,
    Anthropic,
    Google,
    /// Azure OpenAI — uses api-key header and deployment-based URLs.
    /// Endpoint format: {base}/openai/deployments/{model}/chat/completions?api-version={version}
    AzureOpenAi,
    /// Google Vertex AI — the enterprise Gemini surface. Same request/response
    /// shape as the AI-Studio `Google` protocol, but a project/location URL and
    /// OAuth Bearer auth (a GCP access token from `gcloud auth print-access-token`
    /// or a service account) instead of an `?key=` query param. Endpoint format:
    /// `{base}/publishers/google/models/{model}:generateContent`, where `base`
    /// is `https://{loc}-aiplatform.googleapis.com/v1/projects/{proj}/locations/{loc}`.
    VertexAi,
    /// AWS Bedrock — the **Converse** API (`bedrock-runtime`), a unified
    /// messages surface across Bedrock-hosted models (Claude, Llama, Mistral,
    /// Titan, …). Auth is **SigV4** request signing (not a bearer token), with
    /// credentials from the standard AWS env vars; the model's `endpoint` is the
    /// region (e.g. `us-east-1`) and `name` is the Bedrock model id. Non-stream
    /// only for now (Converse streaming uses a separate binary event-stream).
    Bedrock,
}

impl ApiProtocol {
    /// Prompt-cache economics for this provider, relative to its base input
    /// rate — used by the cost scoreboard to price cached tokens correctly.
    /// Anthropic uses explicit breakpoints (deep read discount + write
    /// premium); OpenAI/Azure cache automatically (~0.5× read, no write
    /// charge). Providers whose cache tokens CAR does not parse (Google/Vertex/
    /// Bedrock) report zero cache tokens, so their rates are inert.
    pub fn cache_rates(&self) -> crate::outcome::CacheRates {
        use crate::outcome::CacheRates;
        match self {
            ApiProtocol::Anthropic => CacheRates::ANTHROPIC,
            ApiProtocol::OpenAiCompat | ApiProtocol::OpenAiResponses | ApiProtocol::AzureOpenAi => {
                CacheRates::OPENAI
            }
            // OpenRouter rates differ per upstream model and are carried by
            // ModelSchema::cost. A blanket OpenAI-shaped discount is false.
            ApiProtocol::OpenRouter => CacheRates::NONE,
            ApiProtocol::Google | ApiProtocol::VertexAi | ApiProtocol::Bedrock => CacheRates::NONE,
        }
    }
}

/// Declared performance expectations. Overridden by observed data once available.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct PerformanceEnvelope {
    /// Median latency in milliseconds (declared/estimated).
    #[serde(default)]
    pub latency_p50_ms: Option<u64>,
    /// 99th percentile latency in milliseconds.
    #[serde(default)]
    pub latency_p99_ms: Option<u64>,
    /// Tokens per second throughput.
    #[serde(default)]
    pub tokens_per_second: Option<f64>,
}

/// Cost model for routing optimization.
/// Generation parameters that a model may or may not support.
/// Models declare which params they accept. The inference layer
/// strips unsupported params before sending to the API.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum GenerateParam {
    Temperature,
    TopP,
    TopK,
    MaxTokens,
    StopSequences,
    FrequencyPenalty,
    PresencePenalty,
    Seed,
    ResponseFormat,
    /// Extended thinking / internal reasoning before responding.
    ExtendedThinking,
}

/// Standard parameter set for most models.
pub fn standard_params() -> Vec<GenerateParam> {
    vec![
        GenerateParam::Temperature,
        GenerateParam::TopP,
        GenerateParam::MaxTokens,
        GenerateParam::StopSequences,
        GenerateParam::FrequencyPenalty,
        GenerateParam::PresencePenalty,
        GenerateParam::Seed,
    ]
}

/// Parameter set for reasoning models (no temperature, no top_p).
pub fn reasoning_params() -> Vec<GenerateParam> {
    vec![GenerateParam::MaxTokens, GenerateParam::StopSequences]
}

#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
pub struct TokenPrices {
    /// USD per 1M uncached input tokens.
    #[serde(default)]
    pub input_per_mtok: Option<f64>,
    /// USD per 1M output tokens.
    #[serde(default)]
    pub output_per_mtok: Option<f64>,
    /// USD per 1M cache-read input tokens.
    #[serde(default)]
    pub cache_read_input_per_mtok: Option<f64>,
    /// USD per 1M cache-write input tokens.
    #[serde(default)]
    pub cache_write_input_per_mtok: Option<f64>,
}

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct TokenPricingTier {
    /// Inclusive prompt-token threshold at which this tier applies.
    pub min_prompt_tokens: usize,
    #[serde(flatten)]
    pub prices: TokenPrices,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct CostModel {
    /// USD per 1M input tokens (remote models).
    #[serde(default)]
    pub input_per_mtok: Option<f64>,
    /// USD per 1M output tokens (remote models).
    #[serde(default)]
    pub output_per_mtok: Option<f64>,
    /// USD per 1M cache-read input tokens. Unlike protocol-wide cache
    /// multipliers, this is model-specific and comes from the provider's
    /// published catalog.
    #[serde(default)]
    pub cache_read_input_per_mtok: Option<f64>,
    /// USD per 1M cache-write input tokens, when the provider charges one.
    #[serde(default)]
    pub cache_write_input_per_mtok: Option<f64>,
    /// Prompt-size pricing overrides, sorted by increasing threshold.
    /// The highest threshold not greater than the prompt size wins.
    #[serde(default)]
    pub pricing_tiers: Vec<TokenPricingTier>,
    /// On-disk size in MB (local models).
    #[serde(default)]
    pub size_mb: Option<u64>,
    /// RAM required during inference in MB.
    #[serde(default)]
    pub ram_mb: Option<u64>,
}

impl CostModel {
    pub fn prices_for(&self, prompt_tokens: usize) -> TokenPrices {
        let mut prices = TokenPrices {
            input_per_mtok: self.input_per_mtok,
            output_per_mtok: self.output_per_mtok,
            cache_read_input_per_mtok: self.cache_read_input_per_mtok,
            cache_write_input_per_mtok: self.cache_write_input_per_mtok,
        };
        for tier in self
            .pricing_tiers
            .iter()
            .filter(|tier| tier.min_prompt_tokens <= prompt_tokens)
        {
            if tier.prices.input_per_mtok.is_some() {
                prices.input_per_mtok = tier.prices.input_per_mtok;
            }
            if tier.prices.output_per_mtok.is_some() {
                prices.output_per_mtok = tier.prices.output_per_mtok;
            }
            if tier.prices.cache_read_input_per_mtok.is_some() {
                prices.cache_read_input_per_mtok = tier.prices.cache_read_input_per_mtok;
            }
            if tier.prices.cache_write_input_per_mtok.is_some() {
                prices.cache_write_input_per_mtok = tier.prices.cache_write_input_per_mtok;
            }
        }
        prices
    }

    /// Estimated request cost from the provider's declared token prices.
    /// Unknown price components contribute zero; callers that need to
    /// distinguish unknown pricing should inspect `prices_for` first.
    ///
    /// **This is the routing-score input, not a display or billing figure.**
    /// The zero-fill is load-bearing here — `adaptive_router` normalizes the
    /// result into a 0..1 cost score, and it separately neutralizes models
    /// with no pricing at all, so changing the fill would change routing.
    /// For anything a human reads, use
    /// [`estimated_usd_bounded`](Self::estimated_usd_bounded), which refuses
    /// to bill an unrated bucket at zero and says which way it can be wrong.
    pub fn estimated_usd(
        &self,
        prompt_tokens: usize,
        output_tokens: usize,
        cache_read_tokens: usize,
        cache_write_tokens: usize,
    ) -> f64 {
        let prices = self.prices_for(prompt_tokens);
        let uncached_input = prompt_tokens
            .saturating_sub(cache_read_tokens)
            .saturating_sub(cache_write_tokens);
        (uncached_input as f64 * prices.input_per_mtok.unwrap_or(0.0)
            + output_tokens as f64 * prices.output_per_mtok.unwrap_or(0.0)
            + cache_read_tokens as f64 * prices.cache_read_input_per_mtok.unwrap_or(0.0)
            + cache_write_tokens as f64 * prices.cache_write_input_per_mtok.unwrap_or(0.0))
            / 1_000_000.0
    }

    /// Effective per-bucket rates under one resolved price sheet, in the
    /// bucket order `[uncached input, output, cache read, cache write]`, each
    /// paired with which way a *substituted* rate can be wrong:
    /// `(rate, may_overstate, may_understate)`.
    ///
    /// The two cache buckets substitute the uncached-input rate but are **not
    /// governed by one rule**, because the providers in this catalog do not
    /// price them the same way relative to input:
    ///
    /// | bucket | observed vs input, curated table |
    /// |---|---|
    /// | cache read | `0.10x`–`0.64x` — always a discount |
    /// | cache write | `0.1875x` (Google) … `1.25x` (Anthropic) — **both sides** |
    ///
    /// So substituting input for a missing **cache-read** rate can only be too
    /// high (`may_overstate`), while for a missing **cache-write** rate it can
    /// land either side and gets both flags, rendering `~` rather than a `≤`
    /// the figure cannot honour. Treating the two alike is how `claude-opus-4.8`
    /// — `input 5.0`, `cache_write 6.25` — would have worn a `≤$5.00` ceiling
    /// over a true cost of `$6.25`, or `$10.00` at OpenRouter's 1h-TTL rate.
    ///
    /// **Output** substitutes nothing and refuses instead: output runs
    /// `1.5x`–`8x` input across this same table, which is not a ballpark
    /// estimate in either direction, merely a wrong number wearing a marker.
    /// The line is whether a substitute is *within range and merely of unknown
    /// sign* (estimate, flag it) or *out of range entirely* (refuse) — see
    /// [`estimated_usd_bounded`](Self::estimated_usd_bounded).
    fn bucket_rates(prices: &TokenPrices) -> [(Option<f64>, bool, bool); 4] {
        // A cached READ is always discounted relative to uncached input — the
        // entire point of the cache — so the input rate is a true ceiling.
        let cache_read = match prices.cache_read_input_per_mtok {
            Some(rate) => (Some(rate), false, false),
            None => {
                let substituted = prices.input_per_mtok.is_some();
                (prices.input_per_mtok, substituted, false)
            }
        };
        // A cache WRITE may be a surcharge (Anthropic 1.25x, OpenRouter's 1h
        // TTL 2x) or a discount (Google 0.1875x). Unknown sign, so no bound.
        let cache_write = match prices.cache_write_input_per_mtok {
            Some(rate) => (Some(rate), false, false),
            None => {
                let substituted = prices.input_per_mtok.is_some();
                (prices.input_per_mtok, substituted, substituted)
            }
        };
        [
            (prices.input_per_mtok, false, false),
            (prices.output_per_mtok, false, false),
            cache_read,
            cache_write,
        ]
    }

    /// Cost estimate for a figure a person will read, carrying which way it
    /// can be wrong.
    ///
    /// Differs from [`estimated_usd`](Self::estimated_usd) in refusing to
    /// invent numbers. A token bucket the provider charges for but whose rate
    /// this catalog does not declare is **never billed at zero**, and a figure
    /// that might be wrong never presents itself as exact.
    ///
    /// `tier_prompt_tokens` selects the prompt-size pricing tier and is the
    /// parameter callers most often get wrong:
    ///
    /// - `Some(n)` — the prompt size of **one request**. Tiers resolve exactly.
    /// - `None` — the caller cannot say (a lifetime accumulator has summed
    ///   many requests and lost their boundaries). Base rates are used and the
    ///   result is flagged in whichever direction the model's own tiers run.
    ///
    /// Passing a *summed* token count as `Some` is the bug this signature
    /// exists to prevent: thirty 10K-token requests sum to 300K, which crosses
    /// a 272K threshold that no individual request came near, and every token
    /// ever sent gets priced at the high-context rate — roughly double, stated
    /// with total confidence.
    ///
    /// Two rejected alternatives, for the next person who wants tiers on an
    /// aggregate. **Pricing lifetime totals at the tier their sum lands in** is
    /// the bug above. **Pricing everything at the highest declared tier** does
    /// yield a true ceiling, but a useless one — it doubles the figure for a
    /// user whose prompts never approached the threshold, which is the same
    /// confident wrongness in the other direction. Resolving tiers properly
    /// needs per-request prompt sizes, which means [`crate::ModelProfile`]
    /// would have to accumulate per-tier token buckets at record time; that is
    /// a real feature with a persisted-schema change, not something to fake
    /// here from data that has already been summed away.
    ///
    /// Returns `None` when no defensible number exists — either the model
    /// declares no rate card at all, or a bucket carrying tokens has no rate
    /// and no usable substitute. Output deliberately has no input-rate
    /// fallback: it runs 1.5x–8x input across this catalog, far enough out of
    /// range that no marker could rescue the number. Which buckets substitute,
    /// and which way each substitution can be wrong, is decided in
    /// [`bucket_rates`](Self::bucket_rates) from observed provider pricing —
    /// notably cache *reads* and cache *writes* do not share a direction.
    /// `None` means unpriced, and a caller must render it as such, not as free.
    pub fn estimated_usd_bounded(
        &self,
        tier_prompt_tokens: Option<usize>,
        uncached_input_tokens: usize,
        output_tokens: usize,
        cache_read_tokens: usize,
        cache_write_tokens: usize,
    ) -> Option<ApproxCost> {
        // `prices_for(0)` is the base sheet: no tier threshold is <= 0 in a
        // catalog whose thresholds are positive, so nothing overrides.
        let prices = self.prices_for(tier_prompt_tokens.unwrap_or(0));
        if prices.input_per_mtok.is_none() && prices.output_per_mtok.is_none() {
            // No rate card. Not free — unknown.
            return None;
        }

        let tokens = [
            uncached_input_tokens,
            output_tokens,
            cache_read_tokens,
            cache_write_tokens,
        ];
        let rates = Self::bucket_rates(&prices);
        let mut usd = 0.0;
        let mut may_overstate = false;
        let mut may_understate = false;
        for (count, (rate, substitute_high, substitute_low)) in tokens.into_iter().zip(rates) {
            if count == 0 {
                continue;
            }
            // Charged, rate unknown, no usable substitute — admit we can't.
            let rate = rate?;
            // Direction comes from the bucket, not from one blanket rule: a
            // substituted cache-READ rate can only be high, a substituted
            // cache-WRITE rate can land either side.
            may_overstate |= substitute_high;
            may_understate |= substitute_low;
            usd += count as f64 * rate;
        }

        // Unresolvable tiers: say which way the base sheet can be wrong rather
        // than assuming tiers always cost more. Compare the rate each bucket
        // would actually pay at every declared threshold against the base.
        if tier_prompt_tokens.is_none() {
            for tier in &self.pricing_tiers {
                let at_tier = Self::bucket_rates(&self.prices_for(tier.min_prompt_tokens));
                for (count, ((base_rate, _, _), (tier_rate, _, _))) in
                    tokens.into_iter().zip(rates.iter().zip(at_tier))
                {
                    if count == 0 {
                        continue;
                    }
                    if let (Some(base), Some(tiered)) = (base_rate, tier_rate) {
                        may_understate |= tiered > *base;
                        may_overstate |= tiered < *base;
                    }
                }
            }
        }

        Some(ApproxCost {
            usd: usd / 1_000_000.0,
            may_overstate,
            may_understate,
        })
    }
}

/// A cost figure plus which way it can be wrong.
///
/// Presenting an estimate as an exact price is the same failure as billing an
/// unrated bucket at zero, one step later — so the direction travels with the
/// number instead of being re-derived (or forgotten) at each display site.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ApproxCost {
    /// USD.
    pub usd: f64,
    /// The true cost may be **lower** — a bucket was priced at a substitute
    /// rate that can only be too high (a cache read at the uncached-input
    /// rate), or a pricing tier is cheaper than the base sheet used.
    pub may_overstate: bool,
    /// The true cost may be **higher** — a pricing tier dearer than the base
    /// sheet could not be resolved from the tokens the caller had, or a cache
    /// *write* was priced at the uncached-input rate and the provider charges
    /// a surcharge for it (Anthropic 1.25x, OpenRouter's 1h TTL 2x).
    pub may_understate: bool,
}

impl ApproxCost {
    /// Every rate applied exactly; the figure is the price.
    pub fn is_exact(&self) -> bool {
        !self.may_overstate && !self.may_understate
    }

    /// Prefix for the figure: `≤` a ceiling, `≥` a floor, `~` neither bound
    /// holds, empty when exact. Rendering the number without this is the
    /// defect the type exists to prevent.
    pub fn marker(&self) -> &'static str {
        match (self.may_overstate, self.may_understate) {
            (false, false) => "",
            (true, false) => "≤",
            (false, true) => "≥",
            (true, true) => "~",
        }
    }
}

/// A score on a public benchmark from a published source (model card,
/// paper, leaderboard). The schema is deliberately permissive — no enum
/// of benchmark names — so the catalog can carry whichever benchmarks
/// the upstream provider chose to publish, and new ones can be added
/// without a code change. Scores are stored on a 0.0–1.0 scale (e.g.
/// 73.5% accuracy → 0.735) so they compare cleanly across benchmarks
/// and so `routing_ext::apply_benchmark_priors` can consume them
/// directly when wired in later.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BenchmarkScore {
    /// Benchmark name as published (e.g., "MMLU-Pro", "GPQA-Diamond",
    /// "SWE-bench-Verified", "HumanEval", "MATH").
    pub name: String,
    /// Score on a 0.0–1.0 scale.
    pub score: f64,
    /// Evaluation harness or setup label (e.g., "5-shot", "0-shot CoT",
    /// "agentic", "pass@1"). Optional but strongly recommended — the
    /// same benchmark name can mean different things under different
    /// harnesses.
    #[serde(default)]
    pub harness: Option<String>,
    /// Where the score came from (model card URL, paper, leaderboard
    /// snapshot). Empty when the source is the upstream provider's
    /// announcement and a stable URL is not yet known.
    #[serde(default)]
    pub source_url: Option<String>,
    /// ISO 8601 date of the score snapshot (e.g., "2025-08-12"). Lets
    /// downstream code judge how stale a number is.
    #[serde(default)]
    pub measured_at: Option<String>,
}

/// The full declarative schema for a model.
///
/// Analogous to `ToolSchema` — describes what a model is, what it can do,
/// and how to access it. The router uses this for constraint-based filtering
/// and cold-start scoring before observed performance data is available.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelSchema {
    /// Unique identifier: "provider/model-name:variant" (e.g., "qwen/qwen3-4b:q4_k_m").
    pub id: String,
    /// Human-readable display name.
    pub name: String,
    /// Provider (qwen, openai, anthropic, google, meta, ollama, custom).
    pub provider: String,
    /// Model family for grouping (qwen3, gpt-4, claude-4, llama-3).
    pub family: String,
    /// Semantic version or checkpoint label.
    #[serde(default)]
    pub version: String,
    /// What this model can do — ordered by primary capability first.
    pub capabilities: Vec<ModelCapability>,
    /// Context window in tokens.
    pub context_length: usize,
    /// Per-model maximum OUTPUT tokens the provider will return in one
    /// response. None = unknown; callers fall back to
    /// effective_max_output() which derives a fraction of context_length.
    #[serde(default)]
    pub max_output_tokens: Option<usize>,
    /// Parameter count as human-readable string (e.g., "4B", "30B (3B active)").
    #[serde(default)]
    pub param_count: String,
    /// Quantization (Q4_K_M, Q8_0, F16, none).
    #[serde(default)]
    pub quantization: Option<String>,
    /// Declared performance envelope (initial estimate, overridden by observed data).
    #[serde(default)]
    pub performance: PerformanceEnvelope,
    /// Cost structure.
    #[serde(default)]
    pub cost: CostModel,
    /// How to access this model.
    pub source: ModelSource,
    /// Free-form tags for filtering (e.g., "fast", "multilingual", "moe").
    #[serde(default)]
    pub tags: Vec<String>,
    /// Supported generation parameters. The inference layer strips any parameter
    /// not in this set before sending to the API. Empty = all supported.
    #[serde(default)]
    pub supported_params: Vec<GenerateParam>,
    /// Public benchmark scores as published by the model provider or
    /// reproduced on a public leaderboard (MMLU-Pro, GPQA-Diamond,
    /// SWE-bench, HumanEval, etc.). The built-in catalog ships this
    /// empty — population is a curation step, not a code change. See
    /// `BenchmarkScore` for the field shape and the 0.0–1.0 scoring
    /// convention.
    #[serde(default)]
    pub public_benchmarks: Vec<BenchmarkScore>,
    /// How much the project vouches for this model. The built-in catalog is
    /// `Curated`. Deserialization retains the legacy `Curated` default, so
    /// every user-controlled ingestion boundary must call
    /// [`Self::mark_user_registered`] before persistence or registration.
    /// Gates auto-apply (task #8) and this is surfaced in recommendation
    /// rationale.
    #[serde(default)]
    pub trust_tier: TrustTier,
    /// Superseded models stay listed if installed but are excluded from
    /// fresh recommendations. `#[serde(default)]` → not deprecated.
    #[serde(default)]
    pub deprecated: bool,
    /// Whether this model is currently available (downloaded / reachable).
    /// Not serialized — computed at runtime.
    #[serde(skip)]
    pub available: bool,
    /// Whether this model can be used **right now, without a download**.
    ///
    /// Deliberately narrower than [`Self::available`], which for a local MLX
    /// model is true as soon as an `hf_repo` is declared — `ensure_local()`
    /// lazy-downloads on first use, so a declared repo is "functionally
    /// available" (see #164). That is the right default for open-ended work and
    /// wrong for work on a deadline: a step with a bounded budget that picks a
    /// model it must first fetch spends the whole budget downloading and fails.
    /// That is exactly how `car code`'s 120s contract derivation became
    /// unusable on a machine with no local weights (Parslee-ai/car#638).
    ///
    /// Callers express the requirement with [`crate::IntentHint::require_ready`];
    /// this is the per-candidate fact that hint filters on. Recomputed on every
    /// registration, so a cached schema can't carry a stale value.
    #[serde(skip)]
    pub weights_ready: bool,
}

impl ModelSchema {
    /// Mark a schema as user-controlled rather than project-vetted.
    ///
    /// This is intentionally separate from serde's legacy default: old built-in
    /// and test fixtures omit `trust_tier` and must continue to deserialize,
    /// while `models.json`, CLI imports, and daemon `models.register` must never
    /// inherit `Curated` merely because a caller omitted the field or supplied
    /// a forged value.
    pub fn mark_user_registered(&mut self) {
        self.trust_tier = TrustTier::Community;
    }

    /// Check if this model has a given capability.
    pub fn has_capability(&self, cap: ModelCapability) -> bool {
        self.capabilities.contains(&cap)
    }

    /// Live availability for credential-backed providers. The catalog field is
    /// a startup snapshot; Settings/OAuth changes must affect the next list and
    /// route without a daemon restart.
    pub fn available_now(&self) -> bool {
        match &self.source {
            ModelSource::RemoteApi {
                protocol: ApiProtocol::OpenRouter,
                ..
            } => self.available && crate::openrouter::credential_source().is_some(),
            _ => self.available,
        }
    }

    /// Prompt-cache economics for this model, derived from its remote
    /// protocol. Local / non-remote models have no remote prompt cache, so
    /// their cache rates are inert ([`CacheRates::NONE`]).
    pub fn cache_rates(&self) -> crate::outcome::CacheRates {
        match &self.source {
            ModelSource::RemoteApi {
                protocol: ApiProtocol::OpenRouter,
                ..
            } => {
                let input = self.cost.input_per_mtok.unwrap_or(0.0);
                if input > 0.0 {
                    crate::outcome::CacheRates {
                        read_mult: self.cost.cache_read_input_per_mtok.unwrap_or(0.0) / input,
                        write_mult: self.cost.cache_write_input_per_mtok.unwrap_or(0.0) / input,
                    }
                } else {
                    crate::outcome::CacheRates::NONE
                }
            }
            ModelSource::RemoteApi { protocol, .. } => protocol.cache_rates(),
            _ => crate::outcome::CacheRates::NONE,
        }
    }

    /// Check if this model is local (runs on-device).
    pub fn is_local(&self) -> bool {
        matches!(
            self.source,
            ModelSource::Local { .. }
                | ModelSource::Mlx { .. }
                | ModelSource::WhisperCpp { .. }
                | ModelSource::WindowsSpeech { .. }
                | ModelSource::VllmMlx { .. }
                | ModelSource::AppleFoundationModels { .. }
        )
    }

    /// Check if this model delegates inference to a host-registered
    /// runner (closes Parslee-ai/car-releases#24).
    pub fn is_delegated(&self) -> bool {
        matches!(self.source, ModelSource::Delegated { .. })
    }

    /// Check if this model uses the MLX backend.
    pub fn is_mlx(&self) -> bool {
        matches!(self.source, ModelSource::Mlx { .. })
    }

    /// Check if this model routes to Apple's on-device FoundationModels
    /// framework. True only for `ModelSource::AppleFoundationModels`;
    /// callers must still verify runtime availability before dispatch
    /// (the schema can describe the model on any host, but execution
    /// requires macOS 26+ on Apple Silicon).
    pub fn is_foundation_models(&self) -> bool {
        matches!(self.source, ModelSource::AppleFoundationModels { .. })
    }

    /// Check if this model uses vLLM-MLX backend.
    pub fn is_vllm_mlx(&self) -> bool {
        matches!(self.source, ModelSource::VllmMlx { .. })
    }

    /// Whether this model can only run on Apple Silicon (Metal). True for
    /// MLX, vLLM-MLX, and Apple FoundationModels sources. The recommender
    /// uses this to exclude Metal-only picks on CPU-only / CUDA hosts rather
    /// than storing a redundant backend-compatibility field that could drift
    /// from `source`.
    pub fn requires_apple_silicon(&self) -> bool {
        self.is_mlx() || self.is_vllm_mlx() || self.is_foundation_models()
    }

    /// Check if this model is remote (requires API call).
    pub fn is_remote(&self) -> bool {
        matches!(
            self.source,
            ModelSource::RemoteApi { .. } | ModelSource::Proprietary { .. }
        )
    }

    /// Collect all API key env var names for this model (primary + extras).
    /// Returns empty vec for non-remote models.
    pub fn all_api_key_envs(&self) -> Vec<String> {
        match &self.source {
            ModelSource::RemoteApi {
                api_key_env,
                api_key_envs,
                ..
            } => {
                let mut all = vec![api_key_env.clone()];
                all.extend(api_key_envs.iter().cloned());
                all
            }
            ModelSource::Proprietary {
                auth: ProprietaryAuth::ApiKeyEnv { env_var },
                ..
            }
            | ModelSource::Proprietary {
                auth: ProprietaryAuth::BearerTokenEnv { env_var },
                ..
            } => vec![env_var.clone()],
            _ => vec![],
        }
    }

    /// Get the size in MB (from cost model or 0 if unknown).
    pub fn size_mb(&self) -> u64 {
        self.cost.size_mb.unwrap_or(0)
    }

    /// Get the RAM requirement in MB (from cost model, falls back to size_mb).
    pub fn ram_mb(&self) -> u64 {
        self.cost.ram_mb.unwrap_or_else(|| self.size_mb())
    }

    /// Estimated cost per 1K output tokens in USD. Returns 0.0 for local models.
    pub fn cost_per_1k_output(&self) -> f64 {
        self.cost.output_per_mtok.map(|c| c / 1000.0).unwrap_or(0.0)
    }

    /// The per-turn output-token ceiling to use when the caller didn't
    /// specify one. Prefers the registry-declared `max_output_tokens`;
    /// otherwise derives a quarter of the context window, clamped to a
    /// sane [4096, 32768] band so a 1M-context model doesn't request a
    /// 250K-token response the API rejects and a tiny 8K model doesn't
    /// get an absurdly small ceiling. (Registry value first, computed
    /// fallback second — mirrors a provider lookup with a derived default.)
    pub fn effective_max_output(&self) -> usize {
        self.max_output_tokens
            .unwrap_or_else(|| (self.context_length / 4).clamp(4096, 32_768))
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn sample_local() -> ModelSchema {
        ModelSchema {
            id: "qwen/qwen3-4b:q4_k_m".into(),
            name: "Qwen3-4B".into(),
            provider: "qwen".into(),
            family: "qwen3".into(),
            version: "1.0".into(),
            capabilities: vec![ModelCapability::Generate, ModelCapability::Code],
            context_length: 32768,
            max_output_tokens: None,
            param_count: "4B".into(),
            quantization: Some("Q4_K_M".into()),
            performance: PerformanceEnvelope {
                tokens_per_second: Some(45.0),
                ..Default::default()
            },
            cost: CostModel {
                size_mb: Some(2500),
                ram_mb: Some(2500),
                ..Default::default()
            },
            source: ModelSource::Local {
                hf_repo: "Qwen/Qwen3-4B-GGUF".into(),
                hf_filename: "Qwen3-4B-Q4_K_M.gguf".into(),
                tokenizer_repo: "Qwen/Qwen3-4B".into(),
            },
            tags: vec!["code".into(), "fast".into()],
            supported_params: vec![],
            public_benchmarks: vec![],
            trust_tier: TrustTier::Curated,
            deprecated: false,
            available: false,
            weights_ready: false,
        }
    }

    fn sample_remote() -> ModelSchema {
        ModelSchema {
            id: "anthropic/claude-sonnet-4-6:latest".into(),
            name: "Claude Sonnet 4.6".into(),
            provider: "anthropic".into(),
            family: "claude-4".into(),
            version: "latest".into(),
            capabilities: vec![
                ModelCapability::Generate,
                ModelCapability::Code,
                ModelCapability::Reasoning,
                ModelCapability::ToolUse,
                ModelCapability::Vision,
            ],
            context_length: 200000,
            max_output_tokens: None,
            param_count: String::new(),
            quantization: None,
            performance: PerformanceEnvelope {
                latency_p50_ms: Some(2000),
                latency_p99_ms: Some(8000),
                tokens_per_second: Some(80.0),
            },
            cost: CostModel {
                input_per_mtok: Some(3.0),
                output_per_mtok: Some(15.0),
                ..Default::default()
            },
            source: ModelSource::RemoteApi {
                endpoint: "https://api.anthropic.com/v1/messages".into(),
                api_key_env: "ANTHROPIC_API_KEY".into(),
                api_key_envs: vec![],
                api_version: Some("2023-06-01".into()),
                protocol: ApiProtocol::Anthropic,
            },
            tags: vec!["reasoning".into(), "tool_use".into()],
            supported_params: vec![],
            public_benchmarks: vec![],
            trust_tier: TrustTier::Curated,
            deprecated: false,
            available: false,
            weights_ready: false,
        }
    }

    #[test]
    fn capabilities() {
        let m = sample_local();
        assert!(m.has_capability(ModelCapability::Code));
        assert!(!m.has_capability(ModelCapability::Vision));
    }

    #[test]
    fn local_vs_remote() {
        assert!(sample_local().is_local());
        assert!(!sample_local().is_remote());
        assert!(sample_remote().is_remote());
        assert!(!sample_remote().is_local());
    }

    #[test]
    fn cost() {
        let local = sample_local();
        assert_eq!(local.cost_per_1k_output(), 0.0);

        let remote = sample_remote();
        assert!(remote.cost_per_1k_output() > 0.0);
    }

    #[test]
    fn serde_roundtrip() {
        let local = sample_local();
        let json = serde_json::to_string(&local).unwrap();
        let parsed: ModelSchema = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.id, local.id);
        assert_eq!(parsed.capabilities, local.capabilities);

        let remote = sample_remote();
        let json = serde_json::to_string(&remote).unwrap();
        let parsed: ModelSchema = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.id, remote.id);
        // available is skip-serialized, defaults to false
        assert!(!parsed.available);
    }

    #[test]
    fn trust_tier_and_deprecated_default_when_absent() {
        // Pre-existing ~/.car/models.json configs omit the new fields.
        // They must deserialize to Curated / not-deprecated, not error.
        let json = serde_json::to_string(&sample_local()).unwrap();
        let stripped = json
            .replace(",\"trust_tier\":\"curated\"", "")
            .replace(",\"deprecated\":false", "");
        let parsed: ModelSchema = serde_json::from_str(&stripped).unwrap();
        assert_eq!(parsed.trust_tier, TrustTier::Curated);
        assert!(!parsed.deprecated);
    }

    #[test]
    fn trust_tier_serializes_snake_case() {
        assert_eq!(
            serde_json::to_string(&TrustTier::Community).unwrap(),
            "\"community\""
        );
        assert_eq!(TrustTier::default(), TrustTier::Curated);
    }

    #[test]
    fn requires_apple_silicon_only_for_metal_backends() {
        // GGUF/Candle local and remote models run anywhere CAR builds for.
        assert!(!sample_local().requires_apple_silicon());
        assert!(!sample_remote().requires_apple_silicon());

        let mlx = ModelSchema {
            source: ModelSource::Mlx {
                hf_repo: "mlx-community/Qwen3-4B-4bit".into(),
                hf_weight_file: None,
            },
            ..sample_local()
        };
        assert!(mlx.requires_apple_silicon());

        // vLLM-MLX and Apple FoundationModels are equally Metal-bound.
        let vllm = ModelSchema {
            source: ModelSource::VllmMlx {
                endpoint: "http://localhost:8000".into(),
                model_name: "mlx-community/Qwen3-4B-4bit".into(),
            },
            ..sample_local()
        };
        assert!(vllm.requires_apple_silicon());

        let foundation = ModelSchema {
            source: ModelSource::AppleFoundationModels { use_case: None },
            ..sample_local()
        };
        assert!(foundation.requires_apple_silicon());
    }

    fn priced(
        input: Option<f64>,
        output: Option<f64>,
        cache_read: Option<f64>,
        cache_write: Option<f64>,
    ) -> CostModel {
        CostModel {
            input_per_mtok: input,
            output_per_mtok: output,
            cache_read_input_per_mtok: cache_read,
            cache_write_input_per_mtok: cache_write,
            ..Default::default()
        }
    }

    #[test]
    fn an_undeclared_cache_rate_is_bounded_by_the_input_rate_not_billed_at_zero() {
        // The real shape this exists for: qwen3.5-plus declares input and
        // output but no cache-read rate. 1M cache-read tokens must not be free.
        let cost = priced(Some(0.26), Some(1.56), None, None);
        let bounded = cost
            .estimated_usd_bounded(Some(1_000_000), 0, 0, 1_000_000, 0)
            .expect("a model with input+output rates is priceable");
        assert!(bounded.may_overstate, "substituted rate can only be high");
        assert!(!bounded.may_understate);
        assert_eq!(bounded.marker(), "≤");
        assert!(
            (bounded.usd - 0.26).abs() < 1e-9,
            "cache reads fall back to the $0.26/MTok input rate, got {}",
            bounded.usd
        );

        // The routing-score path still zero-fills, deliberately and untouched.
        assert_eq!(cost.estimated_usd(1_000_000, 0, 1_000_000, 0), 0.0);
    }

    #[test]
    fn an_undeclared_cache_write_rate_claims_no_bound_it_cannot_keep() {
        // The shipped `claude-opus-4.8` shape with its cache-write rate
        // omitted. Anthropic's cache write is a 1.25x SURCHARGE (6.25 against
        // 5.0 input), and OpenRouter's 1h-TTL rate is 2x — so pricing the
        // bucket at the input rate is a FLOOR, and the `≤` a blanket
        // "cache is always cheaper" rule would have produced is a false
        // ceiling over a true cost of $6.25, or $10.00 at the 1h rate.
        let cost = priced(Some(5.0), Some(25.0), Some(0.5), None);
        let bounded = cost
            .estimated_usd_bounded(Some(1_000_000), 0, 0, 0, 1_000_000)
            .expect("input and output rates are published");
        assert!((bounded.usd - 5.0).abs() < 1e-9, "got {}", bounded.usd);
        assert!(
            bounded.may_understate,
            "a cache-write surcharge can exceed the input rate"
        );
        assert_ne!(bounded.marker(), "≤", "must not claim a ceiling it fails");
        assert_eq!(bounded.marker(), "~", "sign is unknown, so neither bound");
        // Both real cache-write rates this shape could carry sit ABOVE the
        // substituted figure — which is exactly why `≤` would have been a
        // false ceiling. Assert the tighter of the two; it implies the looser,
        // and spelling out both comparisons is a `redundant_comparisons` lint.
        let at_anthropics_1_25x: f64 = 1_000_000.0 * 6.25 / 1e6;
        let at_openrouters_1h_2x: f64 = 1_000_000.0 * 10.0 / 1e6;
        assert!(bounded.usd < at_anthropics_1_25x.min(at_openrouters_1h_2x));

        // Declaring the rate makes it exact — the flag tracks substitution,
        // not the mere presence of cache-write tokens.
        let declared = priced(Some(5.0), Some(25.0), Some(0.5), Some(6.25))
            .estimated_usd_bounded(Some(1_000_000), 0, 0, 0, 1_000_000)
            .unwrap();
        assert!(declared.is_exact());
        assert!((declared.usd - 6.25).abs() < 1e-9);

        // The same omission on the cache READ side DOES keep its ceiling —
        // the two directions are not shared. Note the rate must be missing for
        // a substitution to happen at all.
        let read = priced(Some(5.0), Some(25.0), None, Some(6.25))
            .estimated_usd_bounded(Some(1_000_000), 0, 0, 1_000_000, 0)
            .unwrap();
        assert_eq!(read.marker(), "≤");
        assert!((read.usd - 5.0).abs() < 1e-9);
        // A real cache-read rate is a discount, so the ceiling holds.
        assert!(read.usd > 1_000_000.0 * 0.5 / 1e6);
    }

    #[test]
    fn a_declared_cache_rate_is_exact_and_never_flagged() {
        let cost = priced(Some(5.0), Some(25.0), Some(0.5), Some(6.25));
        let bounded = cost
            .estimated_usd_bounded(Some(1_600_000), 1_000_000, 200_000, 500_000, 100_000)
            .expect("fully rated");
        assert!(bounded.is_exact(), "nothing was substituted or unresolved");
        assert_eq!(bounded.marker(), "");
        // 1M uncached x 5 + 200k x 25 + 500k x 0.5 + 100k x 6.25, per MTok.
        assert!((bounded.usd - 10.875).abs() < 1e-9, "got {}", bounded.usd);
        // Identical to the router's figure when every rate is published.
        assert!(
            (bounded.usd - cost.estimated_usd(1_600_000, 200_000, 500_000, 100_000)).abs() < 1e-9
        );
    }

    #[test]
    fn an_unbounded_bucket_refuses_rather_than_understating() {
        // Output has no safe substitute — it is normally the dearer side, so
        // pricing it at the input rate would UNDER-state. Refuse instead.
        let cost = priced(Some(1.0), None, None, None);
        assert_eq!(
            cost.estimated_usd_bounded(Some(1_000), 1_000, 1_000, 0, 0),
            None
        );
        // With no output tokens the same model is priceable and exact.
        let bounded = cost
            .estimated_usd_bounded(Some(1_000), 1_000, 0, 0, 0)
            .unwrap();
        assert!(bounded.is_exact());
    }

    #[test]
    fn no_rate_card_is_unpriced_rather_than_free() {
        let cost = CostModel::default();
        assert_eq!(
            cost.estimated_usd_bounded(Some(1_000), 1_000, 1_000, 0, 0),
            None
        );
        // And a zero-usage priced model is genuinely free, not unpriced.
        let free = priced(Some(0.0), Some(0.0), None, None)
            .estimated_usd_bounded(Some(0), 0, 0, 0, 0)
            .expect("a declared zero rate card is priced");
        assert_eq!(free.usd, 0.0);
        assert!(free.is_exact());
    }

    fn tiered() -> CostModel {
        CostModel {
            input_per_mtok: Some(2.5),
            output_per_mtok: Some(15.0),
            cache_read_input_per_mtok: Some(0.25),
            pricing_tiers: vec![TokenPricingTier {
                min_prompt_tokens: 272_000,
                prices: TokenPrices {
                    input_per_mtok: Some(5.0),
                    output_per_mtok: Some(22.5),
                    cache_read_input_per_mtok: Some(0.5),
                    cache_write_input_per_mtok: None,
                },
            }],
            ..Default::default()
        }
    }

    #[test]
    fn a_known_prompt_size_resolves_the_tier_exactly() {
        let cost = tiered();
        let below = cost
            .estimated_usd_bounded(Some(271_999), 271_999, 0, 0, 0)
            .unwrap();
        assert!(below.is_exact());
        assert!((below.usd - 271_999.0 * 2.5 / 1e6).abs() < 1e-9);

        let above = cost
            .estimated_usd_bounded(Some(272_000), 272_000, 0, 0, 0)
            .unwrap();
        assert!(above.is_exact());
        assert!((above.usd - 272_000.0 * 5.0 / 1e6).abs() < 1e-9);
    }

    #[test]
    fn a_lifetime_aggregate_uses_base_rates_and_admits_it_may_be_low() {
        // Thirty 10K-token requests. Their SUM crosses the 272K threshold that
        // no single request came near — the double-charging bug. `None` says
        // "boundaries lost", so base rates apply and the figure is marked.
        let cost = tiered();
        let aggregate = cost.estimated_usd_bounded(None, 300_000, 0, 0, 0).unwrap();
        assert!(
            (aggregate.usd - 300_000.0 * 2.5 / 1e6).abs() < 1e-9,
            "must use the $2.50 base rate, got {}",
            aggregate.usd
        );
        assert!(aggregate.may_understate, "a dearer tier may apply");
        assert!(!aggregate.may_overstate);
        assert_eq!(aggregate.marker(), "≥");

        // What the bug looked like: summed tokens passed as a real prompt size
        // price at the high-context rate — exactly double, and unmarked.
        let bug = cost
            .estimated_usd_bounded(Some(300_000), 300_000, 0, 0, 0)
            .unwrap();
        assert!((bug.usd - 2.0 * aggregate.usd).abs() < 1e-9);
        assert!(bug.is_exact(), "and it would have claimed to be exact");
    }

    #[test]
    fn a_cheaper_tier_flags_the_aggregate_as_possibly_high_instead() {
        // Direction is derived from the tiers, not assumed. A volume DISCOUNT
        // makes the base-rate figure too high, not too low.
        let cost = CostModel {
            input_per_mtok: Some(2.0),
            output_per_mtok: Some(10.0),
            pricing_tiers: vec![TokenPricingTier {
                min_prompt_tokens: 100_000,
                prices: TokenPrices {
                    input_per_mtok: Some(1.0),
                    ..Default::default()
                },
            }],
            ..Default::default()
        };
        let aggregate = cost.estimated_usd_bounded(None, 500_000, 0, 0, 0).unwrap();
        assert!(aggregate.may_overstate);
        assert!(!aggregate.may_understate);
        assert_eq!(aggregate.marker(), "≤");
    }

    #[test]
    fn both_directions_at_once_claims_neither_bound() {
        // Unrated cache bucket (can be high) plus an unresolved dearer tier
        // (can be low). Neither bound survives, so the figure is just an
        // estimate and must not wear a `≤` it cannot honour.
        let cost = CostModel {
            input_per_mtok: Some(2.0),
            output_per_mtok: Some(10.0),
            pricing_tiers: vec![TokenPricingTier {
                min_prompt_tokens: 100_000,
                prices: TokenPrices {
                    input_per_mtok: Some(4.0),
                    ..Default::default()
                },
            }],
            ..Default::default()
        };
        let aggregate = cost.estimated_usd_bounded(None, 0, 0, 500_000, 0).unwrap();
        assert!(aggregate.may_overstate && aggregate.may_understate);
        assert_eq!(aggregate.marker(), "~");
    }
}