car_inference/

recommend.rs

//! Model recommender — hardware + intent → ranked, explained model picks.
//!
//! This is the framing layer that turns the typed registry
//! (`ModelSchema`), hardware facts (`HardwareInfo` / `SupportedAcceleration`),
//! and the acquisition-intent vocabulary (`UseCase` / `QualityTier` /
//! `Privacy`) into something a non-expert can act on: "given this machine
//! and what I want to do, which model should I install, and why?"
//!
//! The full contract lives in docs/solutions/first-class-model-ux.md. The
//! selection pipeline is deterministic — same `(models, hardware, intent)`
//! always yields the same ranking — and pure (no disk, no network), so the
//! hardware × use-case matrix is unit-testable.
//!
//! This supersedes `hardware::recommend_model` for the user-facing flows
//! (`car setup`, `models.recommend`). That standalone heuristic survives only
//! as a registry-less bootstrap inside `HardwareInfo::detect`; everything that
//! has a registry in hand should call [`recommend`].

use serde::{Deserialize, Serialize};

use crate::hardware::{HardwareInfo, SupportedAcceleration};
use crate::intent::{Privacy, QualityTier, UseCase, UseCaseRole};
use crate::resource_policy::{
    estimate_model_memory_for_checkpoint, model_parameter_billions_active,
    model_parameter_billions_total, CheckpointGeometry, ResourcePolicy, ResourceProfile,
    RECOMMENDATION_CONTEXT_TOKENS,
};
use crate::schema::{ModelSchema, TrustTier};

/// Whether a model fits in the machine's memory for local execution.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FitStatus {
    /// Comfortably fits with headroom for KV cache + overhead.
    Fits,
    /// Too large for this machine's memory budget.
    TooBig,
    /// Runs on an external server (vLLM-MLX) or remote API — local memory
    /// does not apply. Never claimed as a local "fits".
    ServerProvided,
    /// The model declares no usable memory figure, so fit can't be asserted.
    Unknown,
}

/// One ranked recommendation, explained in plain language.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Recommendation {
    /// Registry id (e.g. "qwen/qwen3-4b:q4_k_m"). The caller pulls by this.
    pub model_id: String,
    /// Human-readable name shown to the user.
    pub display_name: String,
    /// The role lane this pick serves.
    pub role: UseCaseRole,
    /// Plain-language reason, generated from the winning factors. Never
    /// exposes quantization / repo / file jargon.
    pub rationale: String,
    /// Download size in MB.
    pub download_mb: u64,
    /// True if the model is already installed.
    pub already_installed: bool,
    /// Local memory fit.
    pub fit: FitStatus,
    /// The acceleration tier this machine would run it on.
    pub acceleration: SupportedAcceleration,
    /// True for on-device models, false for remote/cloud.
    pub is_local: bool,
    /// True when running this pick sends prompts off the machine — the
    /// caller must obtain one-time consent before the first cloud inference.
    pub requires_cloud_consent: bool,
    /// How much the project vouches for this model.
    pub trust_tier: TrustTier,
    /// Internal blended score (higher is better). Exposed for tests/debug.
    pub score: f32,
    /// Whether CAR may choose this candidate automatically for the current
    /// policy lane. False candidates remain visible as explicit heavier or
    /// unknown-memory alternatives that a person can choose deliberately.
    ///
    /// The default preserves deserialization compatibility with responses
    /// produced before this additive field existed.
    #[serde(default = "default_true")]
    pub within_recommendation_target: bool,
}

const fn default_true() -> bool {
    true
}

// --- tuning constants (documented; consistent with hardware.rs scale) ------

/// RAM the OS + other apps need; subtracted from total before the budget.
const OS_RESERVE_MB: u64 = 3072;

/// The result of a recommendation query — never a bare `Vec`, so the caller
/// can tell "here are your picks" from "nothing fits, here's why".
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RecommendationSet {
    /// Ranked, actionable picks (best first). Empty when nothing is eligible
    /// or everything is too big — read `note` in that case.
    pub picks: Vec<Recommendation>,
    /// Eligible models that don't fit this machine's memory, for an honest
    /// "needs more RAM" listing. Ranked by score so the closest miss is first.
    pub not_enough_memory: Vec<Recommendation>,
    /// Plain-language explanation when `picks` is empty, or a heads-up worth
    /// surfacing (e.g. the top pick runs in the cloud). `None` otherwise.
    pub note: Option<String>,
}

/// Memory fit of one catalog row on one machine, as `models.list_unified`
/// publishes it. Three-valued on purpose: a catalog consumer wants to know
/// whether to offer the row, and "the server owns its memory" is, for that
/// question, a fit. [`FitStatus`] keeps the four-way distinction for the
/// recommender, which ranks rather than filters.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum ModelFitStatus {
    /// Fits this machine's active local-model budget, or runs somewhere that
    /// is not this machine's memory at all (remote API, delegated runner,
    /// operator-managed external endpoint).
    Fits,
    /// Too large for this machine's active local-model budget.
    TooBig,
    /// The row declares no usable memory figure, or the accelerator's memory
    /// is unknown, so fit cannot be asserted either way. Also what a client
    /// sees from a daemon that predates the annotation, which is why it is
    /// the `Default`: an absent verdict must never read as too-big.
    #[default]
    Unknown,
}

/// A row's fit annotation: the verdict, the estimate it was judged on, and
/// whether the accelerator can run the row at all.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ModelFit {
    pub fit: ModelFitStatus,
    /// The cold-load peak the verdict was judged against, in MB. `None` when
    /// the row's memory is not this machine's (remote, delegated, external)
    /// or when it declares neither a size nor a RAM figure — the same rows
    /// the recommender refuses to judge by memory.
    pub estimated_peak_mb: Option<u64>,
    /// See [`platform_compatible`].
    pub platform_compatible: bool,
}

/// The `models.list_unified` fit rule. It is `build_recommendation`'s own
/// verdict — the same [`estimate_model_memory_for_checkpoint`] at
/// [`RECOMMENDATION_CONTEXT_TOKENS`], the same `fit_status`, the same policy
/// ceiling — collapsed to the three values a catalog consumer acts on, plus
/// `passes_base_filter`'s platform check. Pure over its inputs: nothing here
/// touches disk or the network, and nothing is persisted.
///
/// `geometry` carries installed checkpoints' own KV geometry, read by the
/// caller from the models directory admission reads (car#2213). An installed
/// row's KV cache is therefore sized as admission sizes it; a row `geometry`
/// does not hold falls back to the parameter count, as admission does. What
/// still separates the two is live memory, which only admission consults.
/// Every reader of this verdict shares the input — `models.list_unified`'s
/// `fit`, `models.recommend`, the portfolio's `never_runs_here`, and
/// `car models fit`.
pub fn model_fit(
    m: &ModelSchema,
    hw: &HardwareInfo,
    policy: Option<&ResourcePolicy>,
    geometry: &CheckpointGeometry,
) -> ModelFit {
    let memory_limits = RecommendationMemoryLimits::for_policy(hw, policy);
    let estimate =
        estimate_model_memory_for_checkpoint(m, hw, RECOMMENDATION_CONTEXT_TOKENS, geometry);
    let status = fit_status(m, hw, &estimate, &memory_limits);
    let fit = match status {
        FitStatus::Fits | FitStatus::ServerProvided => ModelFitStatus::Fits,
        FitStatus::TooBig => ModelFitStatus::TooBig,
        FitStatus::Unknown => ModelFitStatus::Unknown,
    };
    let estimated_peak_mb = match status {
        FitStatus::ServerProvided => None,
        // Mirrors `fit_status`'s own "nothing declared" gate: an estimate
        // derived from no declared figure is not evidence worth publishing.
        _ if m.size_mb() == 0 && m.ram_mb() == 0 => None,
        _ => Some(estimate.estimated_peak_mb),
    };
    ModelFit {
        fit,
        estimated_peak_mb,
        platform_compatible: platform_compatible(m, hw),
    }
}

/// Rank model picks for a machine + intent, best first. Pure over its inputs.
///
/// `models` is typically `UnifiedRegistry::list()`. Returns at most one
/// role's lane today (every `UseCase` is single-role). Too-big-but-eligible
/// models are surfaced separately in `not_enough_memory` rather than dropped
/// silently, and an empty `picks` always comes with an explanatory `note`.
/// `geometry` is installed checkpoints' KV geometry, as for [`model_fit`].
pub fn recommend(
    models: &[&ModelSchema],
    hw: &HardwareInfo,
    use_case: UseCase,
    tier: QualityTier,
    privacy: Privacy,
    geometry: &CheckpointGeometry,
) -> RecommendationSet {
    recommend_inner(models, hw, use_case, tier, privacy, None, geometry)
}

/// Policy-aware recommendation entry point. Every profile supplies the fit
/// ceiling and automatic-selection target. Only Everyday Assistant/Balanced
/// changes the legacy ranking and capability floor.
pub fn recommend_with_policy(
    models: &[&ModelSchema],
    hw: &HardwareInfo,
    policy: &ResourcePolicy,
    use_case: UseCase,
    tier: QualityTier,
    privacy: Privacy,
    geometry: &CheckpointGeometry,
) -> RecommendationSet {
    recommend_inner(models, hw, use_case, tier, privacy, Some(policy), geometry)
}

fn recommend_inner(
    models: &[&ModelSchema],
    hw: &HardwareInfo,
    use_case: UseCase,
    tier: QualityTier,
    privacy: Privacy,
    policy: Option<&ResourcePolicy>,
    geometry: &CheckpointGeometry,
) -> RecommendationSet {
    let accel = hw.supported_acceleration();
    // A model without `ToolUse` cannot run the assistant: `car do` refuses it
    // and substitutes a tool-capable one. That is a property of the USE CASE,
    // not of the resource policy or the quality tier.
    //
    // It used to ride on `everyday_assistant_balanced` below, which also
    // selects a sort order, so the requirement silently applied only on the
    // default profile at the default tier. `--tier fastest` and
    // `--tier most-capable` therefore ranked models the assistant will not use
    // — and told the reader to install the top one with `car setup --for
    // assistant`. Measured before this split: `--tier fastest` returned
    // Qwen3-0.6B first, which has no `ToolUse` (car#1822).
    let assistant_requires_tools = use_case == UseCase::Assistant;
    let everyday_assistant_balanced = policy.is_some_and(|policy| {
        policy.profile == ResourceProfile::Everyday
            && use_case == UseCase::Assistant
            && tier == QualityTier::Balanced
    });
    let memory_limits = RecommendationMemoryLimits::for_policy(hw, policy);
    let sort = |v: &mut Vec<RankedRecommendation>| {
        // Everyday Assistant/Balanced is intentionally memory-first for local
        // candidates. The policy applies only in that lane, so every legacy
        // caller keeps the established score ordering.
        v.sort_by(|a, b| {
            if everyday_assistant_balanced {
                // This is an item-local key, not a pair-dependent branch.
                // That matters when local and cloud candidates are mixed:
                // every comparison observes the same total ordering, so sort
                // transitivity cannot depend on the input permutation.
                let policy_class = |recommendation: &Recommendation| {
                    if recommendation.fit == FitStatus::Unknown {
                        3
                    } else if recommendation.is_local && recommendation.within_recommendation_target
                    {
                        0
                    } else if !recommendation.is_local
                        && recommendation.within_recommendation_target
                    {
                        1
                    } else {
                        2
                    }
                };
                let a_recommendation = &a.recommendation;
                let b_recommendation = &b.recommendation;
                return policy_class(a_recommendation)
                    .cmp(&policy_class(b_recommendation))
                    .then(
                        b_recommendation
                            .already_installed
                            .cmp(&a_recommendation.already_installed),
                    )
                    .then(a.estimated_peak_mb.cmp(&b.estimated_peak_mb))
                    .then(a.latency_p50_ms.cmp(&b.latency_p50_ms))
                    .then_with(|| b_recommendation.score.total_cmp(&a_recommendation.score))
                    .then(a_recommendation.model_id.cmp(&b_recommendation.model_id));
            }
            b.recommendation
                .score
                .total_cmp(&a.recommendation.score)
                .then(
                    b.recommendation
                        .already_installed
                        .cmp(&a.recommendation.already_installed),
                )
                .then(
                    a.recommendation
                        .download_mb
                        .cmp(&b.recommendation.download_mb),
                )
                .then(a.recommendation.model_id.cmp(&b.recommendation.model_id))
        });
    };

    let size_prior_ceiling = size_prior_ceiling(models);
    let (mut picks, mut not_enough_memory): (Vec<_>, Vec<_>) = models
        .iter()
        .filter(|m| {
            passes_base_filter(m, hw, use_case, privacy)
                && (!assistant_requires_tools
                    || m.has_capability(crate::schema::ModelCapability::ToolUse))
        })
        .map(|model| {
            build_recommendation(
                model,
                hw,
                &accel,
                use_case,
                tier,
                &memory_limits,
                geometry,
                size_prior_ceiling,
            )
        })
        .partition(|ranked| ranked.recommendation.fit != FitStatus::TooBig);
    sort(&mut picks);
    sort(&mut not_enough_memory);
    let picks: Vec<_> = picks
        .into_iter()
        .map(|ranked| ranked.recommendation)
        .collect();
    let not_enough_memory: Vec<_> = not_enough_memory
        .into_iter()
        .map(|ranked| ranked.recommendation)
        .collect();

    let note = explain_if_needed(&picks, &not_enough_memory, hw, use_case, tier, privacy)
        .or_else(|| unmeasured_larger_candidates(models, &picks, tier));
    RecommendationSet {
        picks,
        not_enough_memory,
        note,
    }
}

struct RankedRecommendation {
    recommendation: Recommendation,
    estimated_peak_mb: u64,
    latency_p50_ms: u64,
}

#[derive(Clone, Copy)]
struct RecommendationMemoryLimits {
    legacy_budget_mb: u64,
    policy_host_budget_mb: Option<u64>,
    recommendation_target_mb: Option<u64>,
}

impl RecommendationMemoryLimits {
    /// The budgets every fit verdict is judged against: the legacy
    /// acceleration-tier budget, plus the policy's host ceiling and automatic
    /// recommendation target when a policy is in force. One constructor, so
    /// [`recommend_with_policy`] and [`model_fit`] cannot drift apart.
    fn for_policy(hw: &HardwareInfo, policy: Option<&ResourcePolicy>) -> Self {
        Self {
            legacy_budget_mb: memory_budget_mb(hw),
            policy_host_budget_mb: policy.map(|policy| {
                policy
                    .effective_budget(hw.total_ram_mb)
                    .configured_model_ceiling_mb
            }),
            recommendation_target_mb: policy
                .map(|policy| policy.recommendation_target_mb(hw.total_ram_mb)),
        }
    }
}

/// Hard eligibility, minus the fit check (fit is handled by partitioning so
/// too-big models can still be surfaced). A model failing any of these is
/// never shown at all.
fn passes_base_filter(
    m: &ModelSchema,
    hw: &HardwareInfo,
    use_case: UseCase,
    privacy: Privacy,
) -> bool {
    if m.deprecated {
        return false;
    }
    // Capability requirement encodes the role lane (Search⇒Embed, etc.).
    if !use_case
        .required_capabilities()
        .iter()
        .all(|c| m.has_capability(*c))
    {
        return false;
    }
    // Privacy: on-device excludes anything that leaves the machine.
    if privacy == Privacy::OnDevice && !m.is_local() {
        return false;
    }
    // A Metal-only model on a non-Apple machine can't run at all.
    platform_compatible(m, hw)
}

/// Whether this machine can run the model at all. Metal-only sources (MLX,
/// CAR-managed vLLM-MLX, Apple FoundationModels) need Apple Silicon, and
/// GGUF/Candle rows never run there;
/// WindowsSpeech and rows tagged `windows-only` need Windows; rows tagged
/// `linux-only` need Linux. Everything else runs anywhere CAR does. Shared by
/// the recommender's eligibility filter and the `models.list_unified` fit
/// annotation so the two cannot disagree about which rows a machine can host.
pub fn platform_compatible(m: &ModelSchema, hw: &HardwareInfo) -> bool {
    let windows_only = matches!(m.source, crate::schema::ModelSource::WindowsSpeech { .. })
        || m.tags.iter().any(|tag| tag == "windows-only");
    let linux_only = m.tags.iter().any(|tag| tag == "linux-only");
    let apple = matches!(
        hw.supported_acceleration(),
        SupportedAcceleration::Apple { .. }
    );
    let apple_compatible = !m.requires_apple_silicon() || apple;
    // On Apple Silicon CAR runs local text only through MLX: a GGUF request
    // executes as its MLX twin, an exact GGUF pin is refused, and a GGUF row
    // with no twin cannot run at all. Offering the GGUF row there recommended
    // a download that would never execute — and listed every Qwen3 twice.
    let candle_runs_here = !(apple && matches!(m.source, crate::schema::ModelSource::Local { .. }));
    let windows_compatible = !windows_only || hw.os.eq_ignore_ascii_case("windows");
    let linux_compatible = !linux_only || hw.os.eq_ignore_ascii_case("linux");
    apple_compatible && candle_runs_here && windows_compatible && linux_compatible
}

/// Build the honest `note` for the result set. Empty picks always get one.
fn explain_if_needed(
    picks: &[Recommendation],
    too_big: &[Recommendation],
    hw: &HardwareInfo,
    use_case: UseCase,
    tier: QualityTier,
    privacy: Privacy,
) -> Option<String> {
    let purpose = use_case_purpose(use_case);
    if picks.is_empty() {
        let ram_gb = hw.total_ram_mb / 1024;
        return Some(if !too_big.is_empty() {
            match privacy {
                Privacy::OnDevice => format!(
                    "No on-device model for {purpose} fits your {ram_gb} GB machine. \
                     Free up memory, pick a smaller tier, or allow cloud models."
                ),
                Privacy::CloudOk => format!(
                    "No local model for {purpose} fits your {ram_gb} GB machine, and no \
                     cloud model is configured. Add an API key or free up memory."
                ),
            }
        } else {
            format!("No model available for {purpose} on this machine.")
        });
    }
    // Heads-up when the best pick we can offer is the most-capable tier but
    // still ran out of bigger options, or when the top pick is cloud.
    if picks[0].requires_cloud_consent {
        return Some(format!(
            "The best {purpose} pick runs in the cloud and needs your OK before first use. \
             {} fits locally if you prefer on-device.",
            picks
                .iter()
                .find(|p| p.is_local)
                .map(|p| p.display_name.as_str())
                .unwrap_or("No local model")
        ));
    }
    let _ = tier;
    None
}

/// A heads-up when "most capable" had larger candidates it could not judge.
///
/// The quality prior is a published benchmark when one exists and a saturating
/// size curve otherwise, and those are not the same scale — the curve tops out
/// below what a real score reaches, so a measured mid-size model outranks an
/// unmeasured larger one by construction. That is defensible ranking (an
/// unmeasured model is genuinely unproven) but it is not something to state as
/// "the most capable model that fits" while saying nothing about the rest.
///
/// So: name them. The user can see that the answer is bounded by what has been
/// measured, and knows there is something to do about it.
fn unmeasured_larger_candidates(
    models: &[&ModelSchema],
    picks: &[Recommendation],
    tier: QualityTier,
) -> Option<String> {
    if tier != QualityTier::MostCapable {
        return None;
    }
    let top = picks.first()?;
    let top_params = models
        .iter()
        .find(|m| m.id == top.model_id)
        .map(|m| param_billions_total(m))?;

    let mut larger: Vec<&str> = models
        .iter()
        .filter(|m| {
            m.is_local()
                && m.public_benchmarks.is_empty()
                && param_billions_total(m) > top_params * 1.5
        })
        .map(|m| m.name.as_str())
        .collect();
    if larger.is_empty() {
        return None;
    }
    larger.sort_unstable();
    larger.dedup();
    let shown = larger
        .iter()
        .take(3)
        .copied()
        .collect::<Vec<_>>()
        .join(", ");
    let rest = larger.len().saturating_sub(3);
    let and_more = if rest > 0 {
        format!(" and {rest} more")
    } else {
        String::new()
    };
    Some(format!(
        "Ranked among models with a measured quality score. Larger ones this \
         machine can run are unscored, so they cannot be ranked here yet: \
         {shown}{and_more}. Run `scripts/bench-contribute.sh` to score them."
    ))
}

fn use_case_purpose(use_case: UseCase) -> &'static str {
    match use_case {
        UseCase::Assistant => "chat & general help",
        UseCase::Coding => "coding",
        UseCase::Summarize => "summarizing",
        UseCase::Vision => "understanding images",
        UseCase::Transcription => "transcription",
        UseCase::Search => "semantic search",
    }
}

fn build_recommendation(
    m: &ModelSchema,
    hw: &HardwareInfo,
    accel: &SupportedAcceleration,
    use_case: UseCase,
    tier: QualityTier,
    memory_limits: &RecommendationMemoryLimits,
    geometry: &CheckpointGeometry,
    size_prior_ceiling: f32,
) -> RankedRecommendation {
    let estimate =
        estimate_model_memory_for_checkpoint(m, hw, RECOMMENDATION_CONTEXT_TOKENS, geometry);
    let fit = fit_status(m, hw, &estimate, memory_limits);
    let quality = quality_score(m, size_prior_ceiling);
    let latency = latency_score(m, accel);
    let pressure = memory_pressure(&estimate, memory_limits.legacy_budget_mb);
    let w = tier.weights();
    // Higher score is better, so memory *pressure* is inverted.
    let mut score =
        w.quality * quality + w.latency * latency + w.memory_pressure * (1.0 - pressure);
    // Preferred capabilities are a soft bonus, never an eligibility gate.
    let pref_hits = use_case
        .preferred_capabilities()
        .iter()
        .filter(|c| m.has_capability(**c))
        .count();
    score += 0.05 * pref_hits as f32;

    let is_local = m.is_local();
    let within_recommendation_target = match memory_limits.recommendation_target_mb {
        None => true,
        Some(_) if fit == FitStatus::Unknown => false,
        Some(target_mb) if is_local => match hw.supported_acceleration() {
            SupportedAcceleration::Cuda {
                device_memory_mb: Some(device_memory_mb),
            } => {
                let host_required_mb = estimate
                    .estimated_peak_mb
                    .saturating_sub(estimate.weights_mb);
                fit == FitStatus::Fits
                    && estimate.weights_mb <= device_memory_mb
                    && host_required_mb <= target_mb
            }
            SupportedAcceleration::Cuda {
                device_memory_mb: None,
            } => false,
            _ => fit == FitStatus::Fits && estimate.estimated_peak_mb <= target_mb,
        },
        Some(_) => true,
    };
    RankedRecommendation {
        estimated_peak_mb: if is_local {
            estimate.estimated_peak_mb
        } else {
            0
        },
        latency_p50_ms: m.performance.latency_p50_ms.unwrap_or(u64::MAX),
        recommendation: Recommendation {
            model_id: m.id.clone(),
            display_name: m.name.clone(),
            role: use_case.role(),
            rationale: rationale(m, hw, use_case, tier, fit, quality),
            download_mb: if m.downloads_weights() {
                m.size_mb()
            } else {
                0
            },
            already_installed: m.has_installed_weights(),
            fit,
            acceleration: accel.clone(),
            is_local,
            requires_cloud_consent: !is_local,
            trust_tier: m.trust_tier,
            score,
            within_recommendation_target,
        },
    }
}

/// The mean published benchmark score, when the model has one.
fn measured_quality(m: &ModelSchema) -> Option<f32> {
    if m.public_benchmarks.is_empty() {
        return None;
    }
    let sum: f64 = m.public_benchmarks.iter().map(|b| b.score).sum();
    Some((sum / m.public_benchmarks.len() as f64).clamp(0.0, 1.0) as f32)
}

/// What the size curve is scaled to: the best measured local score among the
/// candidates, or 1.0 when none is measured.
///
/// The curve has to stay below what a real score reaches, so that a measured
/// model outranks an unmeasured larger one (see
/// [`unmeasured_larger_candidates`]). A fixed curve only did that while scores
/// sat on one scale: when the judged suite got harder the best local score
/// fell to about 0.66, and an unmeasured 31B's 0.82 from the curve outranked
/// every measurement.
fn size_prior_ceiling(models: &[&ModelSchema]) -> f32 {
    models
        .iter()
        .filter(|m| m.is_local())
        .filter_map(|m| measured_quality(m))
        .reduce(f32::max)
        .unwrap_or(1.0)
}

/// 0.0–1.0 quality prior: published benchmarks when present, else a
/// param-count heuristic (bigger ⇒ generally more capable, with diminishing
/// returns) scaled to `ceiling`.
fn quality_score(m: &ModelSchema, ceiling: f32) -> f32 {
    if let Some(measured) = measured_quality(m) {
        return measured;
    }
    // Quality tracks *total* params (a 30B MoE has 30B-class knowledge even
    // with 3B active). Saturating: 0.6B≈0.08, 4B≈0.36, 8B≈0.53, 30B≈0.81,
    // before scaling.
    let b = param_billions_total(m).max(0.1);
    ((b / (b + 7.0)) * ceiling).clamp(0.0, 1.0)
}

/// 0.0–1.0 latency prior: smaller + better-accelerated ⇒ faster ⇒ higher.
/// Uses *active* params — a 30B MoE with 3B active runs at 3B-ish speed.
fn latency_score(m: &ModelSchema, accel: &SupportedAcceleration) -> f32 {
    let b = param_billions_active(m).max(0.1);
    // Smaller models score higher; 0.6B≈0.93, 4B≈0.6, 8B≈0.43, 30B≈0.14.
    let size_term = 8.0 / (b + 8.0);
    let accel_bonus = match accel {
        SupportedAcceleration::Apple { .. } | SupportedAcceleration::Cuda { .. } => 0.1,
        _ => 0.0,
    };
    (size_term + accel_bonus).clamp(0.0, 1.0)
}

/// Fraction of the memory budget this model consumes (0.0–1.0+). Used
/// inverted in scoring so leaner picks win under memory-pressure weight.
fn memory_pressure(estimate: &crate::resource_policy::ModelMemoryEstimate, budget: u64) -> f32 {
    if budget == 0 {
        return 1.0;
    }
    (estimate.estimated_peak_mb as f32 / budget as f32).clamp(0.0, 1.5)
}

/// Local memory fit verdict for this model on this machine.
fn fit_status(
    m: &ModelSchema,
    hw: &HardwareInfo,
    estimate: &crate::resource_policy::ModelMemoryEstimate,
    memory_limits: &RecommendationMemoryLimits,
) -> FitStatus {
    // Explicitly external servers and remote/delegated models own their own
    // memory. ManagedVllmMlx is CAR-owned and must pass the same local budget
    // check as an in-process model; endpoint spelling never changes ownership.
    if m.is_remote() || m.is_delegated() {
        return FitStatus::ServerProvided;
    }
    // OS-provided implementations own their weights and memory, so the lack of
    // a catalog size is affirmative ownership evidence rather than an unknown
    // local-model estimate.
    if m.is_os_provided() {
        return FitStatus::Fits;
    }
    if m.size_mb() == 0 && m.ram_mb() == 0 {
        return FitStatus::Unknown;
    }
    let required_mb = estimate.estimated_peak_mb;
    let fits = if let Some(host_budget) = memory_limits.policy_host_budget_mb {
        match hw.supported_acceleration() {
            SupportedAcceleration::Cuda {
                device_memory_mb: Some(device_memory_mb),
            } => {
                let host_required_mb = estimate
                    .estimated_peak_mb
                    .saturating_sub(estimate.weights_mb);
                estimate.weights_mb <= device_memory_mb && host_required_mb <= host_budget
            }
            SupportedAcceleration::Cuda {
                device_memory_mb: None,
            } => return FitStatus::Unknown,
            _ => required_mb <= host_budget,
        }
    } else {
        required_mb <= memory_limits.legacy_budget_mb
    };
    if fits {
        FitStatus::Fits
    } else {
        FitStatus::TooBig
    }
}

/// Resident memory this model needs: weights + KV cache at a typical context
/// + backend overhead.
/// Memory available for a model after OS reserve, by acceleration tier.
pub(crate) fn memory_budget_mb(hw: &HardwareInfo) -> u64 {
    match hw.supported_acceleration() {
        SupportedAcceleration::Apple { unified_memory_mb } => {
            unified_memory_mb.saturating_sub(OS_RESERVE_MB)
        }
        SupportedAcceleration::Cuda { device_memory_mb } => {
            device_memory_mb.unwrap_or(hw.total_ram_mb)
        }
        // CPU and unsupported-discrete both run from system RAM.
        _ => hw.total_ram_mb.saturating_sub(OS_RESERVE_MB),
    }
}

/// Total parameter count in billions from `param_count` ("4B", "30B (3B
/// active)" → 30). Drives the *quality* prior. When `param_count` is blank
/// (common for under-curated entries), estimate from on-disk size rather
/// than treating the model as 0B — a 4-bit GGUF is ~0.6 GB per B params.
fn param_billions_total(m: &ModelSchema) -> f32 {
    model_parameter_billions_total(m)
}

/// Active parameter count in billions — the "(N active)" hint for MoE models,
/// falling back to total for dense models. Drives *latency* and KV sizing.
fn param_billions_active(m: &ModelSchema) -> f32 {
    model_parameter_billions_active(m)
}

/// Plain-language rationale from the winning factors. Fixed templates, no
/// free-form prose, so copy stays consistent and translatable.
fn rationale(
    m: &ModelSchema,
    hw: &HardwareInfo,
    use_case: UseCase,
    tier: QualityTier,
    fit: FitStatus,
    quality: f32,
) -> String {
    let purpose = use_case_purpose(use_case);
    let machine = match hw.supported_acceleration() {
        SupportedAcceleration::Apple { unified_memory_mb } => {
            format!(
                "your {} GB Apple Silicon Mac (Metal)",
                unified_memory_mb / 1024
            )
        }
        SupportedAcceleration::Cuda { device_memory_mb } => match device_memory_mb {
            Some(mb) => format!("your {} GB NVIDIA GPU (CUDA)", mb / 1024),
            None => "your NVIDIA GPU (CUDA)".to_string(),
        },
        SupportedAcceleration::UnsupportedDiscreteGpu { .. } | SupportedAcceleration::Cpu => {
            format!("your {} GB machine (CPU)", hw.total_ram_mb / 1024)
        }
    };

    match fit {
        FitStatus::ServerProvided
            if matches!(&m.source, crate::schema::ModelSource::VllmMlx { .. }) =>
        {
            format!(
                "{}: external server for {} — its operator runs the model, nothing to download",
                m.name, purpose
            )
        }
        FitStatus::ServerProvided if m.is_remote() => format!(
            "{}: cloud model for {} — runs on Parslee's servers, nothing to download",
            m.name, purpose
        ),
        FitStatus::ServerProvided => format!(
            "{}: served externally for {} — no local memory needed",
            m.name, purpose
        ),
        _ => {
            let tier_word = match tier {
                QualityTier::Fastest => "fastest",
                QualityTier::Balanced => "best-balanced",
                QualityTier::MostCapable => "most capable",
            };
            let quality_note = if quality >= 0.7 { "high-quality " } else { "" };
            let size = if m.size_mb() >= 1024 {
                format!("{:.1} GB download", m.size_mb() as f64 / 1024.0)
            } else {
                format!("{} MB download", m.size_mb())
            };
            format!(
                "{}: the {} {}{} model that fits {} ({})",
                m.name, tier_word, quality_note, purpose, machine, size
            )
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::hardware::{GpuBackend, GpuDevice, GpuVendor};
    use crate::resource_policy::estimate_model_memory;
    use crate::schema::{CostModel, ModelCapability, ModelSource, PerformanceEnvelope};

    pub(super) fn hw(accel_backend: GpuBackend, ram_mb: u64, gpu_mb: Option<u64>) -> HardwareInfo {
        HardwareInfo {
            os: "test".into(),
            arch: "test".into(),
            cpu_cores: 8,
            total_ram_mb: ram_mb,
            gpu_backend: accel_backend,
            gpu_memory_mb: gpu_mb,
            gpu_devices: vec![],
            recommended_model: String::new(),
            recommended_context: 4096,
            max_model_mb: 0,
        }
    }

    pub(super) fn mac(ram_gb: u64) -> HardwareInfo {
        // Metal backend ⇒ SupportedAcceleration::Apple with unified memory.
        hw(GpuBackend::Metal, ram_gb * 1024, None)
    }

    pub(super) fn local_model(id: &str, name: &str, params: &str, size_mb: u64) -> ModelSchema {
        ModelSchema {
            id: id.into(),
            name: name.into(),
            provider: "qwen".into(),
            family: "qwen3".into(),
            version: String::new(),
            capabilities: vec![ModelCapability::Generate, ModelCapability::Code],
            context_length: 32768,
            max_output_tokens: None,
            param_count: params.into(),
            quantization: Some(crate::schema::Quantization::parse("Q4_K_M")),
            performance: PerformanceEnvelope::default(),
            cost: CostModel {
                size_mb: Some(size_mb),
                ram_mb: Some(size_mb),
                ..Default::default()
            },
            source: ModelSource::Local {
                hf_repo: "x/y".into(),
                hf_filename: "m.gguf".into(),
                tokenizer_repo: "x/y".into(),
            },
            tags: vec![],
            supported_params: vec![],
            public_benchmarks: vec![],
            trust_tier: TrustTier::Curated,
            deprecated: false,
            available: false,
            weights_ready: false,
        }
    }

    fn catalog() -> Vec<ModelSchema> {
        vec![
            local_model("qwen/qwen3-0.6b", "Qwen3-0.6B", "0.6B", 650),
            local_model("qwen/qwen3-4b", "Qwen3-4B", "4B", 2500),
            local_model("qwen/qwen3-8b", "Qwen3-8B", "8B", 4900),
            local_model("qwen/qwen3-30b", "Qwen3-30B-A3B", "30B (3B active)", 17000),
        ]
    }

    /// The same catalog as a Mac sees it: MLX rows. GGUF rows never run on
    /// Apple Silicon — see [`platform_compatible`].
    fn mac_catalog() -> Vec<ModelSchema> {
        catalog().into_iter().map(as_mlx).collect()
    }

    fn as_mlx(mut m: ModelSchema) -> ModelSchema {
        let name =
            m.id.rsplit('/')
                .next()
                .expect("rsplit yields one")
                .to_string();
        m.id = format!("mlx/{name}");
        m.source = ModelSource::Mlx {
            hf_repo: format!("mlx-community/{}", m.name),
            hf_weight_file: None,
        };
        m
    }

    fn qwen_mlx_policy_catalog() -> Vec<ModelSchema> {
        let mut four = local_model("mlx/qwen3-4b:4bit", "Qwen3-4B-MLX", "4B", 2400);
        four.source = ModelSource::Mlx {
            hf_repo: "mlx-community/Qwen3-4B-4bit".into(),
            hf_weight_file: None,
        };
        four.capabilities = vec![
            ModelCapability::Generate,
            ModelCapability::Code,
            ModelCapability::ToolUse,
        ];
        four.performance.latency_p50_ms = Some(294);

        let mut eight = local_model("mlx/qwen3-8b:4bit", "Qwen3-8B-MLX", "8B", 4800);
        eight.source = ModelSource::Mlx {
            hf_repo: "mlx-community/Qwen3-8B-4bit".into(),
            hf_weight_file: None,
        };
        eight.capabilities = vec![
            ModelCapability::Generate,
            ModelCapability::Code,
            ModelCapability::ToolUse,
        ];
        eight.performance.latency_p50_ms = Some(451);
        vec![four, eight]
    }

    fn refs(v: &[ModelSchema]) -> Vec<&ModelSchema> {
        v.iter().collect()
    }

    #[test]
    fn fastest_prefers_the_small_model() {
        let cat = mac_catalog();
        let recs = recommend(
            &refs(&cat),
            &mac(36),
            UseCase::Coding,
            QualityTier::Fastest,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        )
        .picks;
        assert_eq!(recs[0].display_name, "Qwen3-0.6B");
    }

    #[test]
    fn downloadable_catalog_entry_is_not_installed_until_weights_are_ready() {
        let mut model = qwen_mlx_policy_catalog().remove(0);
        model.available = true;
        model.weights_ready = false;

        let set = recommend(
            &[&model],
            &mac(32),
            UseCase::Assistant,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );

        assert_eq!(set.picks.len(), 1);
        assert!(!set.picks[0].already_installed);
    }

    #[test]
    fn everyday_32gb_apple_assistant_balanced_prefers_four_b_and_keeps_eight_b() {
        let mut catalog = qwen_mlx_policy_catalog();
        let mut no_tools = local_model("mlx/qwen3-1.7b:3bit", "Qwen3-1.7B-MLX", "1.7B", 900);
        no_tools.source = ModelSource::Mlx {
            hf_repo: "mlx-community/Qwen3-1.7B-3bit".into(),
            hf_weight_file: None,
        };
        no_tools.capabilities = vec![ModelCapability::Generate];
        catalog.push(no_tools);
        let set = recommend_with_policy(
            &refs(&catalog),
            &mac(32),
            &crate::resource_policy::ResourcePolicy::everyday(),
            UseCase::Assistant,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );

        let ids: Vec<&str> = set
            .picks
            .iter()
            .map(|pick| pick.model_id.as_str())
            .collect();
        assert_eq!(ids, ["mlx/qwen3-4b:4bit", "mlx/qwen3-8b:4bit"]);
        let budget = crate::resource_policy::ResourcePolicy::everyday().effective_budget(32 * 1024);
        for model in &catalog[..2] {
            assert!(
                estimate_model_memory(model, &mac(32), RECOMMENDATION_CONTEXT_TOKENS)
                    .estimated_peak_mb
                    < budget.configured_model_ceiling_mb
            );
        }
    }

    #[test]
    fn everyday_recommends_up_to_its_full_ceiling() {
        let mut four = qwen_mlx_policy_catalog().remove(0);
        four.cost.ram_mb = Some(3_500);
        four.cost.size_mb = Some(3_500);
        let mut nine = four.clone();
        nine.id = "mlx/qwen3-9b:4bit".into();
        nine.name = "Qwen3-9B-MLX".into();
        nine.param_count = "9B".into();
        nine.cost.ram_mb = Some(9_000);
        nine.cost.size_mb = Some(9_000);
        nine.weights_ready = true;
        nine.public_benchmarks = vec![crate::schema::BenchmarkScore {
            name: "quality".into(),
            score: 0.99,
            harness: None,
            source_url: None,
            measured_at: None,
            runs: None,
            spread: None,
        }];
        let catalog = vec![nine, four];

        let set = recommend_with_policy(
            &refs(&catalog),
            &mac(32),
            &ResourcePolicy::everyday(),
            UseCase::Assistant,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );

        // A 9 GB model on a 32 GB Mac fits Everyday's 40% ceiling (13.1 GB)
        // and is offered automatically; under the old half-ceiling target
        // (6.5 GB) it was visible but never selected. Inside the target, its
        // higher quality ranks it first.
        assert_eq!(set.picks[0].model_id, "mlx/qwen3-9b:4bit");
        assert_eq!(set.picks[1].model_id, "mlx/qwen3-4b:4bit");
        assert!(set.picks[0].within_recommendation_target);
        assert!(set.picks[1].within_recommendation_target);

        let only_heavy = recommend_with_policy(
            &[&catalog[0]],
            &mac(32),
            &ResourcePolicy::everyday(),
            UseCase::Assistant,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        assert_eq!(only_heavy.picks[0].fit, FitStatus::Fits);
        assert!(only_heavy.picks[0].within_recommendation_target);
    }

    #[test]
    fn everyday_ranking_is_permutation_stable_across_local_and_cloud_candidates() {
        let mut four = qwen_mlx_policy_catalog().remove(0);
        four.cost.ram_mb = Some(3_500);
        four.cost.size_mb = Some(3_500);

        let mut nine = four.clone();
        nine.id = "mlx/qwen3-9b:4bit".into();
        nine.name = "Qwen3-9B-MLX".into();
        nine.param_count = "9B".into();
        nine.cost.ram_mb = Some(9_000);
        nine.cost.size_mb = Some(9_000);
        nine.public_benchmarks = vec![crate::schema::BenchmarkScore {
            name: "quality".into(),
            score: 0.99,
            harness: None,
            source_url: None,
            measured_at: None,
            runs: None,
            spread: None,
        }];

        let mut cloud = four.clone();
        cloud.id = "remote/tool-use".into();
        cloud.name = "ToolUse Cloud".into();
        cloud.source = ModelSource::RemoteApi {
            endpoint: "https://example.invalid".into(),
            api_key_env: "TEST_KEY".into(),
            api_key_envs: vec![],
            api_version: None,
            protocol: crate::schema::ApiProtocol::OpenAiCompat,
        };
        cloud.cost.ram_mb = None;
        cloud.cost.size_mb = None;
        cloud.public_benchmarks = vec![crate::schema::BenchmarkScore {
            name: "quality".into(),
            score: 1.0,
            harness: None,
            source_url: None,
            measured_at: None,
            runs: None,
            spread: None,
        }];

        let candidates = [four, nine, cloud];
        let permutations = [
            [0, 1, 2],
            [0, 2, 1],
            [1, 0, 2],
            [1, 2, 0],
            [2, 0, 1],
            [2, 1, 0],
        ];
        let expected = ["mlx/qwen3-4b:4bit", "mlx/qwen3-9b:4bit", "remote/tool-use"];
        for permutation in permutations {
            let catalog: Vec<ModelSchema> = permutation
                .into_iter()
                .map(|index| candidates[index].clone())
                .collect();
            let set = recommend_with_policy(
                &refs(&catalog),
                &mac(32),
                &ResourcePolicy::everyday(),
                UseCase::Assistant,
                QualityTier::Balanced,
                Privacy::CloudOk,
                &CheckpointGeometry::default(),
            );
            let actual: Vec<&str> = set
                .picks
                .iter()
                .map(|pick| pick.model_id.as_str())
                .collect();
            assert_eq!(actual, expected, "permutation {permutation:?}");
        }
    }

    #[test]
    fn cuda_policy_checks_gpu_weights_and_host_overhead_as_separate_pools() {
        let mut model = qwen_mlx_policy_catalog().remove(0);
        model.source = ModelSource::Local {
            hf_repo: "x/y".into(),
            hf_filename: "m.gguf".into(),
            tokenizer_repo: "x/y".into(),
        };

        model.cost.ram_mb = Some(1_000);
        model.cost.size_mb = Some(1_000);
        let vram_too_small = recommend_with_policy(
            &[&model],
            &hw(GpuBackend::Cuda, 64 * 1024, Some(900)),
            &ResourcePolicy::everyday(),
            UseCase::Assistant,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        assert_eq!(vram_too_small.not_enough_memory[0].fit, FitStatus::TooBig);

        model.cost.ram_mb = Some(5_000);
        model.cost.size_mb = Some(5_000);
        // The CUDA weights use the 16 GB VRAM pool. Unknown geometry keeps
        // 2,688 MB of host overhead (512 runtime + 1,152 context + 1,024
        // transient), below a 16 GB Everyday target of 3,276 MB.
        let separate_pools_fit = recommend_with_policy(
            &[&model],
            &hw(GpuBackend::Cuda, 16 * 1024, Some(16 * 1024)),
            &ResourcePolicy::everyday(),
            UseCase::Assistant,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        assert_eq!(separate_pools_fit.picks[0].fit, FitStatus::Fits);
        assert!(separate_pools_fit.picks[0].within_recommendation_target);
    }

    #[test]
    fn custom_zero_blocks_automatic_and_explicit_local_fit() {
        let model = qwen_mlx_policy_catalog().remove(0);
        let set = recommend_with_policy(
            &[&model],
            &mac(32),
            &ResourcePolicy::custom_gb(0.0).unwrap(),
            UseCase::Assistant,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );

        assert!(set.picks.is_empty());
        assert_eq!(set.not_enough_memory[0].fit, FitStatus::TooBig);
        assert!(!set.not_enough_memory[0].within_recommendation_target);
    }

    #[test]
    fn local_focused_uses_its_full_configured_ceiling() {
        let mut model = qwen_mlx_policy_catalog().remove(0);
        // 10,400 weights + 512 runtime + 1,152 context + 1,024 transient =
        // 13,088 MB: below Local Focused's full 13,107 MB ceiling, but well
        // above Everyday's 6,553 MB ceiling on this 16 GB fixture.
        model.cost.ram_mb = Some(10_400);
        model.cost.size_mb = Some(10_400);
        let set = recommend_with_policy(
            &[&model],
            &mac(16),
            &ResourcePolicy::local_focused(),
            UseCase::Assistant,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );

        assert_eq!(set.picks[0].fit, FitStatus::Fits);
        assert!(set.picks[0].within_recommendation_target);
    }

    #[test]
    fn unknown_memory_never_outranks_a_known_fit() {
        let mut known = qwen_mlx_policy_catalog().remove(0);
        known.public_benchmarks.clear();
        let mut unknown = known.clone();
        unknown.id = "local/unknown-memory".into();
        unknown.name = "Unknown Memory".into();
        unknown.param_count.clear();
        unknown.cost.ram_mb = None;
        unknown.cost.size_mb = None;
        unknown.public_benchmarks = vec![crate::schema::BenchmarkScore {
            name: "quality".into(),
            score: 1.0,
            harness: None,
            source_url: None,
            measured_at: None,
            runs: None,
            spread: None,
        }];

        let set = recommend_with_policy(
            &refs(&[unknown, known]),
            &mac(32),
            &ResourcePolicy::everyday(),
            UseCase::Assistant,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        assert_eq!(set.picks[0].model_id, "mlx/qwen3-4b:4bit");
        assert_eq!(set.picks[1].fit, FitStatus::Unknown);
        assert!(!set.picks[1].within_recommendation_target);
    }

    #[test]
    fn everyday_assistant_tool_floor_excludes_generate_only_cloud_models() {
        let mut local = qwen_mlx_policy_catalog().remove(0);
        local.public_benchmarks.clear();
        let mut cloud = local.clone();
        cloud.id = "remote/high-score-generate-only".into();
        cloud.name = "Remote Generate Only".into();
        cloud.source = ModelSource::RemoteApi {
            endpoint: "https://api".into(),
            api_key_env: "K".into(),
            api_key_envs: vec![],
            api_version: None,
            protocol: crate::schema::ApiProtocol::OpenAiCompat,
        };
        cloud.capabilities = vec![ModelCapability::Generate];
        cloud.public_benchmarks = vec![crate::schema::BenchmarkScore {
            name: "quality".into(),
            score: 1.0,
            harness: None,
            source_url: None,
            measured_at: None,
            runs: None,
            spread: None,
        }];

        let set = recommend_with_policy(
            &refs(&[cloud, local]),
            &mac(32),
            &ResourcePolicy::everyday(),
            UseCase::Assistant,
            QualityTier::Balanced,
            Privacy::CloudOk,
            &CheckpointGeometry::default(),
        );
        assert_eq!(set.picks.len(), 1);
        assert_eq!(set.picks[0].model_id, "mlx/qwen3-4b:4bit");
    }

    /// The assistant tool floor is a property of the use case, not of the tier
    /// or the entry point.
    ///
    /// Positive control: with the requirement welded to
    /// `everyday_assistant_balanced`, every assertion below except the
    /// `Balanced` one fails — `Fastest` and `MostCapable` returned the
    /// generate-only model, and `recommend` (no policy) returned it at every
    /// tier. That is car#1822: `--tier fastest` ranked Qwen3-0.6B first and
    /// told the reader to install it with `car setup --for assistant`, while
    /// `car do` refuses a model without `ToolUse` and substitutes one.
    #[test]
    fn the_assistant_tool_floor_holds_at_every_tier_and_entry_point() {
        let mut tool_capable = as_mlx(local_model("mlx/tools-4b", "Tools-4B", "4B", 2500));
        tool_capable.capabilities.push(ModelCapability::ToolUse);
        // `local_model` is Generate+Code, so this one is the excluded shape.
        let generate_only = as_mlx(local_model("mlx/chat-0.6b", "Chat-0.6B", "0.6B", 650));
        let models = [tool_capable, generate_only];

        for tier in [
            QualityTier::Fastest,
            QualityTier::Balanced,
            QualityTier::MostCapable,
        ] {
            for with_policy in [false, true] {
                let set = if with_policy {
                    recommend_with_policy(
                        &refs(&models),
                        &mac(32),
                        &ResourcePolicy::everyday(),
                        UseCase::Assistant,
                        tier,
                        Privacy::OnDevice,
                        &CheckpointGeometry::default(),
                    )
                } else {
                    recommend(
                        &refs(&models),
                        &mac(32),
                        UseCase::Assistant,
                        tier,
                        Privacy::OnDevice,
                        &CheckpointGeometry::default(),
                    )
                };
                let ids: Vec<&str> = set.picks.iter().map(|p| p.model_id.as_str()).collect();
                assert_eq!(
                    ids,
                    vec!["mlx/tools-4b"],
                    "tier {tier:?}, with_policy {with_policy}: a model without ToolUse \
                     cannot serve the assistant"
                );
            }
        }

        // Control: the floor is scoped to Assistant. Coding ranks both, so the
        // assertion above is about the use case and not about the catalog.
        let coding = recommend(
            &refs(&models),
            &mac(32),
            UseCase::Coding,
            QualityTier::Fastest,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        assert_eq!(
            coding.picks.len(),
            2,
            "coding has no tool floor; both candidates should rank"
        );
    }

    #[test]
    fn policy_entry_point_preserves_legacy_order_among_policy_eligible_candidates() {
        let catalog = mac_catalog();
        for (policy, use_case, tier) in [
            (
                ResourcePolicy::everyday(),
                UseCase::Assistant,
                QualityTier::Fastest,
            ),
            (
                ResourcePolicy::everyday(),
                UseCase::Assistant,
                QualityTier::MostCapable,
            ),
            (
                ResourcePolicy::everyday(),
                UseCase::Coding,
                QualityTier::Balanced,
            ),
            (
                ResourcePolicy::local_focused(),
                UseCase::Assistant,
                QualityTier::Balanced,
            ),
        ] {
            let legacy = recommend(
                &refs(&catalog),
                &mac(36),
                use_case,
                tier,
                Privacy::OnDevice,
                &CheckpointGeometry::default(),
            );
            let policy_aware = recommend_with_policy(
                &refs(&catalog),
                &mac(36),
                &policy,
                use_case,
                tier,
                Privacy::OnDevice,
                &CheckpointGeometry::default(),
            );
            let legacy_common: Vec<&str> = legacy
                .picks
                .iter()
                .filter(|pick| {
                    policy_aware
                        .picks
                        .iter()
                        .any(|candidate| candidate.model_id == pick.model_id)
                })
                .map(|pick| pick.model_id.as_str())
                .collect();
            let policy_common: Vec<&str> = policy_aware
                .picks
                .iter()
                .filter(|pick| {
                    legacy
                        .picks
                        .iter()
                        .any(|candidate| candidate.model_id == pick.model_id)
                })
                .map(|pick| pick.model_id.as_str())
                .collect();
            assert_eq!(
                policy_common, legacy_common,
                "{policy:?} {use_case:?} {tier:?}"
            );
        }
    }

    #[test]
    fn most_capable_prefers_the_big_model_when_it_fits() {
        let cat = mac_catalog();
        let recs = recommend(
            &refs(&cat),
            &mac(36), // 36 GB Mac fits the 17 GB model
            UseCase::Coding,
            QualityTier::MostCapable,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        )
        .picks;
        assert_eq!(recs[0].display_name, "Qwen3-30B-A3B");
        assert_eq!(recs[0].fit, FitStatus::Fits);
    }

    #[test]
    fn too_big_models_are_excluded_on_small_machines() {
        let cat = mac_catalog();
        let recs = recommend(
            &refs(&cat),
            &mac(8), // 8 GB: 17 GB and 8 GB models shouldn't be offered
            UseCase::Coding,
            QualityTier::MostCapable,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        )
        .picks;
        let names: Vec<&str> = recs.iter().map(|r| r.display_name.as_str()).collect();
        assert!(!names.contains(&"Qwen3-30B-A3B"), "30B must not fit 8GB");
        assert!(recs.iter().all(|r| r.fit == FitStatus::Fits));
        assert!(!recs.is_empty(), "the 0.6B model should still be offered");
    }

    #[test]
    fn balanced_picks_a_capable_model_that_fits() {
        let cat = mac_catalog();
        let recs = recommend(
            &refs(&cat),
            &mac(16),
            UseCase::Coding,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        )
        .picks;
        // On a 16 GB Mac, Balanced should land on a mid model, not the 0.6B
        // and not necessarily the largest.
        assert!(matches!(
            recs[0].display_name.as_str(),
            "Qwen3-4B" | "Qwen3-8B"
        ));
    }

    /// On Apple Silicon a GGUF row never runs — a request for it executes as
    /// its MLX twin — so it is not offered there, and each Qwen3 appears once.
    /// Everywhere else the GGUF row is the local model.
    #[test]
    fn gguf_rows_are_offered_everywhere_but_apple_silicon() {
        let gguf = catalog();
        let both: Vec<ModelSchema> = gguf.iter().cloned().chain(mac_catalog()).collect();
        let on_mac = recommend(
            &refs(&both),
            &mac(64),
            UseCase::Coding,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        assert!(!on_mac.picks.is_empty());
        assert!(on_mac
            .picks
            .iter()
            .chain(&on_mac.not_enough_memory)
            .all(|p| !gguf.iter().any(|g| g.id == p.model_id)));
        let cuda = hw(GpuBackend::Cuda, 64 * 1024, Some(24 * 1024));
        let on_cuda = recommend(
            &refs(&both),
            &cuda,
            UseCase::Coding,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        assert!(!on_cuda.picks.is_empty());
        assert!(on_cuda
            .picks
            .iter()
            .all(|p| gguf.iter().any(|g| g.id == p.model_id)));
        assert!(!platform_compatible(&gguf[0], &mac(64)));
        assert!(platform_compatible(&gguf[0], &cuda));
    }

    #[test]
    fn search_only_returns_embedding_models() {
        let mut cat = mac_catalog();
        let mut embed = as_mlx(local_model("qwen/embed", "Qwen3-Embedding", "0.6B", 640));
        embed.capabilities = vec![ModelCapability::Embed];
        cat.push(embed);
        let recs = recommend(
            &refs(&cat),
            &mac(16),
            UseCase::Search,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        )
        .picks;
        assert_eq!(recs.len(), 1, "only the embed model is in the Search lane");
        assert_eq!(recs[0].display_name, "Qwen3-Embedding");
        assert_eq!(recs[0].role, UseCaseRole::Retrieval);
    }

    #[test]
    fn deprecated_models_are_never_recommended() {
        let mut cat = mac_catalog();
        cat[1].deprecated = true; // deprecate the 4B
        let recs = recommend(
            &refs(&cat),
            &mac(16),
            UseCase::Coding,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        )
        .picks;
        assert!(recs.iter().all(|r| r.display_name != "Qwen3-4B"));
    }

    #[test]
    fn on_device_excludes_cloud_but_cloud_ok_includes_it_with_consent() {
        let mut cat = mac_catalog();
        let mut cloud = local_model("anthropic/sonnet", "Claude Sonnet", "", 0);
        cloud.capabilities = vec![ModelCapability::Generate, ModelCapability::Code];
        cloud.source = ModelSource::RemoteApi {
            endpoint: "https://api".into(),
            api_key_env: "K".into(),
            api_key_envs: vec![],
            api_version: None,
            protocol: crate::schema::ApiProtocol::Anthropic,
        };
        cloud.public_benchmarks = vec![crate::schema::BenchmarkScore {
            name: "SWE-bench".into(),
            score: 0.7,
            harness: None,
            source_url: None,
            measured_at: None,
            runs: None,
            spread: None,
        }];
        cat.push(cloud);

        let on_device = recommend(
            &refs(&cat),
            &mac(16),
            UseCase::Coding,
            QualityTier::MostCapable,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        )
        .picks;
        assert!(on_device.iter().all(|r| r.is_local));

        let cloud_ok = recommend(
            &refs(&cat),
            &mac(16),
            UseCase::Coding,
            QualityTier::MostCapable,
            Privacy::CloudOk,
            &CheckpointGeometry::default(),
        )
        .picks;
        let claude = cloud_ok
            .iter()
            .find(|r| r.display_name == "Claude Sonnet")
            .expect("cloud model eligible under CloudOk");
        assert!(claude.requires_cloud_consent);
        assert_eq!(claude.fit, FitStatus::ServerProvided);
    }

    #[test]
    fn metal_only_model_excluded_on_cpu_host() {
        let mut cat = catalog();
        let mut mlx = local_model("mlx/qwen3-4b", "Qwen3-4B-MLX", "4B", 2400);
        mlx.source = ModelSource::Mlx {
            hf_repo: "mlx-community/x".into(),
            hf_weight_file: None,
        };
        cat.push(mlx);
        // CPU-only Linux box.
        let recs = recommend(
            &refs(&cat),
            &hw(GpuBackend::Cpu, 32 * 1024, None),
            UseCase::Coding,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        )
        .picks;
        assert!(recs.iter().all(|r| r.display_name != "Qwen3-4B-MLX"));
    }

    #[test]
    fn ranking_is_deterministic() {
        let cat = mac_catalog();
        let a = recommend(
            &refs(&cat),
            &mac(16),
            UseCase::Assistant,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        let b = recommend(
            &refs(&cat),
            &mac(16),
            UseCase::Assistant,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        let ids_a: Vec<&str> = a.picks.iter().map(|r| r.model_id.as_str()).collect();
        let ids_b: Vec<&str> = b.picks.iter().map(|r| r.model_id.as_str()).collect();
        assert_eq!(ids_a, ids_b);
    }

    #[test]
    fn rationale_is_plain_language_no_jargon() {
        let cat = mac_catalog();
        let recs = recommend(
            &refs(&cat),
            &mac(36),
            UseCase::Coding,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        )
        .picks;
        let r = &recs[0].rationale;
        assert!(!r.contains("Q4_K_M"), "no quantization jargon");
        assert!(!r.contains("gguf") && !r.contains("hf_repo"));
        assert!(r.contains("coding"), "states the purpose");
    }

    #[test]
    fn all_too_big_surfaces_needs_more_ram_with_a_note() {
        // A 2 GB machine fits nothing in the catalog.
        let cat = catalog();
        let set = recommend(
            &refs(&cat),
            &hw(GpuBackend::Cpu, 2 * 1024, None),
            UseCase::Coding,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        assert!(set.picks.is_empty(), "nothing should fit 2 GB");
        assert!(
            !set.not_enough_memory.is_empty(),
            "too-big models surfaced, not dropped"
        );
        let note = set.note.expect("empty picks must carry a note");
        assert!(note.contains("fits"), "note explains the no-fit: {note}");
        // Closest miss ranked first.
        assert_eq!(set.not_enough_memory[0].fit, FitStatus::TooBig);
    }

    #[test]
    fn all_deprecated_gives_generic_note_not_a_memory_note() {
        // Deprecated models are filtered before the fit partition, so they
        // land in neither picks nor not_enough_memory — the note must be the
        // generic "no model available", not a misleading "needs more RAM".
        let mut cat = mac_catalog();
        for m in &mut cat {
            m.deprecated = true;
        }
        let set = recommend(
            &refs(&cat),
            &mac(36), // plenty of RAM — so a memory note would be wrong
            UseCase::Coding,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        assert!(set.picks.is_empty());
        assert!(set.not_enough_memory.is_empty());
        let note = set.note.expect("must explain");
        assert!(
            !note.contains("fits") && !note.contains("memory"),
            "deprecated-only must not claim a memory problem: {note}"
        );
    }

    #[test]
    fn not_enough_memory_is_ordered_deterministically() {
        let cat = catalog();
        let mk = || {
            recommend(
                &refs(&cat),
                &hw(GpuBackend::Cpu, 3 * 1024, None), // only the 0.6B fits
                UseCase::Coding,
                QualityTier::Balanced,
                Privacy::OnDevice,
                &CheckpointGeometry::default(),
            )
            .not_enough_memory
            .into_iter()
            .map(|r| r.model_id)
            .collect::<Vec<_>>()
        };
        assert!(mk().len() >= 2, "several models should be too big for 3 GB");
        assert_eq!(mk(), mk(), "too-big ordering must be deterministic");
    }

    #[test]
    fn empty_registry_returns_empty_with_a_note() {
        let set = recommend(
            &[],
            &mac(16),
            UseCase::Assistant,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        assert!(set.picks.is_empty());
        assert!(set.not_enough_memory.is_empty());
        assert!(set.note.is_some(), "no-model case must explain itself");
    }

    #[test]
    fn cuda_box_sizes_against_vram() {
        // A 24 GB CUDA GPU fits the 17 GB model under MostCapable.
        let cat = catalog();
        let h = hw(GpuBackend::Cuda, 64 * 1024, Some(24 * 1024));
        let recs = recommend(
            &refs(&cat),
            &h,
            UseCase::Coding,
            QualityTier::MostCapable,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        )
        .picks;
        assert_eq!(recs[0].display_name, "Qwen3-30B-A3B");
    }

    #[test]
    fn unsupported_discrete_gpu_uses_system_ram_not_vram() {
        // A 24 GB discrete GPU CAR can't drive must NOT be used as the budget;
        // a 16 GB-RAM CPU host can't fit the 17 GB model despite the big card.
        let cat = catalog();
        let mut h = hw(GpuBackend::Cpu, 16 * 1024, None);
        h.gpu_devices = vec![GpuDevice {
            vendor: GpuVendor::Nvidia,
            name: "GeForce RTX 4090".into(),
            memory_mb: Some(24_000),
        }];
        // Sanity: this is the UnsupportedDiscreteGpu tier.
        assert!(matches!(
            h.supported_acceleration(),
            crate::hardware::SupportedAcceleration::UnsupportedDiscreteGpu { .. }
        ));
        let recs = recommend(
            &refs(&cat),
            &h,
            UseCase::Coding,
            QualityTier::MostCapable,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        )
        .picks;
        assert!(
            recs.iter().all(|r| r.display_name != "Qwen3-30B-A3B"),
            "17 GB model must not fit a 16 GB-RAM CPU host"
        );
        assert!(!recs.is_empty(), "smaller models still fit");
    }

    #[test]
    fn recommendation_set_wire_shape_is_snake_case_and_stable() {
        // Guards the JSON contract that FFI / JSON-RPC clients decode.
        let cat = mac_catalog();
        let set = recommend(
            &refs(&cat),
            &mac(36),
            UseCase::Coding,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        let json = serde_json::to_string(&set).unwrap();
        assert!(json.contains("\"picks\""));
        assert!(json.contains("\"not_enough_memory\""));
        assert!(json.contains("\"model_id\""));
        assert!(json.contains("\"already_installed\""));
        assert!(json.contains("\"requires_cloud_consent\""));
        assert!(json.contains("\"within_recommendation_target\""));
        assert!(json.contains("\"fit\""));

        let mut legacy = serde_json::to_value(&set.picks[0]).unwrap();
        legacy
            .as_object_mut()
            .unwrap()
            .remove("within_recommendation_target");
        let decoded: Recommendation = serde_json::from_value(legacy).unwrap();
        assert!(decoded.within_recommendation_target);
    }

    #[test]
    fn blank_param_count_estimates_from_size_not_zero() {
        // An under-curated entry with no param_count must not be treated as a
        // 0B model (which would falsely look tiny + low quality).
        let mut m = local_model("x/unknown", "Unknown-Model", "", 4900);
        m.param_count = String::new();
        assert!(
            param_billions_total(&m) > 5.0,
            "4.9 GB ⇒ roughly an 8B model, not 0B"
        );
    }

    // --- models.list_unified fit annotation (car#1399) --------------------

    fn cloud_row(id: &str) -> ModelSchema {
        let mut cloud = local_model(id, "Cloud", "", 0);
        cloud.source = ModelSource::RemoteApi {
            endpoint: "https://example.invalid".into(),
            api_key_env: "TEST_KEY".into(),
            api_key_envs: vec![],
            api_version: None,
            protocol: crate::schema::ApiProtocol::OpenAiCompat,
        };
        cloud.cost.ram_mb = None;
        cloud.cost.size_mb = None;
        cloud
    }

    /// Everyday keeps 40% of unified memory for local models: 3,276 MB on an
    /// 8 GB Mac, 6,553 MB on 16 GB, 13,107 MB on 32 GB. Unknown fixture
    /// geometry conservatively reserves 1,152 MB of context at 8,192 tokens,
    /// yielding Metal peaks of 3,188 MB (0.6B), 5,088 MB (4B), 7,488 MB (8B),
    /// and 19,188 MB (30B-A3B).
    #[test]
    fn unified_fit_is_the_recommenders_verdict_on_every_machine_size() {
        let policy = ResourcePolicy::everyday();
        let cat = qwen_mlx_policy_catalog();
        let four = &cat[0];
        let eight = &cat[1];
        let small = local_model("mlx/qwen3-0.6b:6bit", "Qwen3-0.6B", "0.6B", 500);
        let thirty = local_model(
            "mlx/qwen3-30b-a3b:4bit",
            "Qwen3-30B-A3B",
            "30B (3B active)",
            16_500,
        );
        let at = |m: &ModelSchema, gb: u64| {
            model_fit(m, &mac(gb), Some(&policy), &CheckpointGeometry::default())
        };

        assert_eq!(at(eight, 8).fit, ModelFitStatus::TooBig);
        assert_eq!(at(eight, 16).fit, ModelFitStatus::TooBig);
        assert_eq!(at(eight, 32).fit, ModelFitStatus::Fits);
        assert_eq!(at(four, 8).fit, ModelFitStatus::TooBig);
        assert_eq!(at(four, 16).fit, ModelFitStatus::Fits);
        assert_eq!(at(&small, 8).fit, ModelFitStatus::Fits);
        assert_eq!(at(&thirty, 16).fit, ModelFitStatus::TooBig);
        assert_eq!(at(&thirty, 32).fit, ModelFitStatus::TooBig);

        // The published estimate is the one the verdict was judged on, and
        // the accelerator can run every one of these on a Mac.
        let eight_at_32 = at(eight, 32);
        assert_eq!(
            eight_at_32.estimated_peak_mb,
            Some(
                estimate_model_memory(eight, &mac(32), RECOMMENDATION_CONTEXT_TOKENS)
                    .estimated_peak_mb
            )
        );
        assert!(eight_at_32.platform_compatible);

        // Same rule as the recommender: whatever it partitions as a pick
        // reads `fits`, whatever it lists under not_enough_memory reads
        // `too_big`, on each machine.
        let all = vec![four.clone(), eight.clone(), small, thirty];
        let by_id = |id: &str| all.iter().find(|m| m.id == id).unwrap();
        for gb in [8u64, 16, 32] {
            let set = recommend_with_policy(
                &refs(&all),
                &mac(gb),
                &policy,
                UseCase::Assistant,
                QualityTier::Balanced,
                Privacy::OnDevice,
                &CheckpointGeometry::default(),
            );
            for pick in &set.picks {
                assert_eq!(
                    model_fit(
                        by_id(&pick.model_id),
                        &mac(gb),
                        Some(&policy),
                        &CheckpointGeometry::default()
                    )
                    .fit,
                    ModelFitStatus::Fits,
                    "{gb} GB pick {}",
                    pick.model_id
                );
            }
            for miss in &set.not_enough_memory {
                assert_eq!(
                    model_fit(
                        by_id(&miss.model_id),
                        &mac(gb),
                        Some(&policy),
                        &CheckpointGeometry::default()
                    )
                    .fit,
                    ModelFitStatus::TooBig,
                    "{gb} GB miss {}",
                    miss.model_id
                );
            }
        }
    }

    /// An installed checkpoint's own KV geometry is what the verdict sizes the
    /// KV cache from — the input load-time admission reads — so the list fit
    /// and the recommender's partition move together with it (car#2213). The
    /// fixture declares four times the KV heads the parameter-count fallback
    /// assumes for an 8B row, which takes it from fits to too-big on a 24 GB
    /// Mac under Everyday (9,830 MB ceiling).
    #[test]
    fn an_installed_checkpoints_kv_geometry_decides_the_verdict() {
        let policy = ResourcePolicy::everyday();
        let cat = qwen_mlx_policy_catalog();
        let eight = &cat[1];
        let root = tempfile::tempdir().unwrap();
        let dir = root.path().join(&eight.name);
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(
            dir.join("config.json"),
            r#"{"num_hidden_layers":36,"num_key_value_heads":32,"head_dim":128,"hidden_size":4096,"num_attention_heads":32,"torch_dtype":"bfloat16"}"#,
        )
        .unwrap();
        let installed = CheckpointGeometry::read([eight], root.path());
        let absent = CheckpointGeometry::default();

        let fallback = model_fit(eight, &mac(24), Some(&policy), &absent);
        let real = model_fit(eight, &mac(24), Some(&policy), &installed);
        assert_eq!(fallback.fit, ModelFitStatus::Fits, "{fallback:?}");
        assert_eq!(real.fit, ModelFitStatus::TooBig, "{real:?}");
        assert!(real.estimated_peak_mb > fallback.estimated_peak_mb);

        let partition = |geometry: &CheckpointGeometry| {
            let set = recommend_with_policy(
                &[eight],
                &mac(24),
                &policy,
                UseCase::Assistant,
                QualityTier::Balanced,
                Privacy::OnDevice,
                geometry,
            );
            (
                set.picks.iter().any(|r| r.model_id == eight.id),
                set.not_enough_memory.iter().any(|r| r.model_id == eight.id),
            )
        };
        assert_eq!(partition(&absent), (true, false));
        assert_eq!(partition(&installed), (false, true));

        // A multimodal checkpoint (gemma-4's shape) nests the same geometry
        // under `text_config`; the verdict reads it there.
        let nested_root = tempfile::tempdir().unwrap();
        let nested_dir = nested_root.path().join(&eight.name);
        std::fs::create_dir_all(&nested_dir).unwrap();
        std::fs::write(
            nested_dir.join("config.json"),
            r#"{"model_type":"gemma4_unified","torch_dtype":"bfloat16","vision_config":{},"text_config":{"num_hidden_layers":36,"num_key_value_heads":32,"head_dim":128,"hidden_size":4096,"num_attention_heads":32}}"#,
        )
        .unwrap();
        let nested = CheckpointGeometry::read([eight], nested_root.path());
        assert_eq!(
            model_fit(eight, &mac(24), Some(&policy), &nested),
            real,
            "nested text_config is sized as the flat config is"
        );
        assert_eq!(partition(&nested), (false, true));
    }

    /// A model no machine could ever hold reads `too_big` on every machine
    /// CAR runs on — including the CUDA-compiled Linux/Windows build with no
    /// NVIDIA card, which used to answer `unknown` and so showed the row.
    ///
    /// This is the fit half of `car-cli`'s
    /// `models_list_hides_too_big_and_deprecated_rows_unless_all`. That test
    /// spawns the real binary, so its verdict came from whatever hardware the
    /// runner reported: it passed under `ci.yml` (`--cfg=car_skip_cuda`, CPU
    /// tier) and failed under `build.yml` (CUDA toolkit installed, no GPU) on
    /// the very same commit. Judging the fixture here pins the rule to the
    /// machine profile instead of to the host.
    #[test]
    fn a_model_larger_than_any_machine_is_too_big_on_every_machine() {
        let policy = ResourcePolicy::everyday();
        // The `car models list` fixture: 900 TB of weights.
        let enormous = local_model("test/enormous-model:q4", "Enormous", "9000B", 900_000_000);
        let machines = [
            ("apple 8 GB", mac(8)),
            ("apple 128 GB", mac(128)),
            ("cpu 32 GB", hw(GpuBackend::Cpu, 32 * 1024, None)),
            // The shipped x86_64 Linux/Windows build on a GPU-less box:
            // `detect_gpu_backend` says Cuda from a `#[cfg]`, nvidia-smi
            // reports nothing.
            ("cuda build, no card", hw(GpuBackend::Cuda, 64 * 1024, None)),
            (
                "cuda 24 GB card",
                hw(GpuBackend::Cuda, 64 * 1024, Some(24 * 1024)),
            ),
        ];
        for (label, machine) in machines {
            assert_eq!(
                model_fit(
                    &enormous,
                    &machine,
                    Some(&policy),
                    &CheckpointGeometry::default()
                )
                .fit,
                ModelFitStatus::TooBig,
                "{label} must not claim to hold a 900 TB model"
            );
            assert_eq!(
                model_fit(&enormous, &machine, None, &CheckpointGeometry::default()).fit,
                ModelFitStatus::TooBig,
                "{label} without a policy must not claim to hold a 900 TB model"
            );
        }
    }

    /// The same machine still judges a model it CAN hold as fitting, so the
    /// rule above is a memory verdict and not a blanket refusal.
    #[test]
    fn cuda_build_without_a_card_still_fits_models_that_fit_system_ram() {
        let policy = ResourcePolicy::everyday();
        let small = local_model("qwen/qwen3-0.6b:q4_k_m", "Qwen3-0.6B", "0.6B", 500);
        let no_card = hw(GpuBackend::Cuda, 64 * 1024, None);
        assert_eq!(
            model_fit(
                &small,
                &no_card,
                Some(&policy),
                &CheckpointGeometry::default()
            )
            .fit,
            ModelFitStatus::Fits
        );
    }

    #[test]
    fn unified_fit_platform_check_is_the_base_filters() {
        let cat = qwen_mlx_policy_catalog();
        let mlx = &cat[0];
        let cpu_box = hw(GpuBackend::Cpu, 32 * 1024, None);
        let fit = model_fit(
            mlx,
            &cpu_box,
            Some(&ResourcePolicy::everyday()),
            &CheckpointGeometry::default(),
        );
        assert!(!fit.platform_compatible, "MLX needs Apple Silicon");
        assert!(!passes_base_filter(
            mlx,
            &cpu_box,
            UseCase::Coding,
            Privacy::OnDevice
        ));
        assert!(platform_compatible(mlx, &mac(32)));

        let gguf = local_model("qwen/qwen3-4b:q4_k_m", "Qwen3-4B", "4B", 2_500);
        assert!(
            model_fit(&gguf, &cpu_box, None, &CheckpointGeometry::default()).platform_compatible
        );
        assert!(passes_base_filter(
            &gguf,
            &cpu_box,
            UseCase::Coding,
            Privacy::OnDevice
        ));
    }

    #[test]
    fn unified_fit_for_rows_whose_memory_is_not_this_machines() {
        // Remote: the server owns its memory → fits, no estimate, any platform.
        let cloud = cloud_row("remote/cloud");
        let fit = model_fit(
            &cloud,
            &mac(8),
            Some(&ResourcePolicy::everyday()),
            &CheckpointGeometry::default(),
        );
        assert_eq!(fit.fit, ModelFitStatus::Fits);
        assert_eq!(fit.estimated_peak_mb, None);
        assert!(fit.platform_compatible);
        assert!(
            model_fit(
                &cloud,
                &hw(GpuBackend::Cpu, 8 * 1024, None),
                None,
                &CheckpointGeometry::default()
            )
            .platform_compatible
        );

        // A local row that declares neither size nor RAM: nothing to judge.
        let mut undeclared = local_model("local/undeclared", "Undeclared", "4B", 0);
        undeclared.cost.ram_mb = None;
        undeclared.cost.size_mb = None;
        let fit = model_fit(
            &undeclared,
            &mac(32),
            Some(&ResourcePolicy::everyday()),
            &CheckpointGeometry::default(),
        );
        assert_eq!(fit.fit, ModelFitStatus::Unknown);
        assert_eq!(fit.estimated_peak_mb, None);

        // OS-owned rows fit by definition because their memory is outside the
        // CAR model budget. Their own platform requirement remains separate.
        let mut foundation = local_model("apple/foundation:default", "Apple", "", 0);
        foundation.source = ModelSource::AppleFoundationModels { use_case: None };
        foundation.cost.ram_mb = None;
        foundation.cost.size_mb = None;
        let on_mac = model_fit(
            &foundation,
            &mac(8),
            Some(&ResourcePolicy::everyday()),
            &CheckpointGeometry::default(),
        );
        assert_eq!(on_mac.fit, ModelFitStatus::Fits);
        assert_eq!(on_mac.estimated_peak_mb, None);
        assert!(on_mac.platform_compatible);
        assert!(
            !model_fit(
                &foundation,
                &hw(GpuBackend::Cpu, 64 * 1024, None),
                None,
                &CheckpointGeometry::default()
            )
            .platform_compatible
        );

        let mut windows = local_model("windows/speech-synthesis:os", "Windows", "", 0);
        windows.source = ModelSource::WindowsSpeech {};
        windows.cost.ram_mb = None;
        windows.cost.size_mb = None;
        let on_mac = model_fit(
            &windows,
            &mac(8),
            Some(&ResourcePolicy::everyday()),
            &CheckpointGeometry::default(),
        );
        assert_eq!(on_mac.fit, ModelFitStatus::Fits);
        assert_eq!(on_mac.estimated_peak_mb, None);
        assert!(!on_mac.platform_compatible);
        let mut windows_host = hw(GpuBackend::Cpu, 8 * 1024, None);
        windows_host.os = "windows".into();
        assert!(
            model_fit(
                &windows,
                &windows_host,
                None,
                &CheckpointGeometry::default()
            )
            .platform_compatible
        );

        // The explicit platform tags cover future sources without teaching
        // this rule another backend variant.
        let mut linux = undeclared.clone();
        linux.tags.push("linux-only".into());
        let mut linux_host = hw(GpuBackend::Cpu, 8 * 1024, None);
        linux_host.os = "linux".into();
        assert!(platform_compatible(&linux, &linux_host));
        assert!(!platform_compatible(&linux, &windows_host));
        let mut tagged_windows = undeclared.clone();
        tagged_windows.tags.push("windows-only".into());
        assert!(platform_compatible(&tagged_windows, &windows_host));
        assert!(!platform_compatible(&tagged_windows, &linux_host));

        // Without a policy the legacy tier budget applies — unified memory
        // minus the 3 GB OS reserve, 5,120 MB on an 8 GB Mac — exactly as
        // `recommend` does: the 4B (≈3,940 MB) fits, the 8B (≈6,344 MB) does
        // not, and that is the partition the recommender publishes.
        let cat = qwen_mlx_policy_catalog();
        assert_eq!(
            model_fit(&cat[0], &mac(8), None, &CheckpointGeometry::default()).fit,
            ModelFitStatus::Fits
        );
        assert_eq!(
            model_fit(&cat[1], &mac(8), None, &CheckpointGeometry::default()).fit,
            ModelFitStatus::TooBig
        );
        let legacy = recommend(
            &refs(&cat),
            &mac(8),
            UseCase::Coding,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        fn ids(set: &[Recommendation]) -> Vec<&str> {
            set.iter().map(|pick| pick.model_id.as_str()).collect()
        }
        assert_eq!(ids(&legacy.picks), vec!["mlx/qwen3-4b:4bit"]);
        assert_eq!(ids(&legacy.not_enough_memory), vec!["mlx/qwen3-8b:4bit"]);
    }
}

#[cfg(test)]
mod local_server_fit_tests {
    use super::*;
    use crate::schema::{ModelCapability, ModelSource};

    fn managed_vllm_model(id: &str, size_mb: u64) -> ModelSchema {
        let mut m = super::tests::local_model(id, id, "12B", size_mb);
        m.capabilities.push(ModelCapability::ToolUse);
        m.cost.ram_mb = Some(size_mb + size_mb / 4);
        m.source = ModelSource::ManagedVllmMlx {
            hf_repo: "mlx-community/whatever-4bit".into(),
            hf_weight_file: None,
            draft_hf_repo: None,
        };
        m
    }

    fn external_vllm_model(id: &str, endpoint: &str, size_mb: u64) -> ModelSchema {
        let mut m = super::tests::local_model(id, id, "12B", size_mb);
        m.capabilities.push(ModelCapability::ToolUse);
        m.cost.ram_mb = Some(size_mb + size_mb / 4);
        m.source = ModelSource::VllmMlx {
            endpoint: endpoint.to_string(),
            model_name: "externally-managed-model".into(),
        };
        m
    }

    fn small_mac() -> HardwareInfo {
        super::tests::hw(crate::hardware::GpuBackend::Metal, 16384, Some(12288))
    }

    /// The production break: an explicitly CAR-managed vLLM-MLX model was
    /// classified as server-provided, so a 20 GB allocation could be
    /// recommended to a 16 GB Mac without consuming the configured budget.
    #[test]
    fn managed_vllm_mlx_is_memory_checked_and_rejected_when_over_budget() {
        let big = managed_vllm_model("vllm-mlx/huge:4bit", 20_000);
        let set = recommend_with_policy(
            &[&big],
            &small_mac(),
            &ResourcePolicy::everyday(),
            UseCase::Assistant,
            QualityTier::Balanced,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );

        assert!(set.picks.is_empty());
        assert_eq!(set.not_enough_memory.len(), 1);
        assert_eq!(set.not_enough_memory[0].fit, FitStatus::TooBig);
        assert_eq!(
            set.not_enough_memory[0].download_mb, 20_000,
            "CAR-managed vllm weights must retain their declared download size"
        );
    }

    /// External vLLM is a cloud-consent/server-provided route regardless of the
    /// endpoint spelling or the hardware CAR itself is running on.
    #[test]
    fn external_vllm_mlx_requires_cloud_consent_and_is_cross_platform() {
        let machines = [
            small_mac(),
            super::tests::hw(crate::hardware::GpuBackend::Cpu, 16_384, None),
            super::tests::hw(crate::hardware::GpuBackend::Cuda, 16_384, Some(12_288)),
        ];
        for endpoint in [
            "http://localhost:8000",
            "http://127.0.0.1:8000",
            "https://gpu-owner.example/v1",
        ] {
            let external = external_vllm_model("external/vllm", endpoint, 20_000);
            for machine in &machines {
                let on_device = recommend_with_policy(
                    &[&external],
                    machine,
                    &ResourcePolicy::everyday(),
                    UseCase::Assistant,
                    QualityTier::Balanced,
                    Privacy::OnDevice,
                    &CheckpointGeometry::default(),
                );
                assert!(
                    on_device.picks.is_empty(),
                    "external endpoint {endpoint} must require cloud consent on {:?}",
                    machine.gpu_backend
                );

                let cloud_ok = recommend_with_policy(
                    &[&external],
                    machine,
                    &ResourcePolicy::everyday(),
                    UseCase::Assistant,
                    QualityTier::Balanced,
                    Privacy::CloudOk,
                    &CheckpointGeometry::default(),
                );
                assert_eq!(
                    cloud_ok.picks.len(),
                    1,
                    "external endpoint {endpoint} on {:?}",
                    machine.gpu_backend
                );
                assert_eq!(cloud_ok.picks[0].fit, FitStatus::ServerProvided);
                assert_eq!(
                    cloud_ok.picks[0].download_mb, 0,
                    "external vllm owns its weights, so CAR has no download to report"
                );
                assert!(
                    cloud_ok.picks[0].rationale.contains("external server"),
                    "external vllm rationale must describe its actual owner: {}",
                    cloud_ok.picks[0].rationale
                );
                assert!(
                    !cloud_ok.picks[0].rationale.contains("Parslee's servers"),
                    "external vllm must not be attributed to Parslee: {}",
                    cloud_ok.picks[0].rationale
                );
            }
        }
    }
}

#[cfg(test)]
mod catalog_capability_gap_tests {
    use super::*;
    use crate::schema::{ModelCapability, ModelSchema};

    fn builtin() -> Vec<ModelSchema> {
        serde_json::from_str(include_str!("builtin_catalog.json")).unwrap()
    }

    fn cuda_box(vram_gb: u64, ram_gb: u64) -> crate::hardware::HardwareInfo {
        super::tests::hw(
            crate::hardware::GpuBackend::Cuda,
            ram_gb * 1024,
            Some(vram_gb * 1024),
        )
    }

    /// The real catalog on a Mac offers no GGUF row in any lane: each Qwen3
    /// used to appear twice, once as a download that would never run.
    #[test]
    fn a_mac_is_never_offered_a_gguf_row_from_the_builtin_catalog() {
        let catalog = builtin();
        let refs: Vec<&ModelSchema> = catalog.iter().collect();
        for use_case in [
            UseCase::Assistant,
            UseCase::Coding,
            UseCase::Summarize,
            UseCase::Vision,
            UseCase::Transcription,
            UseCase::Search,
        ] {
            for tier in [
                QualityTier::Fastest,
                QualityTier::Balanced,
                QualityTier::MostCapable,
            ] {
                let set = recommend(
                    &refs,
                    &super::tests::mac(64),
                    use_case,
                    tier,
                    Privacy::OnDevice,
                    &CheckpointGeometry::default(),
                );
                for pick in set.picks.iter().chain(&set.not_enough_memory) {
                    let row = catalog.iter().find(|m| m.id == pick.model_id).unwrap();
                    assert!(
                        !matches!(row.source, crate::schema::ModelSource::Local { .. }),
                        "{use_case:?}/{tier:?} offered GGUF row {}",
                        row.id
                    );
                }
            }
        }
    }

    fn most_capable_on(ram_gb: u64) -> RecommendationSet {
        let catalog: &'static Vec<ModelSchema> = Box::leak(Box::new(builtin()));
        let refs: Vec<&ModelSchema> = catalog.iter().collect();
        recommend(
            &refs,
            &super::tests::mac(ram_gb),
            UseCase::Assistant,
            QualityTier::MostCapable,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        )
    }

    /// The outcome this whole area exists for: on a machine with room for it,
    /// "most capable" returns the highest-scoring model that machine can run —
    /// not the highest-scoring small one.
    ///
    /// It used to answer gemma-4-12B (6.6 GB) on a 64 GB Mac while `--tier
    /// fastest` answered a 35B, because every model carrying a `car-judged`
    /// score was an older, smaller one and an unscored model fell back to a
    /// size prior that saturates below what a real score reaches.
    #[test]
    fn most_capable_returns_the_best_model_the_machine_can_run() {
        let catalog = builtin();
        let set = most_capable_on(64);
        let top = set.picks.first().expect("a 64 GB machine has picks");

        let top_score = catalog
            .iter()
            .find(|m| m.id == top.model_id)
            .and_then(|m| m.public_benchmarks.first())
            .map(|b| b.score)
            .unwrap_or(0.0);

        for m in catalog
            .iter()
            .filter(|m| m.is_local() && m.size_mb() < 24_000)
        {
            if let Some(s) = m.public_benchmarks.first().map(|b| b.score) {
                assert!(
                    s <= top_score,
                    "{} scores {s} but {} ({top_score}) was recommended as most capable",
                    m.id,
                    top.model_id
                );
            }
        }
        assert!(
            top.download_mb > 10_000,
            "a 64 GB machine should be offered a large model, got {} at {} MB",
            top.model_id,
            top.download_mb
        );
    }

    /// A small machine still gets something that fits — the capability tier
    /// must not simply always return the biggest model.
    #[test]
    fn a_small_machine_is_not_offered_a_model_it_cannot_hold() {
        let set = most_capable_on(8);
        let top = set
            .picks
            .first()
            .expect("an 8 GB machine still gets a pick");
        assert!(
            top.fit != FitStatus::TooBig,
            "{} does not fit an 8 GB machine",
            top.model_id
        );
    }

    /// The disclosure fires only while larger models remain unscored, and never
    /// claims they are downloaded — available means CAR can fetch and run them.
    #[test]
    fn the_disclosure_is_accurate_when_it_appears() {
        let set = most_capable_on(64);
        if let Some(note) = set.note.as_deref() {
            if note.contains("unscored") {
                assert!(note.contains("bench-contribute"), "must say how: {note}");
                assert!(
                    !note.contains("installed"),
                    "availability is not installation: {note}"
                );
            }
        }
    }

    /// It is scoped to the tier that makes the capability claim.
    #[test]
    fn other_tiers_do_not_carry_the_disclosure() {
        let catalog = builtin();
        let refs: Vec<&ModelSchema> = catalog.iter().collect();
        for tier in [QualityTier::Fastest, QualityTier::Balanced] {
            let set = recommend(
                &refs,
                &super::tests::mac(64),
                UseCase::Assistant,
                tier,
                Privacy::OnDevice,
                &CheckpointGeometry::default(),
            );
            let carries = set.note.as_deref().is_some_and(|n| n.contains("unscored"));
            assert!(!carries, "{tier:?} should not carry the disclosure");
        }
    }

    /// A CUDA machine must be offered a local model at all. GGUF is its local
    /// path — `backend::candle` is compiled on exactly the targets MLX is not —
    /// so the catalog's `local` rows are its whole local story.
    ///
    /// Catalog coverage, not a regression test for the availability fix:
    /// `recommend` does not read `ModelSchema::available`. That gates the
    /// router's fallback chains and is covered in
    /// `registry::local_availability_tests`.
    #[test]
    fn a_cuda_machine_is_offered_a_local_model() {
        let catalog = builtin();
        let refs: Vec<&ModelSchema> = catalog.iter().collect();
        let set = recommend(
            &refs,
            &cuda_box(24, 64),
            UseCase::Assistant,
            QualityTier::MostCapable,
            Privacy::OnDevice,
            &CheckpointGeometry::default(),
        );
        assert!(
            set.picks.iter().any(|p| p.is_local),
            "a 24 GB CUDA GPU must be offered something local, got {:?}",
            set.picks.iter().map(|p| &p.model_id).collect::<Vec<_>>()
        );
    }

    /// A blank `param_count` is not neutral: the total falls back to
    /// `size_mb / 600` and the *active* count falls back to that total, so a
    /// 4-bit MoE reads as a dense model of its whole on-disk size.
    #[test]
    fn local_generate_models_declare_their_parameter_count() {
        let blank: Vec<String> = builtin()
            .iter()
            .filter(|m| {
                m.capabilities.contains(&ModelCapability::Generate)
                    && m.is_local()
                    && m.param_count.trim().is_empty()
            })
            .map(|m| m.id.clone())
            .collect();
        assert!(
            blank.is_empty(),
            "local generate models with no param_count: {blank:?}"
        );
    }

    /// GLM-4.7-Flash's 4-bit conversion loops ("+ 5 - 5 + 5 - 5 …") on easy
    /// prompts at every sampling temperature, so it scored 0.081 on the judged
    /// suite while the 8-bit conversion answers cleanly (car#3537). The
    /// concierge must offer the 8-bit row and never the 4-bit one.
    #[test]
    fn glm_flash_is_offered_at_8bit_only() {
        let catalog = builtin();
        let row = |id: &str| {
            catalog
                .iter()
                .find(|m| m.id == id)
                .unwrap_or_else(|| panic!("{id} missing from the builtin catalog"))
        };
        let base = |m: &ModelSchema| {
            passes_base_filter(
                m,
                &super::tests::mac(64),
                UseCase::Coding,
                Privacy::OnDevice,
            )
        };
        assert!(!base(row("vllm-mlx/glm-4.7-flash:4bit")));
        assert!(base(row("vllm-mlx/glm-4.7-flash:8bit")));
    }

    /// An MoE's `(N active)` hint is what separates its latency from its size.
    #[test]
    fn an_moe_is_scored_on_its_active_parameters() {
        let catalog = builtin();
        let glm = catalog
            .iter()
            .find(|m| m.id == "vllm-mlx/glm-4.7-flash:8bit")
            .expect("catalog entry");
        let active = crate::resource_policy::model_parameter_billions_active(glm);
        let total = crate::resource_policy::model_parameter_billions_total(glm);
        assert!(
            active < 6.0,
            "top-4-of-64 MoE runs at a few B active, got {active}"
        );
        assert!(total > 20.0, "and carries 30B-class knowledge, got {total}");
    }
}