ballistics-engine 0.45.0

// Allocator selection based on features. jemalloc and mimalloc each define a #[global_allocator],
// and a crate may have at most one — so when both features are enabled (e.g. `--all-features`,
// which docs.rs uses by default) jemalloc yields to mimalloc to keep the build compiling.
#[cfg(all(
    feature = "jemalloc",
    not(feature = "mimalloc"),
    not(target_env = "msvc")
))]
#[global_allocator]
static GLOBAL: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;

#[cfg(all(feature = "mimalloc", not(target_env = "msvc")))]
#[global_allocator]
static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc;

mod mcp_command;
mod solve_json_command;
// MBA-1355: parse_click_value/clicks_for/ClickValue power the CLI's click-graduation
// flags (--elevation-click-value/--windage-click-value) and profile fields.
use ballistics_engine::adjustment::{
    adjustment_display, adjustment_factor, adjustment_unit_label, click_size_mil, clicks_for,
    parse_click_value, windage_adjustment_display, AdjustmentUnit, ClickBase, ClickValue,
};
// Task 6 (truing JSON bridge): drop_to_adjustment's non-test caller (the tall-target arm)
// moved into truing_service; the unit tests below still exercise it directly.
#[cfg(test)]
use ballistics_engine::adjustment::drop_to_adjustment;
// MBA-1348: the saved-profile turret/reticle model (Plan B Task 5) -- ProfileData::optic_profile
// assembles one of these from the profile's twelve turret/hold fields.
use ballistics_engine::optic::{OpticProfile, TravelLimits, TurretState};
// The saved-profile data model (ProfileData & friends) plus its pure-data helpers moved
// into the library (bridge C2) so the JSON command bridge shares one serde wire shape with
// the CLI; file persistence (save_profile/load_profile) and unit conversion (converted_to,
// via the ProfileDataUnitExt trait below) stay here.
use ballistics_engine::profile::{
    require_angular_pair, require_hold_bounds, validate_tracking_cf, ProfileBcSegment, ProfileData,
    ProfileDragPoint, ProfileZeroSet,
};
// The A7pDocument -> ProfileData mapping shared with the bridge's profile.import_a7p.
#[cfg(feature = "profile-import")]
use ballistics_engine::profile_import::{map_a7p_to_profile, sanitize_profile_name, ImportReport};
// MBA-1348 Plan B Task 6: `dial-plan` -- the `plan_corrections` CLI surface.
use ballistics_engine::optic::{
    plan_corrections, AngularCorrection, Axis, DialPlanReportV1, Direction, LimitKind, Preferences,
    Strategy,
};
#[cfg(feature = "pdf")]
use ballistics_engine::pdf_dope_card::{
    calculate_density_altitude, DopeCardConfig, FontSizePreset, RangeUnit,
};
use ballistics_engine::terminal_plot;

#[cfg(feature = "online")]
use ballistics_engine::api_client::{ApiClient, TrajectoryRequestBuilder, TrueVelocityRequest};
use ballistics_engine::bc_table::BcCorrectionTable;
use ballistics_engine::bc_table_5d::{Bc5dError, Bc5dTableManager};
#[cfg(feature = "online")]
use ballistics_engine::bc_table_download::Bc5dDownloader;
use ballistics_engine::cli_api::UnitSystem;
use ballistics_engine::constants::{
    DEFAULT_POWDER_REFERENCE_TEMP_C, DEFAULT_POWDER_REFERENCE_TEMP_F, FPS_TO_MPS, GRAINS_PER_GRAM,
    GRAINS_TO_KG, GRAMS_PER_GRAIN,
};
// MBA-1352: confidence levels for monte-carlo's Wilson/adaptive CLI surface. ConfidenceLevel
// itself derives no clap trait -- mc_stats.rs is deliberately clap-free so it keeps compiling
// unconditionally for wasm32 -- so the CLI-only 90/95/99 mapping lives here (parse_confidence_level).
use ballistics_engine::mc_stats::ConfidenceLevel;
use ballistics_engine::truing::{
    calculate_true_velocity_local, correct_chrono_velocity_fps, dsf_window_start,
    fallback_bullet_length_m, mv_calibration_window, parse_truing_observation,
    run_multi_observation_truing_core, validate_truing_observations, DragModelArg, DropUnit,
    MultiTruingReport, TruingEarthFrame, TruingModelInputsV1, TruingObservation, TruingTwist,
};
// MBA-1392: wind-call truing (back-solve the effective crosswind from an observed miss).
use ballistics_engine::truing_dsf::{apply_dsf, DsfPoint, DsfTable, UpsertOutcome};
use ballistics_engine::truing_plan::{
    plan_truing_experiment_v1, TruingExperimentPlanRequestV1, TruingExperimentPlanV1,
    TruingPlanModeV1,
};
use ballistics_engine::truing_uncertainty::{
    run_uncertainty_truing_v1, NormalPriorV1, TruingApproximationV1, TruingPredictionRequestV1,
    TruingPriorsV1, UncertaintyTruingReportV1, UncertaintyTruingRequestV1,
    WeightedTruingObservationV1,
};
use ballistics_engine::truing_wind::{
    format_wind_truing_report, parse_wind_observation, solve_wind_truing, WindTruingOutput,
    WindTruingRequest, MPH_TO_MPS,
};
// Task 6 (truing JSON bridge): the tall-target arithmetic, shared with a future bridge command.
// Task 9: the `dsf` verb's post-solve derivation (interpolation, Mach, both gates, the DSF
// ratio), shared with the model-driven bridge entry point `derive_dsf_point_v1`.
use ballistics_engine::truing_service::{
    derive_dsf_point_from_solve_v1, tall_target_v1, DsfServiceErrorV1, TallTargetErrorV1,
    TallTargetRequestV1,
};
use ballistics_engine::wez::{compute_wez, parse_target_size, TargetSizeMetric, WezResult, WezRow};
// MBA-1372: SAAMI free-recoil and power-factor calculators.
use ballistics_engine::atmosphere::{
    resolve_station_conditions_with_pressure_mode, PressureReferenceMode,
};
use ballistics_engine::power_factor::{evaluate_all as pf_evaluate_all, scored_power_factor};
use ballistics_engine::recoil::{
    free_recoil, FirearmType, FreeRecoilInputs, GasVelocityModel, POUNDS_TO_KG,
};
use ballistics_engine::{
    run_monte_carlo_adaptive_seeded, trajectory_sampling, AdaptiveMcReportV1,
    AtmosphericConditions, BCSegmentData, BallisticInputs, BcReferenceStandard, DragModel,
    McConvergence, McStopReason, MonteCarloParams, TrajectorySolver, WindConditions,
};
// 0.33.0 decision-support Task 8: HoldCurve (mark-to-range/bdc-match/optimal-zero/reticle
// hold --range) and the sampled-trajectory helpers it solves through, promoted into the
// library. Their shared bracket-and-lerp core, Task 7's `bracket_param`/`Bracket`, is
// crate-private (`pub(crate)`, MBA-1348 review N-2) and reached from here only through
// `HoldCurve::at_range` -- this file has no direct reference to either symbol. CLI argument
// resolution (InverseSolverLoadArgs::resolve) stays here and constructs HoldCurveLoad.
use ballistics_engine::hold_curve::{
    build_trajectory_components, card_sample_max_range_m, range_not_sampled_message,
    run_sampled_flight, run_sampled_trajectory, sample_at_range, CardTruncation, HoldCurve,
    HoldCurveLoad, MarkToRangeOutcome, CARD_SAMPLE_INTERVAL_M,
};
// 0.33.0 decision-support Task 9: CardRow, the shared display-ready row type behind the
// come-ups/range-table/wind-card/compare surfaces (replacing four function-local row
// structs -- ComeUpRow/RangeRow/WindRow/LoadRow -- that each said the same thing a
// different way).
use ballistics_engine::card::CardRow;
// 0.33.0 decision-support Task 12: `adaptive-card` -- the CLI surface over Task 11's
// greedy-insertion engine, itself built on CardRow above.
use ballistics_engine::card::{
    adaptive_card, AdaptiveBudget, AdaptiveCardReportV1, AdaptiveRequest, CardAdjustmentUnit,
    CardError,
};
use ballistics_engine::wind::{parse_wind_direction_standalone, ParsedWindDirection};
// MBA-1349: robust hold corridors over named segmented-wind scenarios.
use ballistics_engine::wind_scenarios::{
    format_robust_hold_report, parse_target_spec, parse_wind_scenario_set, solve_robust_hold,
    CorridorLoad, RobustHoldFormat, RobustHoldRequest, TargetSpec,
};
// 0.33.0 decision-support Tasks 14-15: `explain`/`tolerance`/`error-budget` CLI surfaces for
// MBA-1345/MBA-1347/MBA-1350.
use ballistics_engine::error_budget::{
    error_budget_with_target, ErrorBudgetReportV1, TargetGeometryV1,
};
use ballistics_engine::explain::{explain_difference, DeltaV1, SolutionDiffReportV1};
use ballistics_engine::perturbation::{axis_meta, AxisKind, DifferenceScheme, InputAxis};
use ballistics_engine::solve_json::{
    decode_solve_request_v1, ResolvedSolveRequestV1, SolveErrorEnvelopeV1,
};
use ballistics_engine::tolerance::{tolerance_envelope, LimitingBoundaryV1, ToleranceReportV1};
// MBA-1361: reticle schema, generators and the hold-point API (shared with WASM/FFI).
use ballistics_engine::reticle::{
    format_reticle_description, format_reticle_hold, hold_point_in_reticle, FocalPlane,
    ReticleDescription, ReticleFormat,
};
use clap::{CommandFactory, Parser, Subcommand, ValueEnum};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::error::Error;
use std::fs;
use std::io::{self, Write};
use std::path::{Path, PathBuf};
use strsim::levenshtein;

/// Shared `--wind-direction` help (MBA-1367): ONE string so the degrees+clock grammar
/// cannot drift between the seven subcommands that take a wind direction.
const WIND_DIRECTION_HELP: &str = "Wind direction: degrees (wind-FROM: 0=headwind, \
    90=from right, 180=tailwind, 270=from left) or a clock position (3oc, 10h30, \
    10:30; 12oc = headwind)";

/// Clap value parser for every `--wind-direction` arg (MBA-1367): bare numbers stay
/// degrees exactly as before; marked clock forms (`3oc`, `10h30`, and — legal on
/// standalone flags — `10:30`) map through the shared [`parse_wind_direction_standalone`]
/// helper, preserving `was_clock` for the earth-fixed mode's clock rejection.
fn parse_wind_direction_arg(
    s: &str,
) -> Result<ParsedWindDirection, ballistics_engine::wind::WindDirectionParseError> {
    parse_wind_direction_standalone(s)
}

// ============================================================================
// Terms of Service Acceptance Module (for --online feature)
// ============================================================================

#[cfg(feature = "online")]
const TOS_URL: &str = "https://ballistics.rs/terms.txt";

#[cfg(feature = "online")]
const TOS_VERSION: &str = "2026-01-26";

/// Structure to store TOS acceptance status
#[cfg(feature = "online")]
#[derive(Debug, Serialize, Deserialize)]
struct TosAcceptance {
    accepted: bool,
    accepted_version: String,
    accepted_at: String,
    terms_hash: String,
}

/// Get the path to the TOS acceptance file
#[cfg(feature = "online")]
fn get_tos_file_path() -> Option<PathBuf> {
    dirs::home_dir().map(|home| home.join(".ballistics").join("tos.json"))
}

/// Check if the user has already accepted the current TOS
#[cfg(feature = "online")]
fn check_tos_accepted() -> bool {
    let Some(tos_path) = get_tos_file_path() else {
        return false;
    };

    if !tos_path.exists() {
        return false;
    }

    match fs::read_to_string(&tos_path) {
        Ok(content) => {
            match serde_json::from_str::<TosAcceptance>(&content) {
                Ok(acceptance) => {
                    // Check if accepted and version matches
                    acceptance.accepted && acceptance.accepted_version == TOS_VERSION
                }
                Err(_) => false,
            }
        }
        Err(_) => false,
    }
}

/// Fetch the TOS text from the server
#[cfg(feature = "online")]
fn fetch_tos_text() -> Result<String, String> {
    let mut response = ureq::get(TOS_URL)
        .config()
        .timeout_global(Some(std::time::Duration::from_secs(10)))
        .build()
        .call()
        .map_err(|e| format!("Failed to fetch Terms of Service: {}", e))?;

    response
        .body_mut()
        .read_to_string()
        .map_err(|e| format!("Failed to read Terms of Service: {}", e))
}

/// Stable FNV-1a hash (not affected by Rust version changes unlike DefaultHasher)
#[cfg(feature = "online")]
fn fnv1a_hash(data: &[u8]) -> u64 {
    let mut hash: u64 = 0xcbf29ce484222325;
    for &byte in data {
        hash ^= byte as u64;
        hash = hash.wrapping_mul(0x100000001b3);
    }
    hash
}

/// Calculate a stable hash of the TOS text for tracking changes
#[cfg(feature = "online")]
fn hash_tos(text: &str) -> String {
    format!("{:x}", fnv1a_hash(text.as_bytes()))
}

/// Save TOS acceptance to file
#[cfg(feature = "online")]
fn save_tos_acceptance(accepted: bool, terms_hash: &str) -> Result<(), String> {
    let Some(tos_path) = get_tos_file_path() else {
        return Err("Could not determine home directory".to_string());
    };

    // Create .ballistics directory if it doesn't exist
    if let Some(parent) = tos_path.parent() {
        fs::create_dir_all(parent)
            .map_err(|e| format!("Failed to create .ballistics directory: {}", e))?;
    }

    let acceptance = TosAcceptance {
        accepted,
        accepted_version: TOS_VERSION.to_string(),
        accepted_at: chrono_lite_timestamp(),
        terms_hash: terms_hash.to_string(),
    };

    let json = serde_json::to_string_pretty(&acceptance)
        .map_err(|e| format!("Failed to serialize TOS acceptance: {}", e))?;

    fs::write(&tos_path, json)
        .map_err(|e| format!("Failed to write TOS acceptance file: {}", e))?;

    Ok(())
}

/// Get current timestamp without chrono dependency
#[cfg(feature = "online")]
fn chrono_lite_timestamp() -> String {
    use std::time::{SystemTime, UNIX_EPOCH};

    let duration = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap_or_default();

    format!("{}", duration.as_secs())
}

/// Display TOS and prompt for acceptance
#[cfg(feature = "online")]
fn prompt_tos_acceptance() -> Result<bool, String> {
    eprintln!("\n");
    eprintln!("================================================================================");
    eprintln!("                    TERMS OF SERVICE ACCEPTANCE REQUIRED");
    eprintln!("================================================================================");
    eprintln!();
    eprintln!("The --online feature sends data to a proprietary cloud service.");
    eprintln!("Before using this feature, you must accept the Terms of Service.");
    eprintln!();
    eprintln!("Fetching Terms of Service from {}...", TOS_URL);
    eprintln!();

    // Fetch TOS
    let tos_text = fetch_tos_text()?;
    let terms_hash = hash_tos(&tos_text);

    // Display TOS
    eprintln!("{}", tos_text);
    eprintln!();
    eprintln!("================================================================================");
    eprintln!();

    // Prompt for acceptance
    eprint!("Do you accept the Terms of Service? [y/N]: ");
    io::stderr().flush().ok();

    let mut input = String::new();
    io::stdin()
        .read_line(&mut input)
        .map_err(|e| format!("Failed to read input: {}", e))?;

    let accepted = matches!(input.trim().to_lowercase().as_str(), "y" | "yes");

    // Save acceptance status
    save_tos_acceptance(accepted, &terms_hash)?;

    if accepted {
        eprintln!();
        eprintln!(
            "Terms of Service accepted. This will not be shown again unless the terms change."
        );
        eprintln!();
    } else {
        eprintln!();
        eprintln!("Terms of Service not accepted. The --online feature cannot be used.");
        eprintln!("You can still use local calculations by omitting the --online flag.");
        eprintln!();
    }

    Ok(accepted)
}

/// Check TOS acceptance and prompt if needed. Returns true if online mode can proceed.
#[cfg(feature = "online")]
fn ensure_tos_accepted() -> Result<bool, String> {
    if check_tos_accepted() {
        return Ok(true);
    }

    prompt_tos_acceptance()
}

// ============================================================================
// Custom Value Parsers for f64 Range Validation (MBA-732)
// ============================================================================

/// Create a value parser that validates an f64 is within [min, max].
fn f64_range(min: f64, max: f64) -> clap::builder::ValueParser {
    clap::builder::ValueParser::new(F64RangeParser { min, max })
}

#[derive(Clone, Debug)]
struct F64RangeParser {
    min: f64,
    max: f64,
}

impl clap::builder::TypedValueParser for F64RangeParser {
    type Value = f64;

    fn parse_ref(
        &self,
        _cmd: &clap::Command,
        arg: Option<&clap::Arg>,
        value: &std::ffi::OsStr,
    ) -> Result<Self::Value, clap::Error> {
        let s = value.to_str().ok_or_else(|| {
            let mut err = clap::Error::new(clap::error::ErrorKind::InvalidUtf8);
            if let Some(a) = arg {
                err.insert(
                    clap::error::ContextKind::InvalidArg,
                    clap::error::ContextValue::String(a.get_id().to_string()),
                );
            }
            err
        })?;
        let inner: f64 = s.parse().map_err(|_| {
            let mut err = clap::Error::new(clap::error::ErrorKind::ValueValidation);
            if let Some(a) = arg {
                err.insert(
                    clap::error::ContextKind::InvalidArg,
                    clap::error::ContextValue::String(a.get_id().to_string()),
                );
            }
            err.insert(
                clap::error::ContextKind::InvalidValue,
                clap::error::ContextValue::String(format!("'{}' is not a valid number", s)),
            );
            err
        })?;
        if !inner.is_finite() || inner < self.min || inner > self.max {
            let mut err = clap::Error::new(clap::error::ErrorKind::ValueValidation);
            if let Some(a) = arg {
                err.insert(
                    clap::error::ContextKind::InvalidArg,
                    clap::error::ContextValue::String(a.get_id().to_string()),
                );
            }
            err.insert(
                clap::error::ContextKind::InvalidValue,
                clap::error::ContextValue::String(format!(
                    "{} is not in range {:.6}..={:.6}",
                    inner, self.min, self.max
                )),
            );
            return Err(err);
        }
        Ok(inner)
    }
}

/// `--confidence`'s three permitted levels, parsed directly into
/// [`ConfidenceLevel`] (MBA-1352). That type
/// derives no clap trait of its own -- `mc_stats.rs` is deliberately clap-free so it keeps
/// compiling for `wasm32-unknown-unknown` unconditionally -- so this CLI-only mapping stands
/// in for a `ValueEnum` derive. A plain `fn(&str) -> Result<T, String>` used as a
/// `value_parser` gets its owning `--flag` name attached to the error automatically by clap
/// (see `parse_angular_mil` below for the same convention), so the message only needs to
/// state the value and the allowed choices, matching the dial-plan budget-flags precedent from
/// the Plan B final review (a bad value must name the flag, not just the value).
fn parse_confidence_level(s: &str) -> Result<ConfidenceLevel, String> {
    match s {
        "90" => Ok(ConfidenceLevel::P90),
        "95" => Ok(ConfidenceLevel::P95),
        "99" => Ok(ConfidenceLevel::P99),
        _ => Err(format!("confidence level '{s}' must be one of: 90, 95, 99")),
    }
}

/// `--target-ci-half-width` must be finite and greater than zero -- the same rule
/// [`McConvergence::validate`] enforces on the field it feeds, checked here at parse time so a
/// bad value is a clap usage error naming `--target-ci-half-width` (MBA-1352) rather than the
/// library's struct-qualified `"McConvergence.target_half_width"` message reaching the user
/// unrewritten.
fn parse_positive_half_width(s: &str) -> Result<f64, String> {
    let v: f64 = s
        .parse()
        .map_err(|_| format!("half-width '{s}' is not a valid number"))?;
    if !v.is_finite() || v <= 0.0 {
        return Err(format!(
            "half-width '{s}' must be a finite value greater than zero (probability units, e.g. 0.02 = +-2 percentage points)"
        ));
    }
    Ok(v)
}

#[derive(Parser)]
#[command(name = "ballistics")]
#[command(author = "Ballistics Engine Team")]
#[command(version = env!("CARGO_PKG_VERSION"))]
#[command(about = "High-performance ballistics trajectory calculator", long_about = None)]
struct Cli {
    /// Unit system for input/output (metric or imperial)
    #[arg(short = 'u', long, default_value = "imperial", global = true)]
    units: UnitSystem,

    #[command(subcommand)]
    command: Commands,
}

#[allow(
    clippy::large_enum_variant,
    reason = "variants intentionally mirror the stable flat Clap command shape"
)]
#[derive(Subcommand)]
enum Commands {
    /// Solve one explicit-SI v1 JSON request from stdin and write one JSON envelope to stdout
    SolveJson,

    /// Run a Model Context Protocol (MCP) server over stdio, exposing solve and engine_info tools
    Mcp,

    /// Save a CLI access token (from ballisticsinsight.com/account) for the online reverse solvers
    #[cfg(feature = "online")]
    Login {
        /// The token; if omitted, you'll be prompted to paste it
        #[arg(long)]
        token: Option<String>,
    },

    /// Remove the saved CLI access token
    #[cfg(feature = "online")]
    Logout,

    /// Recommend powders for a load (online reverse solver; needs `login` + a subscription)
    #[cfg(feature = "online")]
    RecommendPowder {
        /// Cartridge name, e.g. "308 Winchester"
        #[arg(long)]
        cartridge: String,
        /// Bullet weight in grains
        #[arg(long)]
        bullet_weight: f64,
        /// Desired muzzle velocity in fps
        #[arg(long)]
        desired_velocity: f64,
        /// Barrel length in inches (optional)
        #[arg(long)]
        barrel_length: Option<f64>,
        /// Velocity tolerance in fps (optional)
        #[arg(long)]
        velocity_tolerance: Option<i64>,
        /// API base URL
        #[arg(long, default_value = "https://api.ballistics.7.62x51mm.sh")]
        api_url: String,
    },

    /// Recommend an optimal barrel twist rate (online reverse solver)
    #[cfg(feature = "online")]
    RecommendTwist {
        /// Bullet caliber in inches
        #[arg(long)]
        caliber: f64,
        /// Bullet weight in grains
        #[arg(long)]
        weight: f64,
        /// Total bullet length in inches
        #[arg(long)]
        overall_length: f64,
        /// Nose length in inches
        #[arg(long)]
        nose_length: f64,
        /// Muzzle velocity in fps (optional)
        #[arg(long)]
        muzzle_velocity: Option<f64>,
        /// API base URL
        #[arg(long, default_value = "https://api.ballistics.7.62x51mm.sh")]
        api_url: String,
    },

    /// Recommend cartridge overall length (online reverse solver)
    #[cfg(feature = "online")]
    RecommendCol {
        /// Cartridge name, e.g. "308 Winchester"
        #[arg(long)]
        cartridge: String,
        /// Bullet weight in grains (optional)
        #[arg(long)]
        bullet_weight: Option<i64>,
        /// Bullet type/model (optional)
        #[arg(long)]
        bullet_type: Option<String>,
        /// API base URL
        #[arg(long, default_value = "https://api.ballistics.7.62x51mm.sh")]
        api_url: String,
    },

    /// Calibrate a bullet's BC from its dimensions (online reverse solver)
    #[cfg(feature = "online")]
    CalibrateBc {
        /// Bullet diameter in inches
        #[arg(long)]
        diameter: f64,
        /// Bullet overall length in inches
        #[arg(long)]
        length: f64,
        /// Bullet weight in grains
        #[arg(long)]
        weight: f64,
        /// Bullet type/model (optional)
        #[arg(long)]
        bullet_type: Option<String>,
        /// API base URL
        #[arg(long, default_value = "https://api.ballistics.7.62x51mm.sh")]
        api_url: String,
    },

    /// Calculate a single trajectory
    Trajectory {
        /// Load parameters from CSV profile file (gun_profiles.csv format).
        /// Requires --profile-row: the file alone selects nothing, and silently
        /// ignoring it was the MBA-1425 trap.
        #[arg(long, value_name = "FILE", requires = "profile_row")]
        profile: Option<PathBuf>,

        /// Row name to load from profile CSV (matches first column, e.g., "R700_65CM").
        /// Legal without --profile: standalone it only labels the PDF dope card's rifle
        /// name, a pre-existing use the MBA-1425 pairing must not break — the silent trap
        /// was the FILE without a selector, not the selector alone.
        #[arg(long, value_name = "NAME")]
        profile_row: Option<String>,

        /// Load a saved profile by name (from ~/.ballistics/profiles/)
        #[arg(long, value_name = "NAME")]
        saved_profile: Option<String>,

        /// Load location/environmental data from CSV file. Requires --site: without a row
        /// selector the file was silently ignored entirely (MBA-1425), and the near-miss
        /// --location-name flag (a PDF header override) made the trap easy to fall into.
        #[arg(long, value_name = "FILE", requires = "site")]
        location: Option<PathBuf>,

        /// Site name to load from location CSV (matches first column, e.g., "KF_LR").
        /// Legal without --location: standalone it only labels the PDF dope card's
        /// location line (unless --location-name overrides it) — same asymmetry as
        /// --profile-row, and for the same MBA-1425 reason.
        #[arg(long, value_name = "NAME")]
        site: Option<String>,

        /// Initial velocity (fps or m/s based on --units)
        #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
        velocity: Option<f64>,

        /// Velocity adjustment (added to base velocity for truing from chronograph data)
        #[arg(long, default_value = "0.0", allow_hyphen_values = true)]
        velocity_adjustment: f64,

        /// Launch angle (degrees)
        #[arg(short = 'a', long, default_value = "0.0")]
        angle: f64,

        /// Ballistic coefficient
        #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
        bc: Option<f64>,

        /// BC adjustment factor (multiplier for truing, e.g., 0.85 = 85% of stated BC)
        #[arg(long, default_value = "1.0")]
        bc_adjustment: f64,

        /// Which standard atmosphere --bc / a saved profile's BC is referenced to
        /// (MBA-1365). Most published BCs (and this engine's own retardation math)
        /// assume ICAO; some vendors (notably Sierra, Hornady, and Barnes for many
        /// bullets) instead publish BCs referenced to the older, denser Army Standard
        /// Metro atmosphere, which under-predicts drag by about 1.8% if fed in
        /// unconverted. Has no effect together with --drag-table: that path divides by
        /// sectional density, not a BC, so no reference conversion is meaningful there.
        /// A BC produced by estimate-bc/true-velocity is always ICAO-referenced — do not
        /// pass army-standard-metro for a fitted value or it will be double-converted.
        #[arg(long, value_enum)]
        bc_reference: Option<BcReferenceStandard>,

        /// Mass (grains for imperial, grams for metric)
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: Option<f64>,

        /// Diameter (inches for imperial, mm for metric)
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: Option<f64>,

        /// Drag model (G1, G2, G5, G6, G7, G8, GI, GS, RA4)
        #[arg(long, default_value = "g1")]
        drag_model: DragModel,

        /// Maximum range (yards or meters based on --units)
        #[arg(long, default_value = "1000.0")]
        max_range: f64,

        /// Integration time step in seconds — RK4/Euler only (the adaptive RK45 default ignores it and steps adaptively)
        #[arg(long, default_value = "0.001", value_parser = f64_range(0.00001, 0.1))]
        time_step: f64,

        /// Wind speed (mph or m/s based on --units)
        #[arg(long, default_value = "0.0")]
        wind_speed: f64,

        /// Wind direction (MBA-1367: shared help const; Option so an explicit entry —
        /// including `12oc` == 0 degrees — is distinguishable from the 0.0 default,
        /// replacing the old `!= 0.0` sentinel).
        #[arg(long, value_parser = parse_wind_direction_arg, help = WIND_DIRECTION_HELP)]
        wind_direction: Option<ParsedWindDirection>,

        /// Reference frame for EVERY wind direction this run consumes (MBA-1368):
        /// `shooter` (default; wind-FROM angles relative to the line of fire — today's
        /// behavior) or `compass` (earth-fixed bearings, 0 = north, covering
        /// --wind-direction, a location CSV's WIND_DIR, and every --wind-segment angle,
        /// re-referenced against --shot-direction at solve time). Compass mode requires
        /// --shot-direction and rejects clock positions (shooter-relative by definition).
        #[arg(long, value_enum, default_value = "shooter")]
        wind_ref: WindReferenceArg,

        /// Vertical wind, mph (imperial) or m/s (metric); positive = updraft (raises POI)
        #[arg(
            long,
            value_parser = f64_range(-100.0, 100.0),
            default_value_t = 0.0,
            allow_hyphen_values = true
        )]
        wind_vertical: f64,

        /// Downrange wind segment "SPEED:ANGLE:UNTIL_DISTANCE" with an optional 4th
        /// ":VERTICAL" field (repeatable).
        /// SPEED/UNTIL_DISTANCE follow --units (mph & yd imperial, m/s & m metric); ANGLE is
        /// degrees, same convention as --wind-direction. The optional 4th field, VERTICAL, is
        /// ALWAYS m/s (positive = updraft, raises POI) regardless of --units — unlike SPEED it
        /// does not follow --units; omit it for the pre-existing 3-field form (vertical wind
        /// 0). Each segment applies from the previous boundary out to UNTIL_DISTANCE; wind is
        /// zero beyond the last segment. Overrides --wind-speed/-direction/-vertical. Not
        /// compatible with --enable-wind-shear.
        #[arg(long = "wind-segment", value_name = "SPEED:ANGLE:DIST[:VERTICAL]", action = clap::ArgAction::Append)]
        wind_segment: Vec<String>,

        /// Manual velocity-dependent BC segment(s): "VMIN:VMAX:BC" (repeatable). VMIN/VMAX are
        /// velocities in --units (fps imperial, m/s metric); the given BC applies while the
        /// bullet's speed is in [VMIN, VMAX). Segments are keyed to VELOCITY (independent of
        /// distance/wind). Overrides --bc-table and --bc-table-dir, and implies
        /// --use-bc-segments.
        #[arg(long = "bc-segment", value_name = "VMIN:VMAX:BC", action = clap::ArgAction::Append)]
        bc_segment: Vec<String>,

        /// Temperature (Fahrenheit or Celsius based on --units; default 59 F / 15 C)
        #[arg(long)]
        temperature: Option<f64>,

        /// Pressure (inHg or hPa based on --units; default 29.92 inHg / 1013.25 hPa)
        #[arg(long)]
        pressure: Option<f64>,

        /// Whether --pressure is absolute station pressure (default) or a sea-level-corrected
        /// altimeter setting (QNH / weather-report "barometer" value, MBA-1397). `qnh` is
        /// reduced to station pressure at --altitude via the ICAO inverse-barometric formula
        /// before use; `absolute` is today's behavior unchanged. Entering a QNH value as
        /// `absolute` (the historical default) at a real altitude over-states air density and
        /// under-states drop. No default_value (like --bc-reference): an explicit flag always
        /// wins, otherwise a `--saved-profile`'s stored mode applies, defaulting to absolute
        /// when neither is present -- byte-identical to every profile saved before this field
        /// existed.
        #[arg(long, value_enum)]
        pressure_type: Option<PressureReferenceMode>,

        /// Humidity (0-100%)
        #[arg(long, default_value = "50.0", value_parser = f64_range(0.0, 100.0))]
        humidity: f64,

        /// Altitude (feet or meters based on --units)
        #[arg(long, default_value = "0.0")]
        altitude: f64,

        /// Density altitude (feet imperial / meters metric based on --units; MBA-1366): the
        /// single-value atmosphere entry mode Shooter, Nosler, AB Analytics, Ballistic AE, and
        /// TRASOL all support as an alternative to entering altitude + pressure + temperature
        /// separately. When given, it SUPERSEDES `--altitude` and `--pressure`/`--pressure-type`
        /// entirely: an ISA-equivalent station altitude/pressure is back-solved from it (NOT
        /// the direct-density bypass — Mach, lapse-rate, and segmented-atmosphere behavior are
        /// all preserved). The resulting temperature defaults to the ISA temperature at that
        /// density altitude, UNLESS an explicit `--temperature` is also given, in which case the
        /// real temperature wins (needed for correct powder-temperature sensitivity and moist
        /// speed of sound) and the implied pressure is re-solved so the density altitude is
        /// still reproduced exactly. A `--location`/CSV `DA`/`DENSITY_ALTITUDE` column is used
        /// when this flag is omitted.
        // MBA-1420: bound the flag so an out-of-range value fails naming --density-altitude.
        // Without this an extreme value drives the pressure inverse negative and surfaces as
        // "atmosphere.pressure must be finite", pointing at a field the user never typed. The
        // band is deliberately wide (and unit-agnostic, since the flag is feet imperial /
        // meters metric): -2000 and 100000 both solve fine, so this only catches nonsense.
        #[arg(long, allow_hyphen_values = true, value_parser = f64_range(-5000.0, 120000.0))]
        density_altitude: Option<f64>,

        /// Output format
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,

        /// Show all trajectory points
        #[arg(long)]
        full: bool,

        /// Render inline terminal charts after the normal output: drop, lateral drift,
        /// velocity, and energy, each vs. range (four stacked panels). Only applies to `-o table` (the default); other
        /// `--output` formats stay machine-readable and unchanged. Bare `--plot` uses the
        /// Unicode braille-dot canvas; `--plot ascii` uses a '*'-per-cell fallback for
        /// terminals/fonts without braille glyph coverage. Monochrome (no ANSI colors —
        /// see src/terminal_plot.rs for why); fixed 72x12-cell canvas per chart, no
        /// terminal-size detection.
        #[arg(long, value_enum, num_args = 0..=1, default_missing_value = "braille")]
        plot: Option<PlotStyle>,

        /// Automatically zero to target distance (overrides --angle)
        #[arg(long)]
        auto_zero: Option<f64>,

        /// Select a named zero set (MBA-1360): a saved profile's `zero_sets` entry (see
        /// `profile zero-set add`), or the set a --profile CSV row's
        /// V_OFFSET_MIL/H_OFFSET_MIL columns define (named after the row). The set's
        /// zero_distance (if any) feeds the auto-zero exactly as the profile's own
        /// zero would (an explicit --auto-zero still wins); its poi_up_mil/poi_right_mil
        /// are added to dial outputs (here: the PDF dope card's Drop/Wind columns) as a
        /// constant angular correction. Unknown names are a hard error listing the
        /// available sets.
        #[arg(long, value_name = "NAME")]
        zero_set: Option<String>,

        /// Deliberate vertical POI offset AT the zero range (inches for imperial, cm for
        /// metric; signed). Positive = the rifle is deliberately zeroed to impact HIGH by
        /// this much at the zero distance (Kestrel "zero height" semantics, MBA-1359).
        /// Applied as an angular bias on the solved zero; requires a zero solve
        /// (--auto-zero or a profile zero) to have any effect.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        zero_poi_up: Option<f64>,

        /// Deliberate horizontal POI offset AT the zero range (inches for imperial, cm for
        /// metric; signed). Positive = impacts RIGHT by this much at the zero distance
        /// (Kestrel "zero offset" semantics, MBA-1359). Applied as an azimuth bias when a
        /// zero is solved; requires a zero solve to have any effect.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        zero_poi_right: Option<f64>,

        /// Sight height above bore (inches for imperial, mm for metric)
        #[arg(long)]
        sight_height: Option<f64>,

        /// Lateral sight-to-bore mount offset for offset-mounted optics (inches for
        /// imperial, mm for metric; signed). Positive = the sight sits RIGHT of the bore
        /// (MBA-1396). Physical mount geometry, distinct from --zero-poi-right's angular
        /// zero-state bias: the bullet starts that far LEFT of the sight line, and a zero
        /// solve adds the windage convergence so it crosses the sight line at the zero
        /// range. Without a zero solve (explicit --angle), only the constant physical
        /// displacement applies — drift starts offset and stays uncorrected.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        sight_offset: Option<f64>,

        /// Bore height above ground (inches for imperial, mm for metric; MBA-1339 unified
        /// this with --sight-height and the WASM --muzzle-height flag). Default: 60in/1500mm
        /// (= 5ft/1.5m). Also accepts --muzzle-height.
        #[arg(long, visible_alias = "muzzle-height")]
        bore_height: Option<f64>,

        /// Ignore ground impact detection (trajectory continues to max range)
        #[arg(long)]
        ignore_ground_impact: bool,

        /// Enable velocity-based BC segmentation
        #[arg(long)]
        use_bc_segments: bool,

        /// Path to a custom drag deck: CSV with `mach,cd` per line, or a vendor `.drg` file
        /// (by extension; Hornady CDM / Lapua radar style). Replaces the G-model + BC for drag; bc_value is ignored when set. Mach-keyed;
        /// out-of-range Mach holds the nearest tabulated Cd.
        #[arg(long, value_name = "FILE")]
        drag_table: Option<PathBuf>,

        /// Whole-curve drag scale for a custom drag table (Hornady AFF / AB CDF style; 1.0 =
        /// neutral, typical truing range 0.90-1.10). Requires --drag-table.
        #[arg(long, value_name = "FACTOR")]
        cd_scale: Option<f64>,

        /// Rifle cant in DEGREES, positive = clockwise from the shooter (top of scope tips
        /// right). Models "zeroed level, fired canted": POI moves right and low. 0 = level.
        #[arg(
            long,
            alias = "cant-angle",
            value_name = "DEGREES",
            default_value_t = 0.0
        )]
        cant: f64,

        /// Print the BC5D-generated segment ladder as ready-to-paste
        /// --bc-segment arguments (requires --bc-table-dir; velocities in
        /// the active --units)
        #[arg(long)]
        print_bc_segments: bool,

        // Advanced Physics Parameters
        /// Enable Magnus effect (requires twist-rate)
        #[arg(long)]
        enable_magnus: bool,

        /// Enable Coriolis effect (requires latitude)
        #[arg(long)]
        enable_coriolis: bool,

        /// Use Euler integration instead of RK45 (RK45 adaptive is default for best accuracy)
        #[arg(long)]
        use_euler: bool,

        /// Use fixed-step RK4 instead of adaptive RK45 (faster but less accurate)
        #[arg(long)]
        use_rk4_fixed: bool,

        /// Enable empirical Litz spin drift calculations
        #[arg(long)]
        enable_spin_drift: bool,

        /// Apply aerodynamic jump as a muzzle launch-angle perturbation (EXPERIMENTAL — heuristic model, MBA-959)
        #[arg(long)]
        enable_aerodynamic_jump: bool,

        /// Enable wind shear (altitude-dependent wind)
        #[arg(long)]
        enable_wind_shear: bool,

        /// Enable trajectory sampling at regular intervals
        #[arg(long)]
        sample_trajectory: bool,

        /// Sampling interval in meters (default: 10)
        /// Trajectory sampling interval in meters (used with --sample-trajectory; always metric, not unit-system dependent)
        #[arg(long, default_value = "10.0")]
        sample_interval: f64,

        /// Which plane sampled drop values are referenced to (MBA-1403): 'los' (default)
        /// measures drop perpendicular to the line of sight; 'target' reports drop as
        /// vertical in the target plane (LOS drop scaled by 1/cos(shooting angle), JBM's
        /// "target plane" reference) and relabels the sampled table/CSV drop column
        #[arg(long, value_enum, default_value_t = DropsReferenceArg::Los)]
        drops_reference: DropsReferenceArg,

        /// Enable pitch damping for transonic stability analysis
        #[arg(long)]
        enable_pitch_damping: bool,

        /// Enable precession/nutation physics for angular motion modeling
        #[arg(long)]
        enable_precession: bool,

        /// Use cluster-based BC degradation for improved accuracy
        #[arg(long)]
        use_cluster_bc: bool,

        /// Path to BC correction table file for offline ML-enhanced corrections
        #[arg(
            long,
            value_name = "FILE",
            help = "Use precomputed BC correction table instead of online API"
        )]
        bc_table: Option<PathBuf>,

        /// Directory containing caliber-specific BC5D tables (e.g., bc5d_308.bin)
        #[arg(
            long,
            value_name = "DIR",
            help = "Use caliber-specific 5D BC correction tables"
        )]
        bc_table_dir: Option<PathBuf>,

        /// Enable auto-download of BC5D correction tables when needed
        #[cfg(feature = "online")]
        #[arg(long, help = "Auto-download BC5D tables when needed")]
        bc_table_auto: bool,

        /// Base URL for BC5D table downloads
        #[cfg(feature = "online")]
        #[arg(
            long,
            default_value = "https://ballistics.tools/downloads/bc5d",
            help = "Base URL for BC5D table downloads"
        )]
        bc_table_url: String,

        /// Force re-download of BC5D tables even if cached
        #[cfg(feature = "online")]
        #[arg(long, help = "Force re-download even if cached")]
        bc_table_refresh: bool,

        /// Bullet length in inches (for BC table lookup; estimated from diameter if not provided)
        #[arg(long)]
        bullet_length: Option<f64>,

        /// Barrel twist rate (inches/turn for imperial, mm/turn for metric; e.g. imperial 10 = 1:10")
        #[arg(long)]
        twist_rate: Option<f64>,

        /// Twist hand: `--twist-right` or `--twist-right true` = right-hand (default);
        /// `--twist-right false` = left-hand
        #[arg(
            long,
            num_args = 0..=1,
            default_value_t = true,
            default_missing_value = "true",
            action = clap::ArgAction::Set
        )]
        twist_right: bool,

        /// Latitude for Coriolis effect and weather zones (degrees, -90 to 90)
        #[arg(long, value_parser = f64_range(-90.0, 90.0), allow_hyphen_values = true)]
        latitude: Option<f64>,

        /// Longitude for weather zones (degrees, -180 to 180)
        #[arg(long, value_parser = f64_range(-180.0, 180.0), allow_hyphen_values = true)]
        longitude: Option<f64>,

        /// Shot direction/azimuth for Coriolis and weather zones (degrees, 0=North, 90=East)
        #[arg(long)]
        shot_direction: Option<f64>,

        /// Shooting angle (degrees, positive = uphill, negative = downhill)
        #[arg(long, default_value = "0.0", allow_hyphen_values = true)]
        shooting_angle: f64,

        /// Enable powder temperature sensitivity
        #[arg(long)]
        use_powder_sensitivity: bool,

        /// Powder temperature sensitivity (fps/°F imperial, m/s/°C metric).
        /// Defaults to 1.0 fps/°F (0.54864 m/s/°C).
        #[arg(long)]
        powder_temp_sensitivity: Option<f64>,

        /// Powder temperature (°F/°C). With --powder-temp-curve, this is the powder
        /// temperature the curve is interpolated at to resolve muzzle velocity (defaults
        /// to --temperature when omitted, i.e. powder assumed at air temperature). With
        /// --powder-temp-sensitivity (linear model), it is the reference temperature the
        /// stated velocity was measured at (defaults to the 70°F equivalent).
        #[arg(long)]
        powder_temp: Option<f64>,

        /// Measured powder-temperature -> muzzle-velocity curve as comma-separated
        /// TEMP:VELOCITY points, e.g. "40:2620,70:2700,100:2760" (temps in F/C,
        /// velocities in fps / m·s⁻¹ per --units). The muzzle velocity is interpolated
        /// from this table at the powder temperature (--powder-temp, or --temperature if
        /// unset; clamped at the endpoints, no extrapolation). Data-driven, non-linear
        /// alternative that OVERRIDES --powder-temp-sensitivity when supplied.
        #[arg(long = "powder-temp-curve", value_name = "TEMP:VEL,...")]
        powder_temp_curve: Option<String>,

        // Zero-day condition overrides for --auto-zero. When supplied, the zero ANGLE is
        // solved under these conditions (the day/velocity the rifle was actually zeroed in)
        // while the trajectory runs under the current shot-day conditions. With no zero-day
        // flags, the shot-day values are reused exactly; coupled powder fallbacks are documented
        // on the individual options below.
        /// Zero-day muzzle velocity for --auto-zero (fps imperial / m·s⁻¹ metric). Use when the
        /// rifle was zeroed at a different velocity than this shot. Overrides both powder models.
        #[arg(long, value_parser = f64_range(0.0, 6000.0))]
        zero_velocity: Option<f64>,

        /// Zero-day air temperature for --auto-zero (°F imperial / °C metric). Also resolves
        /// zero-day velocity for the linear powder-sensitivity model unless --zero-velocity is set.
        #[arg(long, allow_hyphen_values = true)]
        zero_temperature: Option<f64>,

        /// Zero-day barometric pressure for --auto-zero (inHg imperial / hPa metric)
        #[arg(long)]
        zero_pressure: Option<f64>,

        /// Whether --zero-pressure is absolute station pressure or a sea-level-corrected
        /// altimeter setting (QNH), mirroring --pressure-type (MBA-1397). Defaults to the
        /// shot-day --pressure-type when --zero-pressure-type is not given, matching the
        /// "omitting all --zero-* flags reuses the shot-day values" contract above.
        #[arg(long, value_enum)]
        zero_pressure_type: Option<PressureReferenceMode>,

        /// Zero-day relative humidity for --auto-zero (percent, 0-100)
        #[arg(long, value_parser = f64_range(0.0, 100.0))]
        zero_humidity: Option<f64>,

        /// Zero-day altitude for --auto-zero (feet imperial / meters metric)
        #[arg(long, allow_hyphen_values = true)]
        zero_altitude: Option<f64>,

        /// Zero-day density altitude for --auto-zero (feet imperial / meters metric; MBA-1422).
        /// The zero-day counterpart of --density-altitude, letting a zero be torn under
        /// conditions expressed as a single density altitude. SUPERSEDES --zero-altitude and
        /// --zero-pressure/--zero-pressure-type for the zero solve only; the shot-day
        /// atmosphere is untouched. An explicit --zero-temperature still wins over the ISA
        /// temperature at that density altitude.
        #[arg(long, allow_hyphen_values = true, value_parser = f64_range(-5000.0, 120000.0))]
        zero_density_altitude: Option<f64>,

        /// Zero-day powder temperature for --auto-zero (°F/°C). With --powder-temp-curve,
        /// the curve is interpolated at this temperature to resolve the zero-day muzzle
        /// velocity. When omitted, the curve follows an explicit --zero-temperature; otherwise
        /// it inherits an explicit shot-day --powder-temp. An explicit --zero-velocity still
        /// takes precedence.
        #[arg(long, allow_hyphen_values = true)]
        zero_powder_temp: Option<f64>,

        // Online Mode Parameters (feature-gated)
        /// Use Flask API for ML-enhanced trajectory calculation
        #[cfg(feature = "online")]
        #[arg(
            long,
            help = "Route calculations through Flask API for ML enhancements"
        )]
        online: bool,

        /// API endpoint URL
        #[cfg(feature = "online")]
        #[arg(
            long,
            default_value = "https://api.ballistics.7.62x51mm.sh",
            help = "API endpoint URL"
        )]
        api_url: String,

        /// Fall back to local calculation if API unreachable
        #[cfg(feature = "online")]
        #[arg(long, help = "Use local calculation if API fails")]
        offline_fallback: bool,

        /// Compare local and API results side-by-side
        #[cfg(feature = "online")]
        #[arg(long, help = "Show comparison between local and API results")]
        compare: bool,

        /// API request timeout in seconds
        #[cfg(feature = "online")]
        #[arg(long, default_value = "10", help = "API timeout in seconds")]
        api_timeout: u64,

        /// Enable weather zones (requires latitude, longitude, and shot-direction)
        #[cfg(feature = "online")]
        #[arg(long, help = "Enable automatic weather zone generation")]
        enable_weather_zones: bool,

        /// Enable 3D weather corrections (altitude-dependent atmospheric changes)
        #[cfg(feature = "online")]
        #[arg(long, help = "Enable 3D weather with altitude corrections")]
        enable_3d_weather: bool,

        /// Wind shear boundary-layer model (only used with --enable-wind-shear)
        #[arg(
            long,
            value_enum,
            default_value = "power_law",
            help = "Wind shear model: none, logarithmic, power_law, ekman_spiral, custom_layers"
        )]
        wind_shear_model: WindShearModelArg,

        /// Weather zone interpolation method
        #[cfg(feature = "online")]
        #[arg(
            long,
            default_value = "linear",
            help = "Weather zone interpolation: linear, cubic, step"
        )]
        weather_zone_interpolation: String,

        // PDF Dope Card Parameters
        /// Target speed for moving-target holds (mph for imperial, m/s for metric — same
        /// convention as `lead --target-speed`). Drives two independent outputs when > 0:
        /// the PDF dope card's assumed-90-degree-crossing Lead column, and — for every
        /// output format — a per-point mover Ring column/field (MBA-1325): ring radius =
        /// target_speed x point ToF, the "fire when the mover enters the ring" technique.
        /// See CLI_USAGE.md for the full mover-ring writeup. 0 (default) disables both.
        #[arg(long, default_value = "0.0", value_parser = f64_range(0.0, 300.0))]
        target_speed: f64,

        /// Add each point's effective drag coefficient to `--full` JSON (MBA-1423).
        ///
        /// This is the PROJECTILE's own Cd, not the reference table's: a G-model Cd describes
        /// the standard projectile, so it is scaled by the form factor (sectional density / BC)
        /// to describe this bullet. A velocity- or Mach-segmented BC therefore shows its band
        /// steps here, and a custom drag table's curve is already the projectile's own Cd and
        /// passes through unchanged.
        ///
        /// Covers only the speeds the bullet actually flew, not a full Mach sweep. Cd is paired
        /// with the station speed of sound the document reports Mach against, so plotting one
        /// against the other is self-consistent. Off by default: without this flag the JSON is
        /// byte-for-byte what it was.
        ///
        /// JSON only for now. CSV's sampled-interval branch reports a different point type that
        /// carries no Cd, so a column there would be populated in one branch and empty in the
        /// other; that parity work is tracked separately rather than shipped half-done.
        #[arg(long)]
        with_drag_coefficient: bool,

        /// Powder type/name (for PDF metadata)
        #[arg(long)]
        powder: Option<String>,

        /// Bullet name (for PDF metadata)
        #[arg(long)]
        bullet_name: Option<String>,

        /// Location name for PDF header (overrides --site for display)
        #[arg(long)]
        location_name: Option<String>,

        /// Output file path (required for PDF format)
        #[arg(long, value_name = "FILE")]
        output_file: Option<PathBuf>,

        /// Font scale factor for PDF output (1.0 = default, 1.5 = 50% larger)
        #[arg(long, default_value = "1.0")]
        font_scale: f32,

        /// Font size preset (small, medium, large) — overridden by --font-scale if both given
        #[arg(long, value_name = "SIZE")]
        font_preset: Option<String>,

        /// Use bold font for data cells in PDF output
        #[arg(long)]
        bold_data: bool,

        /// Angular unit (mil, moa, smoa, iphy, or clicks) applied ONLY to the PDF dope
        /// card's Drop/Wind/Lead columns (-o pdf) and the --target-speed mover Ring table
        /// column -- it has no effect on the plain table/JSON/CSV output otherwise, and a
        /// warning is printed if neither of those is in play. CSV/JSON ring fields stay
        /// mil/meters — their names carry the unit contract. `clicks` requires
        /// --elevation-click-value (or a saved profile's elevation_click) and formats
        /// whole turret clicks instead of an angle.
        #[arg(long, value_enum, default_value = "mil")]
        adjustment_unit: AdjustmentUnit,

        /// Independent windage unit (MBA-1410): overrides `--adjustment-unit` for the PDF
        /// dope card's Wind/Lead columns only (the mover Ring column and the Drop column
        /// stay on `--adjustment-unit`, i.e. the elevation axis). Falls back to
        /// `--adjustment-unit` when omitted -- the same windage-falls-back-to-elevation
        /// shape `--windage-click-value` already uses. `clicks` is only accepted here when
        /// `--adjustment-unit` is ALSO `clicks` (turret click output needs the elevation
        /// graduation resolved first); pass a plain angle (mil/moa/smoa/iphy) to mix e.g.
        /// mil elevation with moa windage.
        #[arg(long, value_enum)]
        windage_unit: Option<AdjustmentUnit>,

        /// Turret elevation click graduation for `--adjustment-unit clicks`, e.g. 0.1mil or
        /// 0.25moa (falls back to the saved profile's elevation_click when omitted).
        #[arg(long)]
        elevation_click_value: Option<String>,

        /// Turret windage click graduation for `--adjustment-unit clicks` (falls back to the
        /// resolved elevation graduation, then the saved profile's windage_click).
        #[arg(long)]
        windage_click_value: Option<String>,

        /// Elevation-axis scope tracking correction factor from a tall-target test
        /// (MBA-1358): actual measured travel / dialed travel (0.95 = under-tracks 5%).
        /// Elevation dial-unit outputs (the PDF dope card's drop column) are DIVIDED by
        /// it — e.g. dialed 10 / measured 9.5 mil gives CF 0.95, and a 10 mil solution
        /// displays as 10.53. Strictly between 0.5 and 1.5; overrides the saved
        /// profile's elevation_cf. Derive it with `ballistics tall-target`
        #[arg(long, value_name = "FACTOR")]
        elevation_cf: Option<f64>,

        /// Windage-axis scope tracking correction factor (MBA-1358): windage and
        /// mover-lead dial-unit outputs (the Ring column, PDF wind/lead columns) are
        /// divided by it. Same convention, bounds, and profile fallback (windage_cf)
        /// as --elevation-cf
        #[arg(long, value_name = "FACTOR")]
        windage_cf: Option<f64>,
    },

    /// Run Monte Carlo simulation
    MonteCarlo {
        /// Base velocity (fps for imperial, m/s for metric)
        #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
        velocity: f64,

        /// Launch angle (degrees)
        #[arg(short = 'a', long, default_value = "0.0")]
        angle: f64,

        /// Ballistic coefficient
        #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
        bc: f64,

        /// Which standard atmosphere --bc is referenced to (MBA-1365). Most published
        /// BCs (and this engine's own retardation math) assume ICAO; some vendors
        /// (notably Sierra, Hornady, and Barnes for many bullets) instead publish BCs
        /// referenced to the older, denser Army Standard Metro atmosphere, which
        /// under-predicts drag by about 1.8% if fed in unconverted. Has no effect
        /// together with --drag-table.
        #[arg(long, value_enum, default_value = "icao")]
        bc_reference: BcReferenceStandard,

        /// Mass (grains for imperial, grams for metric)
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: f64,

        /// Diameter (inches for imperial, mm for metric)
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: f64,

        /// Number of simulations
        #[arg(short = 'n', long, default_value = "1000")]
        num_sims: usize,

        /// Velocity standard deviation (fps for imperial, m/s for metric)
        #[arg(long, default_value = "1.0")]
        velocity_std: f64,

        /// Angle standard deviation (degrees)
        #[arg(long, default_value = "0.1")]
        angle_std: f64,

        /// BC standard deviation
        #[arg(long, default_value = "0.01")]
        bc_std: f64,

        /// Wind speed standard deviation (mph for imperial, m/s for metric)
        #[arg(long, default_value = "1.0")]
        wind_std: f64,

        /// Wind direction standard deviation (degrees)
        #[arg(long, visible_alias = "wind-dir-std", default_value = "0.0")]
        wind_direction_std: f64,

        /// Base wind speed (mph for imperial, m/s for metric)
        #[arg(long, default_value = "0.0")]
        wind_speed: f64,

        /// Base wind direction (MBA-1367: degrees or clock position, shared help const)
        #[arg(long, default_value = "0.0", value_parser = parse_wind_direction_arg, help = WIND_DIRECTION_HELP)]
        wind_direction: ParsedWindDirection,

        /// Reference frame for --wind-direction (MBA-1368): `shooter` (default) or
        /// `compass` (an earth-fixed bearing, 0 = north, re-referenced against
        /// --shot-direction BEFORE any dispersion sampling). Compass mode requires
        /// --shot-direction and rejects clock positions.
        #[arg(long, value_enum, default_value = "shooter")]
        wind_ref: WindReferenceArg,

        /// Compass bearing of the shot (degrees, 0 = north, 90 = east). Consumed ONLY
        /// by --wind-ref compass on this command (monte-carlo models no Coriolis).
        #[arg(long, value_name = "DEG")]
        shot_direction: Option<f64>,

        /// Base vertical wind, mph (imperial) or m/s (metric); positive = updraft (raises POI)
        #[arg(
            long,
            value_parser = f64_range(-100.0, 100.0),
            default_value_t = 0.0,
            allow_hyphen_values = true
        )]
        wind_vertical: f64,

        /// Target distance (yards for imperial, meters for metric)
        #[arg(long)]
        target_distance: Option<f64>,

        /// Hit-zone radius around the point of aim at the target plane (yards for imperial,
        /// meters for metric). A "hit" is a simulation landing within this radius. Default 0.3 m.
        #[arg(long)]
        target_radius: Option<f64>,

        /// Path to a custom drag deck: CSV `mach,cd` per line, or a vendor `.drg` file (by
        /// extension). Replaces the G-model + BC for drag;
        /// bc_value is ignored when set. Mach-keyed; out-of-range Mach holds the nearest tabulated Cd.
        #[arg(long, value_name = "FILE")]
        drag_table: Option<std::path::PathBuf>,

        /// Whole-curve drag scale for a custom drag table (Hornady AFF / AB CDF style; 1.0 =
        /// neutral, typical truing range 0.90-1.10). Requires --drag-table.
        #[arg(long, value_name = "FACTOR")]
        cd_scale: Option<f64>,

        /// Rifle cant in DEGREES, positive = clockwise from the shooter (top of scope tips
        /// right). Models "zeroed level, fired canted": POI moves right and low. 0 = level.
        #[arg(
            long,
            alias = "cant-angle",
            value_name = "DEGREES",
            default_value_t = 0.0
        )]
        cant: f64,

        /// Lateral sight-to-bore mount offset (inches imperial / mm metric; signed;
        /// positive = sight RIGHT of bore, MBA-1396). monte-carlo solves no zero, so only
        /// the constant physical displacement applies (shifts every sample's lateral
        /// start, and therefore the dispersion center), mirroring --cant's fire-time-only
        /// role here.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        sight_offset: Option<f64>,

        /// WEZ (Weapon Employment Zone) sweep mode: report hit probability vs range for a
        /// target size instead of a single summary. See CLI_USAGE.md's WEZ section.
        #[arg(long)]
        wez: bool,

        /// WEZ target size: `WIDTHxHEIGHT` (inches for imperial, cm for metric; e.g. `18x30`)
        /// for a rectangle centered on the point of aim, or a single number for a circular
        /// radius (same units; same semantics as `--target-radius`, just in target-size units).
        /// Required with `--wez`.
        #[arg(long, value_name = "WxH|R", requires = "wez")]
        target_size: Option<String>,

        /// Shooter's wind CALL error (mph for imperial, m/s for metric): the uncertainty in the
        /// shooter's own estimate of wind speed, as distinct from `--wind-std`'s physical
        /// gustiness. Composed with `--wind-std` in quadrature for the underlying dispersion:
        /// effective_wind_std = sqrt(wind_std^2 + wind_call_error^2). Only used with `--wez`.
        #[arg(long, default_value = "0.0", requires = "wez")]
        wind_call_error: f64,

        /// WEZ sweep start range (yards for imperial, meters for metric).
        #[arg(long, default_value = "200.0", requires = "wez")]
        wez_start: f64,

        /// WEZ sweep end range, inclusive (yards for imperial, meters for metric).
        #[arg(long, default_value = "1000.0", requires = "wez")]
        wez_end: f64,

        /// WEZ sweep step (yards for imperial, meters for metric).
        #[arg(long, default_value = "100.0", requires = "wez")]
        wez_step: f64,

        /// Confidence-controlled sampling (MBA-1352): run in batches until the hit-probability
        /// confidence interval's half-width reaches --target-ci-half-width (or --max-samples is
        /// hit) instead of a fixed --num-sims. Reports sample count, method, confidence level,
        /// and interval alongside the estimate -- see CLI_USAGE.md's "Confidence-Controlled
        /// Sampling" section. Ignores --num-sims (--min-samples is the floor instead) and
        /// --wind-direction-std (the adaptive driver disperses no wind direction, matching
        /// run_monte_carlo_with_wind); incompatible with --wez, which stays fixed-count.
        #[arg(long, conflicts_with = "wez")]
        adaptive: bool,

        /// Confidence level of the reported hit-probability interval: 90, 95, or 99 (default
        /// 95). Applies both to the fixed-count Wilson companion line/JSON key shown alongside
        /// the estimate and, under --adaptive, to the confidence sequence's stopping rule and
        /// interval. Has NO effect with --wez (the sweep reports no interval at all): passing
        /// it there prints a one-line stderr note and does not change the exit status.
        #[arg(long, value_parser = parse_confidence_level)]
        confidence: Option<ConfidenceLevel>,

        /// --adaptive: stop once the confidence interval's half-width is at or below this many
        /// probability units (e.g. 0.02 = the hit probability is known to within about +-2
        /// percentage points).
        #[arg(
            long,
            default_value = "0.02",
            requires = "adaptive",
            allow_hyphen_values = true,
            value_parser = parse_positive_half_width
        )]
        target_ci_half_width: f64,

        /// --adaptive: never stop before this many trials, even if the interval is already
        /// tight (guards against an early run of all-hits or all-misses looking falsely
        /// precise). Default 1000, matching --num-sims's own legacy default.
        #[arg(long, requires = "adaptive")]
        min_samples: Option<u64>,

        /// --adaptive: never run more than this many trials, even if the interval is still
        /// wide. Bounds the wall time of an unreachable --target-ci-half-width; hitting it is
        /// an honest, successful run (exit 0), not an error. Default 100000.
        #[arg(
            long,
            requires = "adaptive",
            value_parser = clap::value_parser!(u64).range(1..)
        )]
        max_samples: Option<u64>,

        /// --adaptive: how many trials to run between convergence checks. Smaller batches can
        /// stop sooner; larger batches check less often.
        #[arg(
            long,
            default_value = "500",
            requires = "adaptive",
            value_parser = clap::value_parser!(u64).range(1..)
        )]
        mc_batch_size: u64,

        /// Seed the Monte Carlo RNG for reproducible output (both the default fixed-count path
        /// and --adaptive). Without it, each run draws fresh randomness and is not reproducible
        /// run to run. Has NO effect with --wez (the sweep seeds itself internally): passing it
        /// there prints a one-line stderr note and does not change the exit status.
        #[arg(long)]
        seed: Option<u64>,

        /// Output format: summary (default), full/json, or statistics (not available with
        /// --adaptive).
        #[arg(short = 'o', long, default_value = "summary")]
        output: MonteCarloOutput,
    },

    /// Calculate zero angle for a target
    Zero {
        /// Initial velocity (fps for imperial, m/s for metric)
        #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
        velocity: f64,

        /// Ballistic coefficient
        #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
        bc: f64,

        /// Which standard atmosphere --bc is referenced to (MBA-1365). Most published
        /// BCs (and this engine's own retardation math) assume ICAO; some vendors
        /// (notably Sierra, Hornady, and Barnes for many bullets) instead publish BCs
        /// referenced to the older, denser Army Standard Metro atmosphere, which
        /// under-predicts drag by about 1.8% if fed in unconverted. Has no effect
        /// together with --drag-table.
        #[arg(long, value_enum, default_value = "icao")]
        bc_reference: BcReferenceStandard,

        /// Mass (grains for imperial, grams for metric)
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: f64,

        /// Diameter (inches for imperial, mm for metric)
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: f64,

        /// Drag model (G1, G2, G5, G6, G7, G8, GI, GS, RA4). Added for MBA-1419: the zero
        /// command lacked this while every sibling — including the browser terminal's own
        /// zero — had it, so a G7 BC silently ran against the G1 reference. Default g1
        /// preserves existing behavior byte-for-byte.
        #[arg(long, default_value = "g1")]
        drag_model: DragModel,

        /// Target distance (yards for imperial, meters for metric). Required unless
        /// --from-angle is given.
        #[arg(
            long,
            required_unless_present = "from_angle",
            conflicts_with = "from_angle"
        )]
        target_distance: Option<f64>,

        /// Given a previously solved/stored bore angle in DEGREES above bore-horizontal (e.g.
        /// a `zero_angle_degrees` value this same command already printed, or `trajectory`'s
        /// auto-zero echo), find the zero RANGE(S) it produces under these conditions (MBA-1402;
        /// Tier 2 review C2). A bore angle generally implies TWO zero distances -- the classic
        /// 25/300-yard battle-zero relationship is exactly this, one angle with a near zero
        /// (~25 yd) and a far zero (~300 yd) -- so this reports BOTH crossings it finds rather
        /// than picking one; it is NOT a single-valued inverse of --target-distance (that
        /// forward solve's chosen root depends on the distance you asked it to hit). Hornady
        /// and Kestrel 4DOF treat the zero angle as the portable quantity: capture it once,
        /// then recover the range(s) it implies later, independent of the day it was
        /// originally solved. Conflicts with --target-distance.
        #[arg(
            long,
            value_name = "DEGREES",
            required_unless_present = "target_distance",
            conflicts_with = "target_distance",
            allow_hyphen_values = true
        )]
        from_angle: Option<f64>,

        /// Target height (yards for imperial, meters for metric)
        #[arg(long, default_value = "0.0", allow_hyphen_values = true)]
        target_height: f64,

        /// Sight height above bore (inches for imperial, mm for metric)
        #[arg(long)]
        sight_height: Option<f64>,

        /// Temperature (Fahrenheit or Celsius based on --units; default 59 F / 15 C)
        #[arg(long)]
        temperature: Option<f64>,

        /// Pressure (inHg or hPa based on --units; default 29.92 inHg / 1013.25 hPa)
        #[arg(long)]
        pressure: Option<f64>,

        /// Whether --pressure is absolute station pressure (default) or a sea-level-corrected
        /// altimeter setting (QNH / weather-report "barometer" value, MBA-1397). See
        /// `trajectory --pressure-type` for the full explanation.
        #[arg(long, value_enum, default_value = "absolute")]
        pressure_type: PressureReferenceMode,

        /// Humidity (0-100%)
        #[arg(long, default_value = "50.0", value_parser = f64_range(0.0, 100.0))]
        humidity: f64,

        /// Altitude (feet or meters based on --units)
        #[arg(long, default_value = "0.0")]
        altitude: f64,

        /// Density altitude (feet imperial / meters metric; MBA-1422): the single-value
        /// atmosphere entry mode, matching `trajectory --density-altitude`. When given it
        /// SUPERSEDES `--altitude` and `--pressure`/`--pressure-type` entirely — an ISA-
        /// equivalent station altitude and pressure are back-solved from it. An explicit
        /// `--temperature` still wins over the ISA temperature at that density altitude, and
        /// the pressure is re-solved so the density altitude is reproduced exactly.
        #[arg(long, allow_hyphen_values = true, value_parser = f64_range(-5000.0, 120000.0))]
        density_altitude: Option<f64>,

        /// Path to a custom drag deck: CSV `mach,cd` per line, or a vendor `.drg` file (by
        /// extension). Replaces the G-model + BC for drag;
        /// bc_value is ignored when set. Mach-keyed; out-of-range Mach holds the nearest tabulated Cd.
        #[arg(long, value_name = "FILE")]
        drag_table: Option<std::path::PathBuf>,

        /// Whole-curve drag scale for a custom drag table (Hornady AFF / AB CDF style; 1.0 =
        /// neutral, typical truing range 0.90-1.10). Requires --drag-table.
        #[arg(long, value_name = "FACTOR")]
        cd_scale: Option<f64>,

        /// Elevation-axis scope tracking correction factor from a tall-target test
        /// (MBA-1358): actual measured travel / dialed travel. The MOA/mrad dial-unit
        /// outputs (zero angle, sight adjustment) are DIVIDED by it; the degrees echo
        /// is a bore angle and is not touched. Strictly between 0.5 and 1.5. Derive it
        /// with `ballistics tall-target`
        #[arg(long, value_name = "FACTOR")]
        elevation_cf: Option<f64>,

        /// Output format
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Estimate BC from trajectory data (drop and/or velocity), for G1, G7, or both.
    ///
    /// MBA-1365: the fitted BC this command reports is always ICAO-referenced (it is
    /// searched under this engine's own ICAO-calibrated retardation math) — do not pass
    /// it back in with `--bc-reference army-standard-metro` on `trajectory`/`monte-carlo`/
    /// `zero`/`profile save`, or it will be double-converted.
    EstimateBC {
        /// Initial velocity (fps for imperial, m/s for metric)
        #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
        velocity: f64,

        /// Mass (grains for imperial, grams for metric)
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: f64,

        /// Diameter (inches for imperial, mm for metric)
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: f64,

        /// Drop data: "dist,drop;dist,drop;..." (distance in yd/m, drop in in/m).
        /// n-point alternative to --distance1/--drop1/--distance2/--drop2.
        #[arg(long)]
        data: Option<String>,

        /// Velocity data: "dist,vel;dist,vel;..." (distance in yd/m, velocity in fps/mps).
        /// Enables the velocity-retention fit variants.
        #[arg(long)]
        velocity_data: Option<String>,

        /// Drag model to estimate: g1, g7, both, or any single family (g2/g5/g6/g8/gi/gs/ra4)
        #[arg(long, default_value = "both")]
        drag_model: String,

        /// Zero range of the drop data, in yd/m (dope cards are zeroed). Given → drop is
        /// fit as drop-below-line-of-sight from a rifle zeroed here. Omitted → drop is
        /// treated as bore-referenced (flat-fire drop below the extended bore axis).
        #[arg(long)]
        zero_range: Option<f64>,

        /// Sight height above bore (inches/mm) for the zeroed drop fit [default 2 in / 50 mm]
        #[arg(long)]
        sight_height: Option<f64>,

        /// Air temperature the data was measured at (°F imperial / °C metric) [default 59 F / 15 C]
        #[arg(long)]
        temperature: Option<f64>,

        /// Barometric pressure the data was measured at (inHg imperial / hPa metric) [default 29.92 / 1013.25]
        #[arg(long)]
        pressure: Option<f64>,
        /// How to interpret `--pressure` (MBA-1416): `absolute` (default) is station pressure
        /// at your altitude; `qnh` is a sea-level-corrected altimeter setting — the kind of
        /// value a weather report or METAR gives — and is reduced to station pressure using
        /// `--altitude`. Omitting this is exactly `absolute`, so existing invocations are
        /// unchanged. Same meaning as `trajectory --pressure-type`.
        #[arg(long, value_enum)]
        pressure_type: Option<PressureReferenceMode>,

        /// Relative humidity the data was measured at (percent, 0–100)
        #[arg(long, default_value = "50.0", value_parser = f64_range(0.0, 100.0))]
        humidity: f64,

        /// Altitude the data was measured at (feet imperial / meters metric)
        #[arg(long, default_value = "0.0")]
        altitude: f64,

        /// Distance 1 (yd/m) — legacy 2-point drop input
        #[arg(long)]
        distance1: Option<f64>,

        /// Drop at distance 1 (inches for imperial, meters for metric) — legacy
        #[arg(long, allow_hyphen_values = true)]
        drop1: Option<f64>,

        /// Distance 2 (yd/m) — legacy 2-point drop input
        #[arg(long)]
        distance2: Option<f64>,

        /// Drop at distance 2 (inches for imperial, meters for metric) — legacy
        #[arg(long, allow_hyphen_values = true)]
        drop2: Option<f64>,

        /// Output format
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Convert a published ballistic coefficient between the G1 and G7 drag families
    ///
    /// Scalar mode converts --bc at exactly one stated --mach or --velocity. Banded mode
    /// converts each repeated --bc-segment and also reports the best single-BC G1/G7 fit.
    /// Banded velocities, --velocity, and --speed-of-sound follow the global --units setting.
    BcConvert {
        /// Drag family the supplied BC value(s) use
        #[arg(long, value_enum, ignore_case = true)]
        source_model: BcConvertModelArg,

        /// Drag family to convert the BC value(s) into
        #[arg(long, value_enum, ignore_case = true)]
        target_model: BcConvertModelArg,

        /// Scalar ballistic coefficient; conflicts with --bc-segment
        #[arg(
            short = 'b',
            long,
            value_parser = f64_range(0.001, 2.0),
            conflicts_with = "bc_segment",
            required_unless_present = "bc_segment"
        )]
        bc: Option<f64>,

        /// Mach number at which to convert a scalar BC; conflicts with --velocity
        #[arg(
            long,
            value_parser = f64_range(0.0, 5.0),
            conflicts_with_all = ["velocity", "bc_segment", "speed_of_sound"]
        )]
        mach: Option<f64>,

        /// Velocity at which to convert a scalar BC (fps imperial, m/s metric)
        #[arg(
            long,
            value_parser = f64_range(0.001, 6000.0),
            conflicts_with_all = ["mach", "bc_segment"]
        )]
        velocity: Option<f64>,

        /// Velocity-banded BC as VMIN:VMAX:BC; repeat for array conversion and family fitting
        #[arg(
            long = "bc-segment",
            value_name = "VMIN:VMAX:BC",
            action = clap::ArgAction::Append,
            conflicts_with_all = ["bc", "mach", "velocity"],
            required_unless_present = "bc"
        )]
        bc_segment: Vec<String>,

        /// Speed of sound in the current velocity units [default: ICAO standard, 1116.437 fps / 340.29 m/s]
        #[arg(
            long,
            value_parser = f64_range(0.001, 6000.0),
            conflicts_with = "mach"
        )]
        speed_of_sound: Option<f64>,

        /// Output format: table (default), csv, or json
        #[arg(short = 'o', long, default_value = "table", ignore_case = true)]
        output: BcConversionOutputFormat,
    },

    /// Generate BC segments for velocity-dependent BC
    GenerateBCSegments {
        /// Base ballistic coefficient
        #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
        bc: f64,

        /// Projectile mass (grains for imperial, grams for metric)
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: f64,

        /// Projectile diameter (inches for imperial, mm for metric)
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: f64,

        /// Bullet model/name (e.g., "SMK", "ELD-M", "VLD")
        #[arg(long, default_value = "")]
        model: String,

        /// Drag model (G1 or G7)
        #[arg(long, default_value = "G1")]
        drag_model: String,

        /// Output format
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Calculate effective muzzle velocity from observed drop
    TrueVelocity {
        /// Measured drop at the target range. Unit is MIL by default; in
        /// multi-observation mode (see --observed) it follows --drop-unit and
        /// counts as the first observation.
        #[arg(long)]
        measured_drop: f64,

        /// Range at which drop was measured (yards for imperial, meters for metric)
        #[arg(long)]
        range: f64,

        /// Additional observed impact "RANGE:DROP" for joint MV+BC calibration
        /// (MBA-1316). Repeatable. RANGE follows --units (yd/m); DROP follows
        /// --drop-unit. With >=1 --observed the command fits muzzle velocity and
        /// (when the observations constrain it) ballistic coefficient jointly via
        /// the real forward model. With zero --observed it behaves exactly as the
        /// classic single-observation velocity truing.
        #[arg(long = "observed", value_name = "RANGE:DROP", action = clap::ArgAction::Append)]
        observed: Vec<String>,

        /// Known one-standard-deviation error for an impact reading, in
        /// --drop-unit. Supplying this enables uncertainty-aware joint MV/BC
        /// truing; an optional third field in --observed (RANGE:DROP:SIGMA)
        /// overrides it for that observation.
        #[arg(long, value_name = "SIGMA")]
        observation_sigma: Option<f64>,

        /// Explicit normal prior for muzzle velocity, MEAN:SIGMA. Values follow
        /// --units (fps for imperial, m/s for metric). Never inferred from
        /// --chrono-velocity.
        #[arg(long, value_name = "MEAN:SIGMA")]
        mv_prior: Option<String>,

        /// Explicit normal prior for the scalar ballistic coefficient,
        /// MEAN:SIGMA (dimensionless).
        #[arg(long, value_name = "MEAN:SIGMA")]
        bc_prior: Option<String>,

        /// Range at which to report a propagated model-drop interval. Repeatable;
        /// follows --units (yards/meters).
        #[arg(long, value_name = "RANGE", action = clap::ArgAction::Append)]
        predict_range: Vec<f64>,

        /// Optional one-standard-deviation error for a future impact reading, in
        /// --drop-unit. Adds a future-observation band alongside the latent model
        /// band at every --predict-range.
        #[arg(long, value_name = "SIGMA")]
        prediction_sigma: Option<f64>,

        /// Unit for --measured-drop and every --observed drop in multi-observation
        /// mode. Ignored in single-observation mode (which is always MIL).
        #[arg(long = "drop-unit", default_value = "mil")]
        drop_unit: DropUnit,

        /// Elevation-axis scope tracking correction factor from a tall-target test
        /// (MBA-1358): actual measured travel / dialed travel. DIALED observations
        /// (mil/moa drops; single-observation mode is always mil) are MULTIPLIED by it
        /// before the fit (scope-dial units -> true angular), so scope tracking error
        /// is not baked into the trued MV/BC; dial-unit report values are shown back
        /// in scope units (÷CF). Linear 'in' drops are tape measurements and are never
        /// scaled. Strictly between 0.5 and 1.5
        #[arg(long, value_name = "FACTOR")]
        elevation_cf: Option<f64>,

        /// Ballistic coefficient
        #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
        bc: f64,

        /// Drag model (G1, G7)
        #[arg(long, default_value = "g1")]
        drag_model: DragModelArg,

        /// Bullet weight (grains for imperial, grams for metric)
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: f64,

        /// Bullet diameter/caliber (inches for imperial, mm for metric)
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: f64,

        /// Chronograph velocity for comparison (fps for imperial, m/s for metric)
        #[arg(long)]
        chrono_velocity: Option<f64>,

        /// Distance downrange from the muzzle at which --chrono-velocity was measured
        /// (feet for imperial, meters for metric). Most chronographs read 10-15 ft
        /// (or 25 m) downrange rather than at the muzzle -- JBM ("Distance to
        /// Chronograph"), Lapua, Ballistic AE, ColdBore, Remington Shoot!, and
        /// Hornady all correct for this. A nonzero value here back-solves the
        /// measured reading to a true muzzle velocity via secant iteration on the
        /// real forward trajectory model, using the SAME --bc/--drag-model/
        /// atmosphere as the rest of this command (McCoy, *Modern Exterior
        /// Ballistics*; JBM's published calculator). Zero or absent is an exact
        /// no-op -- the measured value is used as-is. Requires --chrono-velocity.
        /// Valid range: 1-98 ft / 0.3-30 m downrange (100 ft is OUT of range --
        /// see MIN/MAX_CHRONO_DISTANCE_M in truing.rs); outside that band the
        /// command errors instead of silently producing a bad muzzle velocity.
        #[arg(long, value_name = "DISTANCE")]
        chrono_distance: Option<f64>,

        /// Zero distance (yards for imperial, meters for metric)
        #[arg(long, default_value = "100.0")]
        zero_distance: f64,

        /// Sight height above bore (inches for imperial, mm for metric) [default: 2 in / 50 mm]
        #[arg(long)]
        sight_height: Option<f64>,

        /// Temperature (Fahrenheit for imperial, Celsius for metric; default 59 F / 15 C)
        #[arg(long)]
        temperature: Option<f64>,

        /// Pressure (inHg for imperial, hPa for metric; default 29.92 inHg / 1013.25 hPa)
        #[arg(long)]
        pressure: Option<f64>,
        /// How to interpret `--pressure` (MBA-1416): `absolute` (default) is station pressure
        /// at your altitude; `qnh` is a sea-level-corrected altimeter setting — the kind of
        /// value a weather report or METAR gives — and is reduced to station pressure using
        /// `--altitude`. Omitting this is exactly `absolute`, so existing invocations are
        /// unchanged. Same meaning as `trajectory --pressure-type`.
        #[arg(long, value_enum)]
        pressure_type: Option<PressureReferenceMode>,

        /// Humidity (0-100%)
        #[arg(long, default_value = "50.0", value_parser = f64_range(0.0, 100.0))]
        humidity: f64,

        /// Altitude (feet for imperial, meters for metric)
        #[arg(long, default_value = "0.0")]
        altitude: f64,

        /// Unit system
        #[arg(long, default_value = "imperial")]
        units: UnitSystem,

        /// Directory containing caliber-specific BC5D tables (e.g., bc5d_308.bin)
        #[arg(
            long,
            value_name = "DIR",
            help = "Use caliber-specific 5D BC correction tables"
        )]
        bc_table_dir: Option<PathBuf>,

        /// Enable auto-download of BC5D correction tables when needed
        #[cfg(feature = "online")]
        #[arg(long, help = "Auto-download BC5D tables when needed")]
        bc_table_auto: bool,

        /// Base URL for BC5D table downloads
        #[cfg(feature = "online")]
        #[arg(
            long,
            default_value = "https://ballistics.tools/downloads/bc5d",
            help = "Base URL for BC5D table downloads"
        )]
        bc_table_url: String,

        /// Force offline mode (use local calculation, skip API)
        #[arg(long, help = "Force offline mode using local calculation")]
        offline: bool,

        /// Fall back to local calculation if API fails
        #[cfg(feature = "online")]
        #[arg(long, help = "Use local calculation if API fails")]
        offline_fallback: bool,

        /// API endpoint URL
        #[cfg(feature = "online")]
        #[arg(long, default_value = "https://api.ballistics.7.62x51mm.sh")]
        api_url: String,

        /// API request timeout in seconds
        #[cfg(feature = "online")]
        #[arg(long, default_value = "10")]
        api_timeout: u64,

        /// Bullet length in inches (for BC table lookup; estimated from diameter if not provided)
        #[arg(long)]
        bullet_length: Option<f64>,

        /// Output format
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Back-solve the effective crosswind from an observed horizontal miss (wind-call truing)
    ///
    /// SIGN CONVENTIONS (all of them, in one place):
    ///   --miss             positive = the group landed RIGHT of the aim point.
    ///   solved wind        positive = wind FROM the shooter's LEFT (9 o'clock), which
    ///                      pushes impacts RIGHT; negative = FROM the right, pushing left.
    ///                      The sign follows the deflection it produces. This is the
    ///                      engine's wind-FROM convention (0 = headwind, PI/2 = from the
    ///                      right), as established by the 0.19.0 wind-direction sign fix.
    ///   --twist-right      a right-hand twist drifts RIGHT, left-hand drifts LEFT.
    ///   --shot-direction   compass bearing fired ALONG, 0 = North, 90 = East.
    ///
    /// A horizontal miss is not purely wind. --twist-rate is REQUIRED so gyroscopic spin
    /// drift is modelled and not mistaken for wind; --latitude with --shot-direction adds
    /// Coriolis. Anything the model has no data for stays absorbed in the solved wind, and
    /// the report says which effects those were. Fully offline: no network, no API.
    ///
    /// --miss values are LINEAR inches measured off the target, not dial readings, so scope
    /// tracking correction factors (--elevation-cf / --windage-cf) do NOT apply to them and
    /// this command deliberately has none.
    // The sign table above only reads as a table if clap keeps the line breaks; without
    // this it reflows into one dense paragraph.
    #[command(verbatim_doc_comment)]
    TrueWind {
        /// Observed horizontal miss "RANGE:RIGHT", or "RANGE:RIGHT:SIGMA". Repeatable — each is solved
        /// separately and the report adds the combined answer. RANGE follows --units
        /// (yards imperial / meters metric); RIGHT and SIGMA are LINEAR INCHES in both
        /// unit systems (a tape measurement off the target, matching --drop-unit in).
        /// RIGHT is signed: positive = impact right of aim. SIGMA is the optional
        /// one-standard-deviation error of that measurement; supply it on every --miss or
        /// on none. Deliberately a separate flag from true-velocity's --observed, whose
        /// RANGE:DROP:SIGMA grammar this would otherwise collide with.
        #[arg(
            long = "miss",
            value_name = "RANGE:RIGHT[:SIGMA]",
            action = clap::ArgAction::Append,
            required = true,
            allow_hyphen_values = true
        )]
        miss: Vec<String>,

        /// Known muzzle velocity (fps for imperial, m/s for metric). Wind is the unknown
        /// here, so velocity is an input — true it up with `true-velocity` first if unsure.
        #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
        velocity: f64,

        /// Ballistic coefficient
        #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
        bc: f64,

        /// Drag model (G1, G7)
        #[arg(long, default_value = "g1")]
        drag_model: DragModelArg,

        /// Bullet weight (grains for imperial, grams for metric)
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: f64,

        /// Bullet diameter/caliber (inches for imperial, mm for metric)
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: f64,

        /// Barrel twist rate (inches/turn for imperial, mm/turn for metric; e.g. imperial
        /// 11 = 1:11"). REQUIRED: spin drift is a lateral effect of the same order as a
        /// light wind at long range, so without it the fit would report spin drift as wind.
        #[arg(long, value_parser = f64_range(0.1, 1000.0))]
        twist_rate: f64,

        /// Twist hand: `--twist-right` or `--twist-right true` = right-hand (default);
        /// `--twist-right false` = left-hand
        #[arg(
            long,
            num_args = 0..=1,
            default_value_t = true,
            default_missing_value = "true",
            action = clap::ArgAction::Set
        )]
        twist_right: bool,

        /// Firing latitude (degrees, -90 to 90). With --shot-direction this models
        /// Coriolis so it is subtracted from the miss instead of read as wind.
        #[arg(long, value_parser = f64_range(-90.0, 90.0), allow_hyphen_values = true)]
        latitude: Option<f64>,

        /// Shot direction/azimuth (degrees, 0=North, 90=East). Pairs with --latitude.
        #[arg(long, allow_hyphen_values = true)]
        shot_direction: Option<f64>,

        /// The wind you CALLED (mph for imperial, m/s for metric), same signed convention
        /// as the solved value. Adds a wind-call correction factor (solved / called) to
        /// the report: >1 means you under-call the wind, <1 that you over-call it, and a
        /// negative factor means you called the wrong side.
        #[arg(long, value_name = "SPEED", allow_hyphen_values = true)]
        called_wind: Option<f64>,

        /// Zero distance (yards for imperial, meters for metric)
        #[arg(long, default_value = "100.0")]
        zero_distance: f64,

        /// Sight height above bore (inches for imperial, mm for metric) [default: 2 in / 50 mm]
        #[arg(long)]
        sight_height: Option<f64>,

        /// Temperature (Fahrenheit for imperial, Celsius for metric; default 59 F / 15 C)
        #[arg(long, allow_hyphen_values = true)]
        temperature: Option<f64>,

        /// Pressure (inHg for imperial, hPa for metric; default 29.92 inHg / 1013.25 hPa)
        #[arg(long)]
        pressure: Option<f64>,

        /// How to interpret `--pressure` (MBA-1416): `absolute` (default) is station
        /// pressure at your altitude; `qnh` is a sea-level-corrected altimeter setting,
        /// reduced to station pressure using `--altitude`.
        #[arg(long, value_enum)]
        pressure_type: Option<PressureReferenceMode>,

        /// Humidity (0-100%)
        #[arg(long, default_value = "50.0", value_parser = f64_range(0.0, 100.0))]
        humidity: f64,

        /// Altitude (feet for imperial, meters for metric)
        #[arg(long, default_value = "0.0", allow_hyphen_values = true)]
        altitude: f64,

        /// Unit system
        #[arg(long, default_value = "imperial")]
        units: UnitSystem,

        /// Output format
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Recommend target ranges for an identifiable MV + BC truing experiment
    PlanTruing {
        /// Load nominal load, rifle, and atmosphere values from a saved profile.
        /// Explicit flags override profile values.
        #[arg(long, value_name = "NAME")]
        profile: Option<String>,

        /// Nominal muzzle velocity (fps or m/s based on global --units)
        #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
        velocity: Option<f64>,

        /// Nominal scalar ballistic coefficient
        #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
        bc: Option<f64>,

        /// Scalar drag model (G1 or G7)
        #[arg(long)]
        drag_model: Option<DragModelArg>,

        /// Bullet weight (grains or grams based on global --units)
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: Option<f64>,

        /// Bullet diameter (inches or millimeters based on global --units)
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: Option<f64>,

        /// Comma-separated available target ranges in global --units
        #[arg(
            long,
            value_name = "R1,R2,...",
            value_delimiter = ',',
            num_args = 1..,
            conflicts_with = "range_grid",
            required_unless_present = "range_grid"
        )]
        candidate_ranges: Vec<f64>,

        /// Explicit candidate grid START:END:STEP in global --units
        #[arg(
            long,
            value_name = "START:END:STEP",
            conflicts_with = "candidate_ranges",
            required_unless_present = "candidate_ranges"
        )]
        range_grid: Option<String>,

        /// Number of impact observations to collect
        #[arg(long, default_value_t = 3)]
        observation_count: usize,

        /// Required separation between selected target ranges in global --units
        #[arg(long, default_value_t = 0.0, value_parser = f64_range(0.0, 100000.0))]
        minimum_separation: f64,

        /// Assumed independent one-standard-deviation impact-reading error in
        /// --drop-unit
        #[arg(long, value_parser = f64_range(f64::MIN_POSITIVE, 1000000.0))]
        measurement_resolution: f64,

        /// Unit used for the assumed impact-reading error and predicted drop
        #[arg(long, default_value = "mil")]
        drop_unit: DropUnit,

        /// Zero distance in global --units
        #[arg(long)]
        zero_distance: Option<f64>,

        /// Select a named zero set from the saved profile (MBA-1360, requires --profile).
        /// Only the set's zero_distance participates here (an explicit --zero-distance
        /// still wins); the set's dial corrections do not apply to a truing plan.
        /// Unknown names are a hard error listing the available sets.
        #[arg(long, value_name = "NAME")]
        zero_set: Option<String>,

        /// Sight height (inches or millimeters based on global --units)
        #[arg(long)]
        sight_height: Option<f64>,

        /// Temperature (Fahrenheit or Celsius based on global --units)
        #[arg(long)]
        temperature: Option<f64>,

        /// Pressure (inHg or hPa based on global --units)
        #[arg(long)]
        pressure: Option<f64>,
        /// How to interpret `--pressure` (MBA-1416): `absolute` (default) is station pressure
        /// at your altitude; `qnh` is a sea-level-corrected altimeter setting — the kind of
        /// value a weather report or METAR gives — and is reduced to station pressure using
        /// `--altitude`. Omitting this is exactly `absolute`, so existing invocations are
        /// unchanged. Same meaning as `trajectory --pressure-type`.
        #[arg(long, value_enum)]
        pressure_type: Option<PressureReferenceMode>,

        /// Relative humidity (0-100 percent)
        #[arg(long, value_parser = f64_range(0.0, 100.0))]
        humidity: Option<f64>,

        /// Altitude (feet or meters based on global --units)
        #[arg(long)]
        altitude: Option<f64>,

        /// Output format
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Compute a scope tracking correction factor from a tall-target test (MBA-1358):
    /// CF = actual measured travel / dialed travel. Pure arithmetic — no trajectory
    /// solve. Feed the result to --elevation-cf/--windage-cf or store it on a profile
    /// (elevation_cf/windage_cf).
    TallTarget {
        /// Dialed travel in --unit (e.g. 10 for a 10 mil tall-target test)
        #[arg(long, value_name = "DIAL")]
        dialed: f64,

        /// Actual measured group travel on the target, inches (imperial) or cm
        /// (metric, with --units metric)
        #[arg(long, value_name = "TRAVEL")]
        measured: f64,

        /// Distance to the tall target, yards (imperial) or meters (metric)
        #[arg(long, value_name = "RANGE")]
        range: f64,

        /// Angular unit the turret was dialed in (mil, moa, smoa, or iphy)
        #[arg(long, value_enum, default_value = "mil")]
        unit: AdjustmentUnit,
    },

    /// Calculate Maximum Point-Blank Range (MPBR)
    Mpbr {
        /// Load parameters from saved profile
        #[arg(long, value_name = "NAME")]
        profile: Option<String>,

        /// Initial velocity (fps or m/s based on --units)
        #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
        velocity: Option<f64>,

        /// Ballistic coefficient
        #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
        bc: Option<f64>,

        /// Mass (grains for imperial, grams for metric)
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: Option<f64>,

        /// Diameter (inches for imperial, mm for metric)
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: Option<f64>,

        /// Drag model (G1, G2, G5, G6, G7, G8, GI, GS, RA4)
        #[arg(long, default_value = "g1")]
        drag_model: DragModel,

        /// Vital zone diameter (inches for imperial, cm for metric)
        #[arg(long, default_value = "8.0")]
        vital_zone: f64,

        /// Sight height above bore (inches for imperial, mm for metric)
        #[arg(long)]
        sight_height: Option<f64>,

        /// Deliberate vertical POI offset AT the zero range (inches imperial / cm metric;
        /// signed; positive = impacts HIGH). Same semantics as `trajectory --zero-poi-up`
        /// (MBA-1359); biases every candidate zero the search solves.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        zero_poi_up: Option<f64>,

        /// Deliberate horizontal POI offset AT the zero range (inches imperial / cm metric;
        /// signed; positive = impacts RIGHT). Same semantics as `trajectory
        /// --zero-poi-right` (MBA-1359).
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        zero_poi_right: Option<f64>,

        /// Lateral sight-to-bore mount offset (inches imperial / mm metric; signed;
        /// positive = sight RIGHT of bore). Same semantics as `trajectory --sight-offset`
        /// (MBA-1396).
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        sight_offset: Option<f64>,

        /// Temperature (Fahrenheit or Celsius based on --units; default 59 F / 15 C)
        #[arg(long)]
        temperature: Option<f64>,

        /// Pressure (inHg or hPa based on --units; default 29.92 inHg / 1013.25 hPa)
        #[arg(long)]
        pressure: Option<f64>,
        /// How to interpret `--pressure` (MBA-1416): `absolute` (default) is station pressure
        /// at your altitude; `qnh` is a sea-level-corrected altimeter setting — the kind of
        /// value a weather report or METAR gives — and is reduced to station pressure using
        /// `--altitude`. Omitting this is exactly `absolute`, so existing invocations are
        /// unchanged. Same meaning as `trajectory --pressure-type`.
        #[arg(long, value_enum)]
        pressure_type: Option<PressureReferenceMode>,

        /// Humidity (0-100%)
        #[arg(long, default_value = "50.0", value_parser = f64_range(0.0, 100.0))]
        humidity: f64,

        /// Altitude (feet or meters based on --units)
        #[arg(long, default_value = "0.0")]
        altitude: f64,

        /// Output format
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Generate come-up (elevation adjustment) table
    ComeUps {
        /// Load parameters from saved profile
        #[arg(long, value_name = "NAME")]
        profile: Option<String>,

        /// Initial velocity (fps or m/s based on --units)
        #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
        velocity: Option<f64>,

        /// Ballistic coefficient
        #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
        bc: Option<f64>,

        /// Mass (grains for imperial, grams for metric)
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: Option<f64>,

        /// Diameter (inches for imperial, mm for metric)
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: Option<f64>,

        /// Drag model (G1, G2, G5, G6, G7, G8, GI, GS, RA4)
        #[arg(long, default_value = "g1")]
        drag_model: DragModel,

        /// Zero distance (yards for imperial, meters for metric)
        #[arg(long)]
        zero_distance: f64,

        /// Select a named zero set from the saved profile (MBA-1360, requires --profile).
        /// Its poi_up_mil is added to the come-up dial values as a constant angular
        /// correction; --zero-distance (required here) always wins over the set's own
        /// zero_distance. Unknown names are a hard error listing the available sets.
        #[arg(long, value_name = "NAME")]
        zero_set: Option<String>,

        /// Start range (yards or meters)
        #[arg(long, default_value = "100.0")]
        start: f64,

        /// End range (yards or meters)
        #[arg(long, default_value = "1200.0")]
        end: f64,

        /// Range step (yards or meters)
        #[arg(long, default_value = "50.0", value_parser = f64_range(0.001, 100000.0))]
        step: f64,

        /// Adjustment unit (mil, moa, smoa, iphy, or clicks). `clicks` requires
        /// --elevation-click-value (or a saved profile's elevation_click) and formats
        /// whole turret clicks instead of an angle.
        #[arg(long, default_value = "mil")]
        adjustment_unit: AdjustmentUnit,

        /// Turret elevation click graduation for `--adjustment-unit clicks`, e.g. 0.1mil or
        /// 0.25moa (falls back to the saved profile's elevation_click when omitted).
        #[arg(long)]
        elevation_click_value: Option<String>,

        /// Turret windage click graduation for `--adjustment-unit clicks` (accepted for parity
        /// with `trajectory`; come-ups has no windage column to apply it to).
        #[arg(long)]
        windage_click_value: Option<String>,

        /// Elevation-axis scope tracking correction factor from a tall-target test
        /// (MBA-1358): actual measured travel / dialed travel (0.95 = under-tracks 5%).
        /// The come-up column's dial-unit values (mil/moa/smoa/iphy/clicks) are DIVIDED
        /// by it — e.g. CF 0.95 turns a 10 mil come-up into 10.53. Strictly between
        /// 0.5 and 1.5; overrides the saved profile's elevation_cf. Derive it with
        /// `ballistics tall-target`
        #[arg(long, value_name = "FACTOR")]
        elevation_cf: Option<f64>,

        /// Sight height above bore (inches for imperial, mm for metric)
        #[arg(long)]
        sight_height: Option<f64>,

        /// Deliberate vertical POI offset AT the zero range (inches imperial / cm metric;
        /// signed; positive = impacts HIGH). Same semantics as `trajectory --zero-poi-up`
        /// (MBA-1359); the come-up table is computed from the biased zero.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        zero_poi_up: Option<f64>,

        /// Deliberate horizontal POI offset AT the zero range (inches imperial / cm metric;
        /// signed; positive = impacts RIGHT). Same semantics as `trajectory
        /// --zero-poi-right` (MBA-1359). Accepted for a consistent flag set; come-ups has
        /// no windage column, so it does not change this table.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        zero_poi_right: Option<f64>,

        /// Lateral sight-to-bore mount offset (inches imperial / mm metric; signed;
        /// positive = sight RIGHT of bore). Same semantics as `trajectory --sight-offset`
        /// (MBA-1396). Accepted for a consistent flag set; the offset is lateral-only, so
        /// it does not change this elevation table.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        sight_offset: Option<f64>,

        /// Temperature (Fahrenheit or Celsius based on --units; default 59 F / 15 C)
        #[arg(long)]
        temperature: Option<f64>,

        /// Pressure (inHg or hPa based on --units; default 29.92 inHg / 1013.25 hPa)
        #[arg(long)]
        pressure: Option<f64>,
        /// How to interpret `--pressure` (MBA-1416): `absolute` (default) is station pressure
        /// at your altitude; `qnh` is a sea-level-corrected altimeter setting — the kind of
        /// value a weather report or METAR gives — and is reduced to station pressure using
        /// `--altitude`. Omitting this is exactly `absolute`, so existing invocations are
        /// unchanged. Same meaning as `trajectory --pressure-type`.
        #[arg(long, value_enum)]
        pressure_type: Option<PressureReferenceMode>,

        /// Humidity (0-100%)
        #[arg(long, default_value = "50.0", value_parser = f64_range(0.0, 100.0))]
        humidity: f64,

        /// Altitude (feet or meters based on --units)
        #[arg(long, default_value = "0.0")]
        altitude: f64,

        /// Wind speed (mph or m/s based on --units)
        #[arg(long, default_value = "0.0")]
        wind_speed: f64,

        /// Wind direction (MBA-1367: degrees or clock position, shared help const)
        #[arg(long, default_value = "0.0", value_parser = parse_wind_direction_arg, help = WIND_DIRECTION_HELP)]
        wind_direction: ParsedWindDirection,

        /// Output format
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Derive a Mach-keyed drop-scale-factor (DSF) point from an observed drop, and save it
    /// to a profile's DSF table (MBA-1357).
    ///
    /// Second stage of Applied Ballistics' two-stage truing workflow: after `true-velocity`
    /// fixes the supersonic muzzle velocity/BC against a chronograph and a supersonic
    /// observed drop (Mach above 1.2), `dsf` records transonic/subsonic drop corrections
    /// one observed range at a time. Solves the saved profile's own trajectory (no other
    /// CLI overrides — everything comes from the profile), predicts the drop at `--range`,
    /// and sets `dsf = observed / predicted` at that range's Mach. Up to 6 points; a new
    /// point within 0.05 Mach of an existing one supersedes it. Rejects a supersonic
    /// observation (Mach above 1.2) outright — that belongs to `true-velocity`, not here.
    Dsf {
        /// Saved profile to solve, calibrate, and write the DSF point back to.
        #[arg(long, value_name = "NAME")]
        saved_profile: String,

        /// Range at which the drop was observed (yards for imperial, meters for metric).
        #[arg(long)]
        range: f64,

        /// Observed drop, suffixed with its unit: mil, moa, or in (e.g. 5.1mil, 17.4moa,
        /// 42.0in). No separator between the number and the unit.
        #[arg(long, value_name = "VALUEUNIT")]
        observed_drop: String,

        /// Select a named zero set from the saved profile (MBA-1360). Only the set's
        /// zero_distance participates here (it feeds the profile solve's zero exactly as
        /// the profile's own zero would); the set's dial corrections never touch a DSF
        /// calibration — the observed drop is a physical impact, not a dial value.
        /// Unknown names are a hard error listing the available sets.
        #[arg(long, value_name = "NAME")]
        zero_set: Option<String>,
    },

    /// Moving-target lead table (hold in the direction of target travel)
    Lead {
        /// Load parameters from saved profile
        #[arg(long, value_name = "NAME")]
        profile: Option<String>,

        /// Initial velocity (fps or m/s based on --units)
        #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
        velocity: Option<f64>,

        /// Ballistic coefficient
        #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
        bc: Option<f64>,

        /// Mass (grains for imperial, grams for metric)
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: Option<f64>,

        /// Diameter (inches for imperial, mm for metric)
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: Option<f64>,

        /// Drag model (G1, G2, G5, G6, G7, G8, GI, GS, RA4)
        #[arg(long, default_value = "g1")]
        drag_model: DragModel,

        /// Sight height above bore (inches for imperial, mm for metric)
        #[arg(long)]
        sight_height: Option<f64>,

        /// Temperature (Fahrenheit or Celsius based on --units; default 59 F / 15 C)
        #[arg(long)]
        temperature: Option<f64>,

        /// Pressure (inHg or hPa based on --units; default 29.92 inHg / 1013.25 hPa)
        #[arg(long)]
        pressure: Option<f64>,
        /// How to interpret `--pressure` (MBA-1416): `absolute` (default) is station pressure
        /// at your altitude; `qnh` is a sea-level-corrected altimeter setting — the kind of
        /// value a weather report or METAR gives — and is reduced to station pressure using
        /// `--altitude`. Omitting this is exactly `absolute`, so existing invocations are
        /// unchanged. Same meaning as `trajectory --pressure-type`.
        #[arg(long, value_enum)]
        pressure_type: Option<PressureReferenceMode>,

        /// Humidity (0-100%)
        #[arg(long, default_value = "50.0", value_parser = f64_range(0.0, 100.0))]
        humidity: f64,

        /// Altitude (feet or meters based on --units)
        #[arg(long, default_value = "0.0")]
        altitude: f64,

        /// Wind speed (mph or m/s based on --units)
        #[arg(long, default_value = "0.0")]
        wind_speed: f64,

        /// Wind direction (MBA-1367: degrees or clock position, shared help const)
        #[arg(long, default_value = "0.0", value_parser = parse_wind_direction_arg, help = WIND_DIRECTION_HELP)]
        wind_direction: ParsedWindDirection,

        /// Enable powder temperature sensitivity
        #[arg(long)]
        use_powder_sensitivity: bool,

        /// Powder temperature sensitivity (fps/°F imperial, m/s/°C metric).
        /// Defaults to 1.0 fps/°F (0.54864 m/s/°C).
        #[arg(long)]
        powder_temp_sensitivity: Option<f64>,

        /// Powder temperature (°F/°C). With --powder-temp-curve, this is the powder
        /// temperature the curve is interpolated at to resolve muzzle velocity (defaults
        /// to --temperature when omitted, i.e. powder assumed at air temperature). With
        /// --powder-temp-sensitivity (linear model), it is the reference temperature the
        /// stated velocity was measured at (defaults to the 70°F equivalent).
        #[arg(long)]
        powder_temp: Option<f64>,

        /// Measured powder-temperature -> muzzle-velocity curve as comma-separated
        /// TEMP:VELOCITY points, e.g. "40:2620,70:2700,100:2760" (temps in F/C,
        /// velocities in fps / m·s⁻¹ per --units). The muzzle velocity is interpolated
        /// from this table at the powder temperature (--powder-temp, or --temperature if
        /// unset; clamped at the endpoints, no extrapolation). Data-driven, non-linear
        /// alternative that OVERRIDES --powder-temp-sensitivity when supplied.
        #[arg(long = "powder-temp-curve", value_name = "TEMP:VEL,...")]
        powder_temp_curve: Option<String>,

        /// Target speed (mph for imperial, m/s for metric)
        #[arg(long, value_parser = f64_range(0.0, 300.0))]
        target_speed: f64,

        /// Direction of target travel relative to the line of sight, degrees:
        /// 0 = directly away, 90 = crossing left-to-right, 180 = directly toward,
        /// 270 = crossing right-to-left
        #[arg(long, default_value = "90.0")]
        target_angle: f64,

        /// Target length for body-length holds (inches for imperial, mm for metric)
        #[arg(long, value_parser = f64_range(0.001, 10000.0))]
        target_length: Option<f64>,

        /// Start range (yards or meters)
        #[arg(long, default_value = "100.0")]
        start: f64,

        /// End range (yards or meters)
        #[arg(long, default_value = "600.0")]
        end: f64,

        /// Range step (yards or meters)
        #[arg(long, default_value = "100.0", value_parser = f64_range(0.001, 100000.0))]
        step: f64,

        /// Adjustment unit (mil, moa, smoa, iphy, or clicks). `clicks` requires
        /// --windage-click-value (or a saved profile's windage_click/elevation_click) and
        /// formats whole turret clicks instead of an angle (MBA-1410: lead's single
        /// column is windage-like, so it resolves through the windage graduation).
        #[arg(long, default_value = "mil")]
        adjustment_unit: AdjustmentUnit,

        /// Turret click graduation for `--adjustment-unit clicks`, e.g. 0.1mil or 0.25moa
        /// (falls back to the saved profile's windage_click, then its elevation_click,
        /// when omitted).
        #[arg(long)]
        windage_click_value: Option<String>,

        /// Windage-axis scope tracking correction factor from a tall-target test
        /// (MBA-1358): actual measured travel / dialed travel. Mover lead is a dialed
        /// quantity, so the lead's dial-unit outputs (mil/moa/smoa/iphy/clicks) are
        /// DIVIDED by it; the linear lead distance is not. Strictly between 0.5 and
        /// 1.5; overrides the saved profile's windage_cf
        #[arg(long, value_name = "FACTOR")]
        windage_cf: Option<f64>,

        /// Output format
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Resolve the powder-temperature-adjusted muzzle velocity without running a
    /// trajectory (MBA-737): the linear sensitivity model or a measured
    /// temperature->velocity curve, with an optional sweep table across temperatures.
    Powder {
        /// Nominal muzzle velocity (fps or m/s based on --units) at the reference
        /// temperature. Required for the linear model. With --powder-temp-curve the
        /// curve supplies the velocity and this only anchors the reported shift.
        #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
        velocity: Option<f64>,

        /// Shot-day air temperature (°F/°C based on --units). Drives the linear
        /// model's delta from the reference temperature; with --powder-temp-curve it
        /// is the curve's lookup temperature when --powder-temp is not given (powder
        /// assumed at air temperature).
        #[arg(long)]
        temperature: Option<f64>,

        /// Powder temperature sensitivity (fps/°F imperial, m/s/°C metric).
        /// Defaults to 1.0 fps/°F (0.54864 m/s/°C).
        #[arg(long)]
        powder_temp_sensitivity: Option<f64>,

        /// Powder temperature (°F/°C). With --powder-temp-curve, this is the powder
        /// temperature the curve is interpolated at to resolve muzzle velocity (defaults
        /// to --temperature when omitted, i.e. powder assumed at air temperature). With
        /// the linear model, it is the reference temperature the stated velocity was
        /// measured at (defaults to the 70°F equivalent).
        #[arg(long)]
        powder_temp: Option<f64>,

        /// Measured powder-temperature -> muzzle-velocity curve as comma-separated
        /// TEMP:VELOCITY points, e.g. "40:2620,70:2700,100:2760" (temps in F/C,
        /// velocities in fps / m·s⁻¹ per --units). The muzzle velocity is interpolated
        /// from this table at the powder temperature (--powder-temp, or --temperature if
        /// unset; clamped at the endpoints, no extrapolation). Data-driven, non-linear
        /// alternative that OVERRIDES --powder-temp-sensitivity when supplied.
        #[arg(long = "powder-temp-curve", value_name = "TEMP:VEL,...")]
        powder_temp_curve: Option<String>,

        /// Print a velocity table across a temperature range instead of a single
        /// resolution: START:END:STEP in °F (imperial) or °C (metric), e.g.
        /// "20:110:10". With a curve, the sweep temperatures are powder temperatures.
        #[arg(long, value_name = "START:END:STEP")]
        sweep: Option<String>,

        /// Bullet mass (grains imperial / grams metric). When given, muzzle energy
        /// (ft·lb / J) is reported alongside each resolved velocity.
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: Option<f64>,

        /// Output format (table, json, or csv)
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Free recoil energy, velocity, and impulse from a SAAMI momentum balance
    /// (MBA-1372): ejecta (bullet) + propellant gas recoil against the firearm.
    /// See CLI_USAGE.md for the gas-velocity convention this command defaults to.
    Recoil {
        /// Bullet weight (grains for imperial, grams for metric)
        #[arg(short = 'b', long, value_parser = f64_range(0.1, 2000.0))]
        bullet_weight: f64,

        /// Powder charge weight (grains for imperial, grams for metric)
        #[arg(short = 'c', long, value_parser = f64_range(0.0, 1000.0))]
        charge_weight: f64,

        /// Muzzle velocity (fps or m/s based on --units)
        #[arg(short = 'v', long, value_parser = f64_range(1.0, 6000.0))]
        velocity: f64,

        /// Firearm weight, including all attachments such as scopes and suppressors
        /// (pounds for imperial, kilograms for metric)
        #[arg(short = 'f', long, value_parser = f64_range(0.1, 500.0))]
        firearm_weight: f64,

        /// Firearm type, selecting SAAMI's propellant-gas-velocity multiplier f
        /// (gas velocity = f * muzzle velocity): rifle (f=1.75), pistol (f=1.50),
        /// shotgun-average (f=1.50), shotgun-long (f=1.25). Ignored if
        /// --gas-velocity-factor or --gas-velocity is given.
        #[arg(long, default_value = "rifle")]
        firearm_type: RecoilFirearmTypeArg,

        /// Override the SAAMI type-based multiplier with an explicit ratio
        /// (gas velocity = factor * muzzle velocity). Takes precedence over
        /// --firearm-type; overridden by --gas-velocity if both are given.
        #[arg(long, value_parser = f64_range(0.0, 20.0))]
        gas_velocity_factor: Option<f64>,

        /// Override with an absolute propellant gas velocity (fps or m/s based on
        /// --units), independent of muzzle velocity -- e.g. the classic fixed
        /// "~4700 fps for smokeless powder" rule of thumb. Takes precedence over
        /// both --gas-velocity-factor and --firearm-type.
        #[arg(long, value_parser = f64_range(0.0, 20000.0))]
        gas_velocity: Option<f64>,

        /// Output format (table, json, or csv)
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Power factor (bullet weight x velocity / 1000) with per-organization
    /// USPSA/IDPA/SASS rulebook pass/fail (MBA-1372). See CLI_USAGE.md for the
    /// truncation convention and threshold boundary semantics.
    PowerFactor {
        /// Bullet weight (grains for imperial, grams for metric)
        #[arg(short = 'w', long, value_parser = f64_range(0.1, 2000.0))]
        weight: f64,

        /// Velocity (fps or m/s based on --units)
        #[arg(short = 'v', long, value_parser = f64_range(1.0, 6000.0))]
        velocity: f64,

        /// Filter results to one organization: uspsa, idpa, or sass (default: all)
        #[arg(long)]
        organization: Option<String>,

        /// Output format (table, json, or csv)
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Generate wind drift card (wind deflection at multiple speeds)
    WindCard {
        /// Load parameters from saved profile
        #[arg(long, value_name = "NAME")]
        profile: Option<String>,

        /// Initial velocity (fps or m/s based on --units)
        #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
        velocity: Option<f64>,

        /// Ballistic coefficient
        #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
        bc: Option<f64>,

        /// Mass (grains for imperial, grams for metric)
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: Option<f64>,

        /// Diameter (inches for imperial, mm for metric)
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: Option<f64>,

        /// Drag model (G1, G2, G5, G6, G7, G8, GI, GS, RA4)
        #[arg(long, default_value = "g1")]
        drag_model: DragModel,

        /// Zero distance (yards for imperial, meters for metric)
        #[arg(long)]
        zero_distance: f64,

        /// Select a named zero set from the saved profile (MBA-1360, requires --profile).
        /// Its poi_right_mil is added to the drift dial values as a constant angular
        /// correction; --zero-distance (required here) always wins over the set's own
        /// zero_distance. Unknown names are a hard error listing the available sets.
        #[arg(long, value_name = "NAME")]
        zero_set: Option<String>,

        /// Comma-separated wind speeds to calculate (mph or m/s)
        #[arg(long, default_value = "5,10,15,20")]
        wind_speeds: String,

        /// Wind angle in DEGREES, wind-FROM convention (matches --wind-direction):
        /// 0 = headwind, 90 = from the right (full value), 180 = tailwind,
        /// 270 = from the left. Positive drift = dial right. Default 90.
        #[arg(long, value_parser = f64_range(0.0, 360.0), conflicts_with = "wind_angles")]
        wind_angle: Option<f64>,

        /// Comma-separated wind angles (degrees, wind-FROM) — emits one complete
        /// card per angle. Example: --wind-angles 30,60,90
        #[arg(long, conflicts_with = "wind_angle")]
        wind_angles: Option<String>,

        /// Start range (yards or meters)
        #[arg(long, default_value = "100.0")]
        start: f64,

        /// End range (yards or meters)
        #[arg(long, default_value = "1000.0")]
        end: f64,

        /// Range step (yards or meters)
        #[arg(long, default_value = "100.0", value_parser = f64_range(0.001, 100000.0))]
        step: f64,

        /// Adjustment unit (mil, moa, smoa, iphy, or clicks). `clicks` requires
        /// --windage-click-value (or a saved profile's windage_click/elevation_click) and
        /// formats whole turret clicks instead of an angle (MBA-1410: the whole card is a
        /// windage quantity — crosswind drift — so it resolves through the windage
        /// graduation).
        #[arg(long, default_value = "mil")]
        adjustment_unit: AdjustmentUnit,

        /// Turret click graduation for `--adjustment-unit clicks`, e.g. 0.1mil or 0.25moa
        /// (falls back to the saved profile's windage_click, then its elevation_click,
        /// when omitted).
        #[arg(long)]
        windage_click_value: Option<String>,

        /// Windage-axis scope tracking correction factor from a tall-target test
        /// (MBA-1358): actual measured travel / dialed travel. The wind card's
        /// dial-unit drift values are DIVIDED by it; raw drift inches are not.
        /// Strictly between 0.5 and 1.5; overrides the saved profile's windage_cf
        #[arg(long, value_name = "FACTOR")]
        windage_cf: Option<f64>,

        /// Sight height above bore (inches for imperial, mm for metric)
        #[arg(long)]
        sight_height: Option<f64>,

        /// Deliberate vertical POI offset AT the zero range (inches imperial / cm metric;
        /// signed; positive = impacts HIGH). Same semantics as `trajectory --zero-poi-up`
        /// (MBA-1359); biases the zero the drift columns are computed against.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        zero_poi_up: Option<f64>,

        /// Deliberate horizontal POI offset AT the zero range (inches imperial / cm metric;
        /// signed; positive = impacts RIGHT). Same semantics as `trajectory
        /// --zero-poi-right` (MBA-1359); shifts every drift column by the equivalent
        /// angular bias.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        zero_poi_right: Option<f64>,

        /// Lateral sight-to-bore mount offset (inches imperial / mm metric; signed;
        /// positive = sight RIGHT of bore). Same semantics as `trajectory --sight-offset`
        /// (MBA-1396): drift starts offset left of the sight line and converges to it at
        /// the zero distance.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        sight_offset: Option<f64>,

        /// Temperature (Fahrenheit or Celsius based on --units; default 59 F / 15 C)
        #[arg(long)]
        temperature: Option<f64>,

        /// Pressure (inHg or hPa based on --units; default 29.92 inHg / 1013.25 hPa)
        #[arg(long)]
        pressure: Option<f64>,
        /// How to interpret `--pressure` (MBA-1416): `absolute` (default) is station pressure
        /// at your altitude; `qnh` is a sea-level-corrected altimeter setting — the kind of
        /// value a weather report or METAR gives — and is reduced to station pressure using
        /// `--altitude`. Omitting this is exactly `absolute`, so existing invocations are
        /// unchanged. Same meaning as `trajectory --pressure-type`.
        #[arg(long, value_enum)]
        pressure_type: Option<PressureReferenceMode>,

        /// Humidity (0-100%)
        #[arg(long, default_value = "50.0")]
        humidity: f64,

        /// Altitude (feet or meters based on --units)
        #[arg(long, default_value = "0.0")]
        altitude: f64,

        /// Output format
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Analyze gyroscopic stability (Miller stability factor)
    Stability {
        /// Load parameters from saved profile
        #[arg(long, value_name = "NAME")]
        profile: Option<String>,

        /// Bullet mass (grains for imperial, grams for metric)
        #[arg(short = 'm', long)]
        mass: Option<f64>,

        /// Bullet diameter (inches for imperial, mm for metric)
        #[arg(short = 'd', long)]
        diameter: Option<f64>,

        /// Bullet length (inches for imperial, mm for metric)
        #[arg(short = 'l', long)]
        length: f64,

        /// Barrel twist rate (inches/turn for imperial, mm/turn for metric)
        #[arg(short = 't', long)]
        twist_rate: f64,

        /// Muzzle velocity (fps for imperial, m/s for metric; default: 2700 fps / 823 m/s)
        #[arg(short = 'v', long)]
        velocity: Option<f64>,

        /// Temperature (Fahrenheit or Celsius based on --units; default 59 F / 15 C)
        #[arg(long)]
        temperature: Option<f64>,

        /// Pressure (inHg or hPa based on --units; default 29.92 inHg / 1013.25 hPa)
        #[arg(long)]
        pressure: Option<f64>,
        /// How to interpret `--pressure` (MBA-1416): `absolute` (default) is station pressure
        /// at your altitude; `qnh` is a sea-level-corrected altimeter setting — the kind of
        /// value a weather report or METAR gives — and is reduced to station pressure using
        /// `--altitude`. Omitting this is exactly `absolute`, so existing invocations are
        /// unchanged. Same meaning as `trajectory --pressure-type`.
        #[arg(long, value_enum)]
        pressure_type: Option<PressureReferenceMode>,

        /// Altitude (feet or meters based on --units)
        #[arg(long, default_value = "0.0")]
        altitude: f64,

        /// Output format
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Generate comprehensive range table (drop, wind, velocity, energy, ToF)
    RangeTable {
        /// Load parameters from saved profile
        #[arg(long, value_name = "NAME")]
        profile: Option<String>,

        /// Initial velocity (fps or m/s based on --units)
        #[arg(short = 'v', long)]
        velocity: Option<f64>,

        /// Ballistic coefficient
        #[arg(short = 'b', long)]
        bc: Option<f64>,

        /// Mass (grains for imperial, grams for metric)
        #[arg(short = 'm', long)]
        mass: Option<f64>,

        /// Diameter (inches for imperial, mm for metric)
        #[arg(short = 'd', long)]
        diameter: Option<f64>,

        /// Drag model (G1, G2, G5, G6, G7, G8, GI, GS, RA4)
        #[arg(long, default_value = "g1")]
        drag_model: DragModel,

        /// Zero distance (yards for imperial, meters for metric)
        #[arg(long)]
        zero_distance: f64,

        /// Select a named zero set from the saved profile (MBA-1360, requires --profile).
        /// Its poi_up_mil/poi_right_mil are added to the Drop/Wind dial columns as a
        /// constant angular correction; --zero-distance (required here) always wins over
        /// the set's own zero_distance. Unknown names are a hard error listing the
        /// available sets.
        #[arg(long, value_name = "NAME")]
        zero_set: Option<String>,

        /// Start range (yards or meters)
        #[arg(long, default_value = "100.0")]
        start: f64,

        /// End range (yards or meters)
        #[arg(long, default_value = "1200.0")]
        end: f64,

        /// Range step (yards or meters)
        #[arg(long, default_value = "50.0", value_parser = f64_range(0.001, 100000.0))]
        step: f64,

        /// Wind speed (mph or m/s based on --units)
        #[arg(long, default_value = "10.0")]
        wind_speed: f64,

        /// Wind direction (MBA-1367: degrees or clock position, shared help const)
        #[arg(long, default_value = "90.0", value_parser = parse_wind_direction_arg, help = WIND_DIRECTION_HELP)]
        wind_direction: ParsedWindDirection,

        /// Adjustment unit (mil, moa, smoa, iphy, or clicks), applied to the Drop column
        /// (the elevation axis). `clicks` requires --elevation-click-value (or a saved
        /// profile's elevation_click).
        #[arg(long, default_value = "mil")]
        adjustment_unit: AdjustmentUnit,

        /// Independent windage unit for the Wind column (MBA-1410). Falls back to
        /// `--adjustment-unit` when omitted; `clicks` is only accepted here when
        /// `--adjustment-unit` is ALSO `clicks`.
        #[arg(long, value_enum)]
        windage_unit: Option<AdjustmentUnit>,

        /// Turret elevation click graduation for `--adjustment-unit clicks`, e.g. 0.1mil or
        /// 0.25moa (falls back to the saved profile's elevation_click when omitted).
        #[arg(long)]
        elevation_click_value: Option<String>,

        /// Turret windage click graduation for `--adjustment-unit clicks` (falls back to the
        /// resolved elevation graduation, then the saved profile's windage_click).
        #[arg(long)]
        windage_click_value: Option<String>,

        /// Elevation-axis scope tracking correction factor from a tall-target test
        /// (MBA-1358): actual measured travel / dialed travel. The drop-adjustment
        /// column's dial-unit values are DIVIDED by it; raw drop inches are not
        /// touched. Strictly between 0.5 and 1.5; overrides the saved profile's
        /// elevation_cf
        #[arg(long, value_name = "FACTOR")]
        elevation_cf: Option<f64>,

        /// Windage-axis scope tracking correction factor (MBA-1358): the
        /// wind-adjustment column's dial-unit values are divided by it. Same bounds;
        /// overrides the saved profile's windage_cf
        #[arg(long, value_name = "FACTOR")]
        windage_cf: Option<f64>,

        /// Sight height above bore (inches for imperial, mm for metric)
        #[arg(long)]
        sight_height: Option<f64>,

        /// Deliberate vertical POI offset AT the zero range (inches imperial / cm metric;
        /// signed; positive = impacts HIGH). Same semantics as `trajectory --zero-poi-up`
        /// (MBA-1359); the Drop column is computed from the biased zero.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        zero_poi_up: Option<f64>,

        /// Deliberate horizontal POI offset AT the zero range (inches imperial / cm metric;
        /// signed; positive = impacts RIGHT). Same semantics as `trajectory
        /// --zero-poi-right` (MBA-1359); shifts the Wind column by the equivalent angular
        /// bias.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        zero_poi_right: Option<f64>,

        /// Lateral sight-to-bore mount offset (inches imperial / mm metric; signed;
        /// positive = sight RIGHT of bore). Same semantics as `trajectory --sight-offset`
        /// (MBA-1396): the Wind column starts offset left of the sight line and converges
        /// to it at the zero distance.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        sight_offset: Option<f64>,

        /// Temperature (Fahrenheit or Celsius based on --units; default 59 F / 15 C)
        #[arg(long)]
        temperature: Option<f64>,

        /// Pressure (inHg or hPa based on --units; default 29.92 inHg / 1013.25 hPa)
        #[arg(long)]
        pressure: Option<f64>,
        /// How to interpret `--pressure` (MBA-1416): `absolute` (default) is station pressure
        /// at your altitude; `qnh` is a sea-level-corrected altimeter setting — the kind of
        /// value a weather report or METAR gives — and is reduced to station pressure using
        /// `--altitude`. Omitting this is exactly `absolute`, so existing invocations are
        /// unchanged. Same meaning as `trajectory --pressure-type`.
        #[arg(long, value_enum)]
        pressure_type: Option<PressureReferenceMode>,

        /// Humidity (0-100%)
        #[arg(long, default_value = "50.0", value_parser = f64_range(0.0, 100.0))]
        humidity: f64,

        /// Altitude (feet or meters based on --units)
        #[arg(long, default_value = "0.0")]
        altitude: f64,

        /// Output format
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Compare multiple loads side-by-side at the same conditions (MBA-735)
    Compare {
        /// A load as NAME:DRAG:BC:MASS:VELOCITY with an optional sixth :DIAMETER
        /// field (repeat 2-8 times).
        /// DRAG is g1|g2|g5|g6|g7|g8|gi|gs|ra4; MASS is grains/grams, VELOCITY fps|m/s,
        /// DIAMETER in|mm per --units (diameter defaults to .308 in / 7.82 mm). NAME
        /// must not contain ':'. Mixable with --profile.
        #[arg(long = "load", value_name = "SPEC")]
        loads: Vec<String>,

        /// A saved profile as a load (repeatable; mixable with --load). Like
        /// range-table, a profile's bc_segments/drag_curve are not yet consumed
        /// here — the scalar BC is used.
        #[arg(long = "profile", value_name = "NAME")]
        profiles: Vec<String>,

        /// Shared zero distance (yards for imperial, meters for metric); every
        /// load is zeroed independently at this distance
        #[arg(long)]
        zero_distance: f64,

        /// Start range (yards or meters)
        #[arg(long, default_value = "100.0")]
        start: f64,

        /// End range (yards or meters)
        #[arg(long, default_value = "500.0")]
        end: f64,

        /// Range step (yards or meters)
        #[arg(long, default_value = "100.0", value_parser = f64_range(0.001, 100000.0))]
        step: f64,

        /// Wind speed (mph or m/s based on --units)
        #[arg(long, default_value = "10.0")]
        wind_speed: f64,

        /// Wind direction (MBA-1367: degrees or clock position, shared help const)
        #[arg(long, default_value = "90.0", value_parser = parse_wind_direction_arg, help = WIND_DIRECTION_HELP)]
        wind_direction: ParsedWindDirection,

        /// Adjustment unit (mil, moa, smoa, iphy, or clicks), applied to the Drop column
        /// (the elevation axis). `clicks` requires --elevation-click-value -- compare has
        /// no single --profile (it compares multiple loads), so the graduation always
        /// comes from the explicit flag, never a per-load profile.
        #[arg(long, default_value = "mil")]
        adjustment_unit: AdjustmentUnit,

        /// Independent windage unit for the Drift column (MBA-1410). Falls back to
        /// `--adjustment-unit` when omitted; `clicks` is only accepted here when
        /// `--adjustment-unit` is ALSO `clicks`.
        #[arg(long, value_enum)]
        windage_unit: Option<AdjustmentUnit>,

        /// Turret elevation click graduation for `--adjustment-unit clicks`.
        #[arg(long)]
        elevation_click_value: Option<String>,

        /// Turret windage click graduation for `--adjustment-unit clicks` (falls back to
        /// the resolved elevation graduation when omitted).
        #[arg(long)]
        windage_click_value: Option<String>,

        /// Elevation-axis scope tracking correction factor from a tall-target test
        /// (MBA-1358): actual measured travel / dialed travel. Every load's
        /// drop-adjustment dial values are DIVIDED by it. Strictly between 0.5 and
        /// 1.5; overrides a saved profile's elevation_cf
        #[arg(long, value_name = "FACTOR")]
        elevation_cf: Option<f64>,

        /// Windage-axis scope tracking correction factor (MBA-1358): every load's
        /// wind-adjustment dial values are divided by it. Same bounds; overrides a
        /// saved profile's windage_cf
        #[arg(long, value_name = "FACTOR")]
        windage_cf: Option<f64>,

        /// Sight height above bore (inches for imperial, mm for metric)
        #[arg(long, default_value = "1.5")]
        sight_height: f64,

        /// Deliberate vertical POI offset AT the shared zero range (inches imperial /
        /// cm metric; signed; positive = impacts HIGH). Same semantics as `trajectory
        /// --zero-poi-up` (MBA-1359); applied identically to every compared load.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        zero_poi_up: Option<f64>,

        /// Deliberate horizontal POI offset AT the shared zero range (inches imperial /
        /// cm metric; signed; positive = impacts RIGHT). Same semantics as `trajectory
        /// --zero-poi-right` (MBA-1359); applied identically to every compared load.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        zero_poi_right: Option<f64>,

        /// Lateral sight-to-bore mount offset (inches imperial / mm metric; signed;
        /// positive = sight RIGHT of bore). Same semantics as `trajectory --sight-offset`
        /// (MBA-1396); applied identically to every compared load.
        #[arg(long, value_name = "OFFSET", allow_hyphen_values = true)]
        sight_offset: Option<f64>,

        /// Temperature (F or C based on --units)
        #[arg(long)]
        temperature: Option<f64>,

        /// Pressure (inHg or hPa based on --units)
        #[arg(long)]
        pressure: Option<f64>,
        /// How to interpret `--pressure` (MBA-1416): `absolute` (default) is station pressure
        /// at your altitude; `qnh` is a sea-level-corrected altimeter setting — the kind of
        /// value a weather report or METAR gives — and is reduced to station pressure using
        /// `--altitude`. Omitting this is exactly `absolute`, so existing invocations are
        /// unchanged. Same meaning as `trajectory --pressure-type`.
        #[arg(long, value_enum)]
        pressure_type: Option<PressureReferenceMode>,

        /// Humidity (percent)
        #[arg(long, default_value = "50.0")]
        humidity: f64,

        /// Altitude (feet or meters based on --units)
        #[arg(long, default_value = "0.0")]
        altitude: f64,

        /// Output format (table, json, csv)
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Manage saved ballistic profiles
    Profile {
        #[command(subcommand)]
        action: ProfileAction,
    },

    /// Print a built-in reference drag curve as (Mach, Cd) data (MBA-1424)
    ///
    /// Emits the standard drag function the engine itself interpolates, so a chart or an audit
    /// can use the engine's numbers rather than a re-vendored copy that drifts from them.
    ///
    /// This is the REFERENCE curve for the model's standard projectile, not the effective Cd a
    /// particular bullet flew — for that, see `trajectory --with-drag-coefficient`, which is
    /// form-factor scaled and shows segmented-BC band steps.
    ///
    /// The tables do not share a Mach domain: most run to Mach 5, while GS and RA4 stop at
    /// Mach 4. The output carries whatever the table actually holds; it is not resampled.
    DragCurve {
        /// Drag model to print (G1, G2, G5, G6, G7, G8, GI, GS, RA4)
        #[arg(long, default_value = "g7")]
        drag_model: DragModel,

        /// Output format: table (default), csv, or json
        #[arg(short, long, default_value = "table")]
        output: OutputFormat,
    },

    /// Robust hold corridors across named segmented-wind scenarios (MBA-1349)
    ///
    /// You usually have several concrete plausible wind calls, not a distribution you
    /// believe. This solves each named scenario once through the existing segmented-wind
    /// machinery and reports, at every requested range: every scenario's hold, the
    /// min/max corridor they span, the minimax (Chebyshev-center) hold, the worst-case
    /// miss from it, and whether one hold keeps every scenario inside the target.
    ///
    /// It assigns NO probabilities. The corridor is the span of the hypotheses you
    /// supplied — it is not a confidence interval, and statistical dispersion remains
    /// `monte-carlo --wez`'s job.
    HoldCorridor {
        /// Scenario set JSON file. Segments use the same "SPEED:ANGLE:UNTIL", or
        /// "SPEED:ANGLE:UNTIL:VERTICAL", tokens as --wind-segment, e.g.
        /// {"version":1,"nominal":"low","scenarios":[{"name":"low","segments":["5:90:400"]}]}
        #[arg(long, value_name = "FILE")]
        scenarios: PathBuf,

        /// Comma-separated ranges to report (yards imperial / meters metric)
        #[arg(long, value_name = "R1,R2,...")]
        ranges: String,

        /// Target to judge the corridor against: "rect:WIDTHxHEIGHT" or "circle:DIAMETER"
        /// (inches imperial / cm metric). Omit it and no fit is reported; the minimax hold
        /// then uses the per-axis metric.
        #[arg(long, value_name = "SPEC")]
        target: Option<String>,

        /// Load parameters from a saved profile
        #[arg(long, value_name = "NAME")]
        profile: Option<String>,

        /// Initial velocity (fps or m/s based on --units)
        #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
        velocity: Option<f64>,

        /// Ballistic coefficient
        #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
        bc: Option<f64>,

        /// Mass (grains for imperial, grams for metric)
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: Option<f64>,

        /// Diameter (inches for imperial, mm for metric)
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: Option<f64>,

        /// Drag model (G1, G2, G5, G6, G7, G8, GI, GS, RA4)
        #[arg(long, default_value = "g1")]
        drag_model: DragModel,

        /// Zero distance (yards for imperial, meters for metric). The zero is solved ONCE,
        /// in calm air, and reused by every scenario — a rifle has one zero, and
        /// re-zeroing per scenario would collapse the very corridor this reports.
        #[arg(long)]
        zero_distance: Option<f64>,

        /// Sight height above bore (inches for imperial, mm for metric)
        #[arg(long)]
        sight_height: Option<f64>,

        /// Temperature (Fahrenheit or Celsius based on --units; default 59 F / 15 C)
        #[arg(long)]
        temperature: Option<f64>,

        /// Pressure (inHg or hPa based on --units; default 29.92 inHg / 1013.25 hPa)
        #[arg(long)]
        pressure: Option<f64>,

        /// How to interpret `--pressure` (MBA-1416): `absolute` (default) or `qnh`
        #[arg(long, value_enum)]
        pressure_type: Option<PressureReferenceMode>,

        /// Humidity (0-100%)
        #[arg(long, default_value = "50.0", value_parser = f64_range(0.0, 100.0))]
        humidity: f64,

        /// Altitude (feet or meters based on --units)
        #[arg(long, default_value = "0.0")]
        altitude: f64,

        /// Output format: table (default) or json (versioned RobustHoldReportV1)
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Map each reticle mark to the range where it lands (MBA-1362)
    ///
    /// The inverse of a come-up table: instead of "what do I hold at 600?", it answers
    /// "what range is this mark good for?" — the Nightforce / Nikon Spot On / Swarovski /
    /// TRACT question. Each subtension is converted to TRUE angular for the focal plane and
    /// magnification in use, then the range where angular drop equals it is found by
    /// bisection over one solved trajectory.
    ///
    /// Marks the load cannot reach are REPORTED as such, not dropped from the table.
    MarkToRange {
        /// A mark subtension in milliradians below center; repeatable. Mutually exclusive
        /// with --reticle-json. A non-positive value is accepted and reported as "not a
        /// holdover" rather than rejected, so a whole reticle's marks can be passed
        /// through without pre-filtering.
        #[arg(long = "mark", value_name = "MIL", action = clap::ArgAction::Append, allow_hyphen_values = true)]
        marks: Vec<f64>,

        /// Take the subtensions (and the focal plane and reference magnification) from a
        /// reticle description file instead. Marks on the vertical stadium are used,
        /// including any above center (reported as "not a holdover"); the optical center
        /// and off-axis windage marks are excluded and their count reported.
        #[arg(long, value_name = "FILE")]
        reticle_json: Option<PathBuf>,

        /// Optic magnification in use
        #[arg(long, default_value = "10.0", value_parser = f64_range(0.0001, 1000.0))]
        mag: f64,

        /// Focal plane of the supplied --mark subtensions (ignored with --reticle-json,
        /// which carries its own)
        #[arg(long, default_value = "ffp")]
        focal_plane: FocalPlaneArg,

        /// Magnification the --mark subtensions are true at (--focal-plane sfp only;
        /// ignored with --reticle-json)
        #[arg(long, default_value = "1.0", value_parser = f64_range(0.0001, 1000.0))]
        reference_mag: f64,

        /// Zero distance (yards for imperial, meters for metric)
        #[arg(long)]
        zero_distance: Option<f64>,

        /// Furthest range to search (yards for imperial, meters for metric)
        #[arg(long, default_value = "1500.0", value_parser = f64_range(1.0, 10000.0))]
        max_range: f64,

        #[command(flatten)]
        load: InverseSolverLoadArgs,

        /// Output format: table (default) or json
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Solve the magnification that makes an SFP BDC reticle match this load (MBA-1362)
    ///
    /// The Zeiss Rapid-Z question. Second-focal-plane subtensions scale as
    /// reference-mag / magnification, so there is generally one magnification at which a
    /// generic BDC ladder lines up with a particular load's drops. This is the 1-D least
    /// squares fit of that magnification over the supplied (mark, nominal range) pairs.
    ///
    /// FFP reticles are rejected: their subtensions do not depend on magnification, so
    /// there is nothing to solve.
    BdcMatch {
        /// One "MIL:RANGE" pair per mark: the mark's etched subtension in milliradians and
        /// the range it is meant to hit. Repeatable; at least two are required. RANGE
        /// follows --units.
        #[arg(long = "mark-range", value_name = "MIL:RANGE", action = clap::ArgAction::Append, required = true)]
        mark_ranges: Vec<String>,

        /// Magnification the subtensions are true at (the reticle's calibration point)
        #[arg(long, default_value = "1.0", value_parser = f64_range(0.0001, 1000.0))]
        reference_mag: f64,

        /// Focal plane. Only sfp can be fitted; ffp is rejected with an explanation.
        #[arg(long, default_value = "sfp")]
        focal_plane: FocalPlaneArg,

        /// Warn when any mark's residual exceeds this many milliradians
        #[arg(long, value_name = "MIL", default_value = "0.2", value_parser = f64_range(0.0, 100.0))]
        residual_warn: f64,

        /// Zero distance (yards for imperial, meters for metric)
        #[arg(long)]
        zero_distance: Option<f64>,

        #[command(flatten)]
        load: InverseSolverLoadArgs,

        /// Output format: table (default) or json
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Solve the one zero that makes a whole stage of targets holdable (MBA-1362)
    ///
    /// GeoBallistics HDZ class: a min-max search over zero distance that minimizes the
    /// LARGEST hold any listed target needs, then reports whether a dead-center hold keeps
    /// every one of them inside its vital zone. Unlike `mpbr`, which sizes one vital zone
    /// around one zero, this balances a specific list of ranges against each other.
    OptimalZero {
        /// A target as "RANGE" or "RANGE:HEIGHT_IN"; repeatable, 2 to 16 of them. RANGE
        /// follows --units; HEIGHT is the target's full vertical size in inches (imperial)
        /// or centimeters (metric), falling back to --vital when omitted.
        #[arg(long = "target", value_name = "RANGE[:HEIGHT]", action = clap::ArgAction::Append, required = true)]
        targets: Vec<String>,

        /// Default target height for targets that do not carry their own (inches imperial
        /// / cm metric)
        #[arg(long, value_name = "SIZE", value_parser = f64_range(0.0, 1000.0))]
        vital: Option<f64>,

        #[command(flatten)]
        load: InverseSolverLoadArgs,

        /// Output format: table (default) or json
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Explain why two resolved firing solutions differ, attributed by input group (MBA-1345)
    ///
    /// Takes two solve-json v1 request files, resolves each independently, and attributes the
    /// difference in the observed impact -- at each requested range -- to a symmetric
    /// counterfactual swap of each of the seven input groups (drag, muzzle velocity, zero/sight
    /// geometry, atmosphere, wind, shot geometry, effects). Whatever nonlinear interaction
    /// between groups the seven do not explain is reported once per range as an explicit
    /// interaction remainder, and is never distributed across groups.
    Explain {
        /// Baseline solve-json v1 request file
        #[arg(long, value_name = "FILE")]
        a: PathBuf,

        /// Comparison solve-json v1 request file
        #[arg(long, value_name = "FILE")]
        b: PathBuf,

        /// Comma-separated ranges to explain, in meters. Solve-json requests are already SI,
        /// so this is NOT affected by --units.
        #[arg(long, value_name = "R1,R2,...", value_delimiter = ',', num_args = 1.., required = true)]
        ranges: Vec<f64>,

        /// Output format: table (default) or json
        #[arg(short, long, default_value = "table")]
        output: OutputFormat,
    },

    /// Bound how wrong one input may be before the shot leaves the target (MBA-1350)
    ///
    /// Takes a solve-json v1 request file, resolves it, and bisects each requested axis
    /// outward -- toward its own configured domain's lower bound and, independently, its
    /// upper bound -- until the impact crosses the target boundary. Bounds are ONE VARIABLE
    /// AT A TIME: two inputs each at their own individual limit will generally miss even
    /// though neither alone would, and no bound reported here implies any probability.
    Tolerance {
        /// solve-json v1 request file
        #[arg(long, value_name = "FILE")]
        request: PathBuf,

        /// Range to evaluate the impact at, in meters (not affected by --units)
        #[arg(long)]
        range: f64,

        /// Target geometry: rect:WIDTHxHEIGHT or circle:DIAMETER (inches imperial / cm
        /// metric, per --units -- same convention as hold-corridor --target and
        /// mpbr --vital-zone; converted to meters internally)
        #[arg(long)]
        target: String,

        /// Axis to bound, kebab-case (e.g. wind-speed, muzzle-velocity-mps, cant); repeatable,
        /// at least one required. An unrecognized name is rejected with the full accepted list.
        #[arg(long = "axis", value_name = "AXIS", action = clap::ArgAction::Append, required = true)]
        axes: Vec<String>,

        /// Per-axis search domain as AXIS=LO:HI, in that axis's own physical unit (e.g.
        /// wind-speed=0:20 for m/s, cant=-0.05:0.05 for radians). Repeatable; required once for
        /// every --axis given -- there is no default domain, even for a categorical axis
        /// (whose bounds then simply go unused).
        #[arg(long = "domain", value_name = "AXIS=LO:HI", action = clap::ArgAction::Append)]
        domains: Vec<String>,

        /// Output format: table (default) or json
        #[arg(short, long, default_value = "table")]
        output: OutputFormat,
    },

    /// Rank which declared input is worth measuring better, by its own share of impact
    /// uncertainty (MBA-1347)
    ///
    /// Takes a solve-json v1 request file, resolves it, and propagates each declared one-sigma
    /// input uncertainty (`--sigma AXIS=VALUE`, repeatable) to impact covariance at every
    /// requested range, through the SAME central-difference kernel `explain`/`tolerance` share.
    /// Every declared source is preserved individually and ranked by its own share of impact
    /// variance -- NEVER collapsed into an "other" bucket the way `monte-carlo --wez`'s
    /// attribution is -- so the report ends with a concrete answer: which single input is worth
    /// improving here. A source the kernel cannot evaluate for this request (a categorical axis,
    /// a wind axis absent under segmented wind, one outside its own physical domain, ...) is
    /// named in `unavailable_sources` with the reason, never silently dropped: a dropped source
    /// would read as "contributes no uncertainty," a different fact from "could not be measured."
    ///
    /// With `--target`, each row additionally reports the probability the impact falls inside
    /// that target, and each source's hit-probability gain if it alone were measured perfectly
    /// (its sigma set to zero, every other source unchanged) -- the value-of-information number
    /// this command exists to answer.
    ErrorBudget {
        /// solve-json v1 request file
        #[arg(long, value_name = "FILE")]
        request: PathBuf,

        /// Comma-separated ranges to evaluate, in meters. Solve-json requests are already SI, so
        /// this is NOT affected by --units.
        #[arg(
            long,
            value_name = "R1,R2,...",
            value_delimiter = ',',
            num_args = 1..,
            required = true
        )]
        ranges: Vec<f64>,

        /// Declared one-sigma uncertainty for one input, AXIS=VALUE, in that axis's own physical
        /// unit (e.g. wind-speed=1.5 for 1.5 m/s, muzzle-velocity-mps=5.0 for 5 m/s, cant=0.01
        /// for 0.01 rad); repeatable, at least one required. An unrecognized axis is rejected
        /// with the full accepted list; a duplicate axis or a negative/non-finite value is
        /// rejected by name.
        #[arg(
            long = "sigma",
            value_name = "AXIS=VALUE",
            action = clap::ArgAction::Append,
            required = true
        )]
        sigmas: Vec<String>,

        /// Optional target geometry for the hit-probability / value-of-information columns:
        /// rect:WIDTHxHEIGHT or circle:DIAMETER (inches imperial / cm metric, per --units --
        /// same convention as tolerance --target; converted to meters internally). Omitted:
        /// sources are still ranked, just without a hit probability.
        #[arg(long)]
        target: Option<String>,

        /// Output format: table (default) or json
        #[arg(short, long, default_value = "table")]
        output: OutputFormat,
    },

    /// Reticle hold points and parametric reticle generation (MBA-1361)
    ///
    /// Places a firing solution where a shooter actually reads it — a point in their own
    /// reticle — FFP/SFP aware, with second-focal-plane subtensions rescaled for the
    /// magnification in use. `reticle generate` emits descriptions in the shared schema
    /// that `reticle hold --reticle-json` (and `profile save --reticle-json`) consume.
    ///
    /// Deliberately excluded: Horus/TREMOR grid layouts and wind-dot calibration (both
    /// patented), and any vendor reticle catalog.
    Reticle {
        #[command(subcommand)]
        action: ReticleAction,
    },

    /// Rank dial/hold/hybrid execution plans for a TRUE angular correction on a real optic
    /// (MBA-1348 Phase 3)
    ///
    /// Takes a correction already computed elsewhere (`come-ups`, a solved trajectory, a
    /// spotter call) and turns it into three ranked, executable plans via `plan_corrections`:
    /// dial the whole thing in whole turret clicks, hold the whole thing on the reticle, or
    /// dial what the turret can reach and hold the TRUE angular remainder. Every plan reports
    /// its own honest residual (angular, and linear miss at the given range); an infeasible
    /// plan is still reported in full, never silently dropped or clamped away -- concluding
    /// "this doesn't fit the optic" is itself a successful analysis, so this command exits 0
    /// even when every plan is infeasible.
    ///
    /// Runs no solve at all -- unlike every calculator subcommand in this file, the correction
    /// is a direct input, so this is pure, instant arithmetic.
    DialPlan {
        /// TRUE angular elevation correction to deliver, suffixed (mil/moa/smoa/iphy);
        /// positive = UP. At least one of --elevation/--windage is required.
        #[arg(long, allow_hyphen_values = true, value_parser = parse_angular_mil)]
        elevation: Option<f64>,

        /// TRUE angular windage correction to deliver, suffixed; positive = RIGHT. See
        /// --elevation -- at least one of the two is required.
        #[arg(long, allow_hyphen_values = true, value_parser = parse_angular_mil)]
        windage: Option<f64>,

        /// Range for the linear-miss-at-range residual (yards imperial / meters metric).
        #[arg(long)]
        range: f64,

        /// Saved profile supplying the optic (turret mechanics + reticle hold bounds) and its
        /// tracking correction factors (elevation_cf/windage_cf, default 1.0). Mutually
        /// exclusive with the inline optic flags below.
        #[arg(long, value_name = "NAME")]
        profile: Option<String>,

        /// Elevation turret's click graduation, e.g. 0.1mil or 0.25moa (inline optic, mutually
        /// exclusive with --profile). Required, inline, to define an optic at all -- inline
        /// mode has no tracking-CF flags, so the CF is always 1.0.
        #[arg(long)]
        elevation_click: Option<String>,

        /// Windage turret's click graduation (inline optic); falls back to --elevation-click
        /// when omitted, like `profile save --windage-click`.
        #[arg(long)]
        windage_click: Option<String>,

        /// Click detents per full revolution (inline optic); omit when unknown or the turret
        /// has no revolution markings.
        #[arg(long)]
        clicks_per_rev: Option<u32>,

        /// Whether the elevation turret hard-stops at its lowest travel (inline optic);
        /// purely descriptive, never consulted by the planner itself.
        #[arg(long)]
        zero_stop: Option<bool>,

        /// Elevation travel remaining UP from the current zero (inline optic); required
        /// together with --travel-down.
        #[arg(long, value_parser = parse_angular_mil)]
        travel_up: Option<f64>,

        /// Elevation travel remaining DOWN from the current zero (inline optic); required
        /// together with --travel-up.
        #[arg(long, value_parser = parse_angular_mil)]
        travel_down: Option<f64>,

        /// Windage travel remaining LEFT from the current zero (inline optic); required
        /// together with --windage-travel-right.
        #[arg(long, value_parser = parse_angular_mil)]
        windage_travel_left: Option<f64>,

        /// Windage travel remaining RIGHT from the current zero (inline optic); required
        /// together with --windage-travel-left.
        #[arg(long, value_parser = parse_angular_mil)]
        windage_travel_right: Option<f64>,

        /// The reticle's usable hold extent ABOVE center (inline optic); required together
        /// with --hold-down/--hold-left/--hold-right.
        #[arg(long, value_parser = parse_angular_mil)]
        hold_up: Option<f64>,

        /// The reticle's usable hold extent BELOW center (inline optic). See --hold-up.
        #[arg(long, value_parser = parse_angular_mil)]
        hold_down: Option<f64>,

        /// The reticle's usable hold extent LEFT of center (inline optic). See --hold-up.
        #[arg(long, value_parser = parse_angular_mil)]
        hold_left: Option<f64>,

        /// The reticle's usable hold extent RIGHT of center (inline optic). See --hold-up.
        #[arg(long, value_parser = parse_angular_mil)]
        hold_right: Option<f64>,

        /// The elevation turret's current dialed offset from zero, signed: positive is dialed
        /// UP (inline optic); required together with --turret-wind.
        #[arg(long, allow_hyphen_values = true, value_parser = parse_angular_mil)]
        turret_elev: Option<f64>,

        /// The windage turret's current dialed offset from zero, signed: positive is dialed
        /// RIGHT (inline optic); required together with --turret-elev.
        #[arg(long, allow_hyphen_values = true, value_parser = parse_angular_mil)]
        turret_wind: Option<f64>,

        /// When ranking ties, prefer holding over dialing (the planner otherwise prefers
        /// dialing -- see `plan_corrections`).
        #[arg(long)]
        prefer_hold: bool,

        /// Cap any single hold component's magnitude, TRUE angular, suffixed -- applied
        /// together with (the tighter of it and) the optic's own declared reticle hold bounds.
        #[arg(long, value_name = "MIL", value_parser = parse_angular_mil)]
        max_hold: Option<f64>,

        /// Output format: table (default) or json (versioned DialPlanReportV1)
        #[arg(short, long, default_value = "table")]
        output: OutputFormat,
    },

    /// A range card that provably reconstructs the trajectory within a stated
    /// error budget (MBA-1351)
    ///
    /// Greedy worst-point insertion over the solved trajectory's own sample grid: start from
    /// both range ends plus any anchors, then keep adding whichever audited point is furthest
    /// outside the elevation/windage budget until none is, the row cap binds, or the
    /// remaining error is an irreducible click-quantization floor. A separate dense pass then
    /// MEASURES the finished card and reports its true worst-case error and the grid it was
    /// verified against -- see `assumptions` in the output for the exact, honest limits.
    ///
    /// This does NOT reliably produce fewer rows than a well-chosen fixed step (measured: on
    /// a smooth trajectory it does not beat uniform spacing) -- the value here is a MEASURED
    /// error bound, every anchor the flight reaches present, and no step size to guess.
    ///
    /// An anchor past the end of a truncated card is DROPPED, not fabricated, and the
    /// truncation notice says the card stopped short. On a card the flight covers, an
    /// anchor outside the requested domain is still an error.
    AdaptiveCard {
        #[command(flatten)]
        load: InverseSolverLoadArgs,

        /// Zero distance (yards for imperial, meters for metric)
        #[arg(long)]
        zero_distance: Option<f64>,

        /// Start of the card's range domain (yards imperial / meters metric)
        #[arg(long)]
        start: f64,

        /// End of the card's range domain (yards imperial / meters metric)
        #[arg(long)]
        end: f64,

        /// A range that must appear as a row whatever the measured error says (a known dope
        /// point, a target distance); repeatable.
        #[arg(long = "anchor", value_name = "RANGE", action = clap::ArgAction::Append)]
        anchors: Vec<f64>,

        /// Elevation reconstruction-error budget, suffixed (mil/moa/smoa/iphy, e.g. 0.1mil,
        /// 0.25moa) -- converted into --adjustment's unit. Default: half the profile's
        /// elevation click when --profile supplies one, else 0.1mil.
        #[arg(long, value_name = "VALUEUNIT", value_parser = parse_angular_mil)]
        elevation_budget: Option<f64>,

        /// Windage reconstruction-error budget, suffixed. See --elevation-budget for the
        /// default rule (the profile's windage click, not elevation).
        #[arg(long, value_name = "VALUEUNIT", value_parser = parse_angular_mil)]
        windage_budget: Option<f64>,

        /// Maximum printed rows. The mandatory seed (both range ends plus every anchor) is
        /// never truncated to honor this -- see the report's own rows_capped field.
        #[arg(long, default_value = "25")]
        max_rows: usize,

        /// Printed adjustment unit for the Drop/Wind columns. --profile's click graduation
        /// (when present) still quantizes rows onto its own native unit; this only selects
        /// what that quantized (or, with no profile, exact) angle is printed/measured in.
        #[arg(long, value_enum, default_value = "mil")]
        adjustment: AdaptiveCardAdjustmentArg,

        /// Output file path (required for -o pdf)
        #[arg(long, value_name = "FILE")]
        output_file: Option<PathBuf>,

        /// Output format: table (default), csv, json (versioned AdaptiveCardReportV1), or
        /// pdf (requires the pdf feature and --output-file; the relocated library dope card)
        #[arg(short, long, default_value = "table")]
        output: OutputFormat,
    },

    /// Generate shell completions
    Completions {
        /// Shell to generate completions for
        #[arg(value_enum)]
        shell: clap_complete::Shell,
    },
}

/// `reticle` verbs (MBA-1361).
#[allow(
    clippy::large_enum_variant,
    reason = "variants intentionally mirror the stable flat Clap command shape"
)]
#[derive(Subcommand)]
enum ReticleAction {
    /// Place a firing solution in a reticle and name the nearest mark
    Hold {
        /// Reticle description JSON file (as emitted by `reticle generate ... -o json`).
        /// Wins over --profile's attached reticle.
        #[arg(long, value_name = "FILE")]
        reticle_json: Option<PathBuf>,

        /// Saved profile supplying the reticle (`profile save --reticle-json`) and, for
        /// --range, the load and conditions
        #[arg(long, value_name = "NAME")]
        profile: Option<String>,

        /// Angular drop to hold, milliradians, positive = below the line of sight.
        /// Mutually exclusive with --range.
        #[arg(long, value_name = "MIL", allow_hyphen_values = true)]
        drop_mil: Option<f64>,

        /// Angular wind deflection, milliradians, positive = the bullet goes RIGHT (so the
        /// hold is right of center). Defaults to 0 with --drop-mil.
        #[arg(long, value_name = "MIL", allow_hyphen_values = true)]
        wind_mil: Option<f64>,

        /// Solve the trajectory and take the hold at this range (yards imperial / meters
        /// metric) instead of supplying --drop-mil/--wind-mil directly
        #[arg(long)]
        range: Option<f64>,

        /// Optic magnification in use. Ignored for an FFP reticle beyond validation
        /// (subtensions are magnification-independent there).
        #[arg(long, default_value = "10.0", value_parser = f64_range(0.0001, 1000.0))]
        mag: f64,

        /// Initial velocity (fps or m/s based on --units); required with --range
        #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
        velocity: Option<f64>,

        /// Ballistic coefficient; required with --range
        #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
        bc: Option<f64>,

        /// Mass (grains for imperial, grams for metric); required with --range
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: Option<f64>,

        /// Diameter (inches for imperial, mm for metric); required with --range
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: Option<f64>,

        /// Drag model (G1, G2, G5, G6, G7, G8, GI, GS, RA4)
        #[arg(long, default_value = "g1")]
        drag_model: DragModel,

        /// Zero distance (yards for imperial, meters for metric); required with --range
        #[arg(long)]
        zero_distance: Option<f64>,

        /// Sight height above bore (inches for imperial, mm for metric)
        #[arg(long)]
        sight_height: Option<f64>,

        /// Temperature (Fahrenheit or Celsius based on --units; default 59 F / 15 C)
        #[arg(long)]
        temperature: Option<f64>,

        /// Pressure (inHg or hPa based on --units; default 29.92 inHg / 1013.25 hPa)
        #[arg(long)]
        pressure: Option<f64>,

        /// How to interpret `--pressure` (MBA-1416): `absolute` (default) or `qnh`
        #[arg(long, value_enum)]
        pressure_type: Option<PressureReferenceMode>,

        /// Humidity (0-100%)
        #[arg(long, default_value = "50.0", value_parser = f64_range(0.0, 100.0))]
        humidity: f64,

        /// Altitude (feet or meters based on --units)
        #[arg(long, default_value = "0.0")]
        altitude: f64,

        /// Wind speed (mph or m/s based on --units)
        #[arg(long, default_value = "0.0")]
        wind_speed: f64,

        /// Wind direction (MBA-1367: degrees or clock position, shared help const)
        #[arg(long, default_value = "0.0", value_parser = parse_wind_direction_arg, help = WIND_DIRECTION_HELP)]
        wind_direction: ParsedWindDirection,

        /// Output format: table (default) or json
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },

    /// Build a parametric reticle description
    Generate {
        #[command(subcommand)]
        layout: ReticleLayout,
    },

    /// Convert a third-party "Ventum" reticle spec into the engine's reticle description
    /// (MBA-1440). Emits the schema that `reticle hold --reticle-json` and
    /// `profile save --reticle-json` consume, so a reticle authored in the Ventum tool can
    /// be hold-solved here.
    Import {
        /// Path to the Ventum reticle JSON file
        #[arg(value_name = "FILE")]
        file: PathBuf,

        /// Output format: table (default) or json. `-o json` emits the schema that
        /// `reticle hold --reticle-json` and `profile save --reticle-json` consume.
        #[arg(short = 'o', long, default_value = "table")]
        output: OutputFormat,
    },
}

/// `reticle generate` layouts (MBA-1361). All three are generic parametric geometry — no
/// vendor layout is reproduced (see the `reticle` module's IP exclusions).
#[derive(Subcommand)]
enum ReticleLayout {
    /// A plain mil-hash CROSS: marks along both stadia. Not a filled 2-D grid.
    MilGrid {
        /// Spacing between marks, milliradians
        #[arg(long, default_value = "1.0")]
        spacing: f64,

        /// How far the marked area reaches from center, milliradians
        #[arg(long, default_value = "10.0")]
        extent: f64,

        #[command(flatten)]
        common: ReticleGenerateCommon,
    },

    /// A generic widening holdover tree: row N carries windage dots at +/- 1..N steps
    Tree {
        /// Number of holdover rows below center
        #[arg(long, default_value = "5")]
        rows: usize,

        /// Vertical spacing between rows, milliradians
        #[arg(long, default_value = "1.0")]
        row_spacing: f64,

        /// Windage step within a row, milliradians
        #[arg(long, default_value = "0.5")]
        spread_step: f64,

        #[command(flatten)]
        common: ReticleGenerateCommon,
    },

    /// A BDC ladder from ALREADY-SOLVED drops. This generator runs no solve of its own —
    /// produce the drops with `come-ups`/`trajectory` first, so the ladder's provenance
    /// (load, atmosphere, zero) stays the caller's.
    Bdc {
        /// One "RANGE:DROP_MIL" pair per mark; repeatable. RANGE follows --units
        /// (yards imperial / meters metric); DROP_MIL is milliradians below the line of
        /// sight.
        #[arg(long = "drop", value_name = "RANGE:DROP_MIL", action = clap::ArgAction::Append, required = true, allow_hyphen_values = true)]
        drops: Vec<String>,

        #[command(flatten)]
        common: ReticleGenerateCommon,
    },
}

/// Fields every `reticle generate` layout shares (MBA-1361).
#[derive(clap::Args)]
struct ReticleGenerateCommon {
    /// Name to store in the description (defaults to a generated one)
    #[arg(long)]
    name: Option<String>,

    /// Focal plane: ffp (subtensions constant) or sfp (subtensions scale with
    /// magnification)
    #[arg(long, default_value = "ffp")]
    focal_plane: FocalPlaneArg,

    /// The magnification the subtensions are true at. Meaningful for --focal-plane sfp
    /// only.
    #[arg(long, default_value = "1.0", value_parser = f64_range(0.0001, 1000.0))]
    reference_mag: f64,

    /// Output format: table (default) or json. `-o json` emits the schema that
    /// `reticle hold --reticle-json` and `profile save --reticle-json` consume.
    #[arg(short = 'o', long, default_value = "table")]
    output: OutputFormat,
}

/// The rifle / load / atmosphere arguments every MBA-1362 inverse solver takes.
///
/// Flattened rather than triplicated: `mark-to-range`, `bdc-match` and `optimal-zero` all
/// solve the same trajectory, and three hand-maintained copies of fourteen flags is three
/// chances for them to drift apart on a default. Zero distance is deliberately NOT here —
/// two of the three take it as an input and the third solves for it.
#[derive(clap::Args, Debug, Clone)]
struct InverseSolverLoadArgs {
    /// Load parameters from a saved profile
    #[arg(long, value_name = "NAME")]
    profile: Option<String>,

    /// Initial velocity (fps or m/s based on --units)
    #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
    velocity: Option<f64>,

    /// Ballistic coefficient
    #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
    bc: Option<f64>,

    /// Mass (grains for imperial, grams for metric)
    #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
    mass: Option<f64>,

    /// Diameter (inches for imperial, mm for metric)
    #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
    diameter: Option<f64>,

    /// Drag model (G1, G2, G5, G6, G7, G8, GI, GS, RA4)
    #[arg(long, default_value = "g1")]
    drag_model: DragModel,

    /// Sight height above bore (inches for imperial, mm for metric)
    #[arg(long)]
    sight_height: Option<f64>,

    /// Temperature (Fahrenheit or Celsius based on --units; default 59 F / 15 C)
    #[arg(long)]
    temperature: Option<f64>,

    /// Pressure (inHg or hPa based on --units; default 29.92 inHg / 1013.25 hPa)
    #[arg(long)]
    pressure: Option<f64>,

    /// How to interpret `--pressure` (MBA-1416): `absolute` (default) or `qnh`
    #[arg(long, value_enum)]
    pressure_type: Option<PressureReferenceMode>,

    /// Humidity (0-100%)
    #[arg(long, default_value = "50.0", value_parser = f64_range(0.0, 100.0))]
    humidity: f64,

    /// Altitude (feet or meters based on --units)
    #[arg(long, default_value = "0.0")]
    altitude: f64,

    /// Wind speed (mph or m/s based on --units)
    #[arg(long, default_value = "0.0")]
    wind_speed: f64,

    /// Wind direction (MBA-1367: degrees or clock position, shared help const)
    #[arg(long, default_value = "0.0", value_parser = parse_wind_direction_arg, help = WIND_DIRECTION_HELP)]
    wind_direction: ParsedWindDirection,
}

impl InverseSolverLoadArgs {
    /// Resolve these flags (CLI over saved profile) into a metric [`HoldCurveLoad`] at
    /// `zero_distance` in DISPLAY units.
    ///
    /// Returns the loaded profile too, so a caller that needs another field from it (a zero
    /// distance, typically) does not load it a second time.
    fn resolve(
        &self,
        zero_distance: Option<f64>,
        units: UnitSystem,
    ) -> Result<(HoldCurveLoad, Option<ProfileData>), Box<dyn Error>> {
        let profile = match self.profile.as_deref() {
            Some(name) => Some(load_profile(name)?),
            None => None,
        };
        let require = |value: Option<f64>, flag: &str| -> Result<f64, Box<dyn Error>> {
            value.ok_or_else(|| format!("{flag} is required (directly or from --profile)").into())
        };
        let velocity = require(
            resolve_param(self.velocity, &profile, |p| p.velocity),
            "--velocity",
        )?;
        let bc = require(resolve_param(self.bc, &profile, |p| p.bc), "--bc")?;
        let mass = require(resolve_param(self.mass, &profile, |p| p.mass), "--mass")?;
        let diameter = require(
            resolve_param(self.diameter, &profile, |p| p.diameter),
            "--diameter",
        )?;
        let zero_distance = require(
            zero_distance.or_else(|| profile.as_ref().and_then(|p| p.zero_distance)),
            "--zero-distance",
        )?;
        if zero_distance <= 0.0 {
            return Err("--zero-distance must be greater than zero".into());
        }
        // Same fallback `trajectory --saved-profile`/`come-ups --profile` use.
        let sight_height = self
            .sight_height
            .or_else(|| profile.as_ref().and_then(|p| p.sight_height))
            .unwrap_or(match units {
                UnitSystem::Imperial => 2.0,
                UnitSystem::Metric => 50.0,
            });
        let temperature = UnitConverter::resolve_temperature(self.temperature, units)?;
        // MBA-1416: a declared QNH reduces against this command's own --altitude.
        let pressure = apply_pressure_mode(
            UnitConverter::resolve_pressure(self.pressure, units)?,
            self.altitude,
            self.pressure_type,
            units,
        );

        Ok((
            HoldCurveLoad {
                velocity_mps: UnitConverter::velocity_to_metric(velocity, units),
                bc,
                mass_kg: UnitConverter::mass_to_metric(mass, units),
                diameter_m: UnitConverter::diameter_to_metric(diameter, units),
                drag_model: self.drag_model,
                sight_height_m: UnitConverter::sight_height_to_metric(sight_height, units),
                zero_distance_m: UnitConverter::distance_to_metric(zero_distance, units),
                temperature_c: UnitConverter::temperature_to_metric(temperature, units),
                pressure_hpa: UnitConverter::pressure_to_metric(pressure, units),
                humidity: self.humidity,
                altitude_m: UnitConverter::altitude_to_metric(self.altitude, units),
                wind_speed_mps: UnitConverter::wind_to_metric(self.wind_speed, units),
                wind_direction_deg: self.wind_direction.degrees,
            },
            profile,
        ))
    }
}

/// CLI-facing mirror of `ballistics_engine::reticle::FocalPlane` (MBA-1361), the same thin
/// `ValueEnum` wrapper pattern as `WindReferenceArg`.
#[derive(Debug, Clone, Copy, ValueEnum, Default, PartialEq, Eq)]
enum FocalPlaneArg {
    /// First focal plane: subtensions are the same at every magnification
    #[default]
    Ffp,
    /// Second focal plane: subtensions scale as reference-mag / magnification
    Sfp,
}

impl From<FocalPlaneArg> for FocalPlane {
    fn from(arg: FocalPlaneArg) -> Self {
        match arg {
            FocalPlaneArg::Ffp => FocalPlane::First,
            FocalPlaneArg::Sfp => FocalPlane::Second,
        }
    }
}

#[allow(
    clippy::large_enum_variant,
    reason = "variants intentionally mirror the stable flat Clap command shape"
)]
#[derive(Subcommand)]
enum ProfileAction {
    /// Save a new profile
    Save {
        /// Profile name (used for recall)
        name: String,

        /// Initial velocity (fps or m/s based on --units)
        #[arg(short = 'v', long, value_parser = f64_range(0.0, 6000.0))]
        velocity: f64,

        /// Ballistic coefficient
        #[arg(short = 'b', long, value_parser = f64_range(0.001, 2.0))]
        bc: f64,

        /// Which standard atmosphere `--bc` is referenced to (MBA-1365). Most published
        /// BCs (and this engine's own retardation math) assume ICAO; some vendors
        /// (notably Sierra, Hornady, and Barnes for many bullets) instead publish BCs
        /// referenced to the older, denser Army Standard Metro atmosphere, which reads
        /// about 1.8% too little drag if fed in unconverted. Has no effect together with
        /// a custom drag table (imported via `.a7p`) — that path divides by sectional
        /// density, not a BC, so no reference conversion is meaningful there.
        #[arg(long, value_enum, default_value = "icao")]
        bc_reference: BcReferenceStandard,

        /// Mass (grains for imperial, grams for metric)
        #[arg(short = 'm', long, value_parser = f64_range(0.1, 2000.0))]
        mass: f64,

        /// Diameter (inches for imperial, mm for metric)
        #[arg(short = 'd', long, value_parser = f64_range(0.01, 60.0))]
        diameter: f64,

        /// Drag model (G1, G2, G5, G6, G7, G8, GI, GS, RA4)
        #[arg(long, default_value = "g1")]
        drag_model: DragModel,

        /// Barrel twist rate (inches per turn for imperial, mm per turn for metric)
        #[arg(long)]
        twist_rate: Option<f64>,

        /// Sight height above bore (inches for imperial, mm for metric)
        #[arg(long)]
        sight_height: Option<f64>,

        /// Default zero distance (yards for imperial, meters for metric)
        #[arg(long)]
        zero_distance: Option<f64>,

        /// Default temperature (Fahrenheit for imperial, Celsius for metric; default 59 F / 15 C)
        #[arg(long)]
        temperature: Option<f64>,

        /// Default pressure (inHg for imperial, hPa for metric; default 29.92 inHg / 1013.25 hPa)
        #[arg(long)]
        pressure: Option<f64>,

        /// Whether the saved `pressure` is absolute station pressure (default) or a
        /// sea-level-corrected altimeter setting (QNH, MBA-1397). See
        /// `trajectory --pressure-type` for the full explanation.
        #[arg(long, value_enum, default_value = "absolute")]
        pressure_type: PressureReferenceMode,

        /// Default humidity
        #[arg(long, default_value = "50.0", value_parser = f64_range(0.0, 100.0))]
        humidity: f64,

        /// Default altitude
        #[arg(long, default_value = "0.0")]
        altitude: f64,

        /// Default density altitude (feet imperial / meters metric; MBA-1366). See
        /// `trajectory --density-altitude` for the full precedence rule. Stored in the saved
        /// profile alongside `temperature`/`pressure`/`altitude`/`humidity` — like those
        /// fields, `trajectory --saved-profile` does not currently read any of them back (only
        /// `--location`/CSV feeds shot-day atmosphere there); this is for round-trip storage
        /// parity, not a new saved-profile atmosphere source.
        // MBA-1420: bound the flag so an out-of-range value fails naming --density-altitude.
        // Without this an extreme value drives the pressure inverse negative and surfaces as
        // "atmosphere.pressure must be finite", pointing at a field the user never typed. The
        // band is deliberately wide (and unit-agnostic, since the flag is feet imperial /
        // meters metric): -2000 and 100000 both solve fine, so this only catches nonsense.
        #[arg(long, allow_hyphen_values = true, value_parser = f64_range(-5000.0, 120000.0))]
        density_altitude: Option<f64>,

        /// Bullet name/description
        #[arg(long)]
        bullet_name: Option<String>,

        /// Wind speed (mph or m/s based on --units)
        #[arg(long)]
        wind_speed: Option<f64>,

        /// Wind direction (MBA-1367: degrees or clock position, shared help const;
        /// stored in the profile as plain degrees)
        #[arg(long, value_parser = parse_wind_direction_arg, help = WIND_DIRECTION_HELP)]
        wind_direction: Option<ParsedWindDirection>,

        /// Shooting angle (degrees, positive = uphill, negative = downhill)
        #[arg(long, allow_hyphen_values = true)]
        shooting_angle: Option<f64>,

        /// Auto-zero / zero distance for trajectory
        #[arg(long)]
        auto_zero: Option<f64>,

        /// Right-hand twist (default: true)
        #[arg(long)]
        twist_right: Option<bool>,

        /// Enable velocity-based BC segmentation
        #[arg(long)]
        use_bc_segments: Option<bool>,

        /// Bullet length (inches for imperial, mm for metric; used for BC table lookup)
        #[arg(long)]
        bullet_length: Option<f64>,

        /// Turret elevation click graduation for `--adjustment-unit clicks` (MBA-1355), e.g. 0.1mil
        /// or 0.25moa. Validated at save time so a profile can't store garbage. Without
        /// this flag, re-saving carries the stored value forward unchanged (MBA-1348
        /// review fix) — the twelve turret/hold fields below depend on a click
        /// graduation existing at all, so leaving just this one field on the old
        /// reset-on-omit contract would silently break every carried-forward turret
        /// profile on its very next unrelated re-save. Remove it with --clear-click.
        #[arg(long)]
        elevation_click: Option<String>,

        /// Turret windage click graduation for `--adjustment-unit clicks` (MBA-1355); falls back to
        /// the elevation graduation when neither this flag nor a stored value is
        /// present (see `resolve_click_values`/`ProfileData::optic_profile`). Without
        /// this flag, re-saving carries the stored value forward unchanged, like
        /// `--elevation-click` above.
        #[arg(long)]
        windage_click: Option<String>,

        /// Remove the stored click graduation (MBA-1348 review fix round 2) — clears
        /// BOTH `--elevation-click` and `--windage-click` at once; there is no per-axis
        /// clear, since windage already falls back to elevation and clearing one
        /// without the other has no clean meaning. Mutually exclusive with
        /// `--elevation-click`/`--windage-click` in the same invocation. If the
        /// profile's other eleven turret/hold fields are still set (carried forward or
        /// freshly given), clearing the click alone still fails save-time validation —
        /// a turret model needs a click graduation to be usable at all — naming
        /// `--elevation-click` as the fix; combine with `--clear-turret` to clear
        /// everything at once instead.
        #[arg(long)]
        clear_click: bool,

        /// Remove this profile's DSF (drop-scale-factor) table, if any (MBA-1357). Without
        /// this flag, re-saving an existing profile carries its DSF table forward
        /// unchanged — `profile save` otherwise has no way to express "keep the DSF
        /// calibration, just update these other fields".
        #[arg(long)]
        clear_dsf: bool,

        /// Attach the optic's reticle from a JSON description file (MBA-1361), so
        /// `reticle hold --profile NAME` can place a firing solution in it. Produce one
        /// with `reticle generate ... -o json`. Validated at save time. Without this
        /// flag, re-saving carries any attached reticle forward unchanged.
        #[arg(long, value_name = "FILE")]
        reticle_json: Option<PathBuf>,

        /// Remove this profile's attached reticle, if any (MBA-1361) — the
        /// `--clear-dsf` counterpart for the reticle field.
        #[arg(long)]
        clear_reticle: bool,

        /// Elevation turret's click detents per full revolution (MBA-1348), e.g. 12 on a
        /// turret whose cap marks whole revolutions. Omit when the turret has no
        /// revolution markings, or the count isn't known. Without this flag, re-saving
        /// carries the stored value forward unchanged.
        #[arg(long)]
        clicks_per_rev: Option<u32>,

        /// Whether the elevation turret hard-stops at its lowest travel so it cannot be
        /// dialed below zero (MBA-1348): `true` or `false`. Purely descriptive. Without
        /// this flag, re-saving carries the stored value forward unchanged.
        #[arg(long)]
        zero_stop: Option<bool>,

        /// Elevation travel remaining UP from the current zero, e.g. 28mil or 96moa
        /// (MBA-1348); stored in mil. Required together with --travel-down. Without
        /// this flag, re-saving carries the stored value forward unchanged.
        #[arg(long, value_parser = parse_angular_mil)]
        travel_up: Option<f64>,

        /// Elevation travel remaining DOWN from the current zero (MBA-1348); stored in
        /// mil. Required together with --travel-up. Without this flag, re-saving
        /// carries the stored value forward unchanged.
        #[arg(long, value_parser = parse_angular_mil)]
        travel_down: Option<f64>,

        /// Windage travel remaining LEFT from the current zero (MBA-1348); stored in mil.
        /// Required together with --windage-travel-right. Without this flag, re-saving
        /// carries the stored value forward unchanged.
        #[arg(long, value_parser = parse_angular_mil)]
        windage_travel_left: Option<f64>,

        /// Windage travel remaining RIGHT from the current zero (MBA-1348); stored in
        /// mil. Required together with --windage-travel-left. Without this flag,
        /// re-saving carries the stored value forward unchanged.
        #[arg(long, value_parser = parse_angular_mil)]
        windage_travel_right: Option<f64>,

        /// The reticle's usable hold extent ABOVE center (MBA-1348); stored in mil.
        /// Required together with --hold-down/--hold-left/--hold-right. Without this
        /// flag, re-saving carries the stored value forward unchanged.
        #[arg(long, value_parser = parse_angular_mil)]
        hold_up: Option<f64>,

        /// The reticle's usable hold extent BELOW center (MBA-1348); stored in mil. See
        /// --hold-up. Without this flag, re-saving carries the stored value forward
        /// unchanged.
        #[arg(long, value_parser = parse_angular_mil)]
        hold_down: Option<f64>,

        /// The reticle's usable hold extent LEFT of center (MBA-1348); stored in mil.
        /// See --hold-up. Without this flag, re-saving carries the stored value forward
        /// unchanged.
        #[arg(long, value_parser = parse_angular_mil)]
        hold_left: Option<f64>,

        /// The reticle's usable hold extent RIGHT of center (MBA-1348); stored in mil.
        /// See --hold-up. Without this flag, re-saving carries the stored value forward
        /// unchanged.
        #[arg(long, value_parser = parse_angular_mil)]
        hold_right: Option<f64>,

        /// The elevation turret's current dialed offset from zero, signed: positive is
        /// dialed UP (MBA-1348); stored in mil. Required together with --turret-wind.
        /// Without this flag, re-saving carries the stored value forward unchanged.
        #[arg(long, allow_hyphen_values = true, value_parser = parse_angular_mil)]
        turret_elev: Option<f64>,

        /// The windage turret's current dialed offset from zero, signed: positive is
        /// dialed RIGHT (MBA-1348); stored in mil. Required together with --turret-elev.
        /// Without this flag, re-saving carries the stored value forward unchanged.
        #[arg(long, allow_hyphen_values = true, value_parser = parse_angular_mil)]
        turret_wind: Option<f64>,

        /// Remove all twelve turret-mechanics/reticle-hold-bound fields (MBA-1348 review
        /// fix) — the `--clear-dsf`/`--clear-reticle` counterpart for the turret block.
        /// Mutually exclusive with any of the twelve flags above in the same invocation
        /// (ambiguous intent: clear or set is not a decision this command guesses at).
        /// Does NOT clear `--elevation-click`/`--windage-click`, which are a separate
        /// field pair with their own carry-forward contract and their own
        /// `--clear-click` flag; combine both to clear everything optic-related.
        #[arg(long)]
        clear_turret: bool,
    },

    /// Import a profile from a third-party file (.a7p — ArcherBC2 format)
    #[cfg(feature = "profile-import")]
    Import {
        /// Path to the .a7p file
        file: PathBuf,

        /// Profile name to save under (defaults to the file's profile name, sanitized)
        #[arg(long)]
        name: Option<String>,

        /// Parse and show the full mapping report without saving anything
        #[arg(long)]
        dry_run: bool,

        /// Treat a checksum mismatch as a fatal error instead of a warning
        #[arg(long)]
        strict: bool,

        /// The source device's scope click graduation, e.g. 0.1mil or 0.25moa (MBA-1359).
        /// The .a7p format stores its zeroing state (`zero_x`/`zero_y`) as raw device
        /// CLICK counts but does not store the device's click size, so without this flag
        /// those fields cannot be converted and are reported as unmapped (unchanged
        /// behavior). With it, the click counts are converted to a linear POI offset at
        /// the file's zero distance and stored as the profile's zero POI offset fields.
        #[arg(long, value_name = "CLICK")]
        zero_click: Option<String>,
    },

    /// List all saved profiles
    List,

    /// Show details of a saved profile
    Show {
        /// Profile name
        name: String,
    },

    /// Delete a saved profile
    Delete {
        /// Profile name
        name: String,
    },

    /// Manage a profile's named zero sets (MBA-1360): alternate zero distances and
    /// per-load dial corrections, selected at solve time with `--zero-set NAME`
    ZeroSet {
        #[command(subcommand)]
        action: ZeroSetAction,
    },
}

/// `profile zero-set` verbs (MBA-1360).
#[derive(Subcommand)]
enum ZeroSetAction {
    /// Add (or replace, by name) a zero set on a saved profile
    Add {
        /// Profile name
        profile: String,

        /// Zero set name (selected later with `--zero-set NAME`)
        #[arg(long)]
        name: String,

        /// This set's zero distance (yards imperial / meters metric, global --units) —
        /// same convention as the profile's own zero_distance field. Omit for a
        /// dial-correction-only set.
        #[arg(long)]
        zero_distance: Option<f64>,

        /// Elevation dial correction in MILs added to elevation adjustments when this
        /// set is selected; positive = dial UP more. A load that impacts 0.25 mil HIGH
        /// relative to the master zero needs -0.25 here.
        #[arg(long, value_name = "MIL", allow_hyphen_values = true)]
        poi_up: Option<f64>,

        /// Windage dial correction in MILs added to windage adjustments when this set
        /// is selected; positive = dial RIGHT more. A load that impacts 0.1 mil RIGHT
        /// relative to the master zero needs -0.1 here.
        #[arg(long, value_name = "MIL", allow_hyphen_values = true)]
        poi_right: Option<f64>,

        /// Free-form note stored with the set (e.g. "suppressed", "subsonic load")
        #[arg(long)]
        notes: Option<String>,
    },

    /// Remove a named zero set from a saved profile
    Remove {
        /// Profile name
        profile: String,

        /// Zero set name to remove
        #[arg(long)]
        name: String,
    },

    /// List a saved profile's zero sets
    List {
        /// Profile name
        profile: String,
    },
}

// UnitSystem and DragModelArg moved to ballistics_engine::truing (MBA-1343).

#[derive(Debug, Clone, Copy, ValueEnum)]
enum OutputFormat {
    Json,
    Csv,
    Table,
    Pdf,
}

/// MBA-1375 phase-one drag families. This intentionally does not reuse the full public
/// [`DragModel`] `ValueEnum`: accepting a model whose conversion contract has not shipped yet
/// would turn a future-looking CLI spelling into plausible but unsupported output.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
enum BcConvertModelArg {
    G1,
    G7,
}

/// Output forms that actually exist for `bc-convert`. Keeping this separate from the broad
/// [`OutputFormat`] prevents clap from advertising PDF and then rejecting it at runtime.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
enum BcConversionOutputFormat {
    Json,
    Csv,
    Table,
}

impl From<BcConvertModelArg> for DragModel {
    fn from(value: BcConvertModelArg) -> Self {
        match value {
            BcConvertModelArg::G1 => DragModel::G1,
            BcConvertModelArg::G7 => DragModel::G7,
        }
    }
}

/// CLI-facing mirror of `ballistics_engine::recoil::FirearmType`, selecting SAAMI's
/// type-keyed propellant-gas-velocity multiplier for `recoil --firearm-type` (MBA-1372).
/// Kept as a thin clap `ValueEnum` here (rather than deriving `ValueEnum` on the lib enum
/// itself) so `recoil.rs` stays clap-free and trivially compiles for wasm32, matching the
/// established `WindShearModelArg` pattern.
#[derive(Debug, Clone, Copy, PartialEq, ValueEnum, Default)]
enum RecoilFirearmTypeArg {
    #[default]
    Rifle,
    Pistol,
    #[value(name = "shotgun-average", alias = "shotgun")]
    ShotgunAverage,
    #[value(name = "shotgun-long")]
    ShotgunLong,
}

impl RecoilFirearmTypeArg {
    fn to_engine(self) -> FirearmType {
        match self {
            RecoilFirearmTypeArg::Rifle => FirearmType::Rifle,
            RecoilFirearmTypeArg::Pistol => FirearmType::Pistol,
            RecoilFirearmTypeArg::ShotgunAverage => FirearmType::ShotgunAverage,
            RecoilFirearmTypeArg::ShotgunLong => FirearmType::ShotgunLong,
        }
    }
}

// DropUnit moved to ballistics_engine::truing (MBA-1343).

#[derive(Debug, Clone, Copy, ValueEnum)]
enum MonteCarloOutput {
    Summary,
    /// Full JSON report (also accepted as `full`).
    // MBA-1352: `json` is now the primary/listed spelling (so it shows in `--help`'s
    // possible-values, matching the `-o json` convention every sibling decision-support
    // subcommand uses); `full` survives as a hidden alias so existing scripts keep working.
    // Fixed-count -> `MonteCarloResult` (now with the additive `hit_probability_ci` key);
    // `--adaptive` -> `AdaptiveMcReportV1` verbatim. See the dispatch match on `output` in
    // each of `run_monte_carlo`/`run_monte_carlo_adaptive`.
    #[value(name = "json", alias = "full")]
    Full,
    Statistics,
}

/// Wind-shear boundary-layer profile model. Parsed as a clap enum so invalid
/// values are rejected at the command line (MBA-965). Both snake_case (the
/// historical/engine spelling) and kebab-case are accepted for each model.
#[derive(Debug, Clone, Copy, PartialEq, ValueEnum)]
enum WindShearModelArg {
    None,
    #[value(name = "logarithmic")]
    Logarithmic,
    #[value(
        name = "power_law",
        alias = "power-law",
        alias = "powerlaw",
        alias = "exponential"
    )]
    PowerLaw,
    #[value(name = "ekman_spiral", alias = "ekman-spiral", alias = "ekman")]
    EkmanSpiral,
    #[value(name = "custom_layers", alias = "custom-layers", alias = "custom")]
    CustomLayers,
}

impl WindShearModelArg {
    /// Canonical lower-snake string understood by the engine
    /// (`cli_api`/`wind_shear`).
    fn as_engine_str(self) -> &'static str {
        match self {
            WindShearModelArg::None => "none",
            WindShearModelArg::Logarithmic => "logarithmic",
            WindShearModelArg::PowerLaw => "power_law",
            WindShearModelArg::EkmanSpiral => "ekman_spiral",
            WindShearModelArg::CustomLayers => "custom_layers",
        }
    }
}

/// CLI-facing mirror of `ballistics_engine::wind::WindReference` (MBA-1368), same
/// thin-`ValueEnum`-wrapper pattern as `DropsReferenceArg` below.
#[derive(Debug, Clone, Copy, ValueEnum, Default, PartialEq, Eq)]
enum WindReferenceArg {
    /// Wind directions are shooter-relative wind-FROM angles (0 = headwind) — the
    /// historical default
    #[default]
    Shooter,
    /// Wind directions are earth-fixed compass bearings (0 = north), re-referenced
    /// against --shot-direction at solve time (relative = bearing - shot azimuth)
    Compass,
}

/// Resolves the wind reference frame ONCE at the CLI boundary (MBA-1368): shooter mode
/// returns the entered value untouched (bit-identical); compass mode requires a shot
/// azimuth (hard error naming --shot-direction — never a silent
/// treat-as-shooter-relative, MBA-1425) and rejects clock-position entries (a clock
/// position is shooter-relative by definition, MBA-1367), then re-references the
/// bearing as `bearing - shot azimuth`, normalized to [0, 360). Every wind direction a
/// run consumes — the single --wind-direction (or its CSV fallback) and each
/// --wind-segment angle — flows through here BEFORE any engine wind structure is
/// built, so downstream physics never sees a bearing.
fn resolve_wind_reference(
    wind_ref: WindReferenceArg,
    direction_deg: f64,
    entered_as_clock: bool,
    shot_direction: Option<f64>,
) -> Result<f64, String> {
    match wind_ref {
        WindReferenceArg::Shooter => Ok(direction_deg),
        WindReferenceArg::Compass => {
            if entered_as_clock {
                return Err(
                    "clock positions are shooter-relative by definition; use degrees \
                     with --wind-ref compass"
                        .to_string(),
                );
            }
            let Some(azimuth) = shot_direction else {
                return Err(
                    "--wind-ref compass requires --shot-direction (earth-fixed wind \
                     bearings are re-referenced against the shot azimuth; omitting it \
                     would silently treat bearings as shooter-relative)"
                        .to_string(),
                );
            };
            Ok(
                ballistics_engine::wind::compass_bearing_to_shooter_relative_deg(
                    direction_deg,
                    azimuth,
                ),
            )
        }
    }
}

/// CLI-facing mirror of `ballistics_engine::DropsReference` (MBA-1403), following the
/// thin-`ValueEnum`-wrapper pattern of `RecoilFirearmTypeArg` so `cli_api` stays clap-free.
#[derive(Debug, Clone, Copy, ValueEnum, Default, PartialEq, Eq)]
enum DropsReferenceArg {
    /// Drop measured perpendicular to the line of sight (the historical default)
    #[default]
    Los,
    /// Drop measured vertically in the target plane: LOS-perpendicular drop scaled by
    /// 1/cos(shooting angle), matching JBM's "target plane" reference
    Target,
}

impl DropsReferenceArg {
    fn to_engine(self) -> ballistics_engine::DropsReference {
        match self {
            DropsReferenceArg::Los => ballistics_engine::DropsReference::Los,
            DropsReferenceArg::Target => ballistics_engine::DropsReference::Target,
        }
    }
}

/// Terminal chart renderer for `trajectory --plot` (MBA-1320). Bare `--plot` (no value)
/// resolves to `Braille` via clap's `default_missing_value`; see the `plot` field on
/// `Commands::Trajectory`.
#[derive(Debug, Clone, Copy, ValueEnum, PartialEq, Eq)]
enum PlotStyle {
    /// Unicode braille-dot canvas (2x4 dots per character cell). The default terminal
    /// chart renderer.
    Braille,
    /// ASCII '*'-per-cell canvas, for terminals/fonts without braille glyph coverage.
    Ascii,
}

impl PlotStyle {
    fn as_canvas_style(self) -> terminal_plot::CanvasStyle {
        match self {
            PlotStyle::Braille => terminal_plot::CanvasStyle::Braille,
            PlotStyle::Ascii => terminal_plot::CanvasStyle::Ascii,
        }
    }
}

#[derive(Debug, Serialize, Deserialize)]
struct TrajectoryPoint {
    time: f64,
    x: f64,
    y: f64,
    z: f64,
    velocity: f64,
    energy: f64,
    /// Mover-ring linear radius, meters (MBA-1325): `target_speed_mps * time`. Present
    /// only when `--target-speed` was supplied (> 0); unit is fixed at meters regardless
    /// of `--units` (units-in-the-name, see MBA-1315).
    #[serde(skip_serializing_if = "Option::is_none")]
    mover_ring_m: Option<f64>,
    /// Mover-ring angular radius, milliradians: `mover_ring_m / downrange_m * 1000`.
    /// Omitted at the muzzle (downrange = 0, ratio undefined) and whenever
    /// `mover_ring_m` itself is absent.
    #[serde(skip_serializing_if = "Option::is_none")]
    mover_ring_mil: Option<f64>,
    /// The projectile's own effective drag coefficient at this point, dimensionless (MBA-1423).
    ///
    /// Present only when `--with-drag-coefficient` was supplied, so JSON without the flag keeps
    /// every key it had. Serialized last for the same reason the mover-ring fields were appended:
    /// the pre-existing keys stay byte-identical ahead of it.
    ///
    /// This is the projectile's Cd, not the reference table's — see the flag's help for the
    /// form-factor scaling and why a segmented BC shows band steps here. Absent on a point whose
    /// sectional density is unknown, which is why it stays `Option` even under the flag.
    #[serde(skip_serializing_if = "Option::is_none")]
    drag_coefficient: Option<f64>,
}

#[derive(Debug, Serialize, Deserialize)]
struct TrajectoryResult {
    /// Unit system the numeric fields are expressed in ("imperial" or "metric").
    units: String,
    max_range: f64,
    max_height: f64,
    time_of_flight: f64,
    impact_velocity: f64,
    impact_energy: f64,
    stability_coefficient: Option<f64>,
    spin_drift: Option<f64>,
    /// The zero angle auto-zero solved for this trajectory, degrees above bore-horizontal
    /// (MBA-1402). Present only when `--auto-zero` (or a saved profile's `auto_zero`/
    /// `zero_distance`) ran a zero solve; absent on a bare `--angle` run.
    #[serde(skip_serializing_if = "Option::is_none")]
    zero_angle_degrees: Option<f64>,
    /// Minimum pitch-damping coefficient (only when --enable-pitch-damping).
    #[serde(skip_serializing_if = "Option::is_none")]
    min_pitch_damping: Option<f64>,
    /// Mach number when entering the transonic regime (pitch-damping diagnostic).
    #[serde(skip_serializing_if = "Option::is_none")]
    transonic_mach: Option<f64>,
    /// Maximum yaw angle during flight, radians (only when --enable-precession).
    #[serde(skip_serializing_if = "Option::is_none")]
    max_yaw_angle: Option<f64>,
    /// Maximum precession angle during flight, radians (only when --enable-precession).
    #[serde(skip_serializing_if = "Option::is_none")]
    max_precession_angle: Option<f64>,
    /// Final pitch angle, radians (only when --enable-precession).
    #[serde(skip_serializing_if = "Option::is_none")]
    final_pitch_angle: Option<f64>,
    /// Final yaw angle, radians (only when --enable-precession).
    #[serde(skip_serializing_if = "Option::is_none")]
    final_yaw_angle: Option<f64>,
    trajectory: Vec<TrajectoryPoint>,
    /// Self-describing metadata for this document (MBA-1315), additive only: every key/value
    /// above and every `trajectory[]` point key are unchanged. Appended last so the
    /// pre-existing fields serialize byte-identically ahead of it. See `TrajectoryLegend` for
    /// how the unit/axis text was derived (empirically, from controlled crosswind/no-wind
    /// runs) and CLI_USAGE.md's JSON Format section for the same text with worked examples.
    legend: TrajectoryLegend,
}

/// Concrete unit labels and `trajectory[]` axis semantics for one [`TrajectoryResult`]
/// document (MBA-1315). A field tester's tooling once misread `trajectory[].x`/`z` as feet
/// and swapped their meaning because the legacy JSON never stated either; this block states
/// both. Nested under one `legend` key rather than top-level `units`/`axes` keys because
/// `units` already names the pre-existing "imperial"/"metric" string field on
/// [`TrajectoryResult`].
#[derive(Debug, Serialize, Deserialize)]
struct TrajectoryLegend {
    /// Concrete unit abbreviation for each numeric quantity family in this document.
    units: TrajectoryLegendUnits,
    /// `trajectory[]` point axis semantics, verified empirically (not assumed): a pure
    /// crosswind run and a no-wind run, comparing which point component moved, in which sign
    /// direction, against the table output (see `tests/legacy_trajectory_json_contract.rs`).
    axes: TrajectoryLegendAxes,
}

/// Unit abbreviation for each numeric quantity family. `distance` applies to
/// `trajectory[].x`/`y`/`z`, `max_range`, `max_height`, and `spin_drift`; `velocity` to
/// `trajectory[].velocity` and `impact_velocity`; `energy` to `trajectory[].energy` and
/// `impact_energy`. Angle fields (`max_yaw_angle`, `max_precession_angle`,
/// `final_pitch_angle`, `final_yaw_angle`) and time fields are unit-invariant (always
/// radians / seconds) and are not covered here.
#[derive(Debug, Serialize, Deserialize)]
struct TrajectoryLegendUnits {
    distance: String,
    velocity: String,
    energy: String,
}

/// Axis semantics for `trajectory[]` points. `x` is lateral and `z` is downrange in THIS
/// output — the reverse of the x=lateral/z=depth convention some 3D tooling assumes, and the
/// original source of the field-tester misdiagnosis this ticket fixes.
#[derive(Debug, Serialize, Deserialize)]
struct TrajectoryLegendAxes {
    x: String,
    y: String,
    z: String,
}

impl TrajectoryLegend {
    fn for_units(units: UnitSystem) -> Self {
        let (distance, velocity, energy) = match units {
            UnitSystem::Imperial => ("yd", "fps", "ft-lb"),
            UnitSystem::Metric => ("m", "m/s", "J"),
        };
        TrajectoryLegend {
            units: TrajectoryLegendUnits {
                distance: distance.to_string(),
                velocity: velocity.to_string(),
                energy: energy.to_string(),
            },
            axes: TrajectoryLegendAxes {
                x: "lateral offset from the muzzle's initial aiming direction; positive means \
                    to the shooter's right (e.g. a crosswind FROM the left, --wind-direction \
                    270, drifts x positive; FROM the right, --wind-direction 90, drifts x \
                    negative). Zero at the muzzle."
                    .to_string(),
                y: "height above the ground in the world frame; positive means up. Starts near \
                    bore height and reaches 0 at ground impact. This is NOT height above the \
                    line of sight (compare solve-json v1's LOS-relative drop_m)."
                    .to_string(),
                z: "downrange distance from the muzzle; zero at the muzzle, always increasing."
                    .to_string(),
            },
        }
    }
}

/// Configuration struct for run_trajectory(), replacing the 31+ parameter signature.
/// All distance/velocity/mass/temperature values should be in metric units
/// (converted before construction), except where noted.
struct TrajectoryConfig {
    // Core ballistic params (metric)
    velocity: f64,
    angle: f64,
    bc: f64,
    // Which standard atmosphere `bc` is referenced to (MBA-1365). `Icao` is a no-op.
    bc_reference_standard: BcReferenceStandard,
    mass: f64,
    diameter: f64,
    bullet_length: f64,
    drag_model: DragModel,
    max_range: f64,
    time_step: f64,

    // Environment (metric)
    temperature: f64,
    pressure: f64,
    // Whether `pressure` is absolute station pressure or a sea-level-corrected altimeter
    // setting (QNH) that must be reduced before use (MBA-1397).
    pressure_type: PressureReferenceMode,
    humidity: f64,
    altitude: f64,
    // MBA-1366: true when `--density-altitude` (or a CSV DA/DENSITY_ALTITUDE column) already
    // fully resolved `temperature`/`pressure`/`altitude` above via
    // `atmosphere::resolve_atmosphere_for_density_altitude`. `run_trajectory` uses this to skip
    // re-deriving through `resolve_station_conditions_with_pressure_mode` a second time — that
    // function's default-sentinel heuristic (used to detect an OMITTED --pressure/--temperature)
    // could otherwise misinterpret an already-resolved DA value that happens to land near the
    // sea-level standard as "omitted" and silently re-derive it from `altitude` instead.
    density_altitude_active: bool,

    // Wind (metric)
    wind_speed: f64,
    wind_direction: f64, // degrees at the CLI boundary
    wind_vertical: f64,  // m/s, positive = updraft
    // Downrange-segmented wind (engine units: speed km/h, angle deg, distance m).
    // When non-empty, overrides the scalar wind above.
    wind_segments: Vec<ballistics_engine::wind::WindSegment>,

    // Output
    output: OutputFormat,
    full: bool,
    // Inline terminal chart (MBA-1320); None = no chart (the default). Only rendered for
    // OutputFormat::Table — see run_trajectory's OutputFormat::Table arm.
    plot: Option<PlotStyle>,
    units: UnitSystem,

    // Sight / bore geometry (metric)
    sight_height: f64,
    bore_height: f64,
    ignore_ground_impact: bool,
    // Rifle cant, degrees (CLI boundary; converted to radians for BallisticInputs.cant_angle).
    cant: f64,
    // MBA-1359: deliberate POI offset at the zero range (meters). Carried onto the flight
    // inputs; when `zero_solve_distance_m` is Some, run_trajectory applies the horizontal
    // offset as an azimuth bias (the vertical bias already rides inside `angle`, which the
    // dispatch's zero solve returned biased).
    zero_poi_vertical_m: f64,
    zero_poi_horizontal_m: f64,
    // MBA-1396: lateral sight-to-bore mount offset (meters, positive = sight right of
    // bore). Physical geometry on the flight inputs; its windage-zero convergence shares
    // the MBA-1359 azimuth term via windage_zero_bias_rad.
    sight_offset_lateral_m: f64,
    // Some(zero distance, meters) iff the dispatch solved a zero at that distance
    // (--auto-zero or a profile zero); None for an explicit --angle flight.
    zero_solve_distance_m: Option<f64>,

    // BC options
    use_bc_segments: bool,
    use_cluster_bc: bool,
    bc_segments_data: Option<Vec<BCSegmentData>>,
    // Custom drag deck (--drag-table), takes precedence over the G-model + BC when set.
    custom_drag_table: Option<ballistics_engine::drag::DragTable>,
    // MBA-1356: whole-curve scale for the custom deck (1.0 = neutral). Only meaningful
    // alongside custom_drag_table — see BallisticInputs::cd_scale.
    cd_scale: f64,

    // Advanced physics toggles
    enable_magnus: bool,
    enable_coriolis: bool,
    enable_spin_drift: bool,
    enable_aerodynamic_jump: bool,
    enable_wind_shear: bool,
    wind_shear_model: WindShearModelArg,
    enable_pitch_damping: bool,
    enable_precession: bool,

    // Sampling
    sample_trajectory: bool,
    sample_interval: f64,
    // MBA-1403: which plane sampled drop values are referenced to. `Los` (the default) is
    // byte-identical to historical output; `Target` scales sampled drop (and every
    // downstream mil/moa conversion derived from it) by 1/cos(shooting_angle), relabels
    // the sampled table/CSV drop column, and lets a supplied target height slope the
    // sampler's LOS datum.
    drops_reference: DropsReferenceArg,
    // MBA-1358: scope tracking correction factors (dial-unit outputs DIVIDED by the
    // axis's CF exactly once; raw inches never). 1.0 = no correction, byte-identical.
    // Elevation corrects the PDF dope card's drop column; windage corrects the PDF
    // wind/lead columns and every mover Ring dial output (table/JSON/CSV).
    elevation_cf: f64,
    windage_cf: f64,
    // MBA-1360: the selected zero set's per-load dial corrections (MILs; 0.0 = no set
    // selected, an exact no-op). Added to the PDF dope card's Drop/Wind dial columns
    // (total-correction dials) BEFORE the CF division above; the Lead column and the
    // mover Ring are COMPONENT holds and stay bias-free (the wind dial they compose
    // with already carries the bias).
    zero_set_elevation_bias_mil: f64,
    zero_set_windage_bias_mil: f64,

    // Integration method
    use_rk4: bool,
    use_rk45: bool,

    // Bullet / rifling
    twist_rate: Option<f64>,
    twist_right: bool,
    latitude: Option<f64>,
    shot_direction: Option<f64>, // compass bearing of the shot, degrees, 0=N (for Coriolis)
    shooting_angle: f64,

    // Powder sensitivity
    use_powder_sensitivity: bool,
    powder_temp_sensitivity: f64,
    powder_temp: f64,
    // Optional measured (temperature_celsius, muzzle_velocity_m_s) curve; SI, sorted.
    powder_temp_curve: Option<Vec<(f64, f64)>>,
    // Powder temperature (Celsius) to interpolate the curve at; None = ambient temp.
    powder_curve_temp_c: Option<f64>,

    // Mover ring (MBA-1325): target speed in display units (mph imperial / m/s metric,
    // same convention as `lead --target-speed`). 0.0 (default) disables the per-point
    // Ring column/fields in every output format; also feeds the PDF Lead column.
    target_speed: f64,
    // Per-point effective drag coefficient (MBA-1423): when true, `--full` JSON gains a
    // `drag_coefficient` key per point. False (default) leaves the document byte-identical,
    // so the flag cannot disturb an existing consumer.
    with_drag_coefficient: bool,
    // Angular unit for the ring TABLE column (mil or moa) — from --adjustment-unit,
    // which trajectory already exposes for the PDF dope card. CSV keeps ring_mil and
    // JSON keeps mover_ring_m/mover_ring_mil regardless: those carry the unit in the
    // name (the contract), the table is the human display surface.
    adjustment_unit: AdjustmentUnit,
    // Resolved turret click graduations for `--adjustment-unit clicks` (MBA-1355): Some(...) iff
    // adjustment_unit == Clicks (resolved once, eagerly, in the Trajectory command's
    // dispatch — see resolve_click_values); None for every other adjustment_unit. Drives
    // the mover Ring column and the PDF dope-card rows. MBA-1410: the independent
    // windage-axis UNIT (as opposed to this graduation) lives only on `PdfMetadata` —
    // it is read solely by the PDF dope card's Wind/Lead columns, which already carry
    // their own `PdfMetadata` copy; the mover Ring column stays elevation-only.
    elevation_click: Option<ClickValue>,
    windage_click: Option<ClickValue>,

    // PDF metadata
    pdf_metadata: Option<PdfMetadata>,

    // MBA-1357: saved profile's DSF (drop-scale-factor) table, already validated. `Some`
    // only when --saved-profile pointed at a profile carrying dsf_points. run_trajectory
    // applies it (drop-only correction) to every output format and prints a table-only
    // note; see apply_dsf's doc comment for the drop-only invariant.
    dsf_table: Option<DsfTable>,

    // MBA-1402: the zero angle auto-zero solved for this run, degrees above bore-horizontal.
    // `Some` only when --auto-zero (CLI flag or a saved profile's auto_zero/zero_distance) ran
    // a zero solve for this trajectory; `None` on the bare `--angle` path. Additive: every
    // output format prints/serializes nothing new when this is `None`.
    solved_zero_angle_deg: Option<f64>,
}

/// [`HitProbabilityCi::method`]'s only value on the fixed-count path: the classic fixed-`n`
/// Wilson score interval (MBA-1352), as opposed to `--adaptive`'s anytime-valid confidence
/// sequence (`AdaptiveMcReportV1::method`, a different string entirely -- the two must never
/// be confused, since only one of them is still valid after optional stopping).
const MC_FIXED_COUNT_CI_METHOD: &str = "wilson_fixed_n";

/// Additive companion to [`MonteCarloResult::hit_probability`]: the same point estimate's
/// fixed-`n` Wilson interval (MBA-1352), plus the method name, confidence level, and `n`
/// needed to interpret it without cross-referencing anything else in the payload.
#[derive(Debug, Serialize, Deserialize)]
struct HitProbabilityCi {
    method: String,
    confidence_percent: u32,
    low: f64,
    high: f64,
    samples: u64,
}

#[derive(Debug, Serialize, Deserialize)]
struct MonteCarloResult {
    mean_range: f64,
    std_range: f64,
    mean_impact_velocity: f64,
    std_impact_velocity: f64,
    /// Median radial miss among simulations that reached the target plane; `None` when no
    /// simulation reached it.
    cep: Option<f64>,
    target_shortfall_fraction: f64,
    hit_probability: Option<f64>,
    /// `Some` exactly when `hit_probability` is (i.e. only when `--target-distance` was given);
    /// additive -- absent from no `MonteCarloResult` that existed before MBA-1352, and always
    /// present (possibly JSON `null`, matching `hit_probability`'s own null-not-absent
    /// convention) after it.
    hit_probability_ci: Option<HitProbabilityCi>,
}

// Unit conversion functions
struct UnitConverter;

impl UnitConverter {
    // Input conversions (to metric)
    fn velocity_to_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val,
            UnitSystem::Imperial => val * 0.3048, // fps to m/s
        }
    }

    fn mass_to_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val * 0.001,          // grams to kg
            UnitSystem::Imperial => val * GRAINS_TO_KG, // grains to kg
        }
    }

    fn distance_to_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val,
            UnitSystem::Imperial => val * 0.9144, // yards to meters
        }
    }

    fn diameter_to_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val * 0.001,    // mm to meters
            UnitSystem::Imperial => val * 0.0254, // inches to meters
        }
    }

    fn sight_height_to_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val * 0.001,    // mm to meters
            UnitSystem::Imperial => val * 0.0254, // inches to meters
        }
    }

    fn wind_to_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val,
            UnitSystem::Imperial => val * 0.44704, // mph to m/s
        }
    }

    fn temperature_to_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val,
            UnitSystem::Imperial => (val - 32.0) * 5.0 / 9.0, // Fahrenheit to Celsius
        }
    }

    /// Convert a temperature *difference* (delta), not an absolute point.
    /// A 1 F delta equals a 5/9 C delta (no -32 offset). Used to convert
    /// per-degree quantities such as powder temperature sensitivity (MBA-963).
    fn temperature_delta_to_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val,
            UnitSystem::Imperial => val * 5.0 / 9.0, // Fahrenheit delta to Celsius delta
        }
    }

    fn pressure_to_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val,
            UnitSystem::Imperial => val * 33.8639, // inHg to hPa
        }
    }

    /// Resolve the pressure CLI argument AFTER --units is known.
    ///
    /// `None` -> the per-unit standard atmosphere (29.92 inHg / 1013.25 hPa).
    /// `Some(v)` -> validated against a plausible range in the user's own unit
    /// and returned IN USER UNITS (the caller still applies `pressure_to_metric`).
    fn resolve_pressure(val: Option<f64>, units: UnitSystem) -> Result<f64, String> {
        match (val, units) {
            (None, UnitSystem::Imperial) => Ok(29.92),
            (None, UnitSystem::Metric) => Ok(1013.25),
            (Some(v), UnitSystem::Imperial) => {
                if !(8.0..=33.0).contains(&v) {
                    Err(format!(
                        "--pressure {v} inHg is out of range (expected ~8..33 inHg for imperial units)"
                    ))
                } else {
                    Ok(v)
                }
            }
            (Some(v), UnitSystem::Metric) => {
                if !(250.0..=1100.0).contains(&v) {
                    Err(format!(
                        "--pressure {v} hPa is out of range (expected ~250..1100 hPa for metric units)"
                    ))
                } else {
                    Ok(v)
                }
            }
        }
    }

    /// Resolve the temperature CLI argument AFTER --units is known.
    ///
    /// `None` -> the per-unit standard temperature (59 F / 15 C).
    /// `Some(v)` -> validated against a plausible range in the user's own unit
    /// and returned IN USER UNITS (the caller still applies `temperature_to_metric`).
    fn resolve_temperature(val: Option<f64>, units: UnitSystem) -> Result<f64, String> {
        match (val, units) {
            (None, UnitSystem::Imperial) => Ok(59.0),
            (None, UnitSystem::Metric) => Ok(15.0),
            (Some(v), UnitSystem::Imperial) => {
                if !(-148.0..=392.0).contains(&v) {
                    Err(format!(
                        "--temperature {v} F is out of range (expected ~-148..392 F for imperial units)"
                    ))
                } else {
                    Ok(v)
                }
            }
            (Some(v), UnitSystem::Metric) => {
                if !(-100.0..=200.0).contains(&v) {
                    Err(format!(
                        "--temperature {v} C is out of range (expected ~-100..200 C for metric units)"
                    ))
                } else {
                    Ok(v)
                }
            }
        }
    }

    fn altitude_to_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val,
            UnitSystem::Imperial => val * 0.3048, // feet to meters
        }
    }

    // target_size_to_metric moved to ballistics_engine::wez (MBA-1343 Phase B).

    // Output conversions (from metric)
    fn velocity_from_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val,
            UnitSystem::Imperial => val / 0.3048, // m/s to fps
        }
    }

    fn mass_from_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val * 1000.0,         // kg to grams
            UnitSystem::Imperial => val / GRAINS_TO_KG, // kg to grains
        }
    }

    fn diameter_from_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val * 1000.0,   // meters to mm
            UnitSystem::Imperial => val / 0.0254, // meters to inches
        }
    }

    fn sight_height_from_metric(val: f64, units: UnitSystem) -> f64 {
        Self::diameter_from_metric(val, units)
    }

    fn distance_from_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val,
            UnitSystem::Imperial => val / 0.9144, // meters to yards
        }
    }

    fn wind_from_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val,
            UnitSystem::Imperial => val / 0.44704, // m/s to mph
        }
    }

    fn temperature_from_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val,
            UnitSystem::Imperial => val * 9.0 / 5.0 + 32.0, // Celsius to Fahrenheit
        }
    }

    fn pressure_from_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val,
            UnitSystem::Imperial => val / 33.8639, // hPa to inHg
        }
    }

    fn altitude_from_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val,
            UnitSystem::Imperial => val / 0.3048, // meters to feet
        }
    }

    fn energy_from_metric(val: f64, units: UnitSystem) -> f64 {
        match units {
            UnitSystem::Metric => val,
            UnitSystem::Imperial => val * 0.737562, // Joules to ft-lbs
        }
    }
}

/// Parses a suffixed angular value into milliradians (MBA-1348): `28mil`, `96moa`,
/// `3.5smoa`, `0.5iphy`. The unit suffix is mandatory, mirroring `parse_click_value`'s
/// accepted suffix set (`iphy` aliases `smoa`, the identical unit) — a bare number is
/// rejected naming the accepted suffixes rather than silently guessing a unit. Converts
/// via the same LOCKED factor-ratio table `click_size_mil` uses
/// (`ballistics_engine::adjustment::adjustment_factor`): `value * adjustment_factor(Mil)
/// / adjustment_factor(base)`.
///
/// Unlike `parse_click_value` — which parses a click GRADUATION and must be positive —
/// an angular value here may be zero or negative: turret dialed state
/// (`--turret-elev`/`--turret-wind`) is signed, so this function does not reject sign or
/// magnitude, only shape (a valid finite number with a recognized suffix).
fn parse_angular_mil(s: &str) -> Result<f64, String> {
    let t = s.trim().to_ascii_lowercase();
    let (num, base) = if let Some(n) = t.strip_suffix("smoa") {
        (n, ClickBase::Smoa)
    } else if let Some(n) = t.strip_suffix("iphy") {
        (n, ClickBase::Smoa)
    } else if let Some(n) = t.strip_suffix("moa") {
        (n, ClickBase::Moa)
    } else if let Some(n) = t.strip_suffix("mil") {
        (n, ClickBase::Mil)
    } else {
        return Err(format!(
            "angular value '{s}' needs a unit suffix: mil, moa, smoa, or iphy (e.g. 28mil, 96moa)"
        ));
    };
    let value: f64 = num
        .trim()
        .parse()
        .map_err(|_| format!("angular value '{s}' has an invalid number '{num}'"))?;
    if !value.is_finite() {
        return Err(format!("angular value '{s}' must be finite"));
    }
    Ok(value * adjustment_factor(ClickBase::Mil) / adjustment_factor(base))
}

/// `profile save`'s carry-forward merge for one of the twelve turret/hold fields (MBA-1348
/// review fix I1): an explicit `flag` always wins; otherwise `existing` (the value already
/// on disk, if any) carries forward — UNLESS `clear_turret` (`--clear-turret`) was given,
/// which wins over carry-forward. Mirrors `carried_reticle`'s three-way
/// flag/clear/carry-forward treatment, generalized over `Copy` so the same function serves
/// `f64` (the ten angular fields), `u32` (`clicks_per_revolution`), and `bool` (`zero_stop`)
/// without hand-rolling the identical match twelve times.
///
/// Callers guarantee `flag.is_some() && clear_turret` never both hold for the SAME field by
/// construction: `profile save` rejects `--clear-turret` combined with any of the twelve
/// flags before this is ever called (see the mutual-exclusivity check in the `Save` match
/// arm), so `clear_turret` here always implies every one of `flag`'s twelve call-site
/// arguments is `None` already. The explicit `if clear_turret` branch below is still needed
/// despite that: without it, `flag.or(existing)` would incorrectly resurrect `existing`'s
/// stored value on a clear, since `flag` being `None` looks identical to "the user didn't
/// mention this field" and "the user cleared it" from this function's point of view alone.
fn carry_turret_field<T: Copy>(
    flag: Option<T>,
    existing: Option<T>,
    clear_turret: bool,
) -> Option<T> {
    if clear_turret {
        None
    } else {
        flag.or(existing)
    }
}

/// Unit conversion for loaded profiles. An extension trait rather than an inherent method
/// now that `ProfileData` lives in the library (`ballistics_engine::profile`): the
/// conversion rides on the CLI's own `UnitConverter`, which stays here in `main.rs`, so
/// the method does too. Behavior is unchanged from the pre-move inherent method.
trait ProfileDataUnitExt: Sized {
    /// Convert a loaded profile's display-unit values into the active CLI unit system before
    /// merging them with explicit arguments. The persisted profile remains unchanged.
    fn converted_to(self, target: UnitSystem) -> Result<Self, Box<dyn Error>>;
}

impl ProfileDataUnitExt for ProfileData {
    fn converted_to(mut self, target: UnitSystem) -> Result<Self, Box<dyn Error>> {
        // The units-string parse (and its exact error message) moved into the library with
        // the struct -- profile.validate applies the identical check through it.
        let source = self.unit_system()?;

        // Avoid needless round trips (and preserve every stored bit) for the common same-unit load.
        if source == target {
            return Ok(self);
        }

        self.velocity = UnitConverter::velocity_from_metric(
            UnitConverter::velocity_to_metric(self.velocity, source),
            target,
        );
        self.mass = UnitConverter::mass_from_metric(
            UnitConverter::mass_to_metric(self.mass, source),
            target,
        );
        self.diameter = UnitConverter::diameter_from_metric(
            UnitConverter::diameter_to_metric(self.diameter, source),
            target,
        );
        self.twist_rate = self.twist_rate.map(|value| {
            UnitConverter::diameter_from_metric(
                UnitConverter::diameter_to_metric(value, source),
                target,
            )
        });
        self.sight_height = self.sight_height.map(|value| {
            UnitConverter::sight_height_from_metric(
                UnitConverter::sight_height_to_metric(value, source),
                target,
            )
        });
        self.zero_distance = self.zero_distance.map(|value| {
            UnitConverter::distance_from_metric(
                UnitConverter::distance_to_metric(value, source),
                target,
            )
        });
        self.temperature = UnitConverter::temperature_from_metric(
            UnitConverter::temperature_to_metric(self.temperature, source),
            target,
        );
        self.pressure = UnitConverter::pressure_from_metric(
            UnitConverter::pressure_to_metric(self.pressure, source),
            target,
        );
        self.altitude = UnitConverter::altitude_from_metric(
            UnitConverter::altitude_to_metric(self.altitude, source),
            target,
        );
        self.density_altitude = self.density_altitude.map(|value| {
            UnitConverter::altitude_from_metric(
                UnitConverter::altitude_to_metric(value, source),
                target,
            )
        });
        self.wind_speed = self.wind_speed.map(|value| {
            UnitConverter::wind_from_metric(UnitConverter::wind_to_metric(value, source), target)
        });
        self.auto_zero = self.auto_zero.map(|value| {
            UnitConverter::distance_from_metric(
                UnitConverter::distance_to_metric(value, source),
                target,
            )
        });
        self.bullet_length = self.bullet_length.map(|value| {
            UnitConverter::diameter_from_metric(
                UnitConverter::diameter_to_metric(value, source),
                target,
            )
        });
        // MBA-1360: a zero set's zero_distance shares the profile zero_distance convention
        // above, so it rescales identically. The poi_*_mil dial corrections are angular
        // (unit-invariant) and stay untouched, like elevation_click/windage_click below.
        if let Some(sets) = self.zero_sets.as_mut() {
            for set in sets.iter_mut() {
                set.zero_distance = set.zero_distance.map(|value| {
                    UnitConverter::distance_from_metric(
                        UnitConverter::distance_to_metric(value, source),
                        target,
                    )
                });
            }
        }

        // `bc_segments`, `drag_curve`, `elevation_click`, `windage_click`, `dsf_points`, and
        // `bc_reference` are INTENTIONALLY left untouched here — do not "complete" this by
        // adding a conversion pass for them:
        //   * `ProfileBcSegment::velocity_mps` is pinned to SI regardless of `units` (see its
        //     doc comment), so there is nothing to convert.
        //   * `ProfileDragPoint`'s `mach` and `cd` are both dimensionless, so there is nothing
        //     to convert either.
        //   * `elevation_click`/`windage_click` (MBA-1355) are angular turret graduations
        //     (mil/moa/smoa/iphy, chosen by their own suffix), not linear distances, so
        //     imperial/metric has no bearing on them.
        //   * `DsfPoint`'s `mach` and `dsf` (MBA-1357) are both dimensionless ratios, same
        //     as the drag curve above.
        //   * `bc_reference` (MBA-1365) names a reference ATMOSPHERE, not a linear/angular
        //     display quantity — imperial/metric has no bearing on it either.
        //   * `reticle`'s mark coordinates (MBA-1361) are milliradians from the optical
        //     center — angular, like the click graduations above.
        // Converting them would silently rescale physically meaningful data (e.g. treating an
        // m/s breakpoint as if it were fps) rather than fix anything.
        self.units = match target {
            UnitSystem::Imperial => "imperial",
            UnitSystem::Metric => "metric",
        }
        .to_string();

        Ok(self)
    }
}

// ============================================================================
// Fuzzy Column Name Matching (MBA-614)
// ============================================================================

/// Known column names for gun profiles and locations
const KNOWN_COLUMNS: &[&str] = &[
    // Gun profile columns
    "RIFLE_NAME",
    "BULLET_NAME",
    "CALIBER",
    "BULLET_LENGTH",
    "VELOCITY",
    "MUZZLE_VELOCITY",
    "MV",
    "ZERO_TEMP",
    "ZERO_ALT",
    "ZERO_RANGE",
    "ZERO_DISTANCE",
    "ZERO",
    "BC",
    "BC_TYPE",
    "BC_ADJ",
    "BC_ADJUSTMENT",
    "BULLET_WEIGHT",
    "WIND_SPEED",
    "TARGET_SPEED",
    "WIND_ANGLE",
    "SIGHT_HEIGHT",
    "BARREL_TWIST",
    "TWIST_RATE",
    "TWIST",
    "VELOCITY_ADJ",
    "VEL_ADJ",
    "RANGE_MIN",
    "RANGE_MAX",
    "RANGE_INCR",
    "GUN_MPH",
    "COA",
    "POWDER_NAME",
    "POWDER_CHARGE",
    "PLASTIC_TIP_LENGTH",
    "JBM_BULLET_ID",
    "SPIN_DRIFT",
    "CHART_TYPE",
    "REGENERATE",
    "V_OFFSET_MIL",
    "H_OFFSET_MIL",
    "LATITUDE",
    "LONGITUDE",
    "DRAG_MODEL",
    // Location columns
    "LOCATION_NAME",
    "ALTITUDE",
    "ALT",
    "PRESSURE",
    "PRESSURE(HPA OR INHG)",
    "TARGET_TEMP",
    "TEMPERATURE",
    "TEMP",
    "HUMIDITY",
    "DA",
    "DENSITY_ALTITUDE",
    "WIND_DIR",
    "WIND_DIRECTION",
];

/// Find the closest matching known column name using Levenshtein distance
/// Returns Some((known_name, distance)) if a match within max_distance is found
fn find_closest_column(unknown: &str, max_distance: usize) -> Option<(&'static str, usize)> {
    let unknown_upper = unknown.to_uppercase();

    // First check for exact match
    for &known in KNOWN_COLUMNS {
        if known == unknown_upper {
            return Some((known, 0));
        }
    }

    // Find closest match within max_distance
    KNOWN_COLUMNS
        .iter()
        .filter_map(|&known| {
            let dist = levenshtein(&unknown_upper, known);
            if dist <= max_distance && dist > 0 {
                Some((known, dist))
            } else {
                None
            }
        })
        .min_by_key(|(_, dist)| *dist)
}

/// Normalize a column header, suggesting corrections for typos
/// Returns (normalized_name, was_corrected, original_name)
fn normalize_column_header(header: &str) -> (String, bool, String) {
    let upper = header.trim().to_uppercase();

    // Check if it's a known column or close match
    if let Some((known, dist)) = find_closest_column(&upper, 2) {
        if dist == 0 {
            // Exact match
            (known.to_string(), false, header.to_string())
        } else {
            // Fuzzy match - return corrected name
            (known.to_string(), true, header.to_string())
        }
    } else {
        // Unknown column, keep as-is
        (upper, false, header.to_string())
    }
}

/// Parse a CSV file and return row matching the first column value
/// Parse a CSV file and return row matching the first column value.
/// Uses the `csv` crate for proper quoting/escaping support (MBA-730).
fn load_csv_row(path: &PathBuf, row_name: &str) -> Result<HashMap<String, String>, Box<dyn Error>> {
    use csv::ReaderBuilder;

    let mut reader = ReaderBuilder::new()
        .has_headers(true)
        .comment(Some(b'#'))
        .flexible(true)
        .from_path(path)?;

    // Normalize headers and track fuzzy corrections
    let mut corrections: Vec<(String, String)> = Vec::new();
    let headers: Vec<String> = reader
        .headers()?
        .iter()
        .map(|h| {
            let (normalized, was_corrected, original) = normalize_column_header(h);
            if was_corrected {
                corrections.push((original, normalized.clone()));
            }
            normalized
        })
        .collect();

    // Print warnings for any corrected column names
    for (original, corrected) in &corrections {
        eprintln!(
            "Warning: Column '{}' not recognized - did you mean '{}'? Using {}.",
            original.trim(),
            corrected,
            corrected
        );
    }

    if headers.is_empty() {
        return Err("CSV file has no header row".into());
    }

    // Parse data rows and find matching row
    for record in reader.records() {
        let record = record?;
        if let Some(name) = record.get(0) {
            if name.eq_ignore_ascii_case(row_name) {
                let mut map = HashMap::new();
                for (i, header) in headers.iter().enumerate() {
                    if let Some(val) = record.get(i) {
                        if !val.is_empty() {
                            map.insert(header.clone(), val.to_string());
                        }
                    }
                }
                return Ok(map);
            }
        }
    }
    Err(format!("Row '{}' not found in CSV", row_name).into())
}

/// Get f64 value from HashMap, trying multiple key names
/// Whether a location CSV actually supplied one of these columns as a parseable number.
///
/// `csv_get_f64` collapses "absent" and "present" into one value, which is fine for reading a
/// number but not for deciding PROVENANCE. MBA-1417 needs provenance: a saved profile's pressure
/// mode may only be applied when the profile's pressure VALUE is the one in use, so it has to
/// distinguish "the CSV gave a pressure" from "the CSV gave nothing and we fell back".
fn csv_has(map: &HashMap<String, String>, keys: &[&str]) -> bool {
    keys.iter().any(|key| {
        map.get(&key.to_uppercase())
            .is_some_and(|val| val.parse::<f64>().is_ok())
    })
}

fn csv_get_f64(map: &HashMap<String, String>, keys: &[&str], default: f64) -> f64 {
    for key in keys {
        if let Some(val) = map.get(&key.to_uppercase()) {
            if let Ok(v) = val.parse::<f64>() {
                return v;
            }
        }
    }
    default
}

// ============================================================================
// Profile Management Helpers
// ============================================================================

/// Get the profiles directory (~/.ballistics/profiles/)
fn get_profiles_dir() -> Result<PathBuf, Box<dyn Error>> {
    let home = dirs::home_dir().ok_or("Could not determine home directory")?;
    let dir = home.join(".ballistics").join("profiles");
    fs::create_dir_all(&dir)?;
    Ok(dir)
}

/// Save a profile to disk
fn save_profile(profile: &ProfileData) -> Result<PathBuf, Box<dyn Error>> {
    let dir = get_profiles_dir()?;
    let path = dir.join(format!("{}.json", profile.name));
    let json = serde_json::to_string_pretty(profile)?;
    fs::write(&path, json)?;
    Ok(path)
}

/// Load a profile by name
/// Read and validate a reticle description from a JSON file (MBA-1361).
///
/// File I/O lives here, not in `ballistics_engine::reticle` — that module stays fs-free so
/// it compiles for wasm32 (the same split `drag_file`/`truing_dsf` use). Validation runs at
/// READ time so a malformed description is rejected at the flag that named the file rather
/// than surfacing later as a confusing hold error.
fn load_reticle_description(path: &std::path::Path) -> Result<ReticleDescription, Box<dyn Error>> {
    let content = fs::read_to_string(path)
        .map_err(|e| format!("could not read reticle file {}: {e}", path.display()))?;
    let reticle: ReticleDescription = serde_json::from_str(&content)
        .map_err(|e| format!("invalid reticle JSON in {}: {e}", path.display()))?;
    reticle
        .validate()
        .map_err(|e| format!("invalid reticle in {}: {e}", path.display()))?;
    Ok(reticle)
}

fn load_profile(name: &str) -> Result<ProfileData, Box<dyn Error>> {
    let dir = get_profiles_dir()?;
    let path = dir.join(format!("{}.json", name));
    if !path.exists() {
        return Err(format!(
            "Profile '{}' not found. Use 'ballistics profile list' to see available profiles.",
            name
        )
        .into());
    }
    let content = fs::read_to_string(&path)?;
    let profile: ProfileData = serde_json::from_str(&content)?;
    // MBA-1358: tracking correction factors are validated ON LOAD (hard error naming the
    // field) so a hand-edited or corrupted CF can never silently scale a firing solution.
    if let Some(cf) = profile.elevation_cf {
        validate_tracking_cf(cf, "profile field elevation_cf")?;
    }
    if let Some(cf) = profile.windage_cf {
        validate_tracking_cf(cf, "profile field windage_cf")?;
    }
    Ok(profile)
}

/// MBA-1358: resolve one axis's tracking CF — explicit CLI flag beats the saved
/// profile's field, default 1.0 (no correction). The flag value is validated here
/// (profile values were already validated on load, but re-validating is harmless and
/// keeps this the single resolution point).
fn resolve_tracking_cf(
    flag: Option<f64>,
    profile_value: Option<f64>,
    flag_name: &str,
) -> Result<f64, String> {
    let value = flag.or(profile_value).unwrap_or(1.0);
    validate_tracking_cf(value, flag_name)?;
    Ok(value)
}

/// Load a profile for calculation, converting its stored display units to the active CLI units.
fn load_profile_for_units(name: &str, units: UnitSystem) -> Result<ProfileData, Box<dyn Error>> {
    load_profile(name)?.converted_to(units)
}

/// The result of [`resolve_zero_selection`] (MBA-1360): which zero distance this run
/// uses (display units of the active run) and the selected zero set's per-load dial
/// corrections (MILs, 0.0 when no set is selected — an exact no-op at every dial site).
struct ZeroSelection {
    zero_distance: Option<f64>,
    elevation_bias_mil: f64,
    windage_bias_mil: f64,
}

/// The ONE zero-selection resolution shared by every profile-consuming solve path
/// (MBA-1360, design R9) — trajectory's `final_auto_zero`, the `dsf` verb's profile
/// solve, and `plan-truing`'s zero all flow through here, as does any dial-bias-only
/// consumer (come-ups/wind-card/range-table).
///
/// Precedence: `explicit_zero` (an explicit CLI zero flag) > the selected set's
/// `zero_distance` > `legacy_zero` (the call site's pre-1360 fallback chain, e.g.
/// CSV ZERO_RANGE then profile `auto_zero`/`zero_distance`). With no `--zero-set`
/// selected the set layer vanishes and the result is byte-identical to the legacy
/// resolution. Unknown set names are a hard error listing the available names
/// (MBA-1425: no silent fallback); so is `--zero-set` with no profile to look in.
///
/// `extra_set` is the trajectory command's CSV-derived ephemeral set (a `--profile`
/// CSV row's V_OFFSET_MIL/H_OFFSET_MIL columns, named after the row); it participates
/// in name lookup exactly like a stored set.
fn resolve_zero_selection(
    zero_set_name: Option<&str>,
    profile: Option<&ProfileData>,
    extra_set: Option<&ProfileZeroSet>,
    explicit_zero: Option<f64>,
    legacy_zero: Option<f64>,
) -> Result<ZeroSelection, String> {
    let Some(wanted) = zero_set_name else {
        return Ok(ZeroSelection {
            zero_distance: explicit_zero.or(legacy_zero),
            elevation_bias_mil: 0.0,
            windage_bias_mil: 0.0,
        });
    };

    let stored: &[ProfileZeroSet] = profile.and_then(|p| p.zero_sets.as_deref()).unwrap_or(&[]);
    let candidates: Vec<&ProfileZeroSet> = stored.iter().chain(extra_set).collect();
    if candidates.is_empty() {
        return Err(match profile {
            Some(p) => format!(
                "--zero-set '{wanted}': profile '{}' has no zero sets (add one with \
                 `profile zero-set add {} --name {wanted} ...`)",
                p.name, p.name
            ),
            None => format!(
                "--zero-set '{wanted}' requires a profile to look the set up in \
                 (pass the command's profile flag)"
            ),
        });
    }
    let Some(set) = candidates.iter().find(|s| s.name == wanted) else {
        let names: Vec<&str> = candidates.iter().map(|s| s.name.as_str()).collect();
        return Err(format!(
            "zero set '{wanted}' not found; available zero sets: {}",
            names.join(", ")
        ));
    };

    Ok(ZeroSelection {
        zero_distance: explicit_zero.or(set.zero_distance).or(legacy_zero),
        elevation_bias_mil: set.poi_up_mil.unwrap_or(0.0),
        windage_bias_mil: set.poi_right_mil.unwrap_or(0.0),
    })
}

/// Builds the trajectory command's ephemeral zero set from a `--profile` CSV row's
/// V_OFFSET_MIL/H_OFFSET_MIL columns (MBA-1360; the columns were allowlisted-but-unused
/// since MBA-614). Named after the selected row (`--profile-row`), so
/// `--zero-set <row name>` selects it. `None` when the row carries neither column —
/// including every pre-existing CSV, so runs without `--zero-set` are untouched.
fn zero_set_from_profile_csv(
    csv: &HashMap<String, String>,
    row_name: Option<&str>,
) -> Option<ProfileZeroSet> {
    let has_up = csv_has(csv, &["V_OFFSET_MIL"]);
    let has_right = csv_has(csv, &["H_OFFSET_MIL"]);
    if !has_up && !has_right {
        return None;
    }
    Some(ProfileZeroSet {
        name: row_name.unwrap_or("imported").to_string(),
        zero_distance: None,
        poi_up_mil: has_up.then(|| csv_get_f64(csv, &["V_OFFSET_MIL"], 0.0)),
        poi_right_mil: has_right.then(|| csv_get_f64(csv, &["H_OFFSET_MIL"], 0.0)),
        notes: None,
    })
}

/// List all saved profiles
fn list_profiles() -> Result<Vec<ProfileData>, Box<dyn Error>> {
    let dir = get_profiles_dir()?;
    let mut profiles = Vec::new();
    for entry in fs::read_dir(&dir)? {
        let entry = entry?;
        let path = entry.path();
        if path.extension().and_then(|e| e.to_str()) == Some("json") {
            if let Ok(content) = fs::read_to_string(&path) {
                if let Ok(profile) = serde_json::from_str::<ProfileData>(&content) {
                    profiles.push(profile);
                }
            }
        }
    }
    profiles.sort_by(|a, b| a.name.cmp(&b.name));
    Ok(profiles)
}

/// Delete a profile by name
fn delete_profile(name: &str) -> Result<(), Box<dyn Error>> {
    let dir = get_profiles_dir()?;
    let path = dir.join(format!("{}.json", name));
    if !path.exists() {
        return Err(format!("Profile '{}' not found.", name).into());
    }
    fs::remove_file(&path)?;
    Ok(())
}

// ============================================================================
// .a7p profile import: A7pDocument -> ProfileData mapping + import report
// ============================================================================
//
// The A7pDocument -> ProfileData mapping itself (ImportReport, A7pImportOutcome,
// map_a7p_to_profile, sanitize_profile_name) moved into the library
// (`ballistics_engine::profile_import::map`) so the bridge's `profile.import_a7p`
// shares it verbatim; imported at the top of this file under the same
// `profile-import` feature gate. Only the CLI presentation layer stays here.

#[cfg(feature = "profile-import")]
fn render_import_report(report: &ImportReport) -> String {
    let mut out = String::new();
    out.push_str("Imported fields:\n");
    out.push_str(&format!(
        "  {:<32} {:<26} {:<22} {}\n",
        "SOURCE (.a7p)", "VALUE", "CONVERTED", "DESTINATION"
    ));
    for [field, raw, converted, dest] in &report.mapped {
        out.push_str(&format!("  {field:<32} {raw:<26} {converted:<22} {dest}\n"));
    }
    // muzzle velocity appears in the header row name for the g7 render test
    if !report.unmapped.is_empty() {
        out.push_str("\nNOT imported (no destination in the profile store):\n");
        for (field, why) in &report.unmapped {
            out.push_str(&format!("  {field:<32} {why}\n"));
        }
    }
    if !report.warnings.is_empty() {
        out.push_str("\nWarnings:\n");
        for w in &report.warnings {
            out.push_str(&format!("  ! {w}\n"));
        }
    }
    out
}

/// SMOA/IPHY-per-MIL ratio (3600/1000 = 3.6, exact) for sites that already hold a
/// mil-based value (e.g. `moving_target::LeadSolution::lead_mil`) and need to rescale it
/// to SMOA/IPHY display units without recomputing from raw drop/range (MBA-1355).
fn smoa_per_mil() -> f64 {
    adjustment_factor(ClickBase::Smoa) / adjustment_factor(ClickBase::Mil)
}

/// Resolves the per-axis turret click graduations for `--adjustment-unit clicks` (MBA-1355).
///
/// Precedence per axis: an explicit CLI flag beats the saved profile's field. Windage
/// falls back to the resolved elevation graduation when neither `flag_wind` nor
/// `profile.windage_click` is set (most turrets share one graduation between the two
/// knobs). Elevation MUST resolve from at least one source — clicks output has nowhere
/// else to get a graduation from — so a missing elevation source is the only failure
/// mode, and the error names `--elevation-click-value` so the fix is obvious from the
/// message alone.
///
/// Only `trajectory` and `come-ups` call this; every other command that still accepts
/// `--adjustment-unit clicks` rejects it before reaching here (see
/// `reject_clicks_out_of_scope`).
fn resolve_click_values(
    flag_elev: Option<&str>,
    flag_wind: Option<&str>,
    profile: Option<&ProfileData>,
) -> Result<Option<(ClickValue, ClickValue)>, String> {
    let elev_str = flag_elev
        .map(str::to_string)
        .or_else(|| profile.and_then(|p| p.elevation_click.clone()));
    let Some(elev_str) = elev_str else {
        return Err(
            "--adjustment-unit clicks requires a turret elevation graduation: pass \
             --elevation-click-value <SIZE><UNIT> (e.g. 0.25moa or 0.1mil), or save one on \
             the profile with `profile save --elevation-click`"
                .to_string(),
        );
    };
    let elevation = parse_click_value(&elev_str)?;

    let wind_str = flag_wind
        .map(str::to_string)
        .or_else(|| profile.and_then(|p| p.windage_click.clone()));
    let windage = match wind_str {
        Some(s) => parse_click_value(&s)?,
        None => elevation,
    };

    Ok(Some((elevation, windage)))
}

/// CLI-facing selector for `adaptive-card`'s printed adjustment unit (MBA-1351): mirrors
/// `ballistics_engine::card::CardAdjustmentUnit`, restricted to mil/moa. Deliberately its
/// own thin `ValueEnum` rather than reusing the wider `AdjustmentUnit` above (which also
/// accepts smoa/iphy/clicks) -- the adaptive-card engine has no SMOA/IPHY/whole-click
/// concept, only the printed-table Mil/Moa distinction, so a value outside that pair should
/// be a clap parse error naming the two accepted values, not a runtime error reachable only
/// after solving a trajectory. Same established pattern as `FocalPlaneArg`/
/// `RecoilFirearmTypeArg`.
#[derive(Debug, Clone, Copy, ValueEnum, Default, PartialEq, Eq)]
enum AdaptiveCardAdjustmentArg {
    #[default]
    Mil,
    Moa,
}

impl AdaptiveCardAdjustmentArg {
    fn to_engine(self) -> CardAdjustmentUnit {
        match self {
            Self::Mil => CardAdjustmentUnit::Mil,
            Self::Moa => CardAdjustmentUnit::Moa,
        }
    }

    fn label(self) -> &'static str {
        match self {
            Self::Mil => "MIL",
            Self::Moa => "MOA",
        }
    }
}

/// Resolves an independent windage-axis unit (MBA-1410) against the elevation axis
/// (`--adjustment-unit`): an explicit `--windage-unit` wins, otherwise windage falls back
/// to the elevation unit -- the same shape `resolve_click_values` already uses for the
/// click GRADUATIONS. `clicks` is only reachable on the windage axis when the elevation
/// axis is ALSO `clicks`: turret click output needs a resolved elevation graduation
/// (`resolve_click_values`'s own precondition), so an explicit `--windage-unit clicks`
/// paired with a non-clicks `--adjustment-unit` has no graduation to resolve against and
/// is rejected here rather than silently displaying a raw angle.
fn resolve_windage_unit(
    elevation_unit: AdjustmentUnit,
    windage_unit: Option<AdjustmentUnit>,
) -> Result<AdjustmentUnit, String> {
    let resolved = windage_unit.unwrap_or(elevation_unit);
    if matches!(resolved, AdjustmentUnit::Clicks)
        && !matches!(elevation_unit, AdjustmentUnit::Clicks)
    {
        return Err(
            "--windage-unit clicks requires --adjustment-unit clicks (turret click output \
             needs the resolved elevation graduation)"
                .to_string(),
        );
    }
    Ok(resolved)
}

/// Resolves a single-axis (windage-only) turret click graduation for commands with no
/// elevation column of their own (`wind-card`, `lead`) -- MBA-1410. Precedence: an
/// explicit `--windage-click-value` flag, then the saved profile's `windage_click`, then
/// the profile's `elevation_click` (most turrets share one graduation between the two
/// knobs -- the same windage-falls-back-to-elevation shape `resolve_click_values` uses,
/// collapsed to the one axis these commands actually display).
fn resolve_single_axis_click_value(
    flag_windage: Option<&str>,
    profile: Option<&ProfileData>,
) -> Result<ClickValue, String> {
    let s = flag_windage
        .map(str::to_string)
        .or_else(|| profile.and_then(|p| p.windage_click.clone()))
        .or_else(|| profile.and_then(|p| p.elevation_click.clone()));
    let Some(s) = s else {
        return Err(
            "--adjustment-unit clicks requires a turret click graduation: pass \
             --windage-click-value <SIZE><UNIT> (e.g. 0.25moa or 0.1mil), or save one on \
             the profile with `profile save --windage-click` (or --elevation-click)"
                .to_string(),
        );
    };
    parse_click_value(&s)
}

/// Get a timestamp string without chrono
fn timestamp_string() -> String {
    use std::time::{SystemTime, UNIX_EPOCH};
    let secs = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap_or_default()
        .as_secs();
    format!("{}", secs)
}

/// Warning for drag-model strings `parse_drag_model_arg` cannot resolve at all. As of
/// MBA-1386 every real family (G1/G2/G5/G6/G7/G8/GI/GS/RA4) has a dedicated table and
/// resolves silently; only a genuinely unrecognized string (a typo, or a name the
/// library does not know) still coerces to G1, with this warning.
fn drag_model_arg_warning(s: &str) -> Option<String> {
    if DragModel::from_str(s).is_some() {
        None
    } else {
        Some(format!(
            "warning: drag model '{s}' is not recognized; using G1. Supported models: \
             G1, G2, G5, G6, G7, G8, GI, GS, RA4."
        ))
    }
}

/// Parse a drag-model string (from a saved profile or CSV) into the full family.
/// Unknown strings warn (stderr) and coerce to G1. Non-truing call sites only —
/// truing's forward model is G1/G7-only; see `parse_drag_model_arg_for_truing`.
fn parse_drag_model_arg(s: &str) -> DragModel {
    if let Some(w) = drag_model_arg_warning(s) {
        eprintln!("{w}");
    }
    DragModel::from_str(s).unwrap_or(DragModel::G1)
}

/// Parse a stored profile's `bc_reference` field (MBA-1365) into the engine enum. Accepts
/// the same lowercase-with-hyphens spelling `--bc-reference`/`clap::ValueEnum` produce
/// ("icao", "army-standard-metro"), case-insensitively. `None`/empty defaults to ICAO —
/// byte-identical to every profile saved before this field existed.
fn parse_bc_reference_profile_field(value: Option<&str>) -> Result<BcReferenceStandard, String> {
    match value.map(str::trim) {
        None | Some("") => Ok(BcReferenceStandard::Icao),
        Some(s) => match s.to_ascii_lowercase().as_str() {
            "icao" => Ok(BcReferenceStandard::Icao),
            "army-standard-metro" => Ok(BcReferenceStandard::ArmyStandardMetro),
            other => Err(format!(
                "invalid bc_reference '{other}' (expected 'icao' or 'army-standard-metro')"
            )),
        },
    }
}

/// Spelling `ProfileData.bc_reference` stores for a resolved [`BcReferenceStandard`]
/// (MBA-1365) — the inverse of [`parse_bc_reference_profile_field`]. ICAO is never
/// written out: it is the omitted-field default, so a profile saved without ever
/// touching `--bc-reference` round-trips with no new key (matches the pre-MBA-1365 file
/// shape byte-for-byte).
fn bc_reference_profile_field(value: BcReferenceStandard) -> Option<String> {
    match value {
        BcReferenceStandard::Icao => None,
        BcReferenceStandard::ArmyStandardMetro => Some("army-standard-metro".to_string()),
    }
}

/// Parse a stored profile's `pressure_reference` field (MBA-1397) into the engine enum.
/// Accepts the same lowercase spelling `--pressure-type`/`clap::ValueEnum` produce
/// ("absolute", "qnh"), case-insensitively. `None`/empty defaults to `Absolute` -- byte-
/// identical to every profile saved before this field existed.
///
/// Live at the solve site since MBA-1417 wired the profile atmosphere as a set. It is applied
/// ONLY when the profile's pressure VALUE is the one the run is using: an explicit --pressure or
/// a --location CSV pressure means the stored mode describes some other reading, and inheriting
/// it there is the silent 77 fps error MBA-1397 hit.
fn parse_pressure_reference_profile_field(
    value: Option<&str>,
) -> Result<PressureReferenceMode, String> {
    match value.map(str::trim) {
        None | Some("") => Ok(PressureReferenceMode::Absolute),
        Some(s) => match s.to_ascii_lowercase().as_str() {
            "absolute" => Ok(PressureReferenceMode::Absolute),
            "qnh" => Ok(PressureReferenceMode::Qnh),
            other => Err(format!(
                "invalid pressure_reference '{other}' (expected 'absolute' or 'qnh')"
            )),
        },
    }
}

/// Spelling `ProfileData.pressure_reference` stores for a resolved [`PressureReferenceMode`]
/// (MBA-1397) -- the inverse of [`parse_pressure_reference_profile_field`]. `Absolute` is
/// never written out: it is the omitted-field default, so a profile saved without ever
/// touching `--pressure-type` round-trips with no new key (matches the pre-MBA-1397 file
/// shape byte-for-byte).
fn pressure_reference_profile_field(value: PressureReferenceMode) -> Option<String> {
    match value {
        PressureReferenceMode::Absolute => None,
        PressureReferenceMode::Qnh => Some("qnh".to_string()),
    }
}

/// Pre-apply the MBA-1365 ASM->ICAO BC conversion for call sites that take a raw `bc: f64`
/// and have no `BcReferenceStandard` field to carry through to `TrajectorySolver::new` (the
/// single normalization boundary every other surface uses). Currently only the WEZ sweep
/// (`compute_wez`), which owns its own independent solve plumbing. Exactly the same
/// constant `TrajectorySolver::new` applies, so this is one multiply, not a second one —
/// `compute_wez` always builds inputs at the `Icao` default, so nothing downstream repeats it.
fn resolve_bc_for_reference_standard(bc: f64, standard: BcReferenceStandard) -> f64 {
    match standard {
        BcReferenceStandard::Icao => bc,
        BcReferenceStandard::ArmyStandardMetro => bc * ballistics_engine::constants::ASM_TO_ICAO_BC,
    }
}

/// Warning for drag-model strings `true-velocity`/`plan-truing` cannot use. Truing's
/// forward model is deliberately G1/G7-only (see `truing::DragModelArg`), so any other
/// family — including ones the engine now tables for real, e.g. G5 — still coerces to
/// G1 here, same as the whole CLI did before MBA-1386.
fn truing_drag_model_warning(s: &str) -> Option<String> {
    match s.to_uppercase().as_str() {
        "G1" | "G7" => None,
        other => Some(format!(
            "warning: drag model '{other}' is not supported by truing's forward model \
             (G1/G7 only); using G1."
        )),
    }
}

/// Parse a drag-model string for the truing commands, constrained to G1/G7.
fn parse_drag_model_arg_for_truing(s: &str) -> DragModelArg {
    if let Some(w) = truing_drag_model_warning(s) {
        eprintln!("{w}");
    }
    match s.to_uppercase().as_str() {
        "G7" => DragModelArg::G7,
        _ => DragModelArg::G1,
    }
}

/// Warning text for an auxiliary, non-truing path that is about to coerce a wider
/// `DragModel` down to the scalar G1/G7 family. `feature` names the caller in the warning
/// text (e.g. `"--bc-table correction"`). `None` for G1/G7 themselves, since those are not
/// a coercion. Pure/side-effect-free, same shape as `truing_drag_model_warning` — see
/// `warn_aux_g1_coercion` for the printing wrapper used at call sites.
fn aux_g1_coercion_warning(feature: &str, model: DragModel) -> Option<String> {
    match model {
        DragModel::G7 | DragModel::G1 => None,
        other => Some(format!(
            "warning: {feature} supports G1/G7 only; treating drag model '{other}' as G1"
        )),
    }
}

/// Coerce a resolved `DragModel` to the G1/G7 BC-type string an auxiliary path accepts,
/// printing `aux_g1_coercion_warning`'s text (stderr) when the coercion actually changes
/// anything. Mirrors `parse_drag_model_arg_for_truing`, but for the four auxiliary call
/// sites that were exhaustive 2-arm `G7 | _` matches before MBA-1386 widened `DragModel` to
/// the full G1/G2/G5/G6/G7/G8/GI/GS/RA4 family: the BC-segment estimator
/// (`resolve_velocity_bc_segments`), the `--bc-table` and BC5D correction-table lookups,
/// and the `--online` Flask-bridge request. Each of those still only understands the
/// scalar G1/G7 family and silently coerced anything else to G1 with no warning — unlike
/// truing, which already had one. Called once per site per run (outside any per-row loop).
fn warn_aux_g1_coercion(feature: &str, model: DragModel) -> &'static str {
    if let Some(w) = aux_g1_coercion_warning(feature, model) {
        eprintln!("{w}");
    }
    match model {
        DragModel::G7 => "G7",
        _ => "G1",
    }
}

/// MBA-1356: nudge for a `--cd-scale` far outside the documented typical truing range
/// (0.90-1.10). The engine's own gate (`require_positive` in `validate_for_solve`) only
/// demands finite && > 0 — this is a softer, CLI-level "did you mean this?" check, not a
/// second hard limit. `[0.5, 2.0]` is deliberately wide of the typical band. Pure/side-effect
/// free, same shape as `aux_g1_coercion_warning` — see `resolve_cd_scale` for the call site
/// that actually prints it.
fn cd_scale_range_warning(value: f64) -> Option<String> {
    if (0.5..=2.0).contains(&value) {
        None
    } else {
        Some(format!(
            "warning: --cd-scale {value} is far outside the typical truing range (0.90-1.10)"
        ))
    }
}

/// MBA-1414: `--adjustment-unit` only ever changes two things: the `--target-speed` mover
/// Ring table column, and the PDF dope card's Drop/Wind/Lead columns. Without a nonzero
/// `--target-speed` AND without `-o pdf`, the flag is a silent no-op -- the plain table is
/// always rendered in mil regardless. Mil is excluded even in that case because it is also
/// the `default_value`, so an explicit `--adjustment-unit mil` is indistinguishable from
/// never having passed the flag at all; warning there would fire on the common case for
/// nothing. Pure/side-effect-free, same shape as `cd_scale_range_warning` -- see the
/// Trajectory arm for the call site that actually prints it.
///
/// `windage_unit_explicit` (MBA-1410) is the RAW `--windage-unit` value, before falling
/// back to `elevation_unit` -- the fallback value is never a no-op signal by itself (it
/// was never explicitly requested), only an explicit non-mil `--windage-unit` is. The Ring
/// column never consumes the windage axis (it is elevation-only, see `resolve_windage_unit`'s
/// doc comment on why clicks needs the elevation graduation), so a nonzero `target_speed`
/// only ever excuses the elevation half of this warning, never the windage half.
fn adjustment_unit_noop_warning(
    elevation_unit: AdjustmentUnit,
    windage_unit_explicit: Option<AdjustmentUnit>,
    target_speed: f64,
    is_pdf: bool,
) -> Option<String> {
    if is_pdf {
        return None;
    }
    // `> 0.0` rather than `!= 0.0` so this reads the same as the browser terminal's guard
    // (wasm.rs) and stays correct if a negative ever reaches here; clap's range parser
    // rejects negatives today, so the two forms are equivalent in practice.
    let elevation_consumed = target_speed > 0.0 || elevation_unit == AdjustmentUnit::Mil;
    let windage_consumed = windage_unit_explicit.is_none_or(|u| u == AdjustmentUnit::Mil);
    // Tier 2 review M7 fix: name the flag that is ACTUALLY inert. The two axes are
    // independent (the Ring column is elevation-only -- see the doc comment above), so
    // `--adjustment-unit clicks --target-speed 5 --windage-unit moa` has a live elevation
    // axis (Ring column) but an inert windage axis (no Ring, no PDF); the old message
    // always named `--adjustment-unit` even when it was `--windage-unit` doing nothing.
    let inert_flag = match (elevation_consumed, windage_consumed) {
        (false, false) => "--adjustment-unit and --windage-unit",
        (false, true) => "--adjustment-unit",
        (true, false) => "--windage-unit",
        (true, true) => return None,
    };
    Some(format!(
        "warning: {inert_flag} only affects the mover Ring column and the PDF dope card; \
         add --target-speed or use -o pdf to see it"
    ))
}

/// MBA-1410 fold-in of an MBA-1355 backlog minor: `come-ups` has no windage column (it is
/// a pure elevation table), so `--windage-click-value` can never do anything there --
/// unlike `trajectory`, which resolves it into the Wind/Lead PDF columns. Previously this
/// was silently accepted and discarded; now it gets the same MBA-1414 "inert flag" stderr
/// treatment as `adjustment_unit_noop_warning`, so a shooter who typos `--elevation-click-value`
/// as `--windage-click-value` finds out instead of silently getting no clicks output.
fn windage_click_value_noop_warning(windage_click_value: Option<&str>) -> Option<String> {
    windage_click_value.map(|_| {
        "warning: --windage-click-value has no effect on come-ups (it has no windage \
         column); did you mean --elevation-click-value?"
            .to_string()
    })
}

/// Resolve `--cd-scale` against whether a custom drag table (`--drag-table`) is present on
/// this run. `--cd-scale` multiplies a *custom deck's* interpolated Cd (see
/// `BallisticInputs::cd_scale`) — without a table there is nothing to multiply, and the flag
/// almost certainly means the shooter wanted to true a scalar G1/G7 BC instead (`--bc-adjustment`,
/// a different mechanism entirely). Returns the neutral engine default (`1.0`) when `--cd-scale`
/// was omitted, or `Err` naming the pairing requirement when it was supplied without a table.
/// Printing the out-of-range warning (stderr, once) is this function's side effect; whether to
/// print the pairing error and exit is left to the call site (same split as
/// `resolve_click_values`), which keeps this unit-testable for its `Ok`/`Err` resolution logic.
///
/// `has_bc_adjustment` names whether the CALLING subcommand actually has a `--bc-adjustment`
/// flag to suggest -- `Trajectory` does, but `MonteCarlo` and `Zero` do not, so the pairing
/// error must not point the shooter at a flag that surface doesn't accept.
fn resolve_cd_scale(
    cd_scale: Option<f64>,
    has_custom_drag_table: bool,
    has_bc_adjustment: bool,
) -> Result<f64, String> {
    match cd_scale {
        Some(_) if !has_custom_drag_table => {
            let mut msg = "--cd-scale requires --drag-table".to_string();
            if has_bc_adjustment {
                msg.push_str(" (for G1/G7 use --bc-adjustment instead)");
            }
            Err(msg)
        }
        Some(scale) => {
            if let Some(w) = cd_scale_range_warning(scale) {
                eprintln!("{w}");
            }
            Ok(scale)
        }
        None => Ok(1.0),
    }
}

/// Parse a `--powder-temp-curve` value `"TEMP:VEL,TEMP:VEL,..."` into engine-canonical
/// `(temperature_celsius, muzzle_velocity_m_s)` points, converting from the CLI display
/// units. Points are sorted ascending by temperature; at least two distinct-temperature
/// points are required.
fn parse_powder_temp_curve(s: &str, units: UnitSystem) -> Result<Vec<(f64, f64)>, String> {
    let mut pts: Vec<(f64, f64)> = Vec::new();
    for (i, raw) in s.split(',').enumerate() {
        let part = raw.trim();
        if part.is_empty() {
            continue;
        }
        let (t_str, v_str) = part.split_once(':').ok_or_else(|| {
            format!(
                "--powder-temp-curve point {} '{}' must be TEMP:VELOCITY",
                i + 1,
                part
            )
        })?;
        let t: f64 = t_str.trim().parse().map_err(|_| {
            format!(
                "invalid temperature '{}' in --powder-temp-curve",
                t_str.trim()
            )
        })?;
        let v: f64 = v_str
            .trim()
            .parse()
            .map_err(|_| format!("invalid velocity '{}' in --powder-temp-curve", v_str.trim()))?;
        if v.partial_cmp(&0.0) != Some(std::cmp::Ordering::Greater) {
            return Err(format!(
                "--powder-temp-curve velocity must be positive (got {})",
                v
            ));
        }
        // Convert to SI: absolute temperature F->C and velocity fps->m/s (metric passes through).
        pts.push((
            UnitConverter::temperature_to_metric(t, units),
            UnitConverter::velocity_to_metric(v, units),
        ));
    }
    if pts.len() < 2 {
        return Err(format!(
            "--powder-temp-curve needs at least 2 TEMP:VELOCITY points (got {})",
            pts.len()
        ));
    }
    pts.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap_or(std::cmp::Ordering::Equal));
    for w in pts.windows(2) {
        if (w[0].0 - w[1].0).abs() < f64::EPSILON {
            return Err("--powder-temp-curve has duplicate temperatures".to_string());
        }
    }
    Ok(pts)
}

// (The old thin `parse_wind_segment` wrapper is gone: the trajectory dispatch now calls
// `wind::parse_wind_segment_str_detailed` directly, which it needs for the MBA-1367
// clock provenance + MBA-1368 per-segment compass re-referencing.)

/// Parse a `--bc-segment` value `"VMIN:VMAX:BC"` into a velocity-keyed `BCSegmentData`.
/// VMIN/VMAX are in the CLI display velocity units (fps imperial, m/s metric) and are
/// converted to fps (the engine's segment unit); BC is dimensionless. The BC applies while
/// the bullet's current velocity is in `[VMIN, VMAX)`.
fn parse_bc_segment(s: &str, units: UnitSystem) -> Result<BCSegmentData, String> {
    let parts: Vec<&str> = s.split(':').collect();
    if parts.len() != 3 {
        return Err(format!(
            "--bc-segment expects VMIN:VMAX:BC (e.g. 1500:1800:0.243), got '{}'",
            s
        ));
    }
    let vmin: f64 = parts[0]
        .trim()
        .parse()
        .map_err(|_| format!("--bc-segment: invalid VMIN in '{}'", s))?;
    let vmax: f64 = parts[1]
        .trim()
        .parse()
        .map_err(|_| format!("--bc-segment: invalid VMAX in '{}'", s))?;
    let bc: f64 = parts[2]
        .trim()
        .parse()
        .map_err(|_| format!("--bc-segment: invalid BC in '{}'", s))?;
    if vmin.partial_cmp(&vmax) != Some(std::cmp::Ordering::Less) {
        return Err(format!("--bc-segment: VMIN must be < VMAX in '{}'", s));
    }
    if bc <= 0.0 {
        return Err(format!("--bc-segment: BC must be > 0 in '{}'", s));
    }
    // Display velocity -> fps (the unit the solver compares segment bounds against).
    let to_fps = if matches!(units, UnitSystem::Imperial) {
        1.0
    } else {
        3.280_839_895
    };
    Ok(BCSegmentData {
        velocity_min: vmin * to_fps,
        velocity_max: vmax * to_fps,
        bc_value: bc,
    })
}

/// Load a user drag deck (`--drag-table <FILE>`) as a `Result`, dispatching by file extension
/// (MBA-1409): a `.drg` extension (case-insensitive) is parsed with
/// `ballistics_engine::drag_file::parse_drg` — the vendor Doppler-radar text format — and its
/// points are validated into a `DragTable` via `try_new`; every other extension (including no
/// extension), exactly as before this change, goes through the plain CSV path,
/// `DragTable::from_file`. This is the single shared implementation behind every
/// `--drag-table` call site (`trajectory`, `monte-carlo`, `zero`); kept separate from
/// `load_drag_table_or_exit` (below) so it's unit-testable — that wrapper calls
/// `std::process::exit` on error, which a test process can't safely do.
fn load_drag_table(path: &std::path::Path) -> Result<ballistics_engine::drag::DragTable, String> {
    let is_drg = path
        .extension()
        .and_then(|e| e.to_str())
        .is_some_and(|e| e.eq_ignore_ascii_case("drg"));
    if !is_drg {
        return ballistics_engine::drag::DragTable::from_file(path);
    }
    let text = std::fs::read_to_string(path)
        .map_err(|e| format!("could not read drag table {}: {e}", path.display()))?;
    let curve = ballistics_engine::drag_file::parse_drg(&text)
        .map_err(|e| format!("{} (.drg format): {e}", path.display()))?;
    let (mach, cd): (Vec<f64>, Vec<f64>) = curve.points.into_iter().unzip();
    ballistics_engine::drag::DragTable::try_new(mach, cd)
        .map_err(|e| format!("{}: {e}", path.display()))
}

/// Load a user drag deck for the CLI, exiting with a clear message on any validation error.
fn load_drag_table_or_exit(path: &std::path::Path) -> ballistics_engine::drag::DragTable {
    match load_drag_table(path) {
        Ok(t) => t,
        Err(e) => {
            eprintln!("Error: {e}");
            std::process::exit(1);
        }
    }
}

/// Build an engine [`DragTable`](ballistics_engine::drag::DragTable) from a profile's stored
/// Mach/Cd curve ([`ProfileData::drag_curve`]). Returns a descriptive error (never panics) if
/// the stored points fail `DragTable::try_new`'s validation — `map_a7p_to_profile` already
/// validates on import, so this should only fire for a hand-edited or foreign-tool-written
/// profile JSON.
fn drag_table_from_profile(
    points: &[ProfileDragPoint],
) -> Result<ballistics_engine::drag::DragTable, String> {
    let mach: Vec<f64> = points.iter().map(|p| p.mach).collect();
    let cd: Vec<f64> = points.iter().map(|p| p.cd).collect();
    ballistics_engine::drag::DragTable::try_new(mach, cd)
}

/// Convert a profile's stored velocity-BC breakpoints ([`ProfileData::bc_segments`]) into the
/// engine's velocity-banded [`BCSegmentData`] schedule.
///
/// Mirrors the ArcherBC2 "coefficient row" convention preserved by `A7pProfile::bc_rows()`,
/// which matches standard multi-BC velocity tables (Applied Ballistics/Kestrel-style): each
/// row's OWN velocity is the point *at and above which* that row's BC applies, down to the
/// next (lower-velocity) row's own velocity, which is where the next row's BC takes over.
/// Concretely, after sorting descending by velocity, row `i`'s band is
/// `[breakpoint(i), breakpoint(i-1))` — the fastest row's band is open-ended upward (its own
/// velocity is a floor, not a ceiling: it still governs a muzzle velocity measured higher than
/// its own characterization point) and the SLOWEST row's band is forced open-ended down to
/// zero (overriding its own stated velocity as a lower bound) so the full velocity axis is
/// covered with no gap. This is deliberately non-overlapping and gapless, unlike naively
/// pairing each row with its neighbor's velocity on both sides.
///
/// Velocities convert m/s -> fps (`BCSegmentData`'s unit, matching `parse_bc_segment`). The
/// fastest row's upper bound uses the same 5000 fps top sentinel as
/// `BCSegmentEstimator::estimate_bc_segments` (comfortably above any realistic muzzle
/// velocity), floored to strictly exceed the row's own velocity so an unrealistically fast
/// import still gets a valid (non-empty) top band.
fn bc_segments_from_profile(rows: &[ProfileBcSegment]) -> Vec<BCSegmentData> {
    const MPS_TO_FPS: f64 = 3.280_839_895;
    const TOP_SENTINEL_FPS: f64 = 5000.0;

    let mut sorted: Vec<(f64, f64)> = rows
        .iter()
        .map(|r| (r.bc, r.velocity_mps * MPS_TO_FPS))
        .collect();
    sorted.sort_by(|a, b| b.1.total_cmp(&a.1)); // descending by velocity
    let n = sorted.len();
    sorted
        .iter()
        .enumerate()
        .map(|(i, &(bc, v))| {
            let velocity_max = if i == 0 {
                v.max(TOP_SENTINEL_FPS) + 1.0
            } else {
                sorted[i - 1].1
            };
            let velocity_min = if i + 1 == n { 0.0 } else { v };
            BCSegmentData {
                velocity_min,
                velocity_max,
                bc_value: bc,
            }
        })
        .collect()
}

/// Resolve the velocity-keyed BC schedule once so auto-zero, native flight, and compare flight
/// cannot synthesize different drag inputs. Explicit manual/table segments take precedence over
/// the characteristic-based estimator.
fn resolve_velocity_bc_segments(
    provided: Option<&[BCSegmentData]>,
    use_estimator: bool,
    bc: f64,
    diameter_m: f64,
    mass_kg: f64,
    drag_model: DragModel,
) -> Option<Vec<BCSegmentData>> {
    if let Some(segments) = provided {
        return Some(segments.to_vec());
    }
    if !use_estimator {
        return None;
    }

    Some(
        ballistics_engine::bc_estimation::BCSegmentEstimator::estimate_bc_segments(
            bc,
            diameter_m / 0.0254,
            mass_kg / GRAINS_TO_KG,
            "",
            warn_aux_g1_coercion("--use-bc-segments' estimator", drag_model),
        ),
    )
}

// ============================================================================
// DSF (drop-scale-factor) table support (MBA-1357)
// ============================================================================

/// `"{n} points, Mach {lo:.2}-{hi:.2}"` summary of a DSF table's points, shared by the
/// `dsf` verb's own confirmation output, `profile show`, and the `trajectory`/`come-ups`
/// auto-apply note. `points` must be non-empty (both call sites only reach this behind a
/// `Some(dsf_points)`/non-empty check) — an empty slice reports Mach 0.00-0.00 rather than
/// panicking.
fn dsf_table_summary(points: &[DsfPoint]) -> String {
    let lo = points.first().map(|p| p.mach).unwrap_or(0.0);
    let hi = points.last().map(|p| p.mach).unwrap_or(0.0);
    format!("{} points, Mach {:.2}-{:.2}", points.len(), lo, hi)
}

/// Parse a `--observed-drop` token: a numeric value immediately followed by its unit
/// suffix, no separator — `mil`, `moa`, or `in` (e.g. "5.1mil", "17.4moa", "42.0in").
/// Reuses [`DropUnit`]'s three-unit vocabulary (the same units `true-velocity`'s
/// `--drop-unit`/`--observed` accept, via a separate flag rather than a suffix — see
/// `parse_truing_observation`).
fn parse_observed_drop(s: &str) -> Result<(f64, DropUnit), String> {
    let t = s.trim().to_ascii_lowercase();
    let (num, unit) = if let Some(n) = t.strip_suffix("mil") {
        (n, DropUnit::Mil)
    } else if let Some(n) = t.strip_suffix("moa") {
        (n, DropUnit::Moa)
    } else if let Some(n) = t.strip_suffix("in") {
        (n, DropUnit::In)
    } else {
        return Err(format!(
            "--observed-drop '{s}' needs a unit suffix: mil, moa, or in (e.g. 5.1mil, 17.4moa, 42.0in)"
        ));
    };
    let value: f64 = num
        .trim()
        .parse()
        .map_err(|_| format!("--observed-drop '{s}' has an invalid number '{num}'"))?;
    if !value.is_finite() {
        return Err(format!("--observed-drop '{s}' must be a finite number"));
    }
    Ok((value, unit))
}

/// Solve a saved profile's OWN trajectory for the `dsf` command's derivation step, using
/// only the profile's stored fields — no CLI overrides, since `dsf` exposes none of the
/// physics flags (`--saved-profile`/`--range`/`--observed-drop` are its entire surface).
///
/// A thin adapter (MBA-1357 Task 8, reshaped again per Task 8 review Finding 1): the
/// actual solve is [`ballistics_engine::truing_dsf::solve_for_dsf`], which the JSON
/// bridge can also reach directly without a `Profile` — this converts a loaded profile
/// into that function's [`ballistics_engine::truing_dsf::DsfSolveInputs`] shape and
/// delegates. Unlike the model shape `true-velocity`/`true-wind`/`plan-truing` share,
/// `DsfSolveInputs` carries every field this profile-driven solve has always honored —
/// wind, shooting angle, zero-POI offsets, sight-mount offset, BC reference, BC segments,
/// a custom drag curve — so nothing here changes what `dsf` computes from a profile that
/// sets any of them; see `DsfSolveInputs`'s own doc comment for the (empirically
/// confirmed inert) fields it deliberately omits. Drag model resolves through
/// `parse_drag_model_arg` — the FULL G1/G2/G5/G6/G7/G8/GI/GS/RA4 family, same as
/// `trajectory --saved-profile`, and with no coercion warning for any of them (only a
/// genuinely unrecognized string still warns and falls back to G1). This restores the
/// pre-MBA-1357 behaviour: `DsfSolveInputs::drag_model` was briefly narrowed to
/// `truing::DragModelArg` (G1/G7 only) when this adapter was first written, which
/// silently coerced any other saved profile's drag model to G1 on every `dsf` solve
/// (whole-branch review, Finding 1/Critical) — `dsf`'s scope now matches
/// `trajectory --saved-profile` here exactly, as it always did before this feature.
///
/// `profile` must already be converted to `units` (i.e. loaded via
/// `load_profile_for_units`). `max_range_m` should exceed the target observation range so
/// the solved points bracket it (a short solve, e.g. ground impact before the requested
/// range, is reported by the caller via
/// [`ballistics_engine::truing_dsf::interpolate_position_and_velocity`] returning `None`,
/// not by this function).
///
/// `zero_distance_display` is the RESOLVED zero distance (display units) from
/// `resolve_zero_selection`. `None` (a profile with neither `auto_zero` nor
/// `zero_distance` set, and no `--zero-set` selected) solves flat (`muzzle_angle` 0.0),
/// byte-identical to the pre-Task-8 behaviour — restored here after Task 8 review
/// Finding 2 flagged that the first version of this reshape had turned it into a hard
/// error.
fn solve_profile_for_dsf(
    profile: &ProfileData,
    units: UnitSystem,
    max_range_m: f64,
    zero_distance_display: Option<f64>,
) -> Result<ballistics_engine::cli_api::TrajectoryResult, Box<dyn Error>> {
    let zero_distance_yd = zero_distance_display.map(|zero_distance_display| match units {
        UnitSystem::Imperial => zero_distance_display,
        UnitSystem::Metric => zero_distance_display / 0.9144,
    });

    let velocity_m = UnitConverter::velocity_to_metric(profile.velocity, units);
    let mass_kg = UnitConverter::mass_to_metric(profile.mass, units);
    let diameter_m = UnitConverter::diameter_to_metric(profile.diameter, units);
    let drag_model = parse_drag_model_arg(&profile.drag_model);

    // Same default `trajectory --saved-profile`/`come-ups --profile` fall back to when a
    // profile doesn't carry the field.
    let sight_height_default = match units {
        UnitSystem::Imperial => 2.0,
        UnitSystem::Metric => 50.0,
    };
    let sight_height_m = UnitConverter::sight_height_to_metric(
        profile.sight_height.unwrap_or(sight_height_default),
        units,
    );

    // Saved profiles predate MBA-1339's unified --bore-height flag and never stored one;
    // use the same unit-aware default `trajectory --saved-profile`/`come-ups --profile`
    // fall back to (60 in imperial / 1500 mm metric — NOT the same default in both
    // systems, restored here after MBA-1357 Task 10 review Fix 2 found the DsfSolveInputs
    // reshape had silently narrowed this to the imperial constant regardless of units).
    let bore_height_default_display = match units {
        UnitSystem::Imperial => 60.0,
        UnitSystem::Metric => 1500.0,
    };
    let bore_height_m = match units {
        UnitSystem::Imperial => bore_height_default_display * 0.0254,
        UnitSystem::Metric => bore_height_default_display * 0.001,
    };

    let temperature_c = UnitConverter::temperature_to_metric(profile.temperature, units);
    let pressure_hpa = UnitConverter::pressure_to_metric(profile.pressure, units);
    let altitude_m = UnitConverter::altitude_to_metric(profile.altitude, units);

    let wind_speed_mps = profile
        .wind_speed
        .map(|w| UnitConverter::wind_to_metric(w, units));
    let wind_direction_rad = profile.wind_direction.map(|d| d.to_radians());
    let shooting_angle_rad = profile.shooting_angle.map(|a| a.to_radians());

    let bc_segments = profile
        .bc_segments
        .as_ref()
        .map(|rows| bc_segments_from_profile(rows));
    let custom_drag_table = profile
        .drag_curve
        .as_ref()
        .map(|pts| drag_table_from_profile(pts))
        .transpose()
        .map_err(|e| format!("saved profile's drag curve is invalid: {e}"))?;
    let bc_reference_standard = Some(parse_bc_reference_profile_field(
        profile.bc_reference.as_deref(),
    )?);

    let inputs = ballistics_engine::truing_dsf::DsfSolveInputs {
        muzzle_velocity_fps: velocity_m / 0.3048,
        ballistic_coefficient: profile.bc,
        drag_model,
        mass_gr: mass_kg / GRAINS_TO_KG,
        diameter_in: diameter_m / 0.0254,
        sight_height_in: sight_height_m / 0.0254,
        temperature_f: temperature_c * 9.0 / 5.0 + 32.0,
        pressure_inhg: pressure_hpa / 33.8639,
        // profile.humidity is already 0-100 regardless of `units` (humidity has no
        // imperial/metric distinction), matching DsfSolveInputs::humidity_pct.
        humidity_pct: profile.humidity,
        altitude_ft: altitude_m / 0.3048,
        wind_speed_mps,
        wind_direction_rad,
        shooting_angle_rad,
        // MBA-1359: honor a stored zero POI offset when solving from a saved profile.
        zero_poi_vertical_m: profile.zero_poi_up_m,
        zero_poi_horizontal_m: profile.zero_poi_right_m,
        // MBA-1396: honor a stored lateral sight-mount offset the same way.
        sight_offset_lateral_m: profile.sight_offset_lateral_m,
        bc_reference_standard,
        // MBA-1357 Task 8 review round 2: the flag itself, independent of whether
        // bc_segments is populated — solve_for_dsf ORs it with bc_segments.is_some(),
        // reproducing the historical
        // profile.use_bc_segments.unwrap_or(false) || bc_segments_data.is_some() exactly.
        use_bc_segments: profile.use_bc_segments.unwrap_or(false),
        bc_segments,
        custom_drag_table,
        zero_distance_yd,
        bore_height_m,
    };

    Ok(ballistics_engine::truing_dsf::solve_for_dsf(
        &inputs,
        max_range_m,
    )?)
}

/// Mirrors `Commands::Trajectory`'s own `--max-range` default (1000.0, in the active
/// command's units: yards for imperial, meters for metric) — the envelope
/// `trajectory --saved-profile NAME`/`come-ups --profile NAME` solve by default, absent
/// an explicit `--max-range`. `dsf` has no `--max-range` flag of its own; its solve
/// envelope reuses this same default so the 90%-of-solved-range gate (MBA-1357 Task 2
/// review, Critical #1) reflects the profile's real reach rather than an envelope sized
/// to the requested observation.
const DSF_DEFAULT_SOLVE_ENVELOPE: f64 = 1000.0;

/// Exact text for the `dsf` verb's supersonic-observation rejection gate: the target
/// range's predicted Mach is at or above [`ballistics_engine::truing_dsf::DSF_MACH_CEILING`] (1.2) — that's MV-truing
/// territory (`true-velocity`), not the DSF table's domain.
fn dsf_supersonic_error(mach: f64) -> String {
    format!(
        "error: observation is supersonic (Mach {mach:.2}); calibrate muzzle velocity first \
         (true-velocity), then collect DSF points at Mach <= 1.2"
    )
}

/// Exact text for the "observation beyond 90% of the solved range" warning.
/// `range_display`/`dist_unit` are in the CLI's active `--units` (yd/imperial, m/metric).
fn dsf_beyond_90pct_warning(range_display: f64, dist_unit: &str) -> String {
    format!(
        "warning: observation at {range_display:.0} {dist_unit} is beyond 90% of the solved \
         range; solution reliability degrades past this point"
    )
}

/// Whether a DSF table's highest-Mach point sits below Mach 0.9 — since [`DsfTable`] sorts
/// ascending by Mach and every point is < [`ballistics_engine::truing_dsf::DSF_MACH_CEILING`] (1.2) by construction, the
/// highest point being < 0.9 already means nothing in the table covers the 0.9-1.2
/// transonic band.
fn dsf_table_missing_transonic_coverage(points: &[DsfPoint]) -> bool {
    points.last().map(|p| p.mach < 0.9).unwrap_or(true)
}

/// Exact text for the "no DSF point in the transonic band" warning.
fn dsf_transonic_gap_warning() -> String {
    "warning: no DSF point in the transonic band (Mach 1.2-0.9); transonic drops remain uncorrected"
        .to_string()
}

#[cfg(feature = "online")]
fn online_client(api_url: &str) -> ApiClient {
    ApiClient::new(api_url, 30).with_token(ballistics_engine::credentials::load_token())
}

#[cfg(feature = "online")]
fn online_render(result: Result<serde_json::Value, ballistics_engine::api_client::ApiError>) {
    match result {
        Ok(v) => println!("{}", serde_json::to_string_pretty(&v).unwrap_or_default()),
        Err(e) => {
            eprintln!(
                "{}",
                e.cli_hint()
                    .map(|s| s.to_string())
                    .unwrap_or_else(|| format!("Online request failed: {}", e))
            );
            std::process::exit(1);
        }
    }
}

fn main() -> Result<(), Box<dyn Error>> {
    let cli = Cli::parse();

    match cli.command {
        Commands::SolveJson => std::process::exit(solve_json_command::run_stdio()),

        Commands::Mcp => std::process::exit(mcp_command::run_stdio()),

        #[cfg(feature = "online")]
        Commands::Login { token } => {
            let token = match token {
                Some(t) => t,
                None => {
                    eprintln!("Paste your CLI token from https://ballisticsinsight.com/account:");
                    let mut line = String::new();
                    std::io::stdin().read_line(&mut line).ok();
                    line.trim().to_string()
                }
            };
            if token.is_empty() {
                eprintln!("No token provided.");
                std::process::exit(1);
            }
            match ballistics_engine::credentials::save_token(&token) {
                Ok(()) => {
                    let where_ = ballistics_engine::credentials::credentials_path()
                        .map(|p| p.display().to_string())
                        .unwrap_or_else(|| "the credentials file".to_string());
                    println!("Saved CLI token to {}", where_);
                }
                Err(e) => {
                    eprintln!("Failed to save token: {}", e);
                    std::process::exit(1);
                }
            }
        }

        #[cfg(feature = "online")]
        Commands::Logout => match ballistics_engine::credentials::clear_token() {
            Ok(()) => println!("Removed saved CLI token."),
            Err(e) => {
                eprintln!("Failed to remove token: {}", e);
                std::process::exit(1);
            }
        },

        #[cfg(feature = "online")]
        Commands::RecommendPowder {
            cartridge,
            bullet_weight,
            desired_velocity,
            barrel_length,
            velocity_tolerance,
            api_url,
        } => {
            let mut body = serde_json::json!({
                "cartridge": cartridge,
                "bullet_weight": bullet_weight,
                "desired_velocity": desired_velocity,
            });
            if let Some(bl) = barrel_length {
                body["barrel_length"] = serde_json::Value::from(bl);
            }
            if let Some(vt) = velocity_tolerance {
                body["velocity_tolerance"] = serde_json::Value::from(vt);
            }
            online_render(online_client(&api_url).post_json("/v1/recommend_powders", &body));
        }

        #[cfg(feature = "online")]
        Commands::RecommendTwist {
            caliber,
            weight,
            overall_length,
            nose_length,
            muzzle_velocity,
            api_url,
        } => {
            let mut body = serde_json::json!({
                "caliber": caliber,
                "weight": weight,
                "overall_length": overall_length,
                "nose_length": nose_length,
            });
            if let Some(mv) = muzzle_velocity {
                body["muzzle_velocity"] = serde_json::Value::from(mv);
            }
            online_render(online_client(&api_url).post_json("/v1/recommend_twist", &body));
        }

        #[cfg(feature = "online")]
        Commands::RecommendCol {
            cartridge,
            bullet_weight,
            bullet_type,
            api_url,
        } => {
            let mut params: Vec<(String, String)> = vec![("cartridge".into(), cartridge)];
            if let Some(bw) = bullet_weight {
                params.push(("bullet_weight".into(), bw.to_string()));
            }
            if let Some(bt) = bullet_type {
                params.push(("bullet_type".into(), bt));
            }
            online_render(online_client(&api_url).get_json("/v1/recommend_col", &params));
        }

        #[cfg(feature = "online")]
        Commands::CalibrateBc {
            diameter,
            length,
            weight,
            bullet_type,
            api_url,
        } => {
            let mut body = serde_json::json!({
                "diameter": diameter,
                "length": length,
                "weight": weight,
            });
            if let Some(bt) = bullet_type {
                body["bullet_type"] = serde_json::Value::from(bt);
            }
            online_render(online_client(&api_url).post_json("/v1/calibrate_bc", &body));
        }

        Commands::Trajectory {
            profile,
            profile_row,
            saved_profile,
            location,
            site,
            velocity,
            velocity_adjustment,
            angle,
            bc,
            bc_adjustment,
            bc_reference,
            mass,
            diameter,
            drag_model,
            max_range,
            time_step,
            wind_speed,
            wind_direction,
            wind_ref,
            wind_vertical,
            wind_segment,
            bc_segment,
            temperature,
            pressure,
            pressure_type,
            humidity,
            altitude,
            density_altitude,
            output,
            full,
            plot,
            auto_zero,
            zero_set,
            zero_poi_up,
            zero_poi_right,
            sight_height,
            sight_offset,
            bore_height,
            ignore_ground_impact,
            use_bc_segments,
            drag_table,
            cd_scale,
            cant,
            print_bc_segments,
            enable_magnus,
            enable_coriolis,
            enable_spin_drift,
            enable_aerodynamic_jump,
            enable_wind_shear,
            sample_trajectory,
            sample_interval,
            drops_reference,
            enable_pitch_damping,
            enable_precession,
            use_cluster_bc,
            bc_table,
            bc_table_dir,
            #[cfg(feature = "online")]
            bc_table_auto,
            #[cfg(feature = "online")]
            bc_table_url,
            #[cfg(feature = "online")]
            bc_table_refresh,
            bullet_length,
            twist_rate,
            twist_right,
            latitude,
            longitude,
            shot_direction,
            use_euler,
            use_rk4_fixed,
            shooting_angle,
            use_powder_sensitivity,
            powder_temp_sensitivity,
            powder_temp,
            powder_temp_curve,
            zero_velocity,
            zero_temperature,
            zero_pressure,
            zero_pressure_type,
            zero_humidity,
            zero_altitude,
            zero_density_altitude,
            zero_powder_temp,
            #[cfg(feature = "online")]
            online,
            #[cfg(feature = "online")]
            api_url,
            #[cfg(feature = "online")]
            offline_fallback,
            #[cfg(feature = "online")]
            compare,
            #[cfg(feature = "online")]
            api_timeout,
            #[cfg(feature = "online")]
            enable_weather_zones,
            #[cfg(feature = "online")]
            enable_3d_weather,
            wind_shear_model,
            #[cfg(feature = "online")]
            weather_zone_interpolation,
            // PDF dope card parameters
            target_speed,
            with_drag_coefficient,
            powder,
            bullet_name,
            location_name,
            output_file,
            font_scale,
            font_preset,
            bold_data,
            adjustment_unit,
            windage_unit,
            elevation_click_value,
            windage_click_value,
            elevation_cf,
            windage_cf,
        } => {
            // Load profile from CSV if specified
            let profile_data: HashMap<String, String> =
                if let (Some(path), Some(row)) = (&profile, &profile_row) {
                    match load_csv_row(path, row) {
                        Ok(data) => {
                            eprintln!("Loaded profile '{}' from {:?}", row, path);
                            data
                        }
                        // MBA-1425: a supplied profile that cannot be loaded is a hard error.
                        // The old warn-and-continue ran the shot on defaults the user did not
                        // choose — a clean-looking answer computed from the wrong gun.
                        Err(e) => {
                            return Err(format!(
                                "failed to load profile row '{row}' from {path:?}: {e}"
                            )
                            .into());
                        }
                    }
                } else {
                    HashMap::new()
                };

            // Load saved JSON profile if specified
            let saved_profile_data: Option<ProfileData> = saved_profile.as_ref().map(|name| {
                load_profile_for_units(name, cli.units).unwrap_or_else(|e| {
                    eprintln!("Error loading saved profile: {}", e);
                    std::process::exit(1);
                })
            });
            if let Some(ref sp) = saved_profile_data {
                eprintln!("Loaded saved profile '{}'", sp.name);
            }

            // MBA-1357: resolve the saved profile's DSF table (if any) eagerly too, so a
            // corrupted/hand-edited table fails fast rather than after a full solve below.
            let dsf_table: Option<DsfTable> = saved_profile_data
                .as_ref()
                .and_then(|p| p.dsf_points.clone())
                .map(|points| {
                    DsfTable::from_points(points).unwrap_or_else(|e| {
                        eprintln!("error: saved profile's DSF table is invalid: {e}");
                        std::process::exit(1);
                    })
                });

            // MBA-1414: the unit reaches only the Ring column and the PDF dope card, so
            // say so when this run has neither — otherwise the flag (and the graduation
            // resolved just below) silently changes nothing.
            if let Some(w) = adjustment_unit_noop_warning(
                adjustment_unit,
                windage_unit,
                target_speed,
                matches!(output, OutputFormat::Pdf),
            ) {
                eprintln!("{w}");
            }

            // MBA-1410: independent windage-axis unit for the PDF dope card's Wind/Lead
            // columns (the mover Ring column stays elevation-only — see
            // `resolve_windage_unit`'s doc comment). Resolved before the click graduations
            // below so a `--windage-unit clicks` / `--adjustment-unit`-not-clicks mismatch
            // fails fast with a clear message.
            let windage_unit_resolved = resolve_windage_unit(adjustment_unit, windage_unit)
                .unwrap_or_else(|e| {
                    eprintln!("error: {e}");
                    std::process::exit(1);
                });

            // MBA-1355: resolve turret click graduations FIRST, eagerly — before any of
            // the Ring column / PDF dope card display work below — so a missing
            // graduation fails fast with a clear flag name, regardless of whether this
            // particular run would even reach a display site that needs it.
            let (elevation_click, windage_click): (Option<ClickValue>, Option<ClickValue>) =
                if matches!(adjustment_unit, AdjustmentUnit::Clicks) {
                    match resolve_click_values(
                        elevation_click_value.as_deref(),
                        windage_click_value.as_deref(),
                        saved_profile_data.as_ref(),
                    ) {
                        Ok(Some((el, wi))) => (Some(el), Some(wi)),
                        Ok(None) => (None, None),
                        Err(e) => {
                            eprintln!("error: {e}");
                            std::process::exit(1);
                        }
                    }
                } else {
                    (None, None)
                };

            // Load location from CSV if specified
            let location_data: HashMap<String, String> =
                if let (Some(path), Some(site_name)) = (&location, &site) {
                    match load_csv_row(path, site_name) {
                        Ok(data) => {
                            eprintln!("Loaded location '{}' from {:?}", site_name, path);
                            data
                        }
                        // MBA-1425: same rule as the profile CSV above — a supplied location
                        // that cannot be loaded must stop the run, not silently fall back to
                        // the default atmosphere. A typo'd site name or path produced a
                        // plausible trajectory computed against air the user never asked for.
                        Err(e) => {
                            return Err(format!(
                                "failed to load location '{site_name}' from {path:?}: {e}"
                            )
                            .into());
                        }
                    }
                } else {
                    HashMap::new()
                };

            // Merge values: CLI args override profile/location, profile/location override defaults
            let final_velocity = velocity
                .or_else(|| {
                    let v = csv_get_f64(&profile_data, &["VELOCITY", "MV", "MUZZLE_VELOCITY"], 0.0);
                    if v > 0.0 {
                        Some(v)
                    } else {
                        None
                    }
                })
                .or_else(|| saved_profile_data.as_ref().map(|p| p.velocity))
                .unwrap_or(2800.0);
            let final_velocity_adj = if velocity_adjustment != 0.0 {
                velocity_adjustment
            } else {
                csv_get_f64(&profile_data, &["VELOCITY_ADJ", "VEL_ADJ"], 0.0)
            };
            // Track WHERE the BC came from: a stored reference standard describes the profile's
            // own BC, so it may only be inherited when the BC was inherited too.
            let bc_came_from_saved_profile = bc.is_none()
                && csv_get_f64(&profile_data, &["BC"], 0.0) <= 0.0
                && saved_profile_data.is_some();
            let final_bc = bc
                .or_else(|| {
                    let v = csv_get_f64(&profile_data, &["BC"], 0.0);
                    if v > 0.0 {
                        Some(v)
                    } else {
                        None
                    }
                })
                .or_else(|| saved_profile_data.as_ref().map(|p| p.bc))
                .unwrap_or(0.5);
            // MBA-1365 + whole-branch review (I1): an explicit --bc-reference always wins.
            // Otherwise inherit the profile's stored reference ONLY when this run is also using
            // the profile's BC. A reference standard qualifies one specific BC number; applying
            // a profile's `asm` to a `--bc` (or CSV `BC`) the profile never supplied silently
            // rescaled someone else's value — measured 2144.75 vs 2153.93 fps at 300 yd — and
            // made the double-conversion hazard the docs warn about reachable without the user
            // ever passing the flag. Same rule as the pressure mode below: a qualifier travels
            // with the value it qualifies, or not at all.
            let bc_reference_standard = match bc_reference {
                Some(v) => v,
                None if bc_came_from_saved_profile => parse_bc_reference_profile_field(
                    saved_profile_data
                        .as_ref()
                        .and_then(|p| p.bc_reference.as_deref()),
                )?,
                None => BcReferenceStandard::Icao,
            };
            let final_bc_adj = if bc_adjustment != 1.0 {
                bc_adjustment
            } else {
                csv_get_f64(&profile_data, &["BC_ADJ", "BC_ADJUSTMENT"], 1.0)
            };
            let final_mass = mass
                .or_else(|| saved_profile_data.as_ref().map(|p| p.mass))
                .unwrap_or_else(|| {
                    eprintln!("Error: --mass is required (or use --saved-profile)");
                    std::process::exit(1);
                });
            let final_diameter = diameter
                .or_else(|| saved_profile_data.as_ref().map(|p| p.diameter))
                .unwrap_or_else(|| {
                    eprintln!("Error: --diameter is required (or use --saved-profile)");
                    std::process::exit(1);
                });
            let final_max_range = max_range;
            let final_wind_speed = if wind_speed != 0.0 {
                wind_speed
            } else {
                saved_profile_data
                    .as_ref()
                    .and_then(|p| p.wind_speed)
                    .unwrap_or(0.0)
            };
            // MBA-1367 sentinel fix: explicit presence, not `!= 0.0`, decides whether
            // the CLI value wins over the location CSV — so an explicit
            // `--wind-direction 0` (or `12oc`, which maps to 0 degrees) now beats a
            // CSV WIND_DIR instead of being silently dropped. Behavior change ONLY for
            // the explicit-zero-plus-CSV combination, which previously (surprisingly)
            // let the CSV win; omitted flag + CSV is unchanged.
            let final_wind_direction = match wind_direction {
                Some(d) => d.degrees,
                None => csv_get_f64(&location_data, &["WIND_DIR", "WIND_DIRECTION"], 0.0),
            };
            // MBA-1368: compass bearings (from the flag OR the CSV) become
            // shooter-relative HERE — before the zero solve, the per-atmo-segment
            // winds, and TrajectoryConfig are built — so every downstream
            // WindConditions inherits the converted value. Shooter mode returns the
            // value untouched (bit-identical).
            let final_wind_direction = resolve_wind_reference(
                wind_ref,
                final_wind_direction,
                wind_direction.map(|d| d.was_clock).unwrap_or(false),
                shot_direction,
            )?;

            // Location overrides (environmental conditions).
            // Resolve the per-unit standard once so CSV-less runs use the right
            // standard atmosphere for --units (MBA-960/961).
            let std_temperature = UnitConverter::resolve_temperature(None, cli.units)?;
            let std_pressure = UnitConverter::resolve_pressure(None, cli.units)?;

            // MBA-1417: a saved profile's atmosphere, wired as a SET rather than field by field.
            //
            // Precedence per VALUE is unchanged in spirit: explicit CLI flag > --location CSV >
            // saved profile > built-in standard. The profile simply becomes the innermost
            // fallback instead of the ISA default, so `--saved-profile` finally carries the
            // conditions it has been storing all along. Values arrive already converted to
            // --units by `load_profile_for_units`.
            //
            // The QUALIFIERS are the part that needs care, and the reason this is a set. A
            // pressure MODE describes one specific pressure VALUE, so it may only be inherited
            // when that value is the one actually in use. Inheriting a mode apart from its value
            // is exactly the 77 fps silent error MBA-1397 hit: a profile saved with
            // --pressure-type qnh applied its mode to a CLI absolute reading, giving 2299.49 fps
            // instead of 2222.86 at 300 yd.
            let saved_atmo = saved_profile_data.as_ref();
            let profile_supplied_pressure = pressure.is_none()
                && !csv_has(&location_data, &["PRESSURE", "PRESSURE(HPA OR INHG)"])
                && saved_atmo.is_some();
            let final_temperature = match temperature {
                Some(t) => UnitConverter::resolve_temperature(Some(t), cli.units)?,
                None => csv_get_f64(
                    &location_data,
                    &["TARGET_TEMP", "TEMPERATURE", "TEMP"],
                    csv_get_f64(
                        &profile_data,
                        &["ZERO_TEMP"],
                        saved_atmo.map_or(std_temperature, |p| p.temperature),
                    ),
                ),
            };
            let final_pressure = match pressure {
                Some(p) => UnitConverter::resolve_pressure(Some(p), cli.units)?,
                None => csv_get_f64(
                    &location_data,
                    &["PRESSURE", "PRESSURE(HPA OR INHG)"],
                    saved_atmo.map_or(std_pressure, |p| p.pressure),
                ),
            };
            // MBA-1397 + MBA-1366 review: a pressure MODE describes one specific pressure
            // VALUE, so it must never be inherited apart from it. `trajectory --saved-profile`
            // does not load a profile's stored temperature/pressure/altitude/humidity (a
            // pre-existing gap these fields all share), so inheriting only the stored
            // `pressure_reference` applied a `qnh` mode to whatever pressure the run actually
            // used — a CLI-supplied absolute station reading got silently reduced a second
            // time. Measured at 300 yd: 2299.49 fps inherited vs 2222.86 fps correct, a 77 fps
            // error from a flag the user set once, on a different day, for a different value.
            // MBA-1417 wires the atmosphere as a set, so the stored mode is live again — but
            // ONLY when the profile's pressure value is the one in use. An explicit
            // --pressure-type still wins; a CLI or CSV pressure means the stored mode describes
            // some other reading and is ignored, which is what keeps the bug above fixed.
            let final_pressure_type = match pressure_type {
                Some(mode) => mode,
                None if profile_supplied_pressure => parse_pressure_reference_profile_field(
                    saved_atmo.and_then(|p| p.pressure_reference.as_deref()),
                )?,
                None => PressureReferenceMode::Absolute,
            };
            let final_humidity = if humidity != 50.0 {
                humidity
            } else {
                csv_get_f64(
                    &location_data,
                    &["HUMIDITY"],
                    saved_atmo.map_or(50.0, |p| p.humidity),
                )
            };
            let final_altitude = if altitude != 0.0 {
                altitude
            } else {
                csv_get_f64(
                    &location_data,
                    &["ALTITUDE", "ALT"],
                    csv_get_f64(
                        &profile_data,
                        &["ZERO_ALT"],
                        saved_atmo.map_or(0.0, |p| p.altitude),
                    ),
                )
            };

            // MBA-1366: --density-altitude supersedes --altitude and --pressure/--pressure-type
            // entirely (a CLI flag always wins over a --location/CSV DA/DENSITY_ALTITUDE column,
            // matching every other CSV-backed field above). An explicit --temperature still wins
            // over the ISA-at-density-altitude default; the FAA-rule DA is honored either way (see
            // `atmosphere::resolve_atmosphere_for_density_altitude`'s doc comment for the
            // back-solve). Values here are in DISPLAY units (feet/meters per --units), like
            // final_altitude above; the actual back-solve runs in metric further down.
            //
            // MBA-1417: a profile-stored density_altitude is the third source, and it is the
            // most invasive qualifier of the three, because DA does not merely describe a
            // pressure — it SUPERSEDES the altitude and pressure entirely. So it is honored only
            // when the run has no present-tense pressure or altitude of its own to supersede: no
            // explicit --pressure/--altitude, and nothing from a --location CSV. Letting a DA
            // stored on a different day quietly override a pressure the user just typed would be
            // the same class of error as inheriting a pressure mode apart from its value, with a
            // larger blast radius.
            let final_density_altitude: Option<f64> = match density_altitude {
                Some(da) => Some(da),
                None => {
                    let da_csv = csv_get_f64(&location_data, &["DA", "DENSITY_ALTITUDE"], f64::NAN);
                    if !da_csv.is_nan() {
                        Some(da_csv)
                    } else {
                        let run_supplied_its_own_atmosphere = pressure.is_some()
                            || altitude != 0.0
                            || csv_has(&location_data, &["PRESSURE", "PRESSURE(HPA OR INHG)"])
                            || csv_has(&location_data, &["ALTITUDE", "ALT"]);
                        saved_atmo
                            .filter(|_| !run_supplied_its_own_atmosphere)
                            .and_then(|p| p.density_altitude)
                    }
                }
            };
            if final_density_altitude.is_some() && (pressure.is_some() || pressure_type.is_some()) {
                eprintln!(
                    "note: --density-altitude supersedes --pressure/--pressure-type (station \
                     pressure is derived from density altitude instead)"
                );
            }
            // Whole-branch review (I3): --altitude was superseded just as silently as --pressure
            // but said nothing, so a user who set both saw one note and assumed the other flag
            // had been honored. Density altitude supersedes altitude from EITHER source — flag
            // or `--location` CSV row — so say so whenever an altitude was actually supplied.
            // `altitude` carries a clap default of 0.0 rather than an Option, so this reuses the
            // same "non-default means supplied" sentinel `final_altitude` uses just below; an
            // explicit `--altitude 0` is indistinguishable from the default, as everywhere else.
            if final_density_altitude.is_some() && altitude != 0.0 {
                eprintln!(
                    "note: --density-altitude supersedes --altitude (the station altitude is \
                     back-solved from density altitude instead)"
                );
            }
            let (final_temperature, final_pressure, final_altitude, final_pressure_type) =
                match final_density_altitude {
                    Some(da_display) => {
                        let da_m = UnitConverter::altitude_to_metric(da_display, cli.units);
                        // "Explicit temperature" for DA precedence means a real --temperature
                        // flag, not a CSV/profile-derived fallback (final_temperature above may
                        // already reflect one of those, so gate on the raw Option instead).
                        let explicit_temp_c = temperature.map(|_| {
                            UnitConverter::temperature_to_metric(final_temperature, cli.units)
                        });
                        let (da_altitude_m, da_temp_c, da_pressure_hpa) =
                            ballistics_engine::atmosphere::resolve_atmosphere_for_density_altitude(
                                da_m,
                                explicit_temp_c,
                            );
                        (
                            UnitConverter::temperature_from_metric(da_temp_c, cli.units),
                            UnitConverter::pressure_from_metric(da_pressure_hpa, cli.units),
                            UnitConverter::altitude_from_metric(da_altitude_m, cli.units),
                            PressureReferenceMode::Absolute,
                        )
                    }
                    None => (
                        final_temperature,
                        final_pressure,
                        final_altitude,
                        final_pressure_type,
                    ),
                };

            // Get zero range: CLI --auto-zero > selected zero set (MBA-1360) > profile
            // CSV ZERO_RANGE > saved profile auto_zero/zero_distance — resolved through
            // the shared zero-selection resolver. With no --zero-set the set layer
            // vanishes and this is exactly the historical
            // `auto_zero.or(csv).or(profile.auto_zero.or(zero_distance))` chain.
            let csv_zero_set = zero_set_from_profile_csv(&profile_data, profile_row.as_deref());
            let legacy_zero: Option<f64> = {
                let zero_from_csv =
                    csv_get_f64(&profile_data, &["ZERO_RANGE", "ZERO_DISTANCE", "ZERO"], 0.0);
                if zero_from_csv > 0.0 {
                    Some(zero_from_csv)
                } else {
                    saved_profile_data
                        .as_ref()
                        .and_then(|p| p.auto_zero.or(p.zero_distance))
                }
            };
            let zero_selection = resolve_zero_selection(
                zero_set.as_deref(),
                saved_profile_data.as_ref(),
                csv_zero_set.as_ref(),
                auto_zero,
                legacy_zero,
            )
            .map_err(|e| -> Box<dyn Error> { e.into() })?;
            let final_auto_zero: Option<f64> = zero_selection.zero_distance;

            // Resolve additional params from saved profile (if not explicitly set via CLI)
            let drag_model = if saved_profile_data.is_some() && velocity.is_none() && bc.is_none() {
                saved_profile_data
                    .as_ref()
                    .map(|p| parse_drag_model_arg(&p.drag_model))
                    .unwrap_or(drag_model)
            } else {
                drag_model
            };
            let use_bc_segments = use_bc_segments
                || saved_profile_data
                    .as_ref()
                    .and_then(|p| p.use_bc_segments)
                    .unwrap_or(false);
            let twist_right = saved_profile_data
                .as_ref()
                .and_then(|p| p.twist_right)
                .unwrap_or(twist_right);
            let shooting_angle = if shooting_angle != 0.0 {
                shooting_angle
            } else {
                saved_profile_data
                    .as_ref()
                    .and_then(|p| p.shooting_angle)
                    .unwrap_or(0.0)
            };
            let bullet_length =
                bullet_length.or_else(|| saved_profile_data.as_ref().and_then(|p| p.bullet_length));
            let sight_height =
                sight_height.or_else(|| saved_profile_data.as_ref().and_then(|p| p.sight_height));
            // MBA-1359: deliberate POI offset at the zero range. The CLI flags (inches
            // imperial / cm metric) win over the saved profile's stored values (which are
            // ALWAYS meters — see ProfileData::zero_poi_up_m). 0.0 = no offset.
            let zero_poi_vertical_metric = zero_poi_up
                .map(|v| zero_poi_display_to_metric(v, cli.units))
                .or_else(|| saved_profile_data.as_ref().and_then(|p| p.zero_poi_up_m))
                .unwrap_or(0.0);
            let zero_poi_horizontal_metric = zero_poi_right
                .map(|v| zero_poi_display_to_metric(v, cli.units))
                .or_else(|| saved_profile_data.as_ref().and_then(|p| p.zero_poi_right_m))
                .unwrap_or(0.0);
            // MBA-1396: lateral sight-mount offset, same CLI-over-profile precedence
            // (profile value is ALWAYS meters — see ProfileData::sight_offset_lateral_m).
            let sight_offset_lateral_metric = sight_offset
                .map(|v| sight_offset_display_to_metric(v, cli.units))
                .or_else(|| {
                    saved_profile_data
                        .as_ref()
                        .and_then(|p| p.sight_offset_lateral_m)
                })
                .unwrap_or(0.0);
            // MBA-1358: scope tracking CFs — CLI flag over profile field, validated here
            // (and again on profile load); 1.0 = no correction, byte-identical.
            let elevation_cf = resolve_tracking_cf(
                elevation_cf,
                saved_profile_data.as_ref().and_then(|p| p.elevation_cf),
                "--elevation-cf",
            )?;
            let windage_cf = resolve_tracking_cf(
                windage_cf,
                saved_profile_data.as_ref().and_then(|p| p.windage_cf),
                "--windage-cf",
            )?;
            let twist_rate =
                twist_rate.or_else(|| saved_profile_data.as_ref().and_then(|p| p.twist_rate));
            // --twist-rate is mm/turn in metric and inches/turn in imperial, matching the
            // `stability` subcommand (MBA-970). The engine and all downstream paths
            // (local solver, TrajectoryConfig, the --compare API request) treat twist as
            // inches/turn, so convert once here. Previously metric twist was used raw as
            // inches (~25x off), so e.g. a 254 mm (1:10") twist read as 254"/turn and
            // collapsed stability/spin-drift to ~0.
            let twist_rate = twist_rate.map(|t| match cli.units {
                UnitSystem::Imperial => t,
                UnitSystem::Metric => t / 25.4, // mm/turn -> inches/turn
            });
            // --powder-temp serves two roles (the models are mutually exclusive):
            //   * with --powder-temp-curve: the POWDER temperature to interpolate at.
            //     Only set when the user supplied it; otherwise the curve falls back to
            //     the ambient --temperature (powder assumed at air temperature).
            //   * with --powder-temp-sensitivity (linear): the reference temperature the
            //     stated velocity was measured at (default 70°F / 21°C).
            // powder_curve_temp_c is the curve override in Celsius (Some iff provided);
            // powder_temp is the linear reference in display units (always resolved).
            let powder_curve_temp_c: Option<f64> =
                powder_temp.map(|t| UnitConverter::temperature_to_metric(t, cli.units));
            let powder_temp = powder_temp.unwrap_or(match cli.units {
                UnitSystem::Imperial => DEFAULT_POWDER_REFERENCE_TEMP_F,
                UnitSystem::Metric => DEFAULT_POWDER_REFERENCE_TEMP_C,
            });
            let powder_temp_sensitivity = powder_temp_sensitivity.unwrap_or(match cli.units {
                UnitSystem::Imperial => 1.0,
                UnitSystem::Metric => 0.3048 / (5.0 / 9.0),
            });

            // Parse the optional measured powder-temperature -> velocity curve into
            // canonical SI points. When present it supersedes the linear sensitivity
            // model at solve time (see cli_api::TrajectorySolver::new).
            let powder_temp_curve_si: Option<Vec<(f64, f64)>> = match powder_temp_curve.as_deref() {
                Some(s) => Some(parse_powder_temp_curve(s, cli.units)?),
                None => None,
            };

            // Apply truing adjustments
            let trued_velocity = final_velocity + final_velocity_adj;
            let pre_table_bc = final_bc * final_bc_adj;
            let mut trued_bc = pre_table_bc;
            let trued_velocity_fps = match cli.units {
                UnitSystem::Imperial => trued_velocity,
                UnitSystem::Metric => trued_velocity / 0.3048,
            };
            let caliber_in = match cli.units {
                UnitSystem::Imperial => final_diameter,
                UnitSystem::Metric => final_diameter / 25.4,
            };

            // Apply BC correction from table if provided
            // Generate velocity-dependent BC segments from the table for accurate trajectory
            let mut bc_table_segments: Option<Vec<BCSegmentData>> = None;
            let bc_table_correction: Option<f64> = if let Some(table_path) = &bc_table {
                match BcCorrectionTable::load(table_path) {
                    Ok(table) => {
                        // Get bullet length: CLI arg > CSV profile > estimate from diameter
                        let bullet_length_in = bullet_length
                            .map(|l| match cli.units {
                                UnitSystem::Imperial => l,
                                UnitSystem::Metric => l / 25.4,
                            })
                            .or_else(|| {
                                let len =
                                    csv_get_f64(&profile_data, &["BULLET_LENGTH", "LENGTH"], 0.0);
                                if len > 0.0 {
                                    Some(match cli.units {
                                        UnitSystem::Imperial => len,
                                        UnitSystem::Metric => len / 25.4,
                                    })
                                } else {
                                    None
                                }
                            })
                            .unwrap_or_else(|| {
                                // MBA-1135: mass-based length estimate (was a mass-blind
                                // caliber*3.5 heuristic). Length is a real axis of this BC
                                // correction table. Fall back to caliber*3.5 only if mass<=0.
                                let mass_gr = match cli.units {
                                    UnitSystem::Imperial => final_mass,
                                    UnitSystem::Metric => final_mass * 15.4324,
                                };
                                let est_m = ballistics_engine::stability::estimate_bullet_length_m(
                                    caliber_in * 0.0254,
                                    mass_gr * GRAINS_TO_KG,
                                );
                                if est_m > 0.0 {
                                    est_m / 0.0254
                                } else {
                                    caliber_in * 3.5
                                }
                            });

                        // Get bullet mass in grains
                        let mass_grains = match cli.units {
                            UnitSystem::Imperial => final_mass,         // already in grains
                            UnitSystem::Metric => final_mass * 15.4324, // grams to grains
                        };

                        // BC type string
                        let bc_type_str = warn_aux_g1_coercion("--bc-table correction", drag_model);

                        // Velocity breakpoints for BC segments (denser in transonic region)
                        // These match the table's velocity bins for optimal interpolation
                        let velocity_breakpoints: Vec<f64> = vec![
                            trued_velocity_fps, // Muzzle velocity
                            2700.0,
                            2500.0,
                            2300.0,
                            2100.0,
                            2000.0,
                            1900.0,
                            1800.0,
                            1700.0,
                            1600.0,
                            1500.0,
                            1400.0,
                            1350.0,
                            1300.0,
                            1250.0,
                            1200.0,
                            1150.0,
                            1100.0,
                            1050.0,
                            1000.0,
                            950.0,
                            900.0,
                            850.0,
                            800.0,
                            700.0,
                            600.0,
                            500.0,
                        ];

                        // Filter breakpoints to be below muzzle velocity and sort descending
                        let mut valid_velocities: Vec<f64> = velocity_breakpoints
                            .into_iter()
                            .filter(|&v| v <= trued_velocity_fps && v >= 500.0)
                            .collect();
                        valid_velocities.sort_by(|a, b| b.partial_cmp(a).unwrap());
                        valid_velocities.dedup();

                        // Generate BC segments from table
                        let mut segments: Vec<BCSegmentData> = Vec::new();
                        for i in 0..valid_velocities.len().saturating_sub(1) {
                            let vel_max = valid_velocities[i];
                            let vel_min = valid_velocities[i + 1];
                            let vel_mid = (vel_max + vel_min) / 2.0;

                            // Lookup correction at midpoint velocity
                            let correction = table.lookup(
                                final_bc,
                                bc_type_str,
                                mass_grains,
                                bullet_length_in,
                                vel_mid,
                            );

                            // Calculate corrected BC for this segment
                            let segment_bc = trued_bc * correction;

                            segments.push(BCSegmentData {
                                velocity_min: vel_min,
                                velocity_max: vel_max,
                                bc_value: segment_bc,
                            });
                        }

                        // Get correction at muzzle velocity for display
                        let muzzle_correction = table.lookup(
                            final_bc,
                            bc_type_str,
                            mass_grains,
                            bullet_length_in,
                            trued_velocity_fps,
                        );

                        eprintln!(
                            "BC Table: Loaded {} (v{}, {})",
                            table_path.display(),
                            table.version(),
                            table.dimensions_str()
                        );
                        eprintln!(
                            "BC Table: Generated {} velocity-dependent BC segments",
                            segments.len()
                        );
                        eprintln!("BC Table: Muzzle correction={:.4} for BC={:.3} {} {}gr {:.3}\" @ {:.0}fps",
                            muzzle_correction, final_bc, bc_type_str, mass_grains, bullet_length_in, trued_velocity_fps);

                        // Show BC range if segments were generated
                        if !segments.is_empty() {
                            let min_bc = segments
                                .iter()
                                .map(|s| s.bc_value)
                                .fold(f64::INFINITY, f64::min);
                            let max_bc = segments
                                .iter()
                                .map(|s| s.bc_value)
                                .fold(f64::NEG_INFINITY, f64::max);
                            eprintln!(
                                "BC Table: BC range {:.5} - {:.5} across velocity envelope",
                                min_bc, max_bc
                            );
                            bc_table_segments = Some(segments);
                        }

                        // Still apply correction to trued_bc for display purposes
                        trued_bc *= muzzle_correction;
                        Some(muzzle_correction)
                    }
                    Err(e) => {
                        eprintln!("Warning: Failed to load BC table: {}", e);
                        eprintln!("         Continuing without BC correction table.");
                        None
                    }
                }
            } else {
                None
            };

            // Apply BC correction from 5D caliber-specific table if provided (and bc_table wasn't used)
            // Determine effective table directory: explicit --bc-table-dir, or auto-download cache
            #[cfg(feature = "online")]
            let effective_bc_table_dir: Option<PathBuf> = if bc_table_dir.is_some() {
                bc_table_dir.clone()
            } else if bc_table_auto {
                // Auto-download mode: ensure table is available, use cache directory
                match Bc5dDownloader::new(&bc_table_url, bc_table_refresh) {
                    Ok(mut downloader) => {
                        match downloader.ensure_table(caliber_in) {
                            Ok(table_path) => {
                                // Return the parent directory (cache dir) as table directory
                                table_path.parent().map(|p| p.to_path_buf())
                            }
                            Err(e) => {
                                eprintln!("Warning: {}", e);
                                eprintln!("         Continuing without BC5D correction table.");
                                None
                            }
                        }
                    }
                    Err(e) => {
                        eprintln!("Warning: BC5D table download failed: {}", e);
                        eprintln!("         Continuing without BC5D correction table.");
                        None
                    }
                }
            } else {
                None
            };

            #[cfg(not(feature = "online"))]
            let effective_bc_table_dir: Option<PathBuf> = bc_table_dir.clone();

            // Apply BC correction from 5D caliber-specific table if provided (MBA-744: uses shared helper)
            let bc_table_5d_correction: Option<f64> = if bc_table_correction.is_none() {
                if let Some(table_dir) = &effective_bc_table_dir {
                    let mut manager = Bc5dTableManager::new(table_dir);
                    // Identity guard before any lookup: refuse a table whose header
                    // caliber is not this shot's caliber (see the helper's docs).
                    reject_bc5d_caliber_mismatch(&mut manager, caliber_in)?;

                    let mass_grains = match cli.units {
                        UnitSystem::Imperial => final_mass,
                        UnitSystem::Metric => final_mass * 15.4324,
                    };

                    let bc_type_str = warn_aux_g1_coercion("BC5D correction tables", drag_model);

                    // Print table info if available
                    if let Ok(table) = manager.get_table(caliber_in) {
                        eprintln!(
                            "BC5D Table: Loaded caliber {:.3} (v{}, API {}, {})",
                            table.caliber(),
                            table.version(),
                            table.api_version(),
                            table.dimensions_str()
                        );
                    }

                    let bullet_length_user: Option<f64> = bullet_length
                        .map(|l| match cli.units {
                            UnitSystem::Imperial => l,
                            UnitSystem::Metric => l / 25.4,
                        })
                        .or_else(|| {
                            let csv_len =
                                csv_get_f64(&profile_data, &["BULLET_LENGTH", "LENGTH"], 0.0);
                            if csv_len > 0.0 {
                                Some(match cli.units {
                                    UnitSystem::Imperial => csv_len,
                                    UnitSystem::Metric => csv_len / 25.4,
                                })
                            } else {
                                None
                            }
                        });
                    let length_is_user = bullet_length_user.is_some();
                    let bullet_length_in = bullet_length_user.unwrap_or_else(|| {
                        // MBA-1135: mass-based length estimate (was a mass-blind caliber*3.5
                        // heuristic). Informational for the v2 BC5D table (length is not a
                        // lookup axis); fall back to caliber*3.5 only if mass<=0.
                        let est_m = ballistics_engine::stability::estimate_bullet_length_m(
                            caliber_in * 0.0254,
                            mass_grains * GRAINS_TO_KG,
                        );
                        if est_m > 0.0 {
                            est_m / 0.0254
                        } else {
                            caliber_in * 3.5
                        }
                    });

                    // BC5D segment generation is keyed by the manually adjusted BC. Preserve
                    // that pre-table value so the muzzle lookup samples the same BC axis.
                    let table_base_bc = trued_bc;

                    if let Some(segments) = generate_bc5d_segments(
                        &mut manager,
                        caliber_in,
                        table_base_bc,
                        bc_type_str,
                        mass_grains,
                        Some(trued_velocity_fps),
                        Some(bullet_length_in),
                        length_is_user,
                        if print_bc_segments {
                            Some(cli.units)
                        } else {
                            None
                        },
                    ) {
                        bc_table_segments = Some(segments);

                        let muzzle_correction = manager
                            .lookup(
                                caliber_in,
                                mass_grains,
                                table_base_bc,
                                trued_velocity_fps,
                                trued_velocity_fps,
                                bc_type_str,
                            )
                            .unwrap_or(1.0);
                        eprintln!(
                            "BC5D Table: Muzzle correction={:.4} for BC={:.3} {} {}gr @ {:.0}fps",
                            muzzle_correction,
                            table_base_bc,
                            bc_type_str,
                            mass_grains,
                            trued_velocity_fps
                        );
                        trued_bc = table_base_bc * muzzle_correction;
                        Some(muzzle_correction)
                    } else {
                        None
                    }
                } else {
                    None
                }
            } else {
                None // bc_table was already used
            };

            // Combine corrections for display
            let combined_bc_correction = bc_table_correction.or(bc_table_5d_correction);

            // Show effective values if using profile/location or BC table
            if !profile_data.is_empty()
                || !location_data.is_empty()
                || saved_profile_data.is_some()
                || combined_bc_correction.is_some()
            {
                let bc_info = if let Some(corr) = combined_bc_correction {
                    format!(
                        "BC={:.3} (table-corrected={:.4}, factor={:.4})",
                        final_bc, trued_bc, corr
                    )
                } else {
                    format!("BC={:.3} (trued={:.4})", final_bc, trued_bc)
                };
                eprintln!(
                    "Effective values: velocity={:.1} (trued={:.1}), {}",
                    final_velocity, trued_velocity, bc_info
                );
                if !location_data.is_empty() {
                    eprintln!(
                        "                  altitude={:.0}, temp={:.1}, pressure={:.2}",
                        final_altitude, final_temperature, final_pressure
                    );
                }
            }

            // Rename for clarity
            let bullet_mass = final_mass;
            let bullet_diameter = final_diameter;
            // Convert inputs to metric (using trued/final values)
            let velocity_metric = UnitConverter::velocity_to_metric(trued_velocity, cli.units);
            let mass_metric = UnitConverter::mass_to_metric(bullet_mass, cli.units);
            let diameter_metric = UnitConverter::diameter_to_metric(bullet_diameter, cli.units);
            let max_range_metric = UnitConverter::distance_to_metric(final_max_range, cli.units);
            let wind_speed_metric = UnitConverter::wind_to_metric(final_wind_speed, cli.units);
            let wind_vertical_metric = UnitConverter::wind_to_metric(wind_vertical, cli.units);
            let temperature_metric =
                UnitConverter::temperature_to_metric(final_temperature, cli.units);
            let pressure_metric = UnitConverter::pressure_to_metric(final_pressure, cli.units);
            let altitude_metric = UnitConverter::altitude_to_metric(final_altitude, cli.units);
            // Default sight height: 2 inches for imperial, 50mm for metric
            let sight_height_default = match cli.units {
                UnitSystem::Imperial => 2.0,
                UnitSystem::Metric => 50.0,
            };
            let sight_height_value = sight_height.unwrap_or(sight_height_default);
            let sight_height_metric =
                UnitConverter::sight_height_to_metric(sight_height_value, cli.units);

            // Bore height above ground. MBA-1339 unified this flag onto the same inches/mm
            // units as --sight-height and the WASM --muzzle-height flag (previously feet/
            // meters). Defaults are unchanged: 60 in = 5 ft = 1.524 m; 1500 mm = 1.5 m.
            let bore_height_default = match cli.units {
                UnitSystem::Imperial => 60.0, // inches
                UnitSystem::Metric => 1500.0, // mm
            };
            let bore_height_value = bore_height.unwrap_or(bore_height_default);
            let bore_height_metric = match cli.units {
                UnitSystem::Imperial => bore_height_value * 0.0254, // inches to meters
                UnitSystem::Metric => bore_height_value * 0.001,    // mm to meters
            };
            // Trajectory altitude feeds local air density, so an absurd bore height
            // silently thins the air over the whole flight (a 25 km "muzzle" flies in
            // ~2% density) or blows up the integrator. Warn — never clamp.
            if bore_height_metric > 1000.0 {
                eprintln!(
                    "warning: --bore-height puts the bore {bore_height_metric:.0} m above ground; \
                     air density is computed at trajectory altitude, so this thins the air for \
                     the entire flight. If you meant site elevation use --altitude; to disable \
                     ground-impact truncation use --ignore-ground-impact."
                );
            }

            // Construct PDF metadata if PDF output is requested
            let pdf_metadata = if matches!(output, OutputFormat::Pdf) {
                // Get rifle name from profile_row or use a default
                let rifle_name = profile_row.clone().unwrap_or_else(|| "Rifle".to_string());
                // Get location name: CLI > site > default
                let loc_name = location_name
                    .clone()
                    .or_else(|| site.clone())
                    .unwrap_or_else(|| "Field".to_string());
                // Get powder and bullet from CLI, or from profile if available
                let powder_name = powder
                    .clone()
                    .or_else(|| profile_data.get("POWDER_NAME").cloned())
                    .unwrap_or_default();
                let bullet_display = bullet_name
                    .clone()
                    .or_else(|| profile_data.get("BULLET_NAME").cloned())
                    .unwrap_or_default();

                // Resolve effective font scale: --font-scale overrides --font-preset
                #[cfg(feature = "pdf")]
                let effective_font_scale = if font_scale != 1.0 {
                    font_scale
                } else if let Some(ref preset) = font_preset {
                    FontSizePreset::from_str(preset)
                        .map(|p| p.scale())
                        .unwrap_or_else(|| {
                            eprintln!("Warning: Unknown font preset '{}', using medium", preset);
                            1.0
                        })
                } else {
                    1.0
                };
                #[cfg(not(feature = "pdf"))]
                let effective_font_scale = font_scale;

                Some(PdfMetadata {
                    rifle_name,
                    location_name: loc_name,
                    powder: powder_name,
                    bullet_name: bullet_display,
                    // MBA-1325: was a bare passthrough (always mph, ignoring --units — the
                    // only field in this block that didn't follow the sibling unit-aware
                    // conversions below). --target-speed follows the documented mph
                    // imperial / m/s metric convention like every other speed flag, so
                    // metric callers now get their m/s value converted here instead of it
                    // being silently misread as mph.
                    target_speed_mph: match cli.units {
                        UnitSystem::Imperial => target_speed,
                        UnitSystem::Metric => target_speed / 0.44704,
                    },
                    output_file: output_file.clone(),
                    velocity_fps: match cli.units {
                        UnitSystem::Imperial => trued_velocity,
                        UnitSystem::Metric => trued_velocity / 0.3048,
                    },
                    temperature_f: match cli.units {
                        UnitSystem::Imperial => final_temperature,
                        UnitSystem::Metric => final_temperature * 9.0 / 5.0 + 32.0,
                    },
                    pressure_inhg: match cli.units {
                        UnitSystem::Imperial => final_pressure,
                        UnitSystem::Metric => final_pressure / 33.8639,
                    },
                    altitude_ft: match cli.units {
                        UnitSystem::Imperial => final_altitude,
                        UnitSystem::Metric => final_altitude / 0.3048,
                    },
                    wind_speed_mph: match cli.units {
                        UnitSystem::Imperial => final_wind_speed,
                        UnitSystem::Metric => final_wind_speed / 0.44704,
                    },
                    weight_gr: match cli.units {
                        UnitSystem::Imperial => bullet_mass,
                        UnitSystem::Metric => bullet_mass * 15.4324,
                    },
                    font_scale: effective_font_scale,
                    bold_data,
                    adjustment_unit,
                    windage_unit: windage_unit_resolved,
                })
            } else {
                None
            };

            // Manual velocity:BC segments (--bc-segment "VMIN:VMAX:BC", display units
            // -> fps) take precedence over any --bc-table-dir / BC5D segments resolved
            // above. Resolved BEFORE the auto-zero solve below so the zero angle is
            // computed with the SAME velocity-keyed BC the trajectory uses (otherwise a
            // segment that changes early-flight drag would mis-zero the shot); via
            // bc_table_segments.is_some() this also implies --use-bc-segments.
            let manual_bc_segments: Vec<BCSegmentData> = bc_segment
                .iter()
                .map(|s| parse_bc_segment(s, cli.units))
                .collect::<Result<Vec<_>, String>>()?;
            if !manual_bc_segments.is_empty() {
                bc_table_segments = Some(manual_bc_segments.clone());
                // Manual segments fully override either correction-table format. Restore
                // the manually adjusted, pre-table BC directly so interior gaps use the
                // same scalar fallback with or without a table, keeping parity with WASM.
                trued_bc = pre_table_bc;
            }

            // Saved-profile velocity-BC breakpoints (MBA-1323 Phase 2: `.a7p` multi-row G1/G7
            // import) fill the schedule only when nothing more specific for THIS run already
            // did (no --bc-segment, no --bc-table-dir correction table) — a saved default,
            // not an override of explicit CLI intent.
            if bc_table_segments.is_none() {
                if let Some(rows) = saved_profile_data
                    .as_ref()
                    .and_then(|p| p.bc_segments.as_ref())
                {
                    bc_table_segments = Some(bc_segments_from_profile(rows));
                }
            }

            // Resolve the final velocity-keyed BC schedule before auto-zero. This is the single
            // schedule cloned into the zero solve, native flight, and compare-local flight.
            let bc_segments_data = resolve_velocity_bc_segments(
                bc_table_segments.as_deref(),
                use_bc_segments,
                trued_bc,
                diameter_metric,
                mass_metric,
                drag_model,
            );
            let effective_use_bc_segments = use_bc_segments || bc_segments_data.is_some();

            // Resolve --drag-table once, shared by the zero solve, native flight, and
            // compare-local flight, same as the BC schedule above. A saved profile's Mach/Cd
            // drag curve (MBA-1323 Phase 2: `.a7p` CUSTOM import) is the fallback when
            // --drag-table was not given for THIS run — same "saved default, not an override
            // of explicit CLI intent" precedence as the BC segments above.
            let custom_drag_table =
                drag_table
                    .as_deref()
                    .map(load_drag_table_or_exit)
                    .or_else(|| {
                        saved_profile_data
                            .as_ref()
                            .and_then(|p| p.drag_curve.as_ref())
                            .map(|pts| {
                                drag_table_from_profile(pts).unwrap_or_else(|e| {
                                    eprintln!("Error: saved profile's drag curve is invalid: {e}");
                                    std::process::exit(1);
                                })
                            })
                    });
            if custom_drag_table.is_some() && effective_use_bc_segments {
                eprintln!(
                    "Warning: --drag-table and BC segments were both provided; the drag table takes \
                     precedence and BC segments are ignored."
                );
            }
            // MBA-1356: --cd-scale requires --drag-table; validate before any solve. This
            // surface (Trajectory) has --bc-adjustment, so the pairing error may suggest it.
            let cd_scale = resolve_cd_scale(cd_scale, custom_drag_table.is_some(), true)
                .unwrap_or_else(|e| {
                    eprintln!("error: {e}");
                    std::process::exit(1);
                });

            // MBA-1365: --bc-reference army-standard-metro has no effect once a custom
            // drag table replaces the BC-based retardation model entirely.
            if custom_drag_table.is_some()
                && matches!(
                    bc_reference_standard,
                    BcReferenceStandard::ArmyStandardMetro
                )
            {
                eprintln!(
                    "{}",
                    ballistics_engine::cli_api::BC_REFERENCE_STANDARD_INERT_WARNING
                );
            }

            // Calculate zero angle if auto-zero is specified (from CLI or profile)
            let muzzle_angle = if let Some(zero_distance) = final_auto_zero {
                let zero_distance_metric =
                    UnitConverter::distance_to_metric(zero_distance, cli.units);

                // Resolve the condition set the zero ANGLE is solved under: shot-day values
                // overridden by any --zero-* flags supplied. This models a rifle zeroed on a
                // different day (different air density) and/or at a different muzzle velocity
                // (e.g. from a powder-temp/velocity table), while the trajectory below still
                // runs under the current shot-day conditions. Omitting all --zero-* flags
                // falls through to the shot-day values, reproducing the prior behavior.
                let zero_velocity_metric = match zero_velocity {
                    Some(v) => UnitConverter::velocity_to_metric(v, cli.units),
                    None => velocity_metric,
                };
                let zero_temperature_metric = match zero_temperature {
                    Some(t) => UnitConverter::temperature_to_metric(t, cli.units),
                    None => temperature_metric,
                };
                let zero_pressure_metric = match zero_pressure {
                    Some(p) => UnitConverter::pressure_to_metric(p, cli.units),
                    None => pressure_metric,
                };
                // MBA-1397: an explicit --zero-pressure-type wins; otherwise the zero day
                // shares the shot day's mode (matches "omitting all --zero-* flags reuses the
                // shot-day values" for the numeric pressure above).
                //
                // Whole-branch review (I2): with `--density-altitude` and no `--zero-pressure`,
                // the zero day inherits the DA-derived station pressure, which is ALREADY
                // absolute. An explicit `--zero-pressure-type qnh` then reduced it a second
                // time (apex 1.6959 -> 1.6655 m at an 800 m zero, silently). The mode has no
                // value of its own to describe here, so it cannot apply — the same rule the
                // shot-day reset and the profile-inheritance fix follow. An explicit
                // `--zero-pressure` DOES bring its own value, so its mode is honored.
                let zero_pressure_type_resolved = match zero_pressure_type {
                    Some(mode)
                        if (final_density_altitude.is_some()
                            || zero_density_altitude.is_some())
                            && zero_pressure.is_none() =>
                    {
                        if mode != PressureReferenceMode::Absolute {
                            // Name whichever flag actually supplied the pressure. A zero-day DA
                            // takes precedence over an inherited shot-day one, so report that.
                            let source = if zero_density_altitude.is_some() {
                                "--zero-density-altitude"
                            } else {
                                "--density-altitude"
                            };
                            eprintln!(
                                "warning: --zero-pressure-type is ignored because {source} supplies the zero-day station pressure directly; pass --zero-pressure to declare a zero-day pressure of your own"
                            );
                        }
                        PressureReferenceMode::Absolute
                    }
                    Some(mode) => mode,
                    None => final_pressure_type,
                };
                let zero_humidity_value = zero_humidity.unwrap_or(final_humidity);
                let zero_altitude_metric = match zero_altitude {
                    Some(a) => UnitConverter::altitude_to_metric(a, cli.units),
                    None => altitude_metric,
                };

                // MBA-1422: --zero-density-altitude, the zero-day counterpart of
                // --density-altitude. It supersedes --zero-altitude and --zero-pressure for the
                // ZERO solve only; the shot-day atmosphere above is untouched. An explicit
                // --zero-temperature still wins over the ISA temperature at that density
                // altitude, and the pressure is re-solved around it so the requested density
                // altitude is reproduced exactly.
                //
                // The mode is already handled by zero_pressure_type_resolved above, which now
                // covers this case too: with a zero-day DA and no --zero-pressure, an explicit
                // --zero-pressure-type has no value of its own to describe and is refused rather
                // than re-reducing a pressure the back-solve already produced as absolute. That
                // is the same bug 0.29.0's whole-branch review caught on the shot-day DA path
                // (apex 1.6959 -> 1.6655 m at an 800 m zero, silently).
                let (zero_temperature_metric, zero_pressure_metric, zero_altitude_metric) =
                    match zero_density_altitude {
                        Some(da_display) => {
                            let da_m = UnitConverter::altitude_to_metric(da_display, cli.units);
                            let explicit_zero_temp_c = zero_temperature
                                .map(|t| UnitConverter::temperature_to_metric(t, cli.units));
                            let (da_altitude_m, da_temp_c, da_pressure_hpa) =
                                ballistics_engine::atmosphere::resolve_atmosphere_for_density_altitude(
                                    da_m,
                                    explicit_zero_temp_c,
                                );
                            (da_temp_c, da_pressure_hpa, da_altitude_m)
                        }
                        None => (
                            zero_temperature_metric,
                            zero_pressure_metric,
                            zero_altitude_metric,
                        ),
                    };
                if zero_velocity.is_some()
                    || zero_temperature.is_some()
                    || zero_pressure.is_some()
                    || zero_humidity.is_some()
                    || zero_altitude.is_some()
                    || zero_density_altitude.is_some()
                {
                    eprintln!(
                        "Solving zero angle under supplied zero-day conditions (velocity/atmosphere \
                         may differ from the shot-day trajectory)."
                    );
                }

                // An explicit zero velocity is absolute. Otherwise let the solver apply the
                // linear powder model at the zero-day air temperature; a curve, when present,
                // retains precedence inside TrajectorySolver::new.
                let apply_zero_linear = zero_velocity.is_none() && use_powder_sensitivity;

                // Create inputs for zero calculation
                let zero_inputs = BallisticInputs {
                    muzzle_velocity: zero_velocity_metric,
                    bc_value: trued_bc,
                    bc_type: drag_model,
                    bc_reference_standard,
                    bullet_mass: mass_metric,
                    bullet_diameter: diameter_metric,
                    caliber_inches: diameter_metric / 0.0254,
                    weight_grains: mass_metric / GRAINS_TO_KG,
                    bullet_length: bullet_length
                        .map(|l| match cli.units {
                            UnitSystem::Imperial => l * 0.0254,
                            UnitSystem::Metric => l * 0.001,
                        })
                        .unwrap_or_else(|| fallback_bullet_length_m(diameter_metric, mass_metric)),
                    sight_height: sight_height_metric,
                    muzzle_height: bore_height_metric,
                    ground_threshold: 0.0,
                    altitude: zero_altitude_metric,
                    temperature: zero_temperature_metric,
                    pressure: zero_pressure_metric,
                    humidity: zero_humidity_value,
                    use_powder_sensitivity: apply_zero_linear,
                    powder_temp_sensitivity: if apply_zero_linear {
                        UnitConverter::velocity_to_metric(powder_temp_sensitivity, cli.units)
                            / UnitConverter::temperature_delta_to_metric(1.0, cli.units)
                    } else {
                        0.0
                    },
                    // For the linear model this is the reference temperature at which the
                    // stated velocity was measured; --zero-powder-temp remains curve-only.
                    powder_temp: UnitConverter::temperature_to_metric(powder_temp, cli.units),
                    // Let a powder curve set the zero-day velocity at the zero-day
                    // temperature — UNLESS an explicit --zero-velocity was given, which
                    // takes precedence (the constructor would otherwise override it).
                    powder_temp_curve: if zero_velocity.is_some() {
                        None
                    } else {
                        powder_temp_curve_si.clone()
                    },
                    // Explicit zero-day powder temperature wins; otherwise an explicit zero-day
                    // air temperature retains the existing curve-at-zero-air behavior. With
                    // neither override, inherit the shot-day powder lookup temperature.
                    powder_curve_temp_c: if let Some(t) = zero_powder_temp {
                        Some(UnitConverter::temperature_to_metric(t, cli.units))
                    } else if zero_temperature.is_some() {
                        None
                    } else {
                        powder_curve_temp_c
                    },
                    // Zero with the exact BC configuration the subsequent flight uses. The
                    // resolved schedule covers manual/BC5D data and estimator-generated data;
                    // cluster correction remains a scalar-BC fallback under MBA-1175.
                    use_bc_segments: effective_use_bc_segments,
                    bc_segments_data: bc_segments_data.clone(),
                    use_cluster_bc,
                    custom_drag_table: custom_drag_table.clone(),
                    cd_scale,
                    // MBA-1359: the returned zero angle carries the vertical POI bias; the
                    // horizontal bias is re-derived for the flight inputs in run_trajectory
                    // (the solved-angle copy cannot carry an azimuth term).
                    zero_poi_vertical_m: zero_poi_vertical_metric,
                    zero_poi_horizontal_m: zero_poi_horizontal_metric,
                    // MBA-1396: physical sight geometry participates in the zero trials
                    // (initial lateral position; y-uncoupled, so the elevation search is
                    // unaffected). The windage convergence is likewise re-derived for the
                    // flight inputs in run_trajectory.
                    sight_offset_lateral_m: sight_offset_lateral_metric,
                    ..Default::default()
                };

                let zero_wind = WindConditions {
                    speed: wind_speed_metric,
                    direction: final_wind_direction.to_radians(),
                    vertical_speed: wind_vertical_metric,
                };

                // Target height is the line of sight's ground-referenced height.
                // MBA-1397: with pressure_type == Absolute (default), this is byte-identical
                // to pre-MBA-1397 behavior -- same atmosphere fields, same solver entry point.
                // With Qnh, the zero-day QNH is reduced to station pressure BEFORE the solver
                // sees it, via the presence-aware Authoritative constructor, so it is never
                // re-interpreted through the legacy default-sentinel heuristic.
                let zero_angle = match zero_pressure_type_resolved {
                    PressureReferenceMode::Absolute => {
                        let zero_atmosphere = AtmosphericConditions {
                            temperature: zero_temperature_metric,
                            pressure: zero_pressure_metric,
                            humidity: zero_humidity_value,
                            altitude: zero_altitude_metric,
                        };
                        ballistics_engine::calculate_zero_angle_with_conditions(
                            zero_inputs,
                            zero_distance_metric,
                            bore_height_metric + sight_height_metric,
                            zero_wind,
                            zero_atmosphere,
                        )?
                    }
                    PressureReferenceMode::Qnh => {
                        let (resolved_temp_c, resolved_pressure_hpa) =
                            resolve_station_conditions_with_pressure_mode(
                                zero_temperature_metric,
                                zero_pressure_metric,
                                zero_altitude_metric,
                                PressureReferenceMode::Qnh,
                            );
                        let zero_atmosphere = AtmosphericConditions {
                            temperature: resolved_temp_c,
                            pressure: resolved_pressure_hpa,
                            humidity: zero_humidity_value,
                            altitude: zero_altitude_metric,
                        };
                        ballistics_engine::calculate_zero_angle_with_resolved_conditions(
                            zero_inputs,
                            zero_distance_metric,
                            bore_height_metric + sight_height_metric,
                            zero_wind,
                            zero_atmosphere,
                        )?
                    }
                };

                // Convert to degrees for the trajectory function
                zero_angle.to_degrees()
            } else {
                angle
            };

            // Parse downrange wind segments (display units -> engine units). MBA-1368:
            // in compass mode each segment's angle is an earth-fixed bearing too,
            // re-referenced through the same shared resolver (which also rejects clock
            // forms there — shooter-relative by definition).
            let wind_segments: Vec<ballistics_engine::wind::WindSegment> = wind_segment
                .iter()
                .map(|s| {
                    let (mut segment, was_clock) =
                        ballistics_engine::wind::parse_wind_segment_str_detailed(
                            s,
                            matches!(cli.units, UnitSystem::Imperial),
                        )?;
                    segment.angle_deg = resolve_wind_reference(
                        wind_ref,
                        segment.angle_deg,
                        was_clock,
                        shot_direction,
                    )?;
                    Ok(segment)
                })
                .collect::<Result<Vec<_>, String>>()?;

            // Construct TrajectoryConfig once, used by all code paths
            let traj_config = TrajectoryConfig {
                velocity: velocity_metric,
                angle: muzzle_angle,
                bc: trued_bc,
                bc_reference_standard,
                mass: mass_metric,
                diameter: diameter_metric,
                bullet_length: bullet_length
                    .map(|l| match cli.units {
                        UnitSystem::Imperial => l * 0.0254,
                        UnitSystem::Metric => l * 0.001,
                    })
                    .unwrap_or_else(|| fallback_bullet_length_m(diameter_metric, mass_metric)),
                drag_model,
                max_range: max_range_metric,
                time_step,
                temperature: temperature_metric,
                pressure: pressure_metric,
                pressure_type: final_pressure_type,
                humidity: final_humidity,
                altitude: altitude_metric,
                density_altitude_active: final_density_altitude.is_some(),
                wind_speed: wind_speed_metric,
                wind_direction: final_wind_direction,
                wind_vertical: wind_vertical_metric,
                wind_segments,
                output,
                full,
                plot,
                units: cli.units,
                sight_height: sight_height_metric,
                bore_height: bore_height_metric,
                ignore_ground_impact,
                cant,
                zero_poi_vertical_m: zero_poi_vertical_metric,
                zero_poi_horizontal_m: zero_poi_horizontal_metric,
                sight_offset_lateral_m: sight_offset_lateral_metric,
                zero_solve_distance_m: final_auto_zero
                    .map(|zd| UnitConverter::distance_to_metric(zd, cli.units)),
                use_bc_segments: effective_use_bc_segments,
                use_cluster_bc,
                bc_segments_data: bc_segments_data.clone(),
                custom_drag_table: custom_drag_table.clone(),
                cd_scale,
                enable_magnus,
                enable_coriolis,
                enable_spin_drift,
                enable_aerodynamic_jump,
                enable_wind_shear,
                wind_shear_model,
                enable_pitch_damping,
                enable_precession,
                sample_trajectory,
                sample_interval,
                drops_reference,
                elevation_cf,
                windage_cf,
                // MBA-1360: the selected zero set's dial corrections (0.0 when no
                // --zero-set was given — exact no-op at the display boundary).
                zero_set_elevation_bias_mil: zero_selection.elevation_bias_mil,
                zero_set_windage_bias_mil: zero_selection.windage_bias_mil,
                use_rk4: !use_euler,
                use_rk45: !use_rk4_fixed,
                twist_rate,
                twist_right,
                latitude,
                shot_direction,
                shooting_angle,
                use_powder_sensitivity,
                powder_temp_sensitivity,
                powder_temp,
                powder_temp_curve: powder_temp_curve_si.clone(),
                powder_curve_temp_c,
                target_speed,
                with_drag_coefficient,
                adjustment_unit,
                elevation_click,
                windage_click,
                pdf_metadata: pdf_metadata.clone(),
                dsf_table: dsf_table.clone(),
                // MBA-1402: `muzzle_angle` above is already the solved zero angle (degrees)
                // when auto-zero ran; echo it only in that case, so a bare `--angle` run keeps
                // this `None` and every output format is unchanged. `--auto-zero` is a
                // PRE-EXISTING flag (also set implicitly from a saved profile's
                // auto_zero/zero_distance), so this IS a deliberate, user-visible output
                // change on that existing path: table/JSON/CSV/WASM `trajectory --auto-zero`
                // runs now emit a Zero Angle line/key/row and the WASM banner grows a
                // leading `D° /` term that wasn't there before (Tier 2 review I1). Anything
                // parsing `--auto-zero` output needs to account for the new field.
                solved_zero_angle_deg: final_auto_zero.map(|_| muzzle_angle),
            };

            // Online mode handling
            #[cfg(feature = "online")]
            {
                if online || compare {
                    // Check TOS acceptance before proceeding with online mode
                    match ensure_tos_accepted() {
                        Ok(true) => {
                            // TOS accepted, continue with online mode
                        }
                        Ok(false) => {
                            // TOS not accepted, exit
                            return Err(
                                "Cannot use --online without accepting Terms of Service.".into()
                            );
                        }
                        Err(e) => {
                            eprintln!("Warning: Could not verify TOS acceptance: {}", e);
                            eprintln!("Proceeding with online mode...");
                        }
                    }

                    // Build API request
                    // With no --auto-zero, use 100 in the active CLI distance units.
                    // Convert that fallback before the API request so imperial means
                    // 100 yd (91.44 m), not the previous 100 m / 109.4 yd (MBA-1158).
                    let zero_range_metric = final_auto_zero
                        .map(|d| UnitConverter::distance_to_metric(d, cli.units))
                        .unwrap_or_else(|| UnitConverter::distance_to_metric(100.0, cli.units));

                    let api_request = TrajectoryRequestBuilder::new()
                        .bc_value(trued_bc)
                        // The online Flask bridge is a separate HTTP service that only
                        // understands G1/G7; MBA-1386 widens the native/local family only,
                        // so any other model still degrades to G1 for this remote request.
                        .bc_type(warn_aux_g1_coercion("--online mode", drag_model))
                        .bullet_mass(mass_metric * 1000.0) // kg to grams
                        .muzzle_velocity(velocity_metric)
                        .target_distance(max_range_metric)
                        .zero_range(zero_range_metric)
                        .wind_speed(wind_speed_metric)
                        .wind_angle(final_wind_direction)
                        .temperature(temperature_metric)
                        .pressure(pressure_metric)
                        .humidity(final_humidity)
                        .altitude(altitude_metric)
                        .shooting_angle(shooting_angle)
                        .bullet_diameter(diameter_metric)
                        .ground_threshold(if ignore_ground_impact {
                            f64::NEG_INFINITY
                        } else {
                            0.0
                        })
                        .enable_weather_zones(enable_weather_zones)
                        .enable_3d_weather(enable_3d_weather)
                        .wind_shear_model(wind_shear_model.as_engine_str())
                        .weather_zone_interpolation(&weather_zone_interpolation)
                        .sample_interval(sample_interval)
                        .build()
                        .map_err(|e| format!("Failed to build API request: {}", e))?;

                    // Add optional parameters
                    let mut request = api_request;
                    if let Some(lat) = latitude {
                        request.latitude = Some(lat);
                    }
                    if let Some(lon) = longitude {
                        request.longitude = Some(lon);
                    }
                    if let Some(dir) = shot_direction {
                        request.shot_direction = Some(dir);
                    }
                    // `twist_rate` was already normalized to inches/turn above (metric mm
                    // converted by /25.4, MBA-970), and api_client / the local solver both
                    // consume inches/turn — so forward it verbatim. Both the local and API
                    // legs of --compare see the same converted value, so they stay in
                    // agreement.
                    if let Some(twist) = twist_rate {
                        request.twist_rate = Some(twist);
                    }

                    let api_client = ApiClient::new(&api_url, api_timeout)
                        .with_token(ballistics_engine::credentials::load_token());

                    let api_result = api_client.calculate_trajectory(&request);

                    match (&api_result, compare) {
                        (Ok(api_response), true) => {
                            // Compare mode: run local calculation first, then display side-by-side (MBA-720)
                            eprintln!("Running comparison between local and API calculations...\n");

                            // Run local trajectory to get comparison data BEFORE displaying the table
                            let local_result = {
                                let drag_model_enum = drag_model;
                                let local_wind_direction_rad = final_wind_direction.to_radians();

                                let mut local_inputs = BallisticInputs {
                                    bc_value: trued_bc,
                                    bc_type: drag_model_enum,
                                    bc_reference_standard,
                                    bullet_mass: mass_metric,
                                    muzzle_velocity: velocity_metric,
                                    bullet_diameter: diameter_metric,
                                    bullet_length: bullet_length
                                        .map(|l| match cli.units {
                                            UnitSystem::Imperial => l * 0.0254,
                                            UnitSystem::Metric => l * 0.001,
                                        })
                                        .unwrap_or_else(|| {
                                            fallback_bullet_length_m(diameter_metric, mass_metric)
                                        }),
                                    muzzle_angle: muzzle_angle.to_radians(),
                                    target_distance: max_range_metric,
                                    azimuth_angle: 0.0,
                                    shot_azimuth: shot_direction
                                        .map(|d| d.to_radians())
                                        .unwrap_or(0.0),
                                    shooting_angle: shooting_angle.to_radians(),
                                    cant_angle: cant.to_radians(),
                                    sight_height: sight_height_metric,
                                    muzzle_height: bore_height_metric,
                                    target_height: 0.0,
                                    ground_threshold: if ignore_ground_impact {
                                        f64::NEG_INFINITY
                                    } else {
                                        0.0
                                    },
                                    altitude: altitude_metric,
                                    temperature: temperature_metric,
                                    pressure: pressure_metric,
                                    humidity: final_humidity,
                                    latitude,
                                    wind_speed: wind_speed_metric,
                                    wind_angle: local_wind_direction_rad,
                                    // MBA-1135: caliber/weight-aware default twist (Miller-inverse)
                                    // instead of a fixed 1:12" when the shooter omits --twist-rate.
                                    twist_rate: twist_rate.unwrap_or_else(|| {
                                        ballistics_engine::stability::default_twist_inches(
                                            diameter_metric,
                                            mass_metric,
                                            velocity_metric,
                                        )
                                    }),
                                    is_twist_right: twist_right,
                                    caliber_inches: diameter_metric / 0.0254,
                                    weight_grains: mass_metric / GRAINS_TO_KG,
                                    manufacturer: None,
                                    bullet_model: None,
                                    bullet_id: None,
                                    bullet_cluster: None,
                                    use_rk4: !use_euler,
                                    use_adaptive_rk45: !use_rk4_fixed,
                                    enable_advanced_effects: enable_magnus || enable_coriolis,
                                    enable_magnus,
                                    enable_coriolis,
                                    use_powder_sensitivity,
                                    powder_temp_sensitivity: if use_powder_sensitivity {
                                        // Per-degree DELTA conversion, not absolute point (MBA-963).
                                        UnitConverter::velocity_to_metric(
                                            powder_temp_sensitivity,
                                            cli.units,
                                        ) / UnitConverter::temperature_delta_to_metric(
                                            1.0, cli.units,
                                        )
                                    } else {
                                        0.0
                                    },
                                    powder_temp: UnitConverter::temperature_to_metric(
                                        powder_temp,
                                        cli.units,
                                    ),
                                    powder_temp_curve: powder_temp_curve_si.clone(),
                                    powder_curve_temp_c,
                                    tipoff_yaw: 0.0,
                                    cd_delta2: 7.5,
                                    tipoff_decay_distance: 50.0,
                                    use_bc_segments: effective_use_bc_segments,
                                    bc_segments: None,
                                    bc_segments_data: bc_segments_data.clone(),
                                    use_enhanced_spin_drift: enable_spin_drift,
                                    enable_aerodynamic_jump,
                                    use_form_factor: false,
                                    enable_wind_shear,
                                    wind_shear_model: if enable_wind_shear {
                                        wind_shear_model.as_engine_str().to_string()
                                    } else {
                                        "none".to_string()
                                    },
                                    enable_trajectory_sampling: sample_trajectory,
                                    sample_interval,
                                    // MBA-1403: mirror the main solve so the local
                                    // comparison leg samples in the same drops reference.
                                    drops_reference: drops_reference.to_engine(),
                                    enable_pitch_damping,
                                    enable_precession_nutation: enable_precession,
                                    use_cluster_bc,
                                    bc_type_str: None,
                                    custom_drag_table: custom_drag_table.clone(),
                                    cd_scale,
                                    zero_poi_vertical_m: zero_poi_vertical_metric,
                                    zero_poi_horizontal_m: zero_poi_horizontal_metric,
                                    sight_offset_lateral_m: sight_offset_lateral_metric,
                                };

                                let local_wind = WindConditions {
                                    speed: wind_speed_metric,
                                    direction: local_wind_direction_rad,
                                    vertical_speed: wind_vertical_metric,
                                };
                                let local_atmo = AtmosphericConditions {
                                    temperature: temperature_metric,
                                    pressure: pressure_metric,
                                    humidity: final_humidity,
                                    altitude: altitude_metric,
                                };

                                // The API always zeroes the shot at `zero_range_metric`. If the
                                // user did not supply --auto-zero, zero the local comparison leg
                                // at that same default range instead of firing it at the raw
                                // --angle while comparing it to a zeroed API trajectory.
                                if final_auto_zero.is_none() {
                                    local_inputs.muzzle_angle =
                                        ballistics_engine::calculate_zero_angle_with_conditions(
                                            local_inputs.clone(),
                                            zero_range_metric,
                                            bore_height_metric + sight_height_metric,
                                            local_wind.clone(),
                                            local_atmo.clone(),
                                        )?;
                                }
                                // MBA-1359: both branches are zeroed at zero_range_metric
                                // (the --auto-zero branch inherits `muzzle_angle`, whose
                                // vertical POI bias the dispatch's zero solve already
                                // applied); the azimuth term must be applied to the flight
                                // inputs directly. Exact no-op when the offset is 0.0.
                                local_inputs.azimuth_angle +=
                                    local_inputs.windage_zero_bias_rad(zero_range_metric);

                                let mut local_solver =
                                    TrajectorySolver::new(local_inputs, local_wind, local_atmo);
                                local_solver.set_max_range(max_range_metric);
                                local_solver.set_time_step(time_step);
                                local_solver.solve().ok()
                            };

                            // Display API results with ML info
                            println!("╔════════════════════════════════════════╗");
                            println!("║     COMPARISON: LOCAL vs API           ║");
                            println!("╠════════════════════════════════════════╣");

                            if let Some(ref corrections) = api_response.ml_corrections_applied {
                                if !corrections.is_empty() {
                                    println!("║ ML Corrections Applied:                ║");
                                    for correction in corrections {
                                        println!("║   - {:32} ║", correction);
                                    }
                                    println!("╠════════════════════════════════════════╣");
                                }
                            }

                            if let Some(confidence) = api_response.bc_confidence {
                                println!(
                                    "║ BC Confidence:     {:>8.1}%           ║",
                                    confidence * 100.0
                                );
                                println!("╠════════════════════════════════════════╣");
                            }

                            let (dist_unit, _drop_unit, _vel_unit) = match cli.units {
                                UnitSystem::Metric => ("m", "m", "m/s"),
                                UnitSystem::Imperial => ("yd", "in", "fps"),
                            };

                            println!("║ Range {} │ API Drop │Local Drop│  Δ Drop  ║", dist_unit);
                            println!("╠══════════╪══════════╪══════════╪══════════╣");

                            for point in api_response.trajectory.iter().take(10) {
                                let range_display =
                                    UnitConverter::distance_from_metric(point.range, cli.units);
                                let api_drop_display = if cli.units == UnitSystem::Imperial {
                                    point.drop * 39.3701
                                } else {
                                    point.drop
                                };

                                if let Some(ref local_res) = local_result {
                                    if let Some(pos) = local_res.position_at_range(point.range) {
                                        // API drop is signed height relative to the horizontal
                                        // line of sight (negative below). Local `pos.y` is an
                                        // absolute height above ground, so remove both bore height
                                        // and the sight-over-bore offset before comparing.
                                        let local_drop =
                                            pos.y - (bore_height_metric + sight_height_metric);
                                        let local_drop_display =
                                            if cli.units == UnitSystem::Imperial {
                                                local_drop * 39.3701
                                            } else {
                                                local_drop
                                            };
                                        let delta = api_drop_display - local_drop_display;
                                        println!(
                                            "║ {:>8.1} │ {:>8.2} │ {:>8.2} │ {:>+8.2} ║",
                                            range_display,
                                            api_drop_display,
                                            local_drop_display,
                                            delta
                                        );
                                    } else {
                                        println!(
                                            "║ {:>8.1} │ {:>8.2} │    ---   │    ---   ║",
                                            range_display, api_drop_display
                                        );
                                    }
                                } else {
                                    println!(
                                        "║ {:>8.1} │ {:>8.2} │  error   │    ---   ║",
                                        range_display, api_drop_display
                                    );
                                }
                            }
                            println!("╚══════════╧══════════╧══════════╧══════════╝");
                            println!();
                        }
                        (Ok(api_response), false) => {
                            // Online mode only: display API results
                            display_api_trajectory_result(api_response, output, cli.units, full)?;
                        }
                        (Err(e), _) => {
                            if offline_fallback {
                                eprintln!("Warning: API request failed: {}", e);
                                eprintln!("Falling back to local calculation...\n");

                                run_trajectory(&traj_config)?;
                            } else {
                                eprintln!("Error: API request failed: {}", e);
                                eprintln!("Hint: Use --offline-fallback to use local calculation on API failure");
                                std::process::exit(1);
                            }
                        }
                    }
                } else {
                    // Local calculation (default)
                    run_trajectory(&traj_config)?;
                }
            }

            // Non-online feature: just run local calculation
            #[cfg(not(feature = "online"))]
            {
                run_trajectory(&traj_config)?;
            }
        }

        Commands::MonteCarlo {
            velocity,
            angle,
            bc,
            bc_reference,
            mass,
            diameter,
            num_sims,
            velocity_std,
            angle_std,
            bc_std,
            wind_std,
            wind_direction_std,
            wind_speed,
            wind_direction,
            wind_ref,
            shot_direction,
            wind_vertical,
            target_distance,
            target_radius,
            drag_table,
            cd_scale,
            cant,
            sight_offset,
            wez,
            target_size,
            wind_call_error,
            wez_start,
            wez_end,
            wez_step,
            adaptive,
            confidence,
            target_ci_half_width,
            min_samples,
            max_samples,
            mc_batch_size,
            seed,
            output,
        } => {
            let bullet_mass = mass;
            let bullet_diameter = diameter;
            // MBA-1396: lateral sight-mount offset (inches imperial / mm metric -> meters).
            let sight_offset_lateral_m = sight_offset
                .map(|v| sight_offset_display_to_metric(v, cli.units))
                .unwrap_or(0.0);
            // Convert inputs to metric (MBA-716)
            let velocity_metric = UnitConverter::velocity_to_metric(velocity, cli.units);
            let mass_metric = UnitConverter::mass_to_metric(bullet_mass, cli.units);
            let diameter_metric = UnitConverter::diameter_to_metric(bullet_diameter, cli.units);
            let velocity_std_metric = UnitConverter::velocity_to_metric(velocity_std, cli.units);
            let wind_std_metric = UnitConverter::wind_to_metric(wind_std, cli.units);
            let wind_speed_metric = UnitConverter::wind_to_metric(wind_speed, cli.units);
            let wind_vertical_metric = UnitConverter::wind_to_metric(wind_vertical, cli.units);
            let target_distance_metric =
                target_distance.map(|d| UnitConverter::distance_to_metric(d, cli.units));
            // Hit-zone radius in meters: default 0.3 m, or the user's --target-radius (in the
            // selected unit). MBA-971.
            let target_radius_metric = target_radius
                .map(|r| UnitConverter::distance_to_metric(r, cli.units))
                .unwrap_or(ballistics_engine::DEFAULT_HIT_RADIUS_M);
            // Resolve --drag-table; no bc-segments flag exists on this subcommand, so there is
            // nothing to conflict-warn against (mirrors the trajectory resolve at line ~3338).
            let custom_drag_table = drag_table.as_deref().map(load_drag_table_or_exit);
            // MBA-1356: --cd-scale requires --drag-table; validate before any solve. MonteCarlo
            // has no --bc-adjustment flag, so the pairing error must not suggest one (0.28.1).
            let cd_scale = resolve_cd_scale(cd_scale, custom_drag_table.is_some(), false)
                .unwrap_or_else(|e| {
                    eprintln!("error: {e}");
                    std::process::exit(1);
                });

            // MBA-1368: a compass bearing becomes shooter-relative HERE — before
            // MonteCarloParams is built and therefore before ANY dispersion sampling
            // (the direction sigma disperses around the converted base). Shooter mode
            // passes the entered degrees through untouched (bit-identical).
            let wind_direction_relative_deg = resolve_wind_reference(
                wind_ref,
                wind_direction.degrees,
                wind_direction.was_clock,
                shot_direction,
            )?;

            // MBA-1365: --bc-reference army-standard-metro has no effect once a custom
            // drag table replaces the BC-based retardation model entirely.
            if custom_drag_table.is_some()
                && matches!(bc_reference, BcReferenceStandard::ArmyStandardMetro)
            {
                eprintln!(
                    "{}",
                    ballistics_engine::cli_api::BC_REFERENCE_STANDARD_INERT_WARNING
                );
            }

            if wez {
                // MBA-1317: WEZ (Weapon Employment Zone) sweep mode.
                // MBA-1352 review I2: --confidence/--seed are genuine no-ops here (the sweep's
                // per-row p_hit carries no interval at all, and `run_monte_carlo_wez` seeds
                // itself internally) -- disclosed rather than silent, since an unseeded WEZ run
                // is itself reproducible run-to-run (compute_wez has no per-call randomness of
                // its own to seed), which would otherwise make --seed look honored when tested
                // the obvious way. Additive stderr only; the run still succeeds unchanged.
                if confidence.is_some() {
                    eprintln!(
                        "note: --confidence has no effect with --wez (the sweep reports a bare hit probability, no confidence interval)"
                    );
                }
                if seed.is_some() {
                    eprintln!(
                        "note: --seed has no effect with --wez (the sweep seeds itself internally with a fixed per-range-step seed, not --seed)"
                    );
                }
                let target_size_spec = target_size
                    .as_deref()
                    .ok_or("--target-size is required with --wez (e.g. --target-size 18x30)")?;
                let target_size_parsed = parse_target_size(target_size_spec)
                    .map_err(|e| format!("--target-size: {e}"))?;
                let target_size_metric = target_size_parsed.to_metric(cli.units);
                let wind_call_error_metric =
                    UnitConverter::wind_to_metric(wind_call_error, cli.units);
                let wez_start_metric = UnitConverter::distance_to_metric(wez_start, cli.units);
                let wez_end_metric = UnitConverter::distance_to_metric(wez_end, cli.units);
                let wez_step_metric = UnitConverter::distance_to_metric(wez_step, cli.units);

                // MBA-1365: `compute_wez` owns its own solve plumbing and has no
                // `BcReferenceStandard` field to carry the conversion through, so apply the
                // one ASM->ICAO multiply here instead — to both the mean and its std dev,
                // which is linear-equivalent to converting every sampled BC downstream
                // (k*(bc + std*z) == k*bc + (k*std)*z).
                let bc_wez = resolve_bc_for_reference_standard(bc, bc_reference);
                let bc_std_wez = resolve_bc_for_reference_standard(bc_std, bc_reference);

                run_monte_carlo_wez(
                    velocity_metric,
                    angle,
                    bc_wez,
                    mass_metric,
                    diameter_metric,
                    num_sims,
                    velocity_std_metric,
                    angle_std,
                    bc_std_wez,
                    wind_std_metric,
                    wind_direction_std,
                    wind_speed_metric,
                    wind_direction_relative_deg,
                    wind_vertical_metric,
                    wind_call_error_metric,
                    target_size_metric,
                    wez_start_metric,
                    wez_end_metric,
                    wez_step_metric,
                    custom_drag_table,
                    cd_scale,
                    cant,
                    sight_offset_lateral_m,
                    output,
                    cli.units,
                )?;
            } else if adaptive {
                // MBA-1352: confidence-controlled sampling. --wez is rejected above (clap
                // conflicts_with = "wez"), so this and the WEZ branch above are mutually
                // exclusive by construction.
                run_monte_carlo_adaptive(
                    velocity_metric,
                    angle,
                    bc,
                    bc_reference,
                    mass_metric,
                    diameter_metric,
                    velocity_std_metric,
                    angle_std,
                    bc_std,
                    wind_std_metric,
                    wind_speed_metric,
                    wind_direction_relative_deg,
                    wind_vertical_metric,
                    target_distance_metric,
                    target_radius_metric,
                    custom_drag_table,
                    cd_scale,
                    cant,
                    sight_offset_lateral_m,
                    AdaptiveMcCliControls {
                        confidence,
                        target_half_width: target_ci_half_width,
                        min_samples,
                        max_samples,
                        batch_size: mc_batch_size,
                        seed,
                    },
                    output,
                )?;
            } else {
                run_monte_carlo(
                    velocity_metric,
                    angle,
                    bc,
                    bc_reference,
                    mass_metric,
                    diameter_metric,
                    num_sims,
                    velocity_std_metric,
                    angle_std,
                    bc_std,
                    wind_std_metric,
                    wind_direction_std,
                    wind_speed_metric,
                    wind_direction_relative_deg,
                    wind_vertical_metric,
                    target_distance_metric,
                    target_radius_metric,
                    custom_drag_table,
                    cd_scale,
                    cant,
                    sight_offset_lateral_m,
                    seed,
                    confidence.unwrap_or(ConfidenceLevel::P95),
                    output,
                )?;
            }
        }

        Commands::Zero {
            velocity,
            bc,
            bc_reference,
            mass,
            diameter,
            drag_model,
            target_distance,
            from_angle,
            target_height,
            sight_height,
            temperature,
            pressure,
            pressure_type,
            humidity,
            altitude,
            density_altitude,
            drag_table,
            cd_scale,
            elevation_cf,
            output,
        } => {
            // MBA-1358: zero has no --profile, so the CF comes only from the flag.
            let elevation_cf = resolve_tracking_cf(elevation_cf, None, "--elevation-cf")?;
            let temperature = UnitConverter::resolve_temperature(temperature, cli.units)?;
            let pressure = UnitConverter::resolve_pressure(pressure, cli.units)?;
            let bullet_mass = mass;
            let bullet_diameter = diameter;
            // Convert inputs to metric
            let velocity_metric = UnitConverter::velocity_to_metric(velocity, cli.units);
            let mass_metric = UnitConverter::mass_to_metric(bullet_mass, cli.units);
            let diameter_metric = UnitConverter::diameter_to_metric(bullet_diameter, cli.units);
            let target_height_metric = UnitConverter::distance_to_metric(target_height, cli.units);
            // Default sight height: 2 inches for imperial, 50mm for metric
            let sight_height_default = match cli.units {
                UnitSystem::Imperial => 2.0,
                UnitSystem::Metric => 50.0,
            };
            let sight_height_value = sight_height.unwrap_or(sight_height_default);
            let sight_height_metric =
                UnitConverter::sight_height_to_metric(sight_height_value, cli.units);
            // Convert atmospheric conditions to metric
            let temperature_metric = UnitConverter::temperature_to_metric(temperature, cli.units);
            let pressure_metric = UnitConverter::pressure_to_metric(pressure, cli.units);
            let altitude_metric = UnitConverter::altitude_to_metric(altitude, cli.units);

            // MBA-1422: --density-altitude on `zero`, with the precedence `trajectory` has used
            // since MBA-1366. DA supersedes altitude and pressure outright, which leaves the
            // pressure MODE with no value of its own to describe — so it is forced to Absolute
            // and says so, the same rule the shot-day and zero-day paths already follow. An
            // explicit --temperature still wins, and the pressure is re-solved around it so the
            // requested density altitude is reproduced exactly.
            let (temperature_metric, pressure_metric, altitude_metric, pressure_type) =
                match density_altitude {
                    Some(da_display) => {
                        let da_m = UnitConverter::altitude_to_metric(da_display, cli.units);
                        // This command defaults --temperature rather than taking an Option, so
                        // "explicit" has to be inferred by comparing against the unit system's
                        // own standard rather than by testing for None.
                        let std_temperature_metric = UnitConverter::temperature_to_metric(
                            UnitConverter::resolve_temperature(None, cli.units)?,
                            cli.units,
                        );
                        let explicit_temp_c = (temperature_metric != std_temperature_metric)
                            .then_some(temperature_metric);
                        if pressure_type != PressureReferenceMode::Absolute {
                            eprintln!(
                                "warning: --pressure-type is ignored because --density-altitude supplies the station pressure directly"
                            );
                        }
                        let (da_altitude_m, da_temp_c, da_pressure_hpa) =
                            ballistics_engine::atmosphere::resolve_atmosphere_for_density_altitude(
                                da_m,
                                explicit_temp_c,
                            );
                        (
                            da_temp_c,
                            da_pressure_hpa,
                            da_altitude_m,
                            PressureReferenceMode::Absolute,
                        )
                    }
                    None => (
                        temperature_metric,
                        pressure_metric,
                        altitude_metric,
                        pressure_type,
                    ),
                };
            // Resolve --drag-table; no bc-segments flag exists on this subcommand, so there is
            // nothing to conflict-warn against (mirrors the trajectory resolve at line ~3338).
            let custom_drag_table = drag_table.as_deref().map(load_drag_table_or_exit);
            // MBA-1356: --cd-scale requires --drag-table; validate before any solve. Zero has
            // no --bc-adjustment flag, so the pairing error must not suggest one (0.28.1).
            let cd_scale = resolve_cd_scale(cd_scale, custom_drag_table.is_some(), false)
                .unwrap_or_else(|e| {
                    eprintln!("error: {e}");
                    std::process::exit(1);
                });

            // MBA-1365: --bc-reference army-standard-metro has no effect once a custom
            // drag table replaces the BC-based retardation model entirely.
            if custom_drag_table.is_some()
                && matches!(bc_reference, BcReferenceStandard::ArmyStandardMetro)
            {
                eprintln!(
                    "{}",
                    ballistics_engine::cli_api::BC_REFERENCE_STANDARD_INERT_WARNING
                );
            }

            match from_angle {
                // MBA-1402: inverse mode — a stored bore angle (degrees) is given instead of
                // a target distance; solve the zero RANGE it produces.
                Some(angle_deg) => {
                    run_zero_range_calculation(
                        velocity_metric,
                        bc,
                        bc_reference,
                        mass_metric,
                        diameter_metric,
                        drag_model,
                        angle_deg.to_radians(),
                        target_height_metric,
                        sight_height_metric,
                        temperature_metric,
                        pressure_metric,
                        pressure_type,
                        humidity,
                        altitude_metric,
                        custom_drag_table,
                        cd_scale,
                        elevation_cf,
                        output,
                        cli.units,
                    )?;
                }
                None => {
                    // clap enforces exactly one of --target-distance/--from-angle via
                    // required_unless_present + conflicts_with on both fields.
                    let target_distance = target_distance
                        .expect("clap requires --target-distance when --from-angle is absent");
                    let target_distance_metric =
                        UnitConverter::distance_to_metric(target_distance, cli.units);
                    run_zero_calculation(
                        velocity_metric,
                        bc,
                        bc_reference,
                        mass_metric,
                        diameter_metric,
                        drag_model,
                        target_distance_metric,
                        target_height_metric,
                        sight_height_metric,
                        temperature_metric,
                        pressure_metric,
                        pressure_type,
                        humidity,
                        altitude_metric,
                        custom_drag_table,
                        cd_scale,
                        elevation_cf,
                        output,
                        cli.units,
                    )?;
                }
            }
        }

        Commands::EstimateBC {
            velocity,
            mass,
            diameter,
            data,
            velocity_data,
            drag_model,
            zero_range,
            sight_height,
            temperature,
            pressure,
            pressure_type,
            humidity,
            altitude,
            distance1,
            drop1,
            distance2,
            drop2,
            output,
        } => {
            // Convert scalar inputs to metric (MBA-716).
            let velocity_metric = UnitConverter::velocity_to_metric(velocity, cli.units);
            let mass_metric = UnitConverter::mass_to_metric(mass, cli.units);
            let diameter_metric = UnitConverter::diameter_to_metric(diameter, cli.units);

            // Atmosphere the data was measured at — BC is only meaningful relative to air
            // density, so this must match the dope card's conditions (defaults = ICAO std).
            let atmosphere = AtmosphericConditions {
                temperature: temperature
                    .map(|t| UnitConverter::temperature_to_metric(t, cli.units))
                    .unwrap_or(15.0),
                // MBA-1416: honor --pressure-type here too. Applied only when a pressure was
                // actually supplied — the 1013.25 default is sea-level standard by definition,
                // so reducing it against altitude would corrupt the documented default.
                pressure: pressure
                    .map(|p| {
                        apply_pressure_mode(
                            UnitConverter::pressure_to_metric(p, cli.units),
                            altitude,
                            pressure_type,
                            cli.units,
                        )
                    })
                    .unwrap_or(1013.25),
                humidity,
                altitude: match cli.units {
                    UnitSystem::Imperial => altitude * 0.3048,
                    UnitSystem::Metric => altitude,
                },
            };
            // Zero range (dope-card frame) and sight height, in meters.
            let zero_range_m = zero_range.map(|z| UnitConverter::distance_to_metric(z, cli.units));
            let sight_height_m = sight_height
                .map(|s| match cli.units {
                    UnitSystem::Imperial => s * 0.0254,
                    UnitSystem::Metric => s / 1000.0,
                })
                .unwrap_or(0.05);

            // Drop series: from --data (n-point) or the legacy --distance1/--drop1/... pair.
            let drop_raw: Vec<(f64, f64)> = if let Some(s) = &data {
                parse_data_pairs(s)?
            } else if let (Some(d1), Some(dr1), Some(d2), Some(dr2)) =
                (distance1, drop1, distance2, drop2)
            {
                vec![(d1, dr1), (d2, dr2)]
            } else {
                Vec::new()
            };
            // Velocity series: from --velocity-data (n-point).
            let vel_raw: Vec<(f64, f64)> = match &velocity_data {
                Some(s) => parse_data_pairs(s)?,
                None => Vec::new(),
            };

            if drop_raw.is_empty() && vel_raw.is_empty() {
                return Err(
                    "No data provided. Supply drop data (--data \"d,drop;...\" or \
                     --distance1/--drop1/--distance2/--drop2) and/or velocity data \
                     (--velocity-data \"d,vel;...\")."
                        .into(),
                );
            }

            // Convert both series to metric (distance -> m, drop in -> m, velocity fps -> m/s).
            let drop_metric: Vec<(f64, f64)> = drop_raw
                .iter()
                .map(|(d, drop)| {
                    (
                        UnitConverter::distance_to_metric(*d, cli.units),
                        match cli.units {
                            UnitSystem::Imperial => *drop * 0.0254,
                            UnitSystem::Metric => *drop,
                        },
                    )
                })
                .collect();
            let vel_metric: Vec<(f64, f64)> = vel_raw
                .iter()
                .map(|(d, v)| {
                    (
                        UnitConverter::distance_to_metric(*d, cli.units),
                        UnitConverter::velocity_to_metric(*v, cli.units),
                    )
                })
                .collect();

            let models = parse_drag_models(&drag_model)?;

            // Guard the most common mistake: feeding a zeroed dope card (a point with ~0
            // drop) without --zero-range, which makes the fit treat it as bore-referenced
            // and returns a wrong (often maxed-out) BC.
            if zero_range_m.is_none()
                && drop_metric.iter().any(|(_, dr)| dr.abs() < 0.05)
                && drop_metric.iter().any(|(_, dr)| dr.abs() > 0.25)
            {
                let zd = drop_metric
                    .iter()
                    .min_by(|a, b| a.1.abs().partial_cmp(&b.1.abs()).unwrap())
                    .map(|(d, _)| match cli.units {
                        UnitSystem::Imperial => *d / 0.9144,
                        UnitSystem::Metric => *d,
                    })
                    .unwrap_or(0.0);
                let unit = if cli.units == UnitSystem::Imperial {
                    "yd"
                } else {
                    "m"
                };
                eprintln!(
                    "Warning: your drop data looks zeroed near {zd:.0} {unit} (a point has ~0 drop), \
                     but --zero-range was not given."
                );
                eprintln!(
                    "         Dope-card drops are below line of sight; pass --zero-range {zd:.0} \
                     for an accurate BC. Without it, drop is treated as bore-referenced (flat fire)."
                );
            }

            run_bc_estimation_multi(
                velocity_metric,
                mass_metric,
                diameter_metric,
                &drop_metric,
                &vel_metric,
                &models,
                atmosphere,
                zero_range_m,
                sight_height_m,
                cli.units,
                output,
            )?;
        }

        Commands::BcConvert {
            source_model,
            target_model,
            bc,
            mach,
            velocity,
            bc_segment,
            speed_of_sound,
            output,
        } => {
            run_bc_convert(
                source_model,
                target_model,
                bc,
                mach,
                velocity,
                &bc_segment,
                speed_of_sound,
                output,
                cli.units,
            )?;
        }

        Commands::GenerateBCSegments {
            bc,
            mass,
            diameter,
            model,
            drag_model,
            output,
        } => {
            let bullet_mass = mass;
            let bullet_diameter = diameter;
            // Convert to metric if needed
            let mass_metric = UnitConverter::mass_to_metric(bullet_mass, cli.units);
            let diameter_metric = UnitConverter::diameter_to_metric(bullet_diameter, cli.units);

            run_bc_segment_generation(
                bc,
                mass_metric,
                diameter_metric,
                &model,
                &drag_model,
                output,
                cli.units,
            )?;
        }

        // MBA-1358: tall-target helper — CF = actual measured travel / dialed travel.
        // Pure arithmetic over the same locked angular factors every dial column uses
        // (ballistics_engine::adjustment via drop_to_adjustment); no trajectory solve.
        Commands::TallTarget {
            dialed,
            measured,
            range,
            unit,
        } => {
            // drop_to_adjustment only needs a consistent drop/range length ratio:
            // imperial measures inches at yards (36 in/yd), metric cm at meters.
            let (measured_label, range_label) = match cli.units {
                UnitSystem::Imperial => ("in", "yd"),
                UnitSystem::Metric => ("cm", "m"),
            };
            let metric = matches!(cli.units, UnitSystem::Metric);
            let result = tall_target_v1(&TallTargetRequestV1 {
                dialed,
                measured,
                range,
                unit,
                metric,
            })
            .map_err(|e| {
                // Exhaustive match (no catch-all): a fifth guard added to the service without
                // a corresponding arm here fails to compile, instead of silently emitting a
                // wrong or malformed `--flag` prefix. Strings are the CLI's historical
                // `--flag`-prefixed wording, unchanged from before the extraction.
                match e {
                    TallTargetErrorV1::ClicksNotAngular => {
                        "--unit clicks is not an angular unit; enter the dialed travel in mil, moa, smoa, or iphy".to_string()
                    }
                    TallTargetErrorV1::InvalidDialed => {
                        "--dialed must be a positive angular travel".to_string()
                    }
                    TallTargetErrorV1::InvalidMeasured => {
                        "--measured must be a positive measured travel".to_string()
                    }
                    TallTargetErrorV1::InvalidRange => {
                        "--range must be at least 1 yard/meter".to_string()
                    }
                }
            })?;
            let unit_label = adjustment_unit_label(unit);
            println!();
            println!("Tall-Target Test Result");
            println!("  Dialed travel:   {:.2} {}", dialed, unit_label);
            println!(
                "  Actual travel:   {:.2} {} ({:.2} {} at {:.0} {})",
                result.actual, unit_label, measured, measured_label, range, range_label
            );
            println!(
                "  Correction factor (actual / dialed): {:.4}",
                result.correction_factor
            );
            if !result.within_accepted_band {
                println!(
                    "  warning: {:.4} is outside the accepted (0.5, 1.5) band — the engine \
                     will reject it as a CF; re-check the tall-target measurement",
                    result.correction_factor
                );
            } else {
                println!(
                    "  Enter this as --elevation-cf / profile elevation_cf (or the windage \
                     equivalents); dial solutions are divided by it."
                );
            }
            println!();
        }

        Commands::TrueVelocity {
            measured_drop,
            range,
            observed,
            observation_sigma,
            mv_prior,
            bc_prior,
            predict_range,
            prediction_sigma,
            drop_unit,
            elevation_cf,
            bc,
            drag_model,
            mass,
            diameter,
            chrono_velocity,
            chrono_distance,
            zero_distance,
            sight_height,
            temperature,
            pressure,
            pressure_type,
            humidity,
            altitude,
            units,
            bc_table_dir,
            #[cfg(feature = "online")]
            bc_table_auto,
            #[cfg(feature = "online")]
            bc_table_url,
            offline,
            #[cfg(feature = "online")]
            offline_fallback,
            #[cfg(feature = "online")]
            api_url,
            #[cfg(feature = "online")]
            api_timeout,
            bullet_length,
            output,
        } => {
            // MBA-1358: dialed observations are MULTIPLIED by the elevation tracking
            // CF (scope-dial units -> true angular: a dialed reading of D scope units
            // delivers D * CF true units) before any fit consumes them, so scope
            // tracking error is not baked into the trued MV/BC. Dialed = angular drops:
            // single-observation mode is always MIL, and multi/uncertainty modes are
            // dialed unless --drop-unit in (a tape measurement, never scaled).
            // Dial-unit report values are converted back to scope units (÷CF) at
            // display time, so tables echo what the shooter actually dialed.
            let elevation_cf = resolve_tracking_cf(elevation_cf, None, "--elevation-cf")?;
            let observation_cf = if observed.is_empty() || drop_unit != DropUnit::In {
                elevation_cf
            } else {
                1.0
            };
            let measured_drop = measured_drop * observation_cf;

            let temperature = UnitConverter::resolve_temperature(temperature, units)?;
            // MBA-1416: honor --pressure-type here too, so a QNH altimeter setting means
            // the same thing on this command as it does on `trajectory`.
            let pressure = apply_pressure_mode(
                UnitConverter::resolve_pressure(pressure, units)?,
                altitude,
                pressure_type,
                units,
            );
            // Convert to imperial for calculations (internal calculations use imperial)
            let range_yd = match units {
                UnitSystem::Imperial => range,
                UnitSystem::Metric => range / 0.9144, // meters to yards
            };
            let weight_gr = match units {
                UnitSystem::Imperial => mass,
                UnitSystem::Metric => mass / GRAMS_PER_GRAIN, // grams to grains
            };
            let caliber_in = match units {
                UnitSystem::Imperial => diameter,
                UnitSystem::Metric => diameter / 25.4, // mm to inches
            };
            let chrono_fps = chrono_velocity.map(|v| match units {
                UnitSystem::Imperial => v,
                UnitSystem::Metric => v / 0.3048, // m/s to fps
            });
            let zero_yd = match units {
                UnitSystem::Imperial => zero_distance,
                UnitSystem::Metric => zero_distance / 0.9144,
            };
            let sight_height_default = match units {
                UnitSystem::Imperial => 2.0,
                UnitSystem::Metric => 50.0,
            };
            let sight_height = sight_height.unwrap_or(sight_height_default);
            let sight_in = match units {
                UnitSystem::Imperial => sight_height,
                UnitSystem::Metric => sight_height / 25.4, // mm to inches
            };
            let temp_f = match units {
                UnitSystem::Imperial => temperature,
                UnitSystem::Metric => temperature * 9.0 / 5.0 + 32.0, // C to F
            };
            let press_inhg = match units {
                UnitSystem::Imperial => pressure,
                UnitSystem::Metric => pressure / 33.8639, // hPa to inHg
            };
            let alt_ft = match units {
                UnitSystem::Imperial => altitude,
                UnitSystem::Metric => altitude / 0.3048, // meters to feet
            };

            let drag_str = match drag_model {
                DragModelArg::G1 => "G1",
                DragModelArg::G7 => "G7",
            };

            // Load BC5D tables if available
            // Determine effective table directory: explicit --bc-table-dir, or auto-download cache
            #[cfg(feature = "online")]
            let effective_bc_table_dir: Option<PathBuf> = if bc_table_dir.is_some() {
                bc_table_dir.clone()
            } else if bc_table_auto {
                // Auto-download mode: ensure table is available, use cache directory
                match Bc5dDownloader::new(&bc_table_url, false) {
                    Ok(mut downloader) => {
                        match downloader.ensure_table(caliber_in) {
                            Ok(table_path) => {
                                // Return the parent directory (cache dir) as table directory
                                table_path.parent().map(|p| p.to_path_buf())
                            }
                            Err(e) => {
                                eprintln!("Warning: {}", e);
                                eprintln!("         Continuing without BC5D correction table.");
                                None
                            }
                        }
                    }
                    Err(e) => {
                        eprintln!("Warning: BC5D table download failed: {}", e);
                        eprintln!("         Continuing without BC5D correction table.");
                        None
                    }
                }
            } else {
                None
            };

            #[cfg(not(feature = "online"))]
            let effective_bc_table_dir: Option<PathBuf> = bc_table_dir.clone();

            // Load BC segments from BC5D table if available (MBA-744: uses shared helper)
            let bc_segments: Option<Vec<BCSegmentData>> =
                if let Some(table_dir) = &effective_bc_table_dir {
                    let mut manager = Bc5dTableManager::new(table_dir);
                    // Identity guard before any lookup: refuse a table whose header
                    // caliber is not this shot's caliber (see the helper's docs).
                    reject_bc5d_caliber_mismatch(&mut manager, caliber_in)?;
                    generate_bc5d_segments(
                        &mut manager,
                        caliber_in,
                        bc,
                        drag_str,
                        weight_gr,
                        None,
                        bullet_length,
                        bullet_length.is_some(),
                        None,
                    )
                } else {
                    None
                };

            // MBA-1377: correct a downrange chronograph reading back to muzzle velocity.
            // Pure input-side transform -- runs once here, before `chrono_fps` reaches any
            // display/comparison path below. `truing.rs`'s drop-based solves never see
            // --chrono-distance; it only ever adjusts the value being compared against them.
            if chrono_distance.is_some_and(|d| d != 0.0) && chrono_fps.is_none() {
                return Err("--chrono-distance requires --chrono-velocity".into());
            }
            let chrono_fps = match (chrono_fps, chrono_distance) {
                (Some(measured), Some(d)) if d != 0.0 => {
                    let screen_distance_m = match units {
                        UnitSystem::Imperial => d * 0.3048, // feet to meters
                        UnitSystem::Metric => d,
                    };
                    let correction = correct_chrono_velocity_fps(
                        measured,
                        screen_distance_m,
                        bc,
                        drag_model,
                        weight_gr,
                        caliber_in,
                        temp_f,
                        press_inhg,
                        humidity,
                        alt_ft,
                        &bc_segments,
                    )?;
                    Some(correction.muzzle_velocity_fps)
                }
                _ => chrono_fps,
            };

            // Determine if we should use local calculation
            // Use local if: --offline flag, OR no online feature, OR (no online flag and has bc_table_dir)
            #[cfg(feature = "online")]
            let use_local = offline;
            #[cfg(not(feature = "online"))]
            let use_local = true; // Always use local when online feature not available

            let uncertainty_requested = observation_sigma.is_some()
                || mv_prior.is_some()
                || bc_prior.is_some()
                || !predict_range.is_empty()
                || prediction_sigma.is_some()
                || observed.iter().any(|token| token.matches(':').count() == 2);

            if uncertainty_requested {
                let default_sigma = observation_sigma.ok_or(
                    "--observation-sigma is required for uncertainty-aware truing (it supplies the primary observation's known 1-sigma error)",
                )?;
                if !default_sigma.is_finite() || default_sigma <= 0.0 {
                    return Err("--observation-sigma must be positive and finite".into());
                }
                if observed.is_empty() {
                    return Err(
                        "uncertainty-aware joint MV+BC truing requires at least one --observed RANGE:DROP[:SIGMA] in addition to the primary observation"
                            .into(),
                    );
                }
                if bc_segments
                    .as_ref()
                    .is_some_and(|segments| !segments.is_empty())
                {
                    return Err(
                        "uncertainty-aware scalar-BC truing does not support velocity-banded BC tables; omit --bc-table-dir/--bc-table-auto or fit an explicit table scale model"
                            .into(),
                    );
                }

                // MBA-1358: dialed drops AND their dialed sigmas multiply by the CF
                // once, uniformly, here (measured_drop was already converted above;
                // sigmas are converted after parsing so a token-supplied sigma and the
                // default get exactly one conversion each). *1.0 is exact when no CF
                // is active.
                let mut weighted_observations = Vec::with_capacity(observed.len() + 1);
                weighted_observations.push(WeightedTruingObservationV1 {
                    range_yd,
                    drop: measured_drop,
                    sigma: default_sigma * observation_cf,
                });
                for token in &observed {
                    let (observation, sigma) =
                        parse_uncertain_truing_observation(token, units, default_sigma)?;
                    weighted_observations.push(WeightedTruingObservationV1 {
                        range_yd: observation.range_yd,
                        drop: observation.drop * observation_cf,
                        sigma: sigma * observation_cf,
                    });
                }

                let mv_prior = mv_prior
                    .as_deref()
                    .map(|token| {
                        let (mean, sigma) = parse_normal_prior(token, "--mv-prior")?;
                        let to_fps = match units {
                            UnitSystem::Imperial => 1.0,
                            UnitSystem::Metric => 1.0 / 0.3048,
                        };
                        Ok::<NormalPriorV1, String>(NormalPriorV1 {
                            mean: mean * to_fps,
                            sigma: sigma * to_fps,
                        })
                    })
                    .transpose()?;
                let bc_prior = bc_prior
                    .as_deref()
                    .map(|token| {
                        let (mean, sigma) = parse_normal_prior(token, "--bc-prior")?;
                        Ok::<NormalPriorV1, String>(NormalPriorV1 { mean, sigma })
                    })
                    .transpose()?;
                if prediction_sigma.is_some_and(|sigma| !sigma.is_finite() || sigma <= 0.0) {
                    return Err("--prediction-sigma must be positive and finite".into());
                }
                if prediction_sigma.is_some() && predict_range.is_empty() {
                    return Err("--prediction-sigma requires at least one --predict-range".into());
                }
                let predictions = predict_range
                    .iter()
                    .map(|range| TruingPredictionRequestV1 {
                        range_yd: match units {
                            UnitSystem::Imperial => *range,
                            UnitSystem::Metric => *range / 0.9144,
                        },
                        future_observation_sigma: prediction_sigma,
                    })
                    .collect();
                let initial_mv_fps = mv_prior.map_or(3000.0, |prior| prior.mean);
                let model = TruingModelInputsV1 {
                    muzzle_velocity_fps: initial_mv_fps,
                    ballistic_coefficient: bc,
                    drag_model,
                    mass_gr: weight_gr,
                    diameter_in: caliber_in,
                    zero_distance_yd: zero_yd,
                    sight_height_in: sight_in,
                    temperature_f: temp_f,
                    pressure_inhg: press_inhg,
                    humidity_pct: humidity,
                    altitude_ft: alt_ft,
                };
                model
                    .validate()
                    .map_err(|error| format!("invalid uncertainty-truing model: {error}"))?;
                let request = UncertaintyTruingRequestV1 {
                    model,
                    drop_unit,
                    observations: weighted_observations,
                    priors: TruingPriorsV1 {
                        muzzle_velocity_fps: mv_prior,
                        ballistic_coefficient: bc_prior,
                    },
                    predictions,
                };
                eprintln!(
                    "Fitting {} weighted observations (uncertainty-aware joint MV+BC MAP)...",
                    request.observations.len()
                );
                // MBA-1358: unlike the table-oriented single/multi displays, the
                // uncertainty report is a versioned schema document
                // (truing-uncertainty-v1) consumed for further analysis — its values
                // stay in TRUE (scope-corrected) angular units rather than being scaled
                // back to scope units. Say so when a CF actually changed the inputs.
                if observation_cf != 1.0 {
                    eprintln!(
                        "note: --elevation-cf {observation_cf} converted the dialed observations \
                         to true angular units (dialed × CF); uncertainty-report values are in \
                         true (scope-corrected) angular units"
                    );
                }
                let report = run_uncertainty_truing_v1(&request)?;
                display_uncertainty_truing_result(&report, units, chrono_fps, output)?;
            } else if !observed.is_empty() {
                // MBA-1316: one or more --observed impacts -> joint MV+BC
                // calibration via the real forward model (always computed
                // locally; the online API only supports single-observation
                // velocity truing).
                run_multi_observation_truing(
                    measured_drop,
                    range_yd,
                    &observed,
                    drop_unit,
                    observation_cf,
                    bc,
                    drag_model,
                    weight_gr,
                    caliber_in,
                    zero_yd,
                    sight_in,
                    temp_f,
                    press_inhg,
                    humidity,
                    alt_ft,
                    &bc_segments,
                    chrono_fps,
                    units,
                    output,
                )?;
            } else if use_local {
                // Run local calculation
                eprintln!("Calculating effective velocity locally...");

                match calculate_true_velocity_local(
                    measured_drop,
                    range_yd,
                    bc,
                    drag_model,
                    weight_gr,
                    caliber_in,
                    zero_yd,
                    sight_in,
                    temp_f,
                    press_inhg,
                    humidity,
                    alt_ft,
                    &bc_segments,
                ) {
                    Ok(result) => {
                        // Calculate velocity adjustment if chrono provided
                        let velocity_adjustment =
                            chrono_fps.map(|c| result.effective_velocity_fps - c);
                        let adjustment_percent =
                            chrono_fps.map(|c| (result.effective_velocity_fps - c) / c * 100.0);

                        // Convert output velocity back to user's units if needed
                        let effective_vel = match units {
                            UnitSystem::Imperial => result.effective_velocity_fps,
                            UnitSystem::Metric => result.effective_velocity_fps * 0.3048,
                        };
                        let vel_unit = match units {
                            UnitSystem::Imperial => "fps",
                            UnitSystem::Metric => "m/s",
                        };

                        display_true_velocity_result(
                            effective_vel,
                            vel_unit,
                            velocity_adjustment,
                            adjustment_percent,
                            &result.confidence,
                            result.iterations,
                            // MBA-1358: dial-unit outputs render in scope units (÷CF;
                            // the fit consumed the ×CF true values). /1.0 is exact.
                            result.final_error_mil / observation_cf,
                            result.calculated_drop_mil / observation_cf,
                            measured_drop / observation_cf,
                            units,
                            output,
                            bc_segments.is_some(),
                        )?;
                    }
                    Err(e) => {
                        eprintln!("Error: Local calculation failed: {}", e);
                        std::process::exit(1);
                    }
                }
            } else {
                // Online mode
                #[cfg(feature = "online")]
                {
                    // Check TOS acceptance first
                    if !check_tos_accepted() && !prompt_tos_acceptance()? {
                        eprintln!("Cannot use online features without accepting Terms of Service.");
                        std::process::exit(1);
                    }

                    let request = TrueVelocityRequest {
                        measured_drop_mil: measured_drop,
                        range_yd,
                        bc,
                        drag_model: drag_str.to_string(),
                        weight_gr,
                        caliber: caliber_in,
                        zero_range_yd: Some(zero_yd),
                        chrono_velocity_fps: chrono_fps,
                        altitude_ft: Some(alt_ft),
                        temperature_f: Some(temp_f),
                        pressure_inhg: Some(press_inhg),
                        humidity: Some(humidity),
                        sight_height_in: Some(sight_in),
                        use_bc_enhancement: Some(true),
                    };

                    let api_client = ApiClient::new(&api_url, api_timeout)
                        .with_token(ballistics_engine::credentials::load_token());

                    eprintln!("Calculating effective velocity via API...");

                    match api_client.true_velocity(&request) {
                        Ok(response) => {
                            // Convert output velocity back to user's units if needed
                            let effective_vel = match units {
                                UnitSystem::Imperial => response.effective_velocity_fps,
                                UnitSystem::Metric => response.effective_velocity_fps * 0.3048,
                            };
                            let vel_unit = match units {
                                UnitSystem::Imperial => "fps",
                                UnitSystem::Metric => "m/s",
                            };

                            display_true_velocity_result(
                                effective_vel,
                                vel_unit,
                                response.velocity_adjustment_fps,
                                response.adjustment_percent,
                                &response.confidence,
                                response.iterations,
                                // MBA-1358: same scope-unit rendering as the local path.
                                response.final_error_mil / observation_cf,
                                response.calculated_drop_mil / observation_cf,
                                measured_drop / observation_cf,
                                units,
                                output,
                                false,
                            )?;
                        }
                        Err(e) => {
                            if offline_fallback {
                                eprintln!("Warning: API request failed: {}", e);
                                eprintln!("Falling back to local calculation...\n");

                                match calculate_true_velocity_local(
                                    measured_drop,
                                    range_yd,
                                    bc,
                                    drag_model,
                                    weight_gr,
                                    caliber_in,
                                    zero_yd,
                                    sight_in,
                                    temp_f,
                                    press_inhg,
                                    humidity,
                                    alt_ft,
                                    &bc_segments,
                                ) {
                                    Ok(result) => {
                                        let velocity_adjustment =
                                            chrono_fps.map(|c| result.effective_velocity_fps - c);
                                        let adjustment_percent = chrono_fps.map(|c| {
                                            (result.effective_velocity_fps - c) / c * 100.0
                                        });

                                        let effective_vel = match units {
                                            UnitSystem::Imperial => result.effective_velocity_fps,
                                            UnitSystem::Metric => {
                                                result.effective_velocity_fps * 0.3048
                                            }
                                        };
                                        let vel_unit = match units {
                                            UnitSystem::Imperial => "fps",
                                            UnitSystem::Metric => "m/s",
                                        };

                                        display_true_velocity_result(
                                            effective_vel,
                                            vel_unit,
                                            velocity_adjustment,
                                            adjustment_percent,
                                            &result.confidence,
                                            result.iterations,
                                            // MBA-1358: scope-unit rendering (÷CF).
                                            result.final_error_mil / observation_cf,
                                            result.calculated_drop_mil / observation_cf,
                                            measured_drop / observation_cf,
                                            units,
                                            output,
                                            bc_segments.is_some(),
                                        )?;
                                    }
                                    Err(fallback_err) => {
                                        eprintln!(
                                            "Error: Fallback calculation also failed: {}",
                                            fallback_err
                                        );
                                        std::process::exit(1);
                                    }
                                }
                            } else {
                                eprintln!("API Error: {}", e);
                                // This endpoint is moving behind auth, and "go
                                // offline" was the only advice here — which reads
                                // as an outage when the real cause is a missing or
                                // expired token, and talks the user out of the
                                // online path permanently over a fixable problem.
                                //
                                // Printed unconditionally rather than through
                                // `ApiError::cli_hint()`, which would be the
                                // obvious way to show it only on a 401/402: that
                                // matches on `ServerError`, and nothing builds one
                                // here. ureq 3.x's `http_status_as_error` defaults
                                // on, so an HTTP 401 comes back from `send` as
                                // `Error::StatusCode` and `map_ureq_error` files it
                                // under `NetworkError("http status: 401")` — the
                                // one case this hint exists for is exactly the case
                                // a conditional hint would stay silent on.
                                eprintln!("Hint: If the service rejected your credentials, run `ballistics login` (create a token at https://ballisticsinsight.com/account)");
                                eprintln!("Hint: Use --offline for local calculation or --offline-fallback for automatic fallback");
                                std::process::exit(1);
                            }
                        }
                    }
                }

                #[cfg(not(feature = "online"))]
                {
                    // This branch should never be reached since use_local is always true
                    // when online feature is not available, but add for completeness
                    eprintln!("Error: Online mode not available (compile with --features online)");
                    std::process::exit(1);
                }
            }
        }

        // MBA-1392: wind-call truing. Fully local by construction — there is no API for
        // it and no flag that could reach one.
        Commands::TrueWind {
            miss,
            velocity,
            bc,
            drag_model,
            mass,
            diameter,
            twist_rate,
            twist_right,
            latitude,
            shot_direction,
            called_wind,
            zero_distance,
            sight_height,
            temperature,
            pressure,
            pressure_type,
            humidity,
            altitude,
            units,
            output,
        } => {
            let temperature = UnitConverter::resolve_temperature(temperature, units)?;
            // MBA-1416: a declared QNH reduces against this command's own --altitude,
            // exactly as it does on `trajectory` and `true-velocity`.
            let pressure = apply_pressure_mode(
                UnitConverter::resolve_pressure(pressure, units)?,
                altitude,
                pressure_type,
                units,
            );

            // Convert to the truing core's internal imperial units — factor-for-factor
            // the `Commands::TrueVelocity` dispatch above.
            let velocity_fps = match units {
                UnitSystem::Imperial => velocity,
                UnitSystem::Metric => velocity / 0.3048,
            };
            let weight_gr = match units {
                UnitSystem::Imperial => mass,
                UnitSystem::Metric => mass / GRAMS_PER_GRAIN,
            };
            let caliber_in = match units {
                UnitSystem::Imperial => diameter,
                UnitSystem::Metric => diameter / 25.4,
            };
            let zero_yd = match units {
                UnitSystem::Imperial => zero_distance,
                UnitSystem::Metric => zero_distance / 0.9144,
            };
            let sight_height_default = match units {
                UnitSystem::Imperial => 2.0,
                UnitSystem::Metric => 50.0,
            };
            let sight_height = sight_height.unwrap_or(sight_height_default);
            let sight_in = match units {
                UnitSystem::Imperial => sight_height,
                UnitSystem::Metric => sight_height / 25.4,
            };
            let temp_f = match units {
                UnitSystem::Imperial => temperature,
                UnitSystem::Metric => temperature * 9.0 / 5.0 + 32.0,
            };
            let press_inhg = match units {
                UnitSystem::Imperial => pressure,
                UnitSystem::Metric => pressure / 33.8639,
            };
            let alt_ft = match units {
                UnitSystem::Imperial => altitude,
                UnitSystem::Metric => altitude / 0.3048,
            };
            // --twist-rate is mm/turn in metric and inches/turn in imperial (MBA-970);
            // the engine treats twist as inches/turn everywhere.
            let twist_in = match units {
                UnitSystem::Imperial => twist_rate,
                UnitSystem::Metric => twist_rate / 25.4,
            };
            // --called-wind follows --wind-speed's units: mph imperial, m/s metric.
            let called_mph = called_wind.map(|v| match units {
                UnitSystem::Imperial => v,
                UnitSystem::Metric => v / MPH_TO_MPS,
            });

            // Coriolis needs BOTH halves; one without the other is a mistake, not a
            // partially-usable input (MBA-1425: no silent fallback).
            let earth =
                match (latitude, shot_direction) {
                    (Some(latitude_deg), Some(shot_azimuth_deg)) => Some(TruingEarthFrame {
                        latitude_deg,
                        shot_azimuth_deg,
                    }),
                    (None, None) => None,
                    (Some(_), None) => {
                        return Err(
                            "--latitude also needs --shot-direction before Coriolis can be \
                         modelled (Earth rotation depends on which way downrange points)"
                                .into(),
                        )
                    }
                    (None, Some(_)) => return Err(
                        "--shot-direction also needs --latitude before Coriolis can be modelled"
                            .into(),
                    ),
                };

            let observations = miss
                .iter()
                .map(|token| parse_wind_observation(token, units))
                .collect::<Result<Vec<_>, _>>()?;

            let request = WindTruingRequest {
                observations,
                muzzle_velocity_fps: velocity_fps,
                bc,
                drag_model,
                mass_gr: weight_gr,
                diameter_in: caliber_in,
                zero_distance_yd: zero_yd,
                sight_height_in: sight_in,
                temperature_f: temp_f,
                pressure_inhg: press_inhg,
                humidity_pct: humidity,
                altitude_ft: alt_ft,
                twist: TruingTwist {
                    rate_in: twist_in,
                    right_hand: twist_right,
                },
                earth,
                called_crosswind_mph: called_mph,
            };
            request.validate()?;

            let wind_output = match output {
                OutputFormat::Json => WindTruingOutput::Json,
                OutputFormat::Csv => WindTruingOutput::Csv,
                OutputFormat::Table => WindTruingOutput::Table,
                OutputFormat::Pdf => {
                    eprintln!("Error: PDF output is not supported for wind truing results.");
                    eprintln!("Hint: Use --output json, --output csv, or --output table instead.");
                    std::process::exit(1);
                }
            };

            eprintln!(
                "Back-solving effective wind from {} observed miss{}...",
                request.observations.len(),
                if request.observations.len() == 1 {
                    ""
                } else {
                    "es"
                }
            );
            let report = solve_wind_truing(&request)?;
            // Shared formatter: the WASM terminal renders the same bytes from the same
            // function, so the two surfaces cannot drift.
            print!("{}", format_wind_truing_report(&report, units, wind_output));
        }

        Commands::PlanTruing {
            profile,
            velocity,
            bc,
            drag_model,
            mass,
            diameter,
            candidate_ranges,
            range_grid,
            observation_count,
            minimum_separation,
            measurement_resolution,
            drop_unit,
            zero_distance,
            zero_set,
            sight_height,
            temperature,
            pressure,
            pressure_type,
            humidity,
            altitude,
            output,
        } => {
            let profile_data = profile
                .as_deref()
                .map(|name| load_profile_for_units(name, cli.units))
                .transpose()?;
            if let Some(profile) = &profile_data {
                let has_segments = profile
                    .bc_segments
                    .as_ref()
                    .is_some_and(|segments| !segments.is_empty())
                    || profile.use_bc_segments.unwrap_or(false);
                let has_custom_drag = profile
                    .drag_curve
                    .as_ref()
                    .is_some_and(|curve| !curve.is_empty())
                    || profile.drag_model.eq_ignore_ascii_case("custom");
                if has_segments || has_custom_drag {
                    return Err(format!(
                        "profile '{}' uses {} and cannot be reduced to the scalar G1/G7 BC parameter designed by plan-truing; use a scalar-BC profile or define a separate drag-deck scale model",
                        profile.name,
                        if has_custom_drag {
                            "a custom drag curve"
                        } else {
                            "velocity-banded BC values"
                        }
                    )
                    .into());
                }
            }

            let velocity = velocity
                .or_else(|| profile_data.as_ref().map(|profile| profile.velocity))
                .ok_or("--velocity is required unless --profile supplies it")?;
            let bc = bc
                .or_else(|| profile_data.as_ref().map(|profile| profile.bc))
                .ok_or("--bc is required unless --profile supplies it")?;
            let mass = mass
                .or_else(|| profile_data.as_ref().map(|profile| profile.mass))
                .ok_or("--mass is required unless --profile supplies it")?;
            let diameter = diameter
                .or_else(|| profile_data.as_ref().map(|profile| profile.diameter))
                .ok_or("--diameter is required unless --profile supplies it")?;
            let drag_model = drag_model
                .or_else(|| {
                    profile_data
                        .as_ref()
                        .map(|profile| parse_drag_model_arg_for_truing(&profile.drag_model))
                })
                .unwrap_or(DragModelArg::G1);
            // MBA-1360: explicit --zero-distance > selected zero set > the historical
            // profile zero_distance/auto_zero chain, via the shared resolver (the set's
            // dial corrections are irrelevant to a truing plan and are ignored here).
            let zero_distance = resolve_zero_selection(
                zero_set.as_deref(),
                profile_data.as_ref(),
                None,
                zero_distance,
                profile_data
                    .as_ref()
                    .and_then(|profile| profile.zero_distance.or(profile.auto_zero)),
            )?
            .zero_distance
            .unwrap_or(100.0);
            let sight_height = sight_height
                .or_else(|| {
                    profile_data
                        .as_ref()
                        .and_then(|profile| profile.sight_height)
                })
                .unwrap_or(match cli.units {
                    UnitSystem::Imperial => 2.0,
                    UnitSystem::Metric => 50.0,
                });
            let temperature = UnitConverter::resolve_temperature(
                temperature.or_else(|| profile_data.as_ref().map(|profile| profile.temperature)),
                cli.units,
            )?;
            // MBA-1416: honor --pressure-type here too. `altitude` is Option on this command,
            // so an omitted altitude means no reduction is possible and QNH falls back to the
            // value as given rather than silently reducing against sea level.
            let pressure = apply_pressure_mode(
                UnitConverter::resolve_pressure(
                    pressure.or_else(|| profile_data.as_ref().map(|profile| profile.pressure)),
                    cli.units,
                )?,
                altitude.unwrap_or(0.0),
                pressure_type,
                cli.units,
            );
            let humidity = humidity
                .or_else(|| profile_data.as_ref().map(|profile| profile.humidity))
                .unwrap_or(50.0);
            let altitude = altitude
                .or_else(|| profile_data.as_ref().map(|profile| profile.altitude))
                .unwrap_or(0.0);

            let candidate_ranges = match range_grid.as_deref() {
                Some(grid) => parse_truing_range_grid(grid)?,
                None => candidate_ranges,
            };
            let to_yards = |value: f64| match cli.units {
                UnitSystem::Imperial => value,
                UnitSystem::Metric => value / 0.9144,
            };
            let model = TruingModelInputsV1 {
                muzzle_velocity_fps: match cli.units {
                    UnitSystem::Imperial => velocity,
                    UnitSystem::Metric => velocity / 0.3048,
                },
                ballistic_coefficient: bc,
                drag_model,
                mass_gr: match cli.units {
                    UnitSystem::Imperial => mass,
                    UnitSystem::Metric => mass / GRAMS_PER_GRAIN,
                },
                diameter_in: match cli.units {
                    UnitSystem::Imperial => diameter,
                    UnitSystem::Metric => diameter / 25.4,
                },
                zero_distance_yd: to_yards(zero_distance),
                sight_height_in: match cli.units {
                    UnitSystem::Imperial => sight_height,
                    UnitSystem::Metric => sight_height / 25.4,
                },
                temperature_f: match cli.units {
                    UnitSystem::Imperial => temperature,
                    UnitSystem::Metric => temperature * 9.0 / 5.0 + 32.0,
                },
                pressure_inhg: match cli.units {
                    UnitSystem::Imperial => pressure,
                    UnitSystem::Metric => pressure / 33.8639,
                },
                humidity_pct: humidity,
                altitude_ft: match cli.units {
                    UnitSystem::Imperial => altitude,
                    UnitSystem::Metric => altitude / 0.3048,
                },
            };
            let request = TruingExperimentPlanRequestV1 {
                model,
                candidate_ranges_yd: candidate_ranges.into_iter().map(to_yards).collect(),
                observation_count,
                minimum_separation_yd: to_yards(minimum_separation),
                measurement_sigma_1sd: measurement_resolution,
                drop_unit,
            };
            eprintln!(
                "Evaluating {} candidate ranges for a {}-station truing plan...",
                request.candidate_ranges_yd.len(),
                request.observation_count
            );
            let plan = plan_truing_experiment_v1(&request)?;
            display_truing_experiment_plan(&plan, cli.units, output)?;
        }

        Commands::Mpbr {
            profile,
            velocity,
            bc,
            mass,
            diameter,
            drag_model,
            vital_zone,
            sight_height,
            zero_poi_up,
            zero_poi_right,
            sight_offset,
            temperature,
            pressure,
            pressure_type,
            humidity,
            altitude,
            output,
        } => {
            let temperature = UnitConverter::resolve_temperature(temperature, cli.units)?;
            // MBA-1416: honor --pressure-type here too, so a QNH altimeter setting means
            // the same thing on this command as it does on `trajectory`.
            let pressure = apply_pressure_mode(
                UnitConverter::resolve_pressure(pressure, cli.units)?,
                altitude,
                pressure_type,
                cli.units,
            );
            // Load profile if specified
            let profile_data = profile.as_ref().map(|name| {
                load_profile_for_units(name, cli.units).unwrap_or_else(|e| {
                    eprintln!("Error: {}", e);
                    std::process::exit(1);
                })
            });

            let final_velocity = resolve_param(velocity, &profile_data, |p| p.velocity)
                .unwrap_or_else(|| {
                    eprintln!("Error: --velocity is required (or use --profile)");
                    std::process::exit(1);
                });
            let final_bc = resolve_param(bc, &profile_data, |p| p.bc).unwrap_or_else(|| {
                eprintln!("Error: --bc is required (or use --profile)");
                std::process::exit(1);
            });
            let final_mass = resolve_param(mass, &profile_data, |p| p.mass).unwrap_or_else(|| {
                eprintln!("Error: --mass is required (or use --profile)");
                std::process::exit(1);
            });
            let final_diameter = resolve_param(diameter, &profile_data, |p| p.diameter)
                .unwrap_or_else(|| {
                    eprintln!("Error: --diameter is required (or use --profile)");
                    std::process::exit(1);
                });
            let final_sight_height = sight_height
                .or_else(|| profile_data.as_ref().and_then(|p| p.sight_height))
                .unwrap_or(match cli.units {
                    UnitSystem::Imperial => 2.0,
                    UnitSystem::Metric => 50.0,
                });
            let final_drag_model = match (profile_data.as_ref(), velocity) {
                (Some(profile), None) => parse_drag_model_arg(&profile.drag_model),
                _ => drag_model,
            };
            // MBA-1359: CLI flags (inches imperial / cm metric) win over the profile's
            // stored SI values.
            let zero_poi_vertical_m = zero_poi_up
                .map(|v| zero_poi_display_to_metric(v, cli.units))
                .or_else(|| profile_data.as_ref().and_then(|p| p.zero_poi_up_m))
                .unwrap_or(0.0);
            let zero_poi_horizontal_m = zero_poi_right
                .map(|v| zero_poi_display_to_metric(v, cli.units))
                .or_else(|| profile_data.as_ref().and_then(|p| p.zero_poi_right_m))
                .unwrap_or(0.0);
            // MBA-1396: same CLI-over-profile precedence for the lateral mount offset.
            let sight_offset_lateral_m = sight_offset
                .map(|v| sight_offset_display_to_metric(v, cli.units))
                .or_else(|| profile_data.as_ref().and_then(|p| p.sight_offset_lateral_m))
                .unwrap_or(0.0);

            handle_mpbr(
                final_velocity,
                final_bc,
                final_mass,
                final_diameter,
                final_drag_model,
                vital_zone,
                final_sight_height,
                zero_poi_vertical_m,
                zero_poi_horizontal_m,
                sight_offset_lateral_m,
                temperature,
                pressure,
                humidity,
                altitude,
                cli.units,
                output,
            )?;
        }

        Commands::ComeUps {
            profile,
            velocity,
            bc,
            mass,
            diameter,
            drag_model,
            zero_distance,
            zero_set,
            start,
            end,
            step,
            adjustment_unit,
            elevation_click_value,
            windage_click_value,
            elevation_cf,
            sight_height,
            zero_poi_up,
            zero_poi_right,
            sight_offset,
            temperature,
            pressure,
            pressure_type,
            humidity,
            altitude,
            wind_speed,
            wind_direction,
            output,
        } => {
            let temperature = UnitConverter::resolve_temperature(temperature, cli.units)?;
            // MBA-1416: honor --pressure-type here too, so a QNH altimeter setting means
            // the same thing on this command as it does on `trajectory`.
            let pressure = apply_pressure_mode(
                UnitConverter::resolve_pressure(pressure, cli.units)?,
                altitude,
                pressure_type,
                cli.units,
            );
            let profile_data = profile.as_ref().map(|name| {
                load_profile_for_units(name, cli.units).unwrap_or_else(|e| {
                    eprintln!("Error: {}", e);
                    std::process::exit(1);
                })
            });

            // MBA-1410: come-ups has no windage column, so --windage-click-value can never
            // do anything -- warn instead of silently accepting it (the MBA-1414 inert-flag
            // treatment).
            if let Some(w) = windage_click_value_noop_warning(windage_click_value.as_deref()) {
                eprintln!("{w}");
            }

            // MBA-1358: elevation tracking CF — flag over profile field, validated here.
            let elevation_cf = resolve_tracking_cf(
                elevation_cf,
                profile_data.as_ref().and_then(|p| p.elevation_cf),
                "--elevation-cf",
            )?;

            // MBA-1360: selected zero set. --zero-distance is required on this command,
            // so the set can never change the zero here — only its elevation dial
            // correction applies (added to the come-up column before the CF division).
            let zero_selection = resolve_zero_selection(
                zero_set.as_deref(),
                profile_data.as_ref(),
                None,
                Some(zero_distance),
                None,
            )?;

            // MBA-1355: resolve the elevation click graduation FIRST — before any of the
            // work below — so a missing graduation fails fast with a clear flag name.
            // come-ups has no windage column, so the resolved windage value (which would
            // otherwise just default to the elevation one) is intentionally discarded.
            let elevation_click: Option<ClickValue> =
                if matches!(adjustment_unit, AdjustmentUnit::Clicks) {
                    match resolve_click_values(
                        elevation_click_value.as_deref(),
                        windage_click_value.as_deref(),
                        profile_data.as_ref(),
                    ) {
                        Ok(Some((el, _wi))) => Some(el),
                        Ok(None) => None,
                        Err(e) => {
                            eprintln!("error: {e}");
                            std::process::exit(1);
                        }
                    }
                } else {
                    None
                };

            let final_velocity = resolve_param(velocity, &profile_data, |p| p.velocity)
                .unwrap_or_else(|| {
                    eprintln!("Error: --velocity is required (or use --profile)");
                    std::process::exit(1);
                });
            let final_bc = resolve_param(bc, &profile_data, |p| p.bc).unwrap_or_else(|| {
                eprintln!("Error: --bc is required (or use --profile)");
                std::process::exit(1);
            });
            let final_mass = resolve_param(mass, &profile_data, |p| p.mass).unwrap_or_else(|| {
                eprintln!("Error: --mass is required (or use --profile)");
                std::process::exit(1);
            });
            let final_diameter = resolve_param(diameter, &profile_data, |p| p.diameter)
                .unwrap_or_else(|| {
                    eprintln!("Error: --diameter is required (or use --profile)");
                    std::process::exit(1);
                });
            let final_sight_height = sight_height
                .or_else(|| profile_data.as_ref().and_then(|p| p.sight_height))
                .unwrap_or(match cli.units {
                    UnitSystem::Imperial => 2.0,
                    UnitSystem::Metric => 50.0,
                });
            let final_drag_model = match (profile_data.as_ref(), velocity) {
                (Some(profile), None) => parse_drag_model_arg(&profile.drag_model),
                _ => drag_model,
            };
            // MBA-1323 Phase 2: a `.a7p`-imported profile's velocity-BC segments / Mach-Cd
            // drag curve, resolved to engine shapes. come-ups has no --bc-segment/--drag-table
            // CLI flags of its own, so a saved profile is the only source for these.
            let bc_segments_data = profile_data
                .as_ref()
                .and_then(|p| p.bc_segments.as_ref())
                .map(|rows| bc_segments_from_profile(rows));
            let custom_drag_table = profile_data
                .as_ref()
                .and_then(|p| p.drag_curve.as_ref())
                .map(|pts| {
                    drag_table_from_profile(pts).unwrap_or_else(|e| {
                        eprintln!("Error: saved profile's drag curve is invalid: {e}");
                        std::process::exit(1);
                    })
                });
            // MBA-1357: saved profile's DSF table, if any (come-ups has no --drag-table-style
            // flag of its own for this either — a saved profile is the only source).
            let dsf_table: Option<DsfTable> = profile_data
                .as_ref()
                .and_then(|p| p.dsf_points.clone())
                .map(|points| {
                    DsfTable::from_points(points).unwrap_or_else(|e| {
                        eprintln!("error: saved profile's DSF table is invalid: {e}");
                        std::process::exit(1);
                    })
                });

            // MBA-1359: CLI flags (inches imperial / cm metric) win over the profile's
            // stored SI values.
            let zero_poi_vertical_m = zero_poi_up
                .map(|v| zero_poi_display_to_metric(v, cli.units))
                .or_else(|| profile_data.as_ref().and_then(|p| p.zero_poi_up_m))
                .unwrap_or(0.0);
            let zero_poi_horizontal_m = zero_poi_right
                .map(|v| zero_poi_display_to_metric(v, cli.units))
                .or_else(|| profile_data.as_ref().and_then(|p| p.zero_poi_right_m))
                .unwrap_or(0.0);
            // MBA-1396: same CLI-over-profile precedence for the lateral mount offset.
            let sight_offset_lateral_m = sight_offset
                .map(|v| sight_offset_display_to_metric(v, cli.units))
                .or_else(|| profile_data.as_ref().and_then(|p| p.sight_offset_lateral_m))
                .unwrap_or(0.0);

            handle_come_ups(
                final_velocity,
                final_bc,
                final_mass,
                final_diameter,
                final_drag_model,
                zero_distance,
                start,
                end,
                step,
                adjustment_unit,
                elevation_click,
                elevation_cf,
                zero_selection.elevation_bias_mil,
                final_sight_height,
                zero_poi_vertical_m,
                zero_poi_horizontal_m,
                sight_offset_lateral_m,
                temperature,
                pressure,
                humidity,
                altitude,
                wind_speed,
                wind_direction.degrees,
                cli.units,
                output,
                bc_segments_data,
                custom_drag_table,
                dsf_table,
            )?;
        }

        Commands::Dsf {
            saved_profile,
            range,
            observed_drop,
            zero_set,
        } => {
            let (observed_value, drop_unit) =
                parse_observed_drop(&observed_drop).unwrap_or_else(|e| {
                    eprintln!("error: {e}");
                    std::process::exit(1);
                });

            if !range.is_finite() || range <= 0.0 {
                eprintln!("error: --range must be a positive, finite distance");
                std::process::exit(1);
            }

            let mut profile =
                load_profile_for_units(&saved_profile, cli.units).unwrap_or_else(|e| {
                    eprintln!("Error: {}", e);
                    std::process::exit(1);
                });

            let dist_unit = match cli.units {
                UnitSystem::Imperial => "yd",
                UnitSystem::Metric => "m",
            };

            let range_m = UnitConverter::distance_to_metric(range, cli.units);
            // The solve envelope is the profile's OWN configured max range — i.e. exactly
            // what `trajectory --saved-profile NAME` would solve with no explicit
            // --max-range (MBA-1357 Task 2 review, Critical #1: sizing this to the
            // observation itself made the 90%-of-solved-range gate below fire
            // unconditionally). Only extend it — with the pre-existing 5% headroom so the
            // solved points bracket the requested range even when it lands exactly on a
            // natural stopping point — when the observation lies beyond that default
            // envelope; in that case the observation legitimately being "near/beyond the
            // solved max" is real signal, not an artifact of how far we chose to solve.
            let default_envelope_m =
                UnitConverter::distance_to_metric(DSF_DEFAULT_SOLVE_ENVELOPE, cli.units);
            let solve_max_range_m = if range_m > default_envelope_m {
                range_m * 1.05
            } else {
                default_envelope_m
            };

            // MBA-1360: the profile solve's zero flows through the shared resolver — a
            // selected set's zero_distance feeds it exactly as the profile's own zero
            // would; with no --zero-set this IS the historical auto_zero/zero_distance
            // chain. The set's dial corrections never touch a DSF calibration (the
            // observed drop is a physical impact, not a dial value).
            let dsf_zero_selection = resolve_zero_selection(
                zero_set.as_deref(),
                Some(&profile),
                None,
                None,
                profile.auto_zero.or(profile.zero_distance),
            )?;
            let result = solve_profile_for_dsf(
                &profile,
                cli.units,
                solve_max_range_m,
                dsf_zero_selection.zero_distance,
            )?;

            // MBA-1357 Task 9: the derivation itself (interpolation, Mach, both gates, the
            // DSF ratio) is shared with the bridge's model-driven `derive_dsf_point_v1` via
            // this function — see truing_service.rs's module doc comment for why the CLI
            // still solves through the profile-rich DsfSolveInputs above rather than going
            // through that narrower model-driven entry point directly. Error variants are
            // matched exhaustively and reformatted into the CLI's own historical,
            // units-aware wording (the service's own text is yard-only, since a bare
            // TruingModelInputsV1 has no metric/imperial distinction) so output stays
            // byte-identical to before this extraction.
            let derived =
                derive_dsf_point_from_solve_v1(&result, range_m, observed_value, drop_unit)
                    .unwrap_or_else(|e| {
                        match e {
                            DsfServiceErrorV1::Supersonic { mach, .. } => {
                                eprintln!("{}", dsf_supersonic_error(mach));
                            }
                            DsfServiceErrorV1::OutOfRange { .. } => {
                                let solved_range_display = UnitConverter::distance_from_metric(
                                    result.max_range,
                                    cli.units,
                                );
                                eprintln!(
                                "error: saved profile '{}' trajectory does not reach {range:.0} \
                                 {dist_unit} (solved to {solved_range_display:.0} {dist_unit})",
                                profile.name
                            );
                            }
                            DsfServiceErrorV1::DegenerateDrop { .. } => {
                                eprintln!(
                                    "error: predicted drop at {range:.0} {dist_unit} is zero or \
                                 non-finite; cannot compute a DSF ratio"
                                );
                            }
                            DsfServiceErrorV1::InvalidInput(_)
                            | DsfServiceErrorV1::ForwardModel(_) => {
                                eprintln!("error: {e}");
                            }
                        }
                        std::process::exit(1);
                    });

            // Gate 2's warning (MBA-1357 Task 2 review, Critical #1 — a compound condition,
            // not the 90% ratio alone) is signalled by a non-empty warnings vec; the CLI
            // reconstructs its own exact, units-aware wording rather than printing the
            // service's yard-only text.
            if !derived.warnings.is_empty() {
                eprintln!("{}", dsf_beyond_90pct_warning(range, dist_unit));
            }

            let mach = derived.mach;
            let dsf = derived.dsf;

            let mut table = DsfTable::from_points(profile.dsf_points.clone().unwrap_or_default())
                .unwrap_or_else(|e| {
                    eprintln!("error: saved profile's existing DSF table is invalid: {e}");
                    std::process::exit(1);
                });

            // MBA-1357 Task 2 review, Important #1: the plan requires the append/supersede
            // outcome on stdout ("say so on stdout"), unlike the WARNINGS above/below
            // (90%-of-range, transonic-band gap), which legitimately stay on stderr.
            match table.upsert(DsfPoint { mach, dsf }) {
                Ok(UpsertOutcome::Appended) => {
                    println!("Added DSF point: Mach {mach:.2} -> DSF {dsf:.4}");
                }
                Ok(UpsertOutcome::Replaced { old }) => {
                    println!(
                        "Superseded DSF point (Mach {:.2} -> DSF {:.4}) with Mach {mach:.2} -> DSF {dsf:.4}",
                        old.mach, old.dsf
                    );
                }
                Err(e) => {
                    eprintln!("error: {e}");
                    std::process::exit(1);
                }
            }

            // Gate 3: table-wide transonic-band coverage warning (post-upsert state).
            if dsf_table_missing_transonic_coverage(table.points()) {
                eprintln!("{}", dsf_transonic_gap_warning());
            }

            // MBA-1405 Task 2: DSF validity window note (stdout — `dsf` has no --output
            // flag, so this is always the "table path"). Uses the solve already
            // performed above (`result`); no extra trajectory solve needed.
            match dsf_window_start(result.mach_0_9_distance_m) {
                Some(start_m) => {
                    let start_display = UnitConverter::distance_from_metric(start_m, cli.units);
                    println!(
                        "note: DSF window: at or beyond {start_display:.1} {dist_unit} (90% of \
                         the Mach 0.9 distance)"
                    );
                }
                None => {
                    println!("note: no subsonic window inside the solved range");
                }
            }

            profile.dsf_points = Some(table.points().to_vec());
            let path = save_profile(&profile)?;
            eprintln!("Profile '{}' saved to {:?}", profile.name, path);

            println!(
                "DSF table for '{}' ({}):",
                profile.name,
                dsf_table_summary(table.points())
            );
            for p in table.points() {
                println!("  Mach {:.2}  DSF {:.4}", p.mach, p.dsf);
            }
        }

        Commands::Lead {
            profile,
            velocity,
            bc,
            mass,
            diameter,
            drag_model,
            sight_height,
            temperature,
            pressure,
            pressure_type,
            humidity,
            altitude,
            wind_speed,
            wind_direction,
            use_powder_sensitivity,
            powder_temp_sensitivity,
            powder_temp,
            powder_temp_curve,
            target_speed,
            target_angle,
            target_length,
            start,
            end,
            step,
            adjustment_unit,
            windage_click_value,
            windage_cf,
            output,
        } => {
            let temperature = UnitConverter::resolve_temperature(temperature, cli.units)?;
            // MBA-1416: honor --pressure-type here too, so a QNH altimeter setting means
            // the same thing on this command as it does on `trajectory`.
            let pressure = apply_pressure_mode(
                UnitConverter::resolve_pressure(pressure, cli.units)?,
                altitude,
                pressure_type,
                cli.units,
            );
            let profile_data = profile.as_ref().map(|name| {
                load_profile_for_units(name, cli.units).unwrap_or_else(|e| {
                    eprintln!("Error: {}", e);
                    std::process::exit(1);
                })
            });

            // MBA-1410: resolve the (windage) click graduation FIRST — before any of the
            // work below — so a missing graduation fails fast with a clear flag name, same
            // shape as trajectory/come-ups's elevation_click resolution.
            let windage_click: Option<ClickValue> =
                if matches!(adjustment_unit, AdjustmentUnit::Clicks) {
                    match resolve_single_axis_click_value(
                        windage_click_value.as_deref(),
                        profile_data.as_ref(),
                    ) {
                        Ok(c) => Some(c),
                        Err(e) => {
                            eprintln!("error: {e}");
                            std::process::exit(1);
                        }
                    }
                } else {
                    None
                };

            let final_velocity = resolve_param(velocity, &profile_data, |p| p.velocity)
                .unwrap_or_else(|| {
                    eprintln!("Error: --velocity is required (or use --profile)");
                    std::process::exit(1);
                });
            let final_bc = resolve_param(bc, &profile_data, |p| p.bc).unwrap_or_else(|| {
                eprintln!("Error: --bc is required (or use --profile)");
                std::process::exit(1);
            });
            let final_mass = resolve_param(mass, &profile_data, |p| p.mass).unwrap_or_else(|| {
                eprintln!("Error: --mass is required (or use --profile)");
                std::process::exit(1);
            });
            let final_diameter = resolve_param(diameter, &profile_data, |p| p.diameter)
                .unwrap_or_else(|| {
                    eprintln!("Error: --diameter is required (or use --profile)");
                    std::process::exit(1);
                });
            let final_sight_height = sight_height
                .or_else(|| profile_data.as_ref().and_then(|p| p.sight_height))
                .unwrap_or(match cli.units {
                    UnitSystem::Imperial => 2.0,
                    UnitSystem::Metric => 50.0,
                });
            let final_drag_model = match (&profile_data, velocity) {
                (Some(p), None) => parse_drag_model_arg(&p.drag_model),
                _ => drag_model,
            };

            // Powder temperature plumbing (MBA-1325), identical resolution to the
            // `trajectory` command: --powder-temp serves as either the curve's lookup
            // temperature (defaults to --temperature) or the linear model's reference
            // temperature (defaults to the 70F/21C equivalent); powder_curve_temp_c
            // captures whether it was explicitly given (Some) so the curve can fall
            // back to ambient temperature (None) rather than a synthesized default.
            let powder_curve_temp_c: Option<f64> =
                powder_temp.map(|t| UnitConverter::temperature_to_metric(t, cli.units));
            let powder_temp = powder_temp.unwrap_or(match cli.units {
                UnitSystem::Imperial => DEFAULT_POWDER_REFERENCE_TEMP_F,
                UnitSystem::Metric => DEFAULT_POWDER_REFERENCE_TEMP_C,
            });
            let powder_temp_sensitivity = powder_temp_sensitivity.unwrap_or(match cli.units {
                UnitSystem::Imperial => 1.0,
                UnitSystem::Metric => 0.3048 / (5.0 / 9.0),
            });
            let powder_temp_curve_si: Option<Vec<(f64, f64)>> = match powder_temp_curve.as_deref() {
                Some(s) => Some(parse_powder_temp_curve(s, cli.units)?),
                None => None,
            };

            // MBA-1323 Phase 2: a `.a7p`-imported profile's velocity-BC segments / Mach-Cd
            // drag curve, resolved to engine shapes. lead has no --bc-segment/--drag-table
            // CLI flags of its own, so a saved profile is the only source for these.
            let bc_segments_data = profile_data
                .as_ref()
                .and_then(|p| p.bc_segments.as_ref())
                .map(|rows| bc_segments_from_profile(rows));
            let custom_drag_table = profile_data
                .as_ref()
                .and_then(|p| p.drag_curve.as_ref())
                .map(|pts| {
                    drag_table_from_profile(pts).unwrap_or_else(|e| {
                        eprintln!("Error: saved profile's drag curve is invalid: {e}");
                        std::process::exit(1);
                    })
                });

            // MBA-1358: windage-axis tracking CF (mover lead is a dialed quantity).
            let windage_cf = resolve_tracking_cf(
                windage_cf,
                profile_data.as_ref().and_then(|p| p.windage_cf),
                "--windage-cf",
            )?;

            handle_lead(
                final_velocity,
                final_bc,
                final_mass,
                final_diameter,
                final_drag_model,
                final_sight_height,
                temperature,
                pressure,
                humidity,
                altitude,
                wind_speed,
                wind_direction.degrees,
                use_powder_sensitivity,
                powder_temp_sensitivity,
                powder_temp,
                powder_temp_curve_si,
                powder_curve_temp_c,
                target_speed,
                target_angle,
                target_length,
                start,
                end,
                step,
                adjustment_unit,
                windage_click,
                windage_cf,
                cli.units,
                output,
                bc_segments_data,
                custom_drag_table,
            )?;
        }

        Commands::Powder {
            velocity,
            temperature,
            powder_temp_sensitivity,
            powder_temp,
            powder_temp_curve,
            sweep,
            mass,
            output,
        } => {
            let powder_temp_curve_si: Option<Vec<(f64, f64)>> = match powder_temp_curve.as_deref() {
                Some(s) => Some(parse_powder_temp_curve(s, cli.units)?),
                None => None,
            };
            handle_powder(
                velocity,
                temperature,
                powder_temp_sensitivity,
                powder_temp,
                powder_temp_curve_si,
                sweep,
                mass,
                cli.units,
                output,
            )?;
        }

        Commands::Recoil {
            bullet_weight,
            charge_weight,
            velocity,
            firearm_weight,
            firearm_type,
            gas_velocity_factor,
            gas_velocity,
            output,
        } => {
            handle_recoil(
                bullet_weight,
                charge_weight,
                velocity,
                firearm_weight,
                firearm_type.to_engine(),
                gas_velocity_factor,
                gas_velocity,
                cli.units,
                output,
            )?;
        }

        Commands::PowerFactor {
            weight,
            velocity,
            organization,
            output,
        } => {
            handle_power_factor(weight, velocity, organization, cli.units, output)?;
        }

        Commands::WindCard {
            profile,
            velocity,
            bc,
            mass,
            diameter,
            drag_model,
            zero_distance,
            zero_set,
            wind_speeds,
            wind_angle,
            wind_angles,
            start,
            end,
            step,
            adjustment_unit,
            windage_click_value,
            windage_cf,
            sight_height,
            zero_poi_up,
            zero_poi_right,
            sight_offset,
            temperature,
            pressure,
            pressure_type,
            humidity,
            altitude,
            output,
        } => {
            let temperature = UnitConverter::resolve_temperature(temperature, cli.units)?;
            // MBA-1416: honor --pressure-type here too, so a QNH altimeter setting means
            // the same thing on this command as it does on `trajectory`.
            let pressure = apply_pressure_mode(
                UnitConverter::resolve_pressure(pressure, cli.units)?,
                altitude,
                pressure_type,
                cli.units,
            );
            let profile_data = profile.as_ref().map(|name| {
                load_profile_for_units(name, cli.units).unwrap_or_else(|e| {
                    eprintln!("Error: {}", e);
                    std::process::exit(1);
                })
            });

            // MBA-1410: resolve the (windage) click graduation FIRST — before any of the
            // work below — so a missing graduation fails fast with a clear flag name.
            let windage_click: Option<ClickValue> =
                if matches!(adjustment_unit, AdjustmentUnit::Clicks) {
                    match resolve_single_axis_click_value(
                        windage_click_value.as_deref(),
                        profile_data.as_ref(),
                    ) {
                        Ok(c) => Some(c),
                        Err(e) => {
                            eprintln!("error: {e}");
                            std::process::exit(1);
                        }
                    }
                } else {
                    None
                };

            let final_velocity = resolve_param(velocity, &profile_data, |p| p.velocity)
                .unwrap_or_else(|| {
                    eprintln!("Error: --velocity is required (or use --profile)");
                    std::process::exit(1);
                });
            let final_bc = resolve_param(bc, &profile_data, |p| p.bc).unwrap_or_else(|| {
                eprintln!("Error: --bc is required (or use --profile)");
                std::process::exit(1);
            });
            let final_mass = resolve_param(mass, &profile_data, |p| p.mass).unwrap_or_else(|| {
                eprintln!("Error: --mass is required (or use --profile)");
                std::process::exit(1);
            });
            let final_diameter = resolve_param(diameter, &profile_data, |p| p.diameter)
                .unwrap_or_else(|| {
                    eprintln!("Error: --diameter is required (or use --profile)");
                    std::process::exit(1);
                });
            let final_sight_height = sight_height
                .or_else(|| profile_data.as_ref().and_then(|p| p.sight_height))
                .unwrap_or(match cli.units {
                    UnitSystem::Imperial => 2.0,
                    UnitSystem::Metric => 50.0,
                });
            let final_drag_model = match (profile_data.as_ref(), velocity) {
                (Some(profile), None) => parse_drag_model_arg(&profile.drag_model),
                _ => drag_model,
            };

            // Parse wind speeds
            let ws_vec: Vec<f64> = wind_speeds
                .split(',')
                .filter_map(|s| s.trim().parse::<f64>().ok())
                .collect();
            if ws_vec.is_empty() {
                eprintln!("Error: --wind-speeds must contain at least one valid number (e.g., '5,10,15,20')");
                std::process::exit(1);
            }

            // Resolve wind angle(s): neither flag → legacy full-value 90° card
            // (byte-identical to pre-MBA-727 output); --wind-angle → single
            // angle-aware card; --wind-angles → one card per angle.
            let (wind_angle_vec, legacy_labels): (Vec<f64>, bool) = if let Some(angle) = wind_angle
            {
                (vec![angle], false)
            } else if let Some(csv) = wind_angles.as_ref() {
                let mut angles = Vec::new();
                for tok in csv.split(',') {
                    let tok = tok.trim();
                    let angle: f64 = tok.parse().map_err(|_| {
                        format!("--wind-angles contains an invalid number: '{}'", tok)
                    })?;
                    if angle.is_nan() || !(0.0..=360.0).contains(&angle) {
                        return Err(
                            format!("--wind-angles value '{}' must be in [0, 360]", tok).into()
                        );
                    }
                    angles.push(angle);
                }
                // (no empty-check needed: split(',') yields >=1 token and every
                // token either pushes or errors via `?`)
                (angles, false)
            } else {
                (vec![90.0], true)
            };

            // MBA-1359: CLI flags (inches imperial / cm metric) win over the profile's
            // stored SI values.
            let zero_poi_vertical_m = zero_poi_up
                .map(|v| zero_poi_display_to_metric(v, cli.units))
                .or_else(|| profile_data.as_ref().and_then(|p| p.zero_poi_up_m))
                .unwrap_or(0.0);
            let zero_poi_horizontal_m = zero_poi_right
                .map(|v| zero_poi_display_to_metric(v, cli.units))
                .or_else(|| profile_data.as_ref().and_then(|p| p.zero_poi_right_m))
                .unwrap_or(0.0);
            // MBA-1396: same CLI-over-profile precedence for the lateral mount offset.
            let sight_offset_lateral_m = sight_offset
                .map(|v| sight_offset_display_to_metric(v, cli.units))
                .or_else(|| profile_data.as_ref().and_then(|p| p.sight_offset_lateral_m))
                .unwrap_or(0.0);

            // MBA-1358: windage-axis tracking CF for the drift dial values.
            let windage_cf = resolve_tracking_cf(
                windage_cf,
                profile_data.as_ref().and_then(|p| p.windage_cf),
                "--windage-cf",
            )?;

            // MBA-1360: selected zero set. --zero-distance is required on this command,
            // so only the set's windage dial correction applies (the whole card is a
            // windage quantity).
            let zero_selection = resolve_zero_selection(
                zero_set.as_deref(),
                profile_data.as_ref(),
                None,
                Some(zero_distance),
                None,
            )?;

            handle_wind_card(
                final_velocity,
                final_bc,
                final_mass,
                final_diameter,
                final_drag_model,
                zero_distance,
                &ws_vec,
                &wind_angle_vec,
                legacy_labels,
                start,
                end,
                step,
                adjustment_unit,
                windage_click,
                windage_cf,
                zero_selection.windage_bias_mil,
                final_sight_height,
                zero_poi_vertical_m,
                zero_poi_horizontal_m,
                sight_offset_lateral_m,
                temperature,
                pressure,
                humidity,
                altitude,
                cli.units,
                output,
            )?;
        }

        Commands::Stability {
            profile,
            mass,
            diameter,
            length,
            twist_rate,
            velocity,
            temperature,
            pressure,
            pressure_type,
            altitude,
            output,
        } => {
            let temperature = UnitConverter::resolve_temperature(temperature, cli.units)?;
            // MBA-1416: honor --pressure-type here too, so a QNH altimeter setting means
            // the same thing on this command as it does on `trajectory`.
            let pressure = apply_pressure_mode(
                UnitConverter::resolve_pressure(pressure, cli.units)?,
                altitude,
                pressure_type,
                cli.units,
            );
            let profile_data = profile.as_ref().map(|name| {
                load_profile_for_units(name, cli.units).unwrap_or_else(|e| {
                    eprintln!("Error: {}", e);
                    std::process::exit(1);
                })
            });

            let final_mass = resolve_param(mass, &profile_data, |p| p.mass).unwrap_or_else(|| {
                eprintln!("Error: --mass is required (or use --profile)");
                std::process::exit(1);
            });
            let final_diameter = resolve_param(diameter, &profile_data, |p| p.diameter)
                .unwrap_or_else(|| {
                    eprintln!("Error: --diameter is required (or use --profile)");
                    std::process::exit(1);
                });
            let final_velocity = velocity.unwrap_or(match cli.units {
                UnitSystem::Imperial => 2700.0,
                UnitSystem::Metric => 823.0,
            });

            handle_stability(
                final_mass,
                final_diameter,
                length,
                twist_rate,
                final_velocity,
                temperature,
                pressure,
                altitude,
                cli.units,
                output,
            )?;
        }

        Commands::RangeTable {
            profile,
            velocity,
            bc,
            mass,
            diameter,
            drag_model,
            zero_distance,
            zero_set,
            start,
            end,
            step,
            wind_speed,
            wind_direction,
            adjustment_unit,
            windage_unit,
            elevation_click_value,
            windage_click_value,
            elevation_cf,
            windage_cf,
            sight_height,
            zero_poi_up,
            zero_poi_right,
            sight_offset,
            temperature,
            pressure,
            pressure_type,
            humidity,
            altitude,
            output,
        } => {
            let temperature = UnitConverter::resolve_temperature(temperature, cli.units)?;
            // MBA-1416: honor --pressure-type here too, so a QNH altimeter setting means
            // the same thing on this command as it does on `trajectory`.
            let pressure = apply_pressure_mode(
                UnitConverter::resolve_pressure(pressure, cli.units)?,
                altitude,
                pressure_type,
                cli.units,
            );
            let profile_data = profile.as_ref().map(|name| {
                load_profile_for_units(name, cli.units).unwrap_or_else(|e| {
                    eprintln!("Error: {}", e);
                    std::process::exit(1);
                })
            });

            // MBA-1410: resolve the independent windage unit and, if either axis needs
            // one, the turret click graduations — before any of the work below, so a
            // mismatch or a missing graduation fails fast with a clear message.
            let windage_unit_resolved = resolve_windage_unit(adjustment_unit, windage_unit)
                .unwrap_or_else(|e| {
                    eprintln!("error: {e}");
                    std::process::exit(1);
                });
            let (elevation_click, windage_click): (Option<ClickValue>, Option<ClickValue>) =
                if matches!(adjustment_unit, AdjustmentUnit::Clicks) {
                    match resolve_click_values(
                        elevation_click_value.as_deref(),
                        windage_click_value.as_deref(),
                        profile_data.as_ref(),
                    ) {
                        Ok(Some((el, wi))) => (Some(el), Some(wi)),
                        Ok(None) => (None, None),
                        Err(e) => {
                            eprintln!("error: {e}");
                            std::process::exit(1);
                        }
                    }
                } else {
                    (None, None)
                };

            let final_velocity = resolve_param(velocity, &profile_data, |p| p.velocity)
                .unwrap_or_else(|| {
                    eprintln!("Error: --velocity is required (or use --profile)");
                    std::process::exit(1);
                });
            let final_bc = resolve_param(bc, &profile_data, |p| p.bc).unwrap_or_else(|| {
                eprintln!("Error: --bc is required (or use --profile)");
                std::process::exit(1);
            });
            let final_mass = resolve_param(mass, &profile_data, |p| p.mass).unwrap_or_else(|| {
                eprintln!("Error: --mass is required (or use --profile)");
                std::process::exit(1);
            });
            let final_diameter = resolve_param(diameter, &profile_data, |p| p.diameter)
                .unwrap_or_else(|| {
                    eprintln!("Error: --diameter is required (or use --profile)");
                    std::process::exit(1);
                });
            let final_sight_height = sight_height
                .or_else(|| profile_data.as_ref().and_then(|p| p.sight_height))
                .unwrap_or(match cli.units {
                    UnitSystem::Imperial => 2.0,
                    UnitSystem::Metric => 50.0,
                });
            let final_drag_model = match (profile_data.as_ref(), velocity) {
                (Some(profile), None) => parse_drag_model_arg(&profile.drag_model),
                _ => drag_model,
            };

            // MBA-1359: CLI flags (inches imperial / cm metric) win over the profile's
            // stored SI values.
            let zero_poi_vertical_m = zero_poi_up
                .map(|v| zero_poi_display_to_metric(v, cli.units))
                .or_else(|| profile_data.as_ref().and_then(|p| p.zero_poi_up_m))
                .unwrap_or(0.0);
            let zero_poi_horizontal_m = zero_poi_right
                .map(|v| zero_poi_display_to_metric(v, cli.units))
                .or_else(|| profile_data.as_ref().and_then(|p| p.zero_poi_right_m))
                .unwrap_or(0.0);
            // MBA-1396: same CLI-over-profile precedence for the lateral mount offset.
            let sight_offset_lateral_m = sight_offset
                .map(|v| sight_offset_display_to_metric(v, cli.units))
                .or_else(|| profile_data.as_ref().and_then(|p| p.sight_offset_lateral_m))
                .unwrap_or(0.0);
            // MBA-1358: per-axis tracking CFs, flag-over-profile.
            let elevation_cf = resolve_tracking_cf(
                elevation_cf,
                profile_data.as_ref().and_then(|p| p.elevation_cf),
                "--elevation-cf",
            )?;
            let windage_cf = resolve_tracking_cf(
                windage_cf,
                profile_data.as_ref().and_then(|p| p.windage_cf),
                "--windage-cf",
            )?;

            // MBA-1360: selected zero set. --zero-distance is required on this command,
            // so only the set's dial corrections apply (Drop/Wind columns).
            let zero_selection = resolve_zero_selection(
                zero_set.as_deref(),
                profile_data.as_ref(),
                None,
                Some(zero_distance),
                None,
            )?;

            handle_range_table(
                final_velocity,
                final_bc,
                final_mass,
                final_diameter,
                final_drag_model,
                zero_distance,
                start,
                end,
                step,
                wind_speed,
                wind_direction.degrees,
                adjustment_unit,
                windage_unit_resolved,
                elevation_click,
                windage_click,
                elevation_cf,
                windage_cf,
                zero_selection.elevation_bias_mil,
                zero_selection.windage_bias_mil,
                final_sight_height,
                zero_poi_vertical_m,
                zero_poi_horizontal_m,
                sight_offset_lateral_m,
                temperature,
                pressure,
                humidity,
                altitude,
                cli.units,
                output,
            )?;
        }

        Commands::Compare {
            loads,
            profiles,
            zero_distance,
            start,
            end,
            step,
            wind_speed,
            wind_direction,
            adjustment_unit,
            windage_unit,
            elevation_click_value,
            windage_click_value,
            elevation_cf,
            windage_cf,
            sight_height,
            zero_poi_up,
            zero_poi_right,
            sight_offset,
            temperature,
            pressure,
            pressure_type,
            humidity,
            altitude,
            output,
        } => {
            let temperature = UnitConverter::resolve_temperature(temperature, cli.units)?;
            // MBA-1416: honor --pressure-type here too, so a QNH altimeter setting means
            // the same thing on this command as it does on `trajectory`.
            let pressure = apply_pressure_mode(
                UnitConverter::resolve_pressure(pressure, cli.units)?,
                altitude,
                pressure_type,
                cli.units,
            );

            // MBA-1410: resolve the independent windage unit and, if either axis needs
            // one, the turret click graduations — before any of the work below. compare
            // has no single --profile, so the graduations come only from the explicit
            // flags (profile: None).
            let windage_unit_resolved = resolve_windage_unit(adjustment_unit, windage_unit)
                .unwrap_or_else(|e| {
                    eprintln!("error: {e}");
                    std::process::exit(1);
                });
            let (elevation_click, windage_click): (Option<ClickValue>, Option<ClickValue>) =
                if matches!(adjustment_unit, AdjustmentUnit::Clicks) {
                    match resolve_click_values(
                        elevation_click_value.as_deref(),
                        windage_click_value.as_deref(),
                        None,
                    ) {
                        Ok(Some((el, wi))) => (Some(el), Some(wi)),
                        Ok(None) => (None, None),
                        Err(e) => {
                            eprintln!("error: {e}");
                            std::process::exit(1);
                        }
                    }
                } else {
                    (None, None)
                };

            // Assemble the load list: explicit --load specs first, then --profile loads,
            // preserving command-line order within each group. Load #1 is the delta baseline.
            let mut compare_loads: Vec<CompareLoadSpec> = Vec::new();
            for spec in &loads {
                compare_loads.push(parse_compare_load_spec(spec, cli.units)?);
            }
            for name in &profiles {
                let p = load_profile_for_units(name, cli.units)?;
                // MBA-1323 Phase 2 shape: a profile's velocity-BC segments / Mach-Cd
                // drag curve, resolved to engine shapes and used by zeroing AND the
                // sampled runs (the scalar-BC-only caveat is lifted for compare).
                let bc_segments_data = p
                    .bc_segments
                    .as_ref()
                    .map(|rows| bc_segments_from_profile(rows));
                let custom_drag_table = p
                    .drag_curve
                    .as_ref()
                    .map(|pts| {
                        drag_table_from_profile(pts).map_err(|e| {
                            format!("profile '{name}': saved drag curve is invalid: {e}")
                        })
                    })
                    .transpose()?;
                compare_loads.push(CompareLoadSpec {
                    name: name.clone(),
                    drag_model: parse_drag_model_arg(&p.drag_model),
                    bc: p.bc,
                    mass: p.mass,
                    velocity: p.velocity,
                    diameter: p.diameter,
                    bc_segments_data,
                    custom_drag_table,
                });
            }
            if compare_loads.len() < 2 {
                return Err("compare needs at least 2 loads (via --load and/or --profile)".into());
            }
            if compare_loads.len() > 8 {
                return Err("compare supports at most 8 loads".into());
            }
            if start >= end {
                return Err("--start must be less than --end".into());
            }

            // MBA-1359: compare has no single profile, so the offsets come only from the
            // explicit CLI flags (inches imperial / cm metric), applied to every load.
            let zero_poi_vertical_m = zero_poi_up
                .map(|v| zero_poi_display_to_metric(v, cli.units))
                .unwrap_or(0.0);
            let zero_poi_horizontal_m = zero_poi_right
                .map(|v| zero_poi_display_to_metric(v, cli.units))
                .unwrap_or(0.0);
            // MBA-1396: compare has no single profile — CLI flag only, every load.
            let sight_offset_lateral_m = sight_offset
                .map(|v| sight_offset_display_to_metric(v, cli.units))
                .unwrap_or(0.0);
            // MBA-1358: compare has no single profile — CLI flags only, every load.
            let elevation_cf = resolve_tracking_cf(elevation_cf, None, "--elevation-cf")?;
            let windage_cf = resolve_tracking_cf(windage_cf, None, "--windage-cf")?;

            handle_compare(
                compare_loads,
                zero_distance,
                start,
                end,
                step,
                wind_speed,
                wind_direction.degrees,
                adjustment_unit,
                windage_unit_resolved,
                elevation_click,
                windage_click,
                elevation_cf,
                windage_cf,
                sight_height,
                zero_poi_vertical_m,
                zero_poi_horizontal_m,
                sight_offset_lateral_m,
                temperature,
                pressure,
                humidity,
                altitude,
                cli.units,
                output,
            )?;
        }

        Commands::Profile { action } => {
            match action {
                ProfileAction::Save {
                    name,
                    velocity,
                    bc,
                    bc_reference,
                    mass,
                    diameter,
                    drag_model,
                    twist_rate,
                    sight_height,
                    zero_distance,
                    temperature,
                    pressure,
                    pressure_type,
                    humidity,
                    altitude,
                    density_altitude,
                    bullet_name,
                    wind_speed,
                    wind_direction,
                    shooting_angle,
                    auto_zero,
                    twist_right,
                    use_bc_segments,
                    bullet_length,
                    elevation_click,
                    windage_click,
                    clear_click,
                    clear_dsf,
                    reticle_json,
                    clear_reticle,
                    clicks_per_rev,
                    zero_stop,
                    travel_up,
                    travel_down,
                    windage_travel_left,
                    windage_travel_right,
                    hold_up,
                    hold_down,
                    hold_left,
                    hold_right,
                    turret_elev,
                    turret_wind,
                    clear_turret,
                } => {
                    let temperature = UnitConverter::resolve_temperature(temperature, cli.units)?;
                    let pressure = UnitConverter::resolve_pressure(pressure, cli.units)?;
                    let units_str = match cli.units {
                        UnitSystem::Imperial => "imperial",
                        UnitSystem::Metric => "metric",
                    };

                    // MBA-1357: `profile save` re-saving an existing profile is otherwise a
                    // full overwrite from the given flags (see `bc_segments`/`drag_curve`
                    // above, which are always reset to None here) — but a DSF table isn't
                    // something this command can express at all, so silently dropping it on
                    // every unrelated edit would be hostile. Carry it forward unless
                    // `--clear-dsf` asked to drop it. MBA-1359: the zero POI offsets are in
                    // the same class (only `.a7p --zero-click` import or a hand edit can
                    // produce them), so they are carried forward the same way.
                    let existing_profile = load_profile(&name).ok();
                    let carried_dsf_points = if clear_dsf {
                        None
                    } else {
                        existing_profile.as_ref().and_then(|p| p.dsf_points.clone())
                    };
                    let carried_zero_poi_up_m =
                        existing_profile.as_ref().and_then(|p| p.zero_poi_up_m);
                    let carried_zero_poi_right_m =
                        existing_profile.as_ref().and_then(|p| p.zero_poi_right_m);
                    let carried_sight_offset_lateral_m = existing_profile
                        .as_ref()
                        .and_then(|p| p.sight_offset_lateral_m);
                    // MBA-1358: like dsf_points/zero POI above — `profile save` cannot
                    // express tracking CFs (derive them with `tall-target`, store by hand
                    // edit), so a re-save carries any stored values forward.
                    let carried_elevation_cf =
                        existing_profile.as_ref().and_then(|p| p.elevation_cf);
                    let carried_windage_cf = existing_profile.as_ref().and_then(|p| p.windage_cf);
                    // MBA-1360: zero sets are managed by `profile zero-set`, which this
                    // command cannot express — carry them forward like dsf_points.
                    let carried_zero_sets =
                        existing_profile.as_ref().and_then(|p| p.zero_sets.clone());
                    // MBA-1361: an attached reticle is either supplied here as a JSON file,
                    // explicitly cleared, or carried forward — same three-way treatment as
                    // the DSF table above. Validated at save time so a profile can never
                    // store a description `reticle hold` would later reject.
                    if reticle_json.is_some() && clear_reticle {
                        return Err(
                            "--reticle-json and --clear-reticle are mutually exclusive".into()
                        );
                    }
                    let carried_reticle = match (&reticle_json, clear_reticle) {
                        (Some(path), _) => Some(load_reticle_description(path)?),
                        (None, true) => None,
                        (None, false) => existing_profile.as_ref().and_then(|p| p.reticle.clone()),
                    };

                    // MBA-1348 review fix I1: the twelve turret/hold fields are hardware
                    // spec-sheet facts a shooter doesn't have memorized (clicks-per-rev,
                    // travel, hold bounds, dialed state) — silently dropping them on every
                    // unrelated re-save (a chrono update, a new lot's velocity) would be a
                    // real data-loss footgun, exactly like DSF/reticle/CF/zero-sets above.
                    // They now follow the SAME carry-forward contract: an explicit flag
                    // wins, an omitted one carries the existing profile's value forward,
                    // and `--clear-turret` (mutually exclusive with all twelve flags in the
                    // same invocation, checked below) clears all twelve at once — a single
                    // flag, not twelve individual `--clear-*` flags, since removing one
                    // hardware fact while keeping the rest isn't a realistic workflow.
                    let any_turret_flag_given = clicks_per_rev.is_some()
                        || zero_stop.is_some()
                        || travel_up.is_some()
                        || travel_down.is_some()
                        || windage_travel_left.is_some()
                        || windage_travel_right.is_some()
                        || hold_up.is_some()
                        || hold_down.is_some()
                        || hold_left.is_some()
                        || hold_right.is_some()
                        || turret_elev.is_some()
                        || turret_wind.is_some();
                    if clear_turret && any_turret_flag_given {
                        let mut conflicting = Vec::new();
                        if clicks_per_rev.is_some() {
                            conflicting.push("--clicks-per-rev");
                        }
                        if zero_stop.is_some() {
                            conflicting.push("--zero-stop");
                        }
                        if travel_up.is_some() {
                            conflicting.push("--travel-up");
                        }
                        if travel_down.is_some() {
                            conflicting.push("--travel-down");
                        }
                        if windage_travel_left.is_some() {
                            conflicting.push("--windage-travel-left");
                        }
                        if windage_travel_right.is_some() {
                            conflicting.push("--windage-travel-right");
                        }
                        if hold_up.is_some() {
                            conflicting.push("--hold-up");
                        }
                        if hold_down.is_some() {
                            conflicting.push("--hold-down");
                        }
                        if hold_left.is_some() {
                            conflicting.push("--hold-left");
                        }
                        if hold_right.is_some() {
                            conflicting.push("--hold-right");
                        }
                        if turret_elev.is_some() {
                            conflicting.push("--turret-elev");
                        }
                        if turret_wind.is_some() {
                            conflicting.push("--turret-wind");
                        }
                        return Err(format!(
                            "--clear-turret and {} are mutually exclusive",
                            conflicting.join(", ")
                        )
                        .into());
                    }
                    // MBA-1348 review fix round 2: --clear-click is the removal path the
                    // click-carry-forward change above needs (see the elevation_click/
                    // windage_click merge below) -- symmetric with --clear-turret's
                    // conflict check, one flag clearing both clicks at once (there is no
                    // per-axis clear; windage already falls back to elevation).
                    if clear_click && (elevation_click.is_some() || windage_click.is_some()) {
                        let mut conflicting = Vec::new();
                        if elevation_click.is_some() {
                            conflicting.push("--elevation-click");
                        }
                        if windage_click.is_some() {
                            conflicting.push("--windage-click");
                        }
                        return Err(format!(
                            "--clear-click and {} are mutually exclusive",
                            conflicting.join(", ")
                        )
                        .into());
                    }
                    let existing_optic = existing_profile.as_ref();
                    let carried_clicks_per_revolution = carry_turret_field(
                        clicks_per_rev,
                        existing_optic.and_then(|p| p.clicks_per_revolution),
                        clear_turret,
                    );
                    let carried_zero_stop = carry_turret_field(
                        zero_stop,
                        existing_optic.and_then(|p| p.zero_stop),
                        clear_turret,
                    );
                    let carried_elevation_travel_up_mil = carry_turret_field(
                        travel_up,
                        existing_optic.and_then(|p| p.elevation_travel_up_mil),
                        clear_turret,
                    );
                    let carried_elevation_travel_down_mil = carry_turret_field(
                        travel_down,
                        existing_optic.and_then(|p| p.elevation_travel_down_mil),
                        clear_turret,
                    );
                    let carried_windage_travel_left_mil = carry_turret_field(
                        windage_travel_left,
                        existing_optic.and_then(|p| p.windage_travel_left_mil),
                        clear_turret,
                    );
                    let carried_windage_travel_right_mil = carry_turret_field(
                        windage_travel_right,
                        existing_optic.and_then(|p| p.windage_travel_right_mil),
                        clear_turret,
                    );
                    let carried_turret_elevation_dialed_mil = carry_turret_field(
                        turret_elev,
                        existing_optic.and_then(|p| p.turret_elevation_dialed_mil),
                        clear_turret,
                    );
                    let carried_turret_windage_dialed_mil = carry_turret_field(
                        turret_wind,
                        existing_optic.and_then(|p| p.turret_windage_dialed_mil),
                        clear_turret,
                    );
                    let carried_hold_bound_up_mil = carry_turret_field(
                        hold_up,
                        existing_optic.and_then(|p| p.hold_bound_up_mil),
                        clear_turret,
                    );
                    let carried_hold_bound_down_mil = carry_turret_field(
                        hold_down,
                        existing_optic.and_then(|p| p.hold_bound_down_mil),
                        clear_turret,
                    );
                    let carried_hold_bound_left_mil = carry_turret_field(
                        hold_left,
                        existing_optic.and_then(|p| p.hold_bound_left_mil),
                        clear_turret,
                    );
                    let carried_hold_bound_right_mil = carry_turret_field(
                        hold_right,
                        existing_optic.and_then(|p| p.hold_bound_right_mil),
                        clear_turret,
                    );

                    // MBA-1355: validate a NEWLY SUPPLIED click graduation at save time (a
                    // carried-forward value below was already validated when first saved).
                    if let Some(ref v) = elevation_click {
                        parse_click_value(v)
                            .map_err(|e| format!("--elevation-click '{v}' is invalid: {e}"))?;
                    }
                    if let Some(ref v) = windage_click {
                        parse_click_value(v)
                            .map_err(|e| format!("--windage-click '{v}' is invalid: {e}"))?;
                    }
                    // MBA-1348 review fix I1 (round 2: now with --clear-click):
                    // elevation_click/windage_click carry forward on an unrelated re-save,
                    // like the twelve turret fields above -- they depend on a click
                    // graduation existing at all (optic_profile()'s elevation_click gate),
                    // so leaving just this one field pair on the old reset-on-omit contract
                    // would silently break every carried-forward turret profile on its very
                    // next unrelated re-save. --clear-click (checked above for conflicts
                    // with --elevation-click/--windage-click) is the removal path that
                    // carry-forward itself needs, since an omitted flag no longer means
                    // "remove" the way it used to.
                    let elevation_click = if clear_click {
                        None
                    } else {
                        elevation_click
                            .or_else(|| existing_optic.and_then(|p| p.elevation_click.clone()))
                    };
                    let windage_click = if clear_click {
                        None
                    } else {
                        windage_click
                            .or_else(|| existing_optic.and_then(|p| p.windage_click.clone()))
                    };

                    let profile = ProfileData {
                        name: name.clone(),
                        velocity,
                        bc,
                        mass,
                        diameter,
                        drag_model: drag_model.to_string(),
                        twist_rate,
                        sight_height,
                        zero_distance,
                        units: units_str.to_string(),
                        temperature,
                        pressure,
                        humidity,
                        altitude,
                        bullet_name,
                        created: Some(timestamp_string()),
                        wind_speed,
                        wind_direction: wind_direction.map(|d| d.degrees),
                        shooting_angle,
                        auto_zero,
                        twist_right,
                        use_bc_segments,
                        bullet_length,
                        elevation_click,
                        windage_click,
                        // `profile save` only accepts a scalar BC/drag-model today; a full
                        // velocity-banded schedule or Mach/Cd curve can only be produced by
                        // `.a7p` import (see map_a7p_to_profile).
                        bc_segments: None,
                        drag_curve: None,
                        dsf_points: carried_dsf_points,
                        bc_reference: bc_reference_profile_field(bc_reference),
                        pressure_reference: pressure_reference_profile_field(pressure_type),
                        density_altitude,
                        zero_poi_up_m: carried_zero_poi_up_m,
                        zero_poi_right_m: carried_zero_poi_right_m,
                        sight_offset_lateral_m: carried_sight_offset_lateral_m,
                        elevation_cf: carried_elevation_cf,
                        windage_cf: carried_windage_cf,
                        zero_sets: carried_zero_sets,
                        reticle: carried_reticle,
                        // MBA-1348 review fix I1: carry-forward, like every other field
                        // above that this command cannot fully express standalone -- see
                        // the `any_turret_flag_given`/`carry_turret_field` block above.
                        clicks_per_revolution: carried_clicks_per_revolution,
                        zero_stop: carried_zero_stop,
                        elevation_travel_up_mil: carried_elevation_travel_up_mil,
                        elevation_travel_down_mil: carried_elevation_travel_down_mil,
                        windage_travel_left_mil: carried_windage_travel_left_mil,
                        windage_travel_right_mil: carried_windage_travel_right_mil,
                        turret_elevation_dialed_mil: carried_turret_elevation_dialed_mil,
                        turret_windage_dialed_mil: carried_turret_windage_dialed_mil,
                        hold_bound_up_mil: carried_hold_bound_up_mil,
                        hold_bound_down_mil: carried_hold_bound_down_mil,
                        hold_bound_left_mil: carried_hold_bound_left_mil,
                        hold_bound_right_mil: carried_hold_bound_right_mil,
                    };

                    // MBA-1348: assemble + validate the optic profile (turret mechanics +
                    // reticle hold bounds) at save time too -- the same save-time guarantee
                    // as the elevation/windage click checks above -- so a profile can never
                    // be saved with, e.g., a dialed turret state outside its own declared
                    // travel, a non-positive click size, or an incomplete travel/hold pair.
                    if let Some(optic) = profile
                        .optic_profile()
                        .map_err(|e| format!("optic profile: {e}"))?
                    {
                        optic
                            .validate()
                            .map_err(|e| format!("optic profile: {e}"))?;
                    }

                    let path = save_profile(&profile)?;
                    eprintln!("Profile '{}' saved to {:?}", name, path);
                }

                #[cfg(feature = "profile-import")]
                ProfileAction::Import {
                    file,
                    name,
                    dry_run,
                    strict,
                    zero_click,
                } => {
                    use ballistics_engine::profile_import::{parse_a7p, EnvelopeStatus};
                    // MBA-1359: parse the device click graduation up front so a malformed
                    // value fails before any file work.
                    let zero_click: Option<ballistics_engine::adjustment::ClickValue> =
                        match zero_click.as_deref() {
                            Some(raw) => Some(
                                ballistics_engine::adjustment::parse_click_value(raw)
                                    .map_err(|e| format!("--zero-click: {e}"))?,
                            ),
                            None => None,
                        };
                    let bytes = fs::read(&file)
                        .map_err(|e| format!("cannot read {}: {e}", file.display()))?;
                    let doc =
                        parse_a7p(&bytes).map_err(|e| format!("not a usable .a7p file: {e}"))?;
                    if strict {
                        if let EnvelopeStatus::Mismatch { expected, actual } = &doc.envelope {
                            return Err(format!(
                                "checksum mismatch (file says {expected}, payload hashes to {actual}) — refusing under --strict"
                            )
                            .into());
                        }
                    }
                    // Sanitize the --name override the same way a name derived from the
                    // file itself is sanitized (map_a7p_to_profile does that internally
                    // when there is no override) — an unsanitized override would otherwise
                    // be written verbatim into the profile store's file path.
                    let sanitized_name = name.as_deref().map(|raw| {
                        let sanitized = sanitize_profile_name(raw);
                        if sanitized != raw {
                            println!(
                                "note: profile name sanitized to '{sanitized}' for the profile store"
                            );
                        }
                        sanitized
                    });
                    let outcome = map_a7p_to_profile(&doc, sanitized_name.as_deref(), zero_click)?;
                    print!("{}", render_import_report(&outcome.report));
                    if dry_run {
                        println!("\nDry run — nothing saved.");
                    } else {
                        let path = save_profile(&outcome.profile)?;
                        println!(
                            "\nSaved profile '{}' -> {}",
                            outcome.profile.name,
                            path.display()
                        );
                    }
                }

                ProfileAction::List => {
                    let profiles = list_profiles()?;
                    if profiles.is_empty() {
                        println!("No saved profiles. Use 'ballistics profile save <name> ...' to create one.");
                    } else {
                        println!("Saved Profiles:");
                        println!("┌────────────────────┬────────┬───────┬────────┬──────────┬──────────┐");
                        println!("│ Name               │ Vel    │ BC    │ Mass   │ Diameter │ Drag     │");
                        println!("├────────────────────┼────────┼───────┼────────┼──────────┼──────────┤");
                        for p in &profiles {
                            println!(
                                "│ {:<18} │{:>7.0} │{:>6.3} │{:>7.1} │{:>9.3} │ {:<8} │",
                                p.name, p.velocity, p.bc, p.mass, p.diameter, p.drag_model
                            );
                        }
                        println!("└────────────────────┴────────┴───────┴────────┴──────────┴──────────┘");
                    }
                }

                ProfileAction::Show { name } => {
                    let profile = load_profile(&name)?;
                    println!();
                    println!("Profile: {}", profile.name);
                    println!("╔════════════════════════════════════════╗");
                    println!(
                        "║  Velocity:      {:>10.1} {:<10}  ║",
                        profile.velocity,
                        if profile.units == "metric" {
                            "m/s"
                        } else {
                            "fps"
                        }
                    );
                    if profile.drag_curve.is_some() {
                        // No scalar BC applies to a full drag curve — see
                        // map_a7p_to_profile's CUSTOM handling. Printing the inert 0.0
                        // sentinel here would read as a real coefficient, so it is
                        // replaced by the "Drag curve:" summary line below instead.
                        println!("║  BC:            {:<23}║", "not applicable (CUSTOM)");
                    } else {
                        println!("║  BC:            {:>10.4}             ║", profile.bc);
                    }
                    println!(
                        "║  Mass:          {:>10.1} {:<10}  ║",
                        profile.mass,
                        if profile.units == "metric" { "g" } else { "gr" }
                    );
                    println!(
                        "║  Diameter:      {:>10.3} {:<10}  ║",
                        profile.diameter,
                        if profile.units == "metric" {
                            "mm"
                        } else {
                            "in"
                        }
                    );
                    println!("║  Drag model:    {:>10}             ║", profile.drag_model);
                    if let Some(tw) = profile.twist_rate {
                        println!("║  Twist rate:    {:>10.1}             ║", tw);
                    }
                    if let Some(sh) = profile.sight_height {
                        println!(
                            "║  Sight height:  {:>10.2} {:<10}  ║",
                            sh,
                            if profile.units == "metric" {
                                "mm"
                            } else {
                                "in"
                            }
                        );
                    }
                    if let Some(zd) = profile.zero_distance {
                        println!(
                            "║  Zero distance: {:>10.0} {:<10}  ║",
                            zd,
                            if profile.units == "metric" { "m" } else { "yd" }
                        );
                    }
                    if let Some(ref bn) = profile.bullet_name {
                        println!("║  Bullet:        {:<24}  ║", bn);
                    }
                    if let Some(ws) = profile.wind_speed {
                        println!(
                            "║  Wind speed:    {:>10.1} {:<10}  ║",
                            ws,
                            if profile.units == "metric" {
                                "m/s"
                            } else {
                                "mph"
                            }
                        );
                    }
                    if let Some(wd) = profile.wind_direction {
                        println!("║  Wind dir:      {:>10.1}°            ║", wd);
                    }
                    if let Some(sa) = profile.shooting_angle {
                        println!("║  Shoot angle:   {:>10.1}°            ║", sa);
                    }
                    if let Some(az) = profile.auto_zero {
                        println!(
                            "║  Auto-zero:     {:>10.0} {:<10}  ║",
                            az,
                            if profile.units == "metric" { "m" } else { "yd" }
                        );
                    }
                    if let Some(tr) = profile.twist_right {
                        println!(
                            "║  Twist:         {:>10}             ║",
                            if tr { "Right" } else { "Left" }
                        );
                    }
                    if let Some(ubc) = profile.use_bc_segments {
                        println!(
                            "║  BC segments:   {:>10}             ║",
                            if ubc { "Enabled" } else { "Disabled" }
                        );
                    }
                    if let Some(bl) = profile.bullet_length {
                        println!(
                            "║  Bullet length: {:>10.3} {:<10}  ║",
                            bl,
                            if profile.units == "metric" {
                                "mm"
                            } else {
                                "in"
                            }
                        );
                    }
                    if let Some(ref ec) = profile.elevation_click {
                        println!("║  Elev click:    {:<23}║", ec);
                    }
                    if let Some(ref wc) = profile.windage_click {
                        println!("║  Wind click:    {:<23}║", wc);
                    }
                    // MBA-1323 Phase 2: velocity-BC bands / Mach-Cd drag curve summaries
                    // (count + range). velocity_mps is always SI (see ProfileBcSegment).
                    if let Some(ref segs) = profile.bc_segments {
                        let vmin = segs
                            .iter()
                            .map(|s| s.velocity_mps)
                            .fold(f64::INFINITY, f64::min);
                        let vmax = segs
                            .iter()
                            .map(|s| s.velocity_mps)
                            .fold(f64::NEG_INFINITY, f64::max);
                        println!(
                            "║  BC bands:      {:<23}║",
                            format!("{} rows, {:.0}-{:.0} m/s", segs.len(), vmin, vmax)
                        );
                    }
                    if let Some(ref curve) = profile.drag_curve {
                        let mmin = curve.iter().map(|p| p.mach).fold(f64::INFINITY, f64::min);
                        let mmax = curve
                            .iter()
                            .map(|p| p.mach)
                            .fold(f64::NEG_INFINITY, f64::max);
                        println!(
                            "║  Drag curve:    {:<23}║",
                            format!("{} pts, Mach {:.2}-{:.2}", curve.len(), mmin, mmax)
                        );
                    }
                    println!(
                        "║  Temperature:   {:>10.1} {:<10}  ║",
                        profile.temperature,
                        if profile.units == "metric" {
                            "°C"
                        } else {
                            "°F"
                        }
                    );
                    println!(
                        "║  Pressure:      {:>10.2} {:<10}  ║",
                        profile.pressure,
                        if profile.units == "metric" {
                            "hPa"
                        } else {
                            "inHg"
                        }
                    );
                    println!("║  Humidity:      {:>10.1}%            ║", profile.humidity);
                    println!(
                        "║  Altitude:      {:>10.0} {:<10}  ║",
                        profile.altitude,
                        if profile.units == "metric" { "m" } else { "ft" }
                    );
                    println!("╚════════════════════════════════════════╝");

                    // MBA-1357: DSF (drop-scale-factor) table, one line per point. Printed
                    // outside the fixed-width box above since the row count varies (1-6).
                    if let Some(ref points) = profile.dsf_points {
                        println!();
                        println!("DSF table ({}):", dsf_table_summary(points));
                        for p in points {
                            println!("  Mach {:.2}  DSF {:.4}", p.mach, p.dsf);
                        }
                    }
                }

                ProfileAction::Delete { name } => {
                    delete_profile(&name)?;
                    eprintln!("Profile '{}' deleted.", name);
                }

                // MBA-1360: named zero-set management. Operates on the profile's OWN
                // units (the stored file), converting flag distances from the global
                // --units first, so a metric profile edited from an imperial shell
                // stores a correctly-scaled value.
                ProfileAction::ZeroSet { action } => match action {
                    ZeroSetAction::Add {
                        profile,
                        name,
                        zero_distance,
                        poi_up,
                        poi_right,
                        notes,
                    } => {
                        let mut data = load_profile(&profile)?;
                        for (flag, v) in [("--poi-up", poi_up), ("--poi-right", poi_right)] {
                            if let Some(v) = v {
                                if !v.is_finite() || v.abs() >= 100.0 {
                                    return Err(format!(
                                        "{flag} must be a finite dial correction smaller than \
                                         100 mils (got {v})"
                                    )
                                    .into());
                                }
                            }
                        }
                        let profile_units = match data.units.trim().to_ascii_lowercase().as_str() {
                            "metric" => UnitSystem::Metric,
                            _ => UnitSystem::Imperial,
                        };
                        let zero_distance = zero_distance.map(|v| {
                            if !v.is_finite() || v <= 0.0 {
                                eprintln!(
                                    "error: --zero-distance must be a positive, finite distance"
                                );
                                std::process::exit(1);
                            }
                            UnitConverter::distance_from_metric(
                                UnitConverter::distance_to_metric(v, cli.units),
                                profile_units,
                            )
                        });
                        let set = ProfileZeroSet {
                            name: name.clone(),
                            zero_distance,
                            poi_up_mil: poi_up,
                            poi_right_mil: poi_right,
                            notes,
                        };
                        let sets = data.zero_sets.get_or_insert_with(Vec::new);
                        if let Some(existing) = sets.iter_mut().find(|s| s.name == name) {
                            *existing = set;
                            eprintln!("Replaced zero set '{name}' on profile '{profile}'.");
                        } else {
                            sets.push(set);
                            eprintln!("Added zero set '{name}' to profile '{profile}'.");
                        }
                        save_profile(&data)?;
                    }
                    ZeroSetAction::Remove { profile, name } => {
                        let mut data = load_profile(&profile)?;
                        let sets = data.zero_sets.take().unwrap_or_default();
                        let before = sets.len();
                        let remaining: Vec<ProfileZeroSet> =
                            sets.into_iter().filter(|s| s.name != name).collect();
                        if remaining.len() == before {
                            let names: Vec<&str> =
                                remaining.iter().map(|s| s.name.as_str()).collect();
                            return Err(format!(
                                "zero set '{name}' not found on profile '{profile}'; {}",
                                if names.is_empty() {
                                    "the profile has no zero sets".to_string()
                                } else {
                                    format!("available zero sets: {}", names.join(", "))
                                }
                            )
                            .into());
                        }
                        // Drop the key entirely when the last set is removed, so the
                        // stored JSON round-trips back to its pre-zero-sets shape.
                        data.zero_sets = if remaining.is_empty() {
                            None
                        } else {
                            Some(remaining)
                        };
                        save_profile(&data)?;
                        eprintln!("Removed zero set '{name}' from profile '{profile}'.");
                    }
                    ZeroSetAction::List { profile } => {
                        let data = load_profile(&profile)?;
                        let sets = data.zero_sets.as_deref().unwrap_or(&[]);
                        if sets.is_empty() {
                            println!("Profile '{profile}' has no zero sets.");
                        } else {
                            let dist_unit = if data.units.trim().eq_ignore_ascii_case("metric") {
                                "m"
                            } else {
                                "yd"
                            };
                            println!("Zero sets for '{profile}':");
                            for s in sets {
                                let mut parts: Vec<String> = Vec::new();
                                if let Some(zd) = s.zero_distance {
                                    parts.push(format!("zero {zd:.0} {dist_unit}"));
                                }
                                if let Some(up) = s.poi_up_mil {
                                    parts.push(format!("up {up:+.2} mil"));
                                }
                                if let Some(right) = s.poi_right_mil {
                                    parts.push(format!("right {right:+.2} mil"));
                                }
                                if parts.is_empty() {
                                    parts.push("(empty)".to_string());
                                }
                                match &s.notes {
                                    Some(n) => {
                                        println!("  {:<20} {} — {n}", s.name, parts.join(", "))
                                    }
                                    None => println!("  {:<20} {}", s.name, parts.join(", ")),
                                }
                            }
                        }
                    }
                },
            }
        }

        Commands::DragCurve { drag_model, output } => {
            run_drag_curve(drag_model, output)?;
        }

        Commands::Reticle { action } => {
            handle_reticle(action, cli.units)?;
        }

        Commands::HoldCorridor {
            scenarios,
            ranges,
            target,
            profile,
            velocity,
            bc,
            mass,
            diameter,
            drag_model,
            zero_distance,
            sight_height,
            temperature,
            pressure,
            pressure_type,
            humidity,
            altitude,
            output,
        } => {
            handle_hold_corridor(
                scenarios,
                ranges,
                target,
                profile,
                velocity,
                bc,
                mass,
                diameter,
                drag_model,
                zero_distance,
                sight_height,
                temperature,
                pressure,
                pressure_type,
                humidity,
                altitude,
                cli.units,
                output,
            )?;
        }

        Commands::MarkToRange {
            marks,
            reticle_json,
            mag,
            focal_plane,
            reference_mag,
            zero_distance,
            max_range,
            load,
            output,
        } => {
            handle_mark_to_range(
                marks,
                reticle_json,
                mag,
                focal_plane,
                reference_mag,
                zero_distance,
                max_range,
                load,
                cli.units,
                output,
            )?;
        }

        Commands::BdcMatch {
            mark_ranges,
            reference_mag,
            focal_plane,
            residual_warn,
            zero_distance,
            load,
            output,
        } => {
            handle_bdc_match(
                mark_ranges,
                reference_mag,
                focal_plane,
                residual_warn,
                zero_distance,
                load,
                cli.units,
                output,
            )?;
        }

        Commands::OptimalZero {
            targets,
            vital,
            load,
            output,
        } => {
            handle_optimal_zero(targets, vital, load, cli.units, output)?;
        }

        Commands::Explain {
            a,
            b,
            ranges,
            output,
        } => {
            handle_explain(a, b, ranges, output)?;
        }

        Commands::Tolerance {
            request,
            range,
            target,
            axes,
            domains,
            output,
        } => {
            handle_tolerance(request, range, target, axes, domains, cli.units, output)?;
        }

        Commands::ErrorBudget {
            request,
            ranges,
            sigmas,
            target,
            output,
        } => {
            handle_error_budget(request, ranges, sigmas, target, cli.units, output)?;
        }

        Commands::DialPlan {
            elevation,
            windage,
            range,
            profile,
            elevation_click,
            windage_click,
            clicks_per_rev,
            zero_stop,
            travel_up,
            travel_down,
            windage_travel_left,
            windage_travel_right,
            hold_up,
            hold_down,
            hold_left,
            hold_right,
            turret_elev,
            turret_wind,
            prefer_hold,
            max_hold,
            output,
        } => {
            handle_dial_plan(
                elevation,
                windage,
                range,
                profile,
                elevation_click,
                windage_click,
                clicks_per_rev,
                zero_stop,
                travel_up,
                travel_down,
                windage_travel_left,
                windage_travel_right,
                hold_up,
                hold_down,
                hold_left,
                hold_right,
                turret_elev,
                turret_wind,
                prefer_hold,
                max_hold,
                cli.units,
                output,
            )?;
        }

        Commands::AdaptiveCard {
            load,
            zero_distance,
            start,
            end,
            anchors,
            elevation_budget,
            windage_budget,
            max_rows,
            adjustment,
            output_file,
            output,
        } => {
            handle_adaptive_card(
                load,
                zero_distance,
                start,
                end,
                anchors,
                elevation_budget,
                windage_budget,
                max_rows,
                adjustment,
                output_file,
                cli.units,
                output,
            )?;
        }

        Commands::Completions { shell } => {
            let mut cmd = Cli::command();
            clap_complete::generate(shell, &mut cmd, "ballistics", &mut std::io::stdout());
        }
    }

    Ok(())
}

/// PDF-specific metadata for dope card generation
#[derive(Debug, Clone, Default)]
struct PdfMetadata {
    rifle_name: String,
    location_name: String,
    powder: String,
    bullet_name: String,
    target_speed_mph: f64,
    output_file: Option<PathBuf>,
    // Original imperial values for header display
    velocity_fps: f64,
    temperature_f: f64,
    pressure_inhg: f64,
    altitude_ft: f64,
    wind_speed_mph: f64,
    weight_gr: f64,
    font_scale: f32,
    bold_data: bool,
    adjustment_unit: AdjustmentUnit,
    // MBA-1410: independent windage-axis unit for the Wind/Lead columns (Drop stays on
    // `adjustment_unit`, the elevation axis). Falls back to `adjustment_unit` when
    // `--windage-unit` is omitted — see `resolve_windage_unit`.
    windage_unit: AdjustmentUnit,
}

/// Builds one dope-card `CardRow` from a sampled trajectory point -- the only row source
/// on the `trajectory -o pdf` call site. Extracted out of that call site's `.map()`
/// closure (Task 10 fix-round, C-1) so the legacy-integer-range guarantee is
/// unit-testable directly, without spinning up the CLI or parsing PDF bytes.
#[cfg(feature = "pdf")]
#[allow(clippy::too_many_arguments)]
fn dope_card_row_from_sample(
    s: &trajectory_sampling::TrajectorySample,
    pdf_meta: &PdfMetadata,
    elevation_click: Option<ClickValue>,
    windage_click: Option<ClickValue>,
    zero_set_elevation_bias_mil: f64,
    zero_set_windage_bias_mil: f64,
    elevation_cf: f64,
    windage_cf: f64,
) -> CardRow {
    // Convert distance to yards for range
    let range_yd = UnitConverter::distance_from_metric(s.distance_m, UnitSystem::Imperial);
    // Convert drop to yards (s.drop_m is already in meters, positive = below line of sight)
    let drop_yd = s.drop_m / 0.9144; // meters to yards
                                     // Convert drift to yards
    let drift_yd = s.wind_drift_m / 0.9144;
    // Lead: how far the target moves during the bullet's flight, as an
    // angular hold. Movement (yd) = speed (yd/s) * time; 1760/3600 = mph->yd/s.
    // Shared moving-target math (MBA-1287): mph → m/s, perpendicular
    // (90°) crossing — lead_m = speed·TOF exactly, as before; the yd
    // conversion chain differs from the old 1760/3600 factor by ≤1 ulp.
    let lead_m = ballistics_engine::lead_from_tof(
        pdf_meta.target_speed_mph * 0.44704,
        90.0,
        s.time_s,
        s.distance_m,
    )
    .lead_m;
    let lead_yd = lead_m / 0.9144;
    let elevation_unit = pdf_meta.adjustment_unit;
    let windage_unit = pdf_meta.windage_unit;

    CardRow {
        // Fix-round C-1: sampled distances are exact multiples of --sample-interval IN
        // METRES (default 10.0 m; trajectory_sampling's distances are `i as f64 *
        // step_size`), so their yard conversion is genuinely ~0.3-0.4 yd off an integer
        // (100 m -> 109.36 yd) -- nowhere near format_range's noise band, NOT
        // "near-exact yards" as this comment wrongly claimed before the fix-round.
        // Round here, matching the legacy `DopeCardRow { range_yd: u32, .. }` cast
        // exactly, so the ONE shipped dope-card path keeps its byte-identical integer
        // Range column. `generate_dope_card_pdf`'s own `format_range` still renders a
        // genuinely fractional range with one decimal -- that support exists for a
        // future caller with non-integer ranges (Task 11/12's adaptive cards), not
        // this one.
        range: range_yd.round(),
        // Drop: positive = dial up (bullet below LOS). drop_m is already
        // positive-below-LOS (sample_trajectory: los_y - y_interp), matching the
        // come-up / range tables, so do NOT negate it (this column was sign-flipped).
        // Rendered in MIL/MOA/SMOA/IPHY (MBA-724) or whole clicks (MBA-1355) per
        // its own axis unit (MBA-1410): drop uses the elevation unit/graduation,
        // wind/lead the (possibly different) windage one.
        // MBA-1360: the selected zero set's dial corrections join the
        // Drop/Wind columns here (total-correction dials); the Lead
        // column is a COMPONENT hold (composed on top of the wind dial,
        // which already carries the bias) so it stays bias-free.
        //
        // NOTE: these three still divide/bias on the RAW (unrounded) `range_yd`, exactly
        // as before the fix-round -- only the CardRow's own displayed `range` field
        // above is rounded. The adjustment math has always used the true sample
        // distance, never the display value.
        drop_adj: Some(
            adjustment_display(
                drop_yd,
                range_yd,
                elevation_unit,
                elevation_click,
                zero_set_elevation_bias_mil,
                elevation_cf,
            )
            .value,
        ),
        // Wind: positive = dial right for wind from right
        wind_adj: Some(
            windage_adjustment_display(
                drift_yd,
                range_yd,
                windage_unit,
                windage_click,
                zero_set_windage_bias_mil,
                windage_cf,
            )
            .value,
        ),
        // Lead for a moving target (a dialed quantity — the windage CF divides it, MBA-1358)
        lead_adj: Some(
            windage_adjustment_display(
                lead_yd,
                range_yd,
                windage_unit,
                windage_click,
                0.0,
                windage_cf,
            )
            .value,
        ),
        drop_linear: None,
        come_up: None,
        wind_linear: None,
        velocity: None,
        energy: None,
        time: None,
        wind_columns: Vec::new(),
    }
}

// ============================================================================
// BC5D Segment Generation Helper (MBA-744)
// ============================================================================

/// Refuse a `--bc-table-dir` whose table for this caliber is not actually a table for
/// this caliber.
///
/// `Bc5dTableManager::get_table` selects `bc5d_<key>.bin` by NAME but verifies the
/// header caliber, returning [`Bc5dError::CaliberMismatch`] when the file's CONTENT
/// belongs to another caliber (a rotated manifest, a hand-copied `.bin`, a generator
/// bug). That is fatal on purpose: a wrong-caliber table still produces a full,
/// plausible-looking ladder and silently biases every row, so it is worse than no table
/// at all — see `Bc5dTable::ensure_caliber_matches`. Without this pre-check the mismatch
/// would surface as `generate_bc5d_segments` quietly returning no segments, i.e. exactly
/// the silent uncorrected solve we must not produce.
///
/// Every OTHER load failure keeps the historical lenient behavior (no table for this
/// caliber, unreadable file -> continue without the correction); only a caliber
/// mismatch, which means the operator handed us the wrong data, stops the run.
fn reject_bc5d_caliber_mismatch(
    manager: &mut Bc5dTableManager,
    caliber_in: f64,
) -> Result<(), String> {
    match manager.get_table(caliber_in) {
        Err(error @ Bc5dError::CaliberMismatch { .. }) => Err(format!("--bc-table-dir: {error}")),
        _ => Ok(()),
    }
}

/// Generate velocity-dependent BC segments from a Bc5dTableManager.
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments preserve the existing BC5D compatibility helper"
)]
fn generate_bc5d_segments(
    manager: &mut Bc5dTableManager,
    caliber: f64,
    base_bc: f64,
    drag_type: &str,
    weight_grains: f64,
    muzzle_velocity_fps: Option<f64>,
    bullet_length_in: Option<f64>,
    length_is_user: bool,
    print_ladder_units: Option<UnitSystem>,
) -> Option<Vec<BCSegmentData>> {
    let mut velocity_breakpoints: Vec<f64> = vec![
        4000.0, 3500.0, 3000.0, 2700.0, 2500.0, 2300.0, 2100.0, 2000.0, 1900.0, 1800.0, 1700.0,
        1600.0, 1500.0, 1400.0, 1350.0, 1300.0, 1250.0, 1200.0, 1150.0, 1100.0, 1050.0, 1000.0,
        950.0, 900.0, 850.0, 800.0, 700.0, 600.0, 500.0,
    ];

    if let Some(mv) = muzzle_velocity_fps {
        velocity_breakpoints.push(mv);
    }

    let mut valid_velocities: Vec<f64> = velocity_breakpoints
        .into_iter()
        .filter(|&v| v >= 500.0 && muzzle_velocity_fps.is_none_or(|mv| v <= mv))
        .collect();
    valid_velocities.sort_by(|a, b| b.partial_cmp(a).unwrap());
    valid_velocities.dedup();

    let reference_muzzle_velocity = valid_velocities.first().copied().unwrap_or(3000.0);

    let mut segments: Vec<BCSegmentData> = Vec::new();
    let mut any_correction_found = false;

    for i in 0..valid_velocities.len().saturating_sub(1) {
        let vel_max = valid_velocities[i];
        let vel_min = valid_velocities[i + 1];
        let vel_mid = (vel_max + vel_min) / 2.0;

        if let Ok(correction) = manager.lookup(
            caliber,
            weight_grains,
            base_bc,
            reference_muzzle_velocity,
            vel_mid,
            drag_type,
        ) {
            any_correction_found = true;
            let segment_bc = base_bc * correction;

            segments.push(BCSegmentData {
                velocity_min: vel_min,
                velocity_max: vel_max,
                bc_value: segment_bc,
            });
        }
    }

    if any_correction_found && !segments.is_empty() {
        let length_display = bullet_length_in.unwrap_or_else(|| {
            // MBA-1135: mass-based length estimate (was a mass-blind caliber*3.5 heuristic).
            let est_m = ballistics_engine::stability::estimate_bullet_length_m(
                caliber * 0.0254,
                weight_grains * GRAINS_TO_KG,
            );
            if est_m > 0.0 {
                est_m / 0.0254
            } else {
                caliber * 3.5
            }
        });
        eprintln!(
            "BC5D Table: Generated {} velocity-dependent BC segments",
            segments.len()
        );
        // Length is informational only: the v2 5D table axes are
        // [drag_type][weight][bc][muzzle_vel][current_vel] — length is NOT a
        // lookup dimension. Label the value's source honestly (a previous
        // version printed "(est)" even for user-supplied values).
        eprintln!(
            "BC5D Table: {:.3}\" caliber, {:.1}gr, {:.3}\" length ({}; not a lookup axis)",
            caliber,
            weight_grains,
            length_display,
            if length_is_user { "user" } else { "est" }
        );
        let min_bc = segments
            .iter()
            .map(|s| s.bc_value)
            .fold(f64::INFINITY, f64::min);
        let max_bc = segments
            .iter()
            .map(|s| s.bc_value)
            .fold(f64::NEG_INFINITY, f64::max);
        eprintln!(
            "BC5D Table: BC range {:.5} - {:.5} across velocity envelope",
            min_bc, max_bc
        );
        // --print-bc-segments: dump the ladder as ready-to-paste --bc-segment
        // arguments (e.g. to run BC5D-equivalent corrections offline in the
        // WASM CLI, which accepts --bc-segment but cannot hold the tables).
        if let Some(units) = print_ladder_units {
            let (to_unit, unit_label) = match units {
                UnitSystem::Imperial => (1.0, "fps"),
                UnitSystem::Metric => (0.3048, "m/s"),
            };
            eprintln!(
                "BC5D Table: segment ladder (velocities in {unit_label}; paste as arguments):"
            );
            // Use shortest round-trip endpoint text: fixed decimal precision can collapse a
            // genuine narrow muzzle band into VMIN==VMAX, which the paste-back parser rejects.
            for seg in &segments {
                let display_min = seg.velocity_min * to_unit;
                let mut display_max = seg.velocity_max * to_unit;
                // Multiplication can itself map adjacent fps floats to the same metric float.
                // Preserve the strict parser contract with the smallest representable nudge.
                if display_max <= display_min {
                    display_max = display_min.next_up();
                }
                eprintln!(
                    "  --bc-segment {}:{}:{:.5}",
                    display_min, display_max, seg.bc_value
                );
            }
        }
        Some(segments)
    } else {
        eprintln!(
            "Warning: No BC5D table data found for caliber {:.3}\"",
            caliber
        );
        None
    }
}

// fallback_bullet_length_m moved to ballistics_engine::truing (MBA-1343).

/// How the mover Ring table column (MBA-1325) turns its raw mil angle into the display
/// value for the active `--adjustment-unit` (MBA-1355): every unit except Clicks is a
/// constant multiply; Clicks instead rounds to a whole click count via a resolved
/// [`ClickValue`].
#[derive(Debug, Clone, Copy)]
enum RingUnit {
    Factor(f64),
    Clicks(ClickValue),
}

fn run_trajectory(config: &TrajectoryConfig) -> Result<(), Box<dyn Error>> {
    // Destructure config for convenient access throughout the function
    let TrajectoryConfig {
        velocity,
        angle,
        bc,
        bc_reference_standard,
        mass,
        diameter,
        bullet_length,
        drag_model,
        max_range,
        time_step,
        temperature,
        pressure,
        pressure_type,
        humidity,
        altitude,
        density_altitude_active,
        wind_speed,
        wind_direction,
        wind_vertical,
        ref wind_segments,
        output,
        full,
        plot,
        units,
        sight_height,
        bore_height,
        ignore_ground_impact,
        cant,
        zero_poi_vertical_m,
        zero_poi_horizontal_m,
        sight_offset_lateral_m,
        zero_solve_distance_m,
        use_bc_segments,
        use_cluster_bc,
        ref bc_segments_data,
        ref custom_drag_table,
        cd_scale,
        enable_magnus,
        enable_coriolis,
        enable_spin_drift,
        enable_aerodynamic_jump,
        enable_wind_shear,
        wind_shear_model,
        enable_pitch_damping,
        enable_precession,
        sample_trajectory,
        sample_interval,
        drops_reference,
        elevation_cf,
        windage_cf,
        zero_set_elevation_bias_mil,
        zero_set_windage_bias_mil,
        use_rk4,
        use_rk45,
        twist_rate,
        twist_right,
        latitude,
        shot_direction,
        shooting_angle,
        use_powder_sensitivity,
        powder_temp_sensitivity,
        powder_temp,
        ref powder_temp_curve,
        powder_curve_temp_c,
        target_speed,
        with_drag_coefficient,
        adjustment_unit,
        elevation_click,
        windage_click,
        ref pdf_metadata,
        ref dsf_table,
        solved_zero_angle_deg,
    } = *config;

    // Mover ring (MBA-1325): a per-point Ring column/field, additive across table/JSON/CSV,
    // enabled only when --target-speed > 0 (same units convention as `lead --target-speed`:
    // mph imperial / m/s metric). Resolved once here so every output branch below agrees.
    let target_speed_mps = UnitConverter::wind_to_metric(target_speed, units);
    let ring_enabled = target_speed_mps > 0.0;
    // Ring TABLE column angular unit honors --adjustment-unit (review fix M3). The MOA
    // conversion uses the crate's locked printed-table dial constant (MBA-724):
    // MOA_PER_UNIT_RATIO / MIL_PER_UNIT_RATIO == exactly 3.438 — deliberately NOT the
    // exact-angle 3437.7467/1000, so Ring(moa)/Ring(mil) keeps the same ratio as every
    // other MIL/MOA column pair this CLI prints (see moving_target.rs module docs).
    //
    // MBA-1355: Clicks has no fixed factor — it needs a resolved elevation graduation to
    // round the ring's mil angle to whole clicks (`RingUnit::Clicks`), rather than
    // scaling by a constant like every other unit (`RingUnit::Factor`). The Ring column
    // isn't cleanly "elevation" or "windage" (a moving-target lead ring is its own axis),
    // so it reuses the elevation click graduation, same as the PDF dope card's Drop
    // column below.
    let (ring_hdr, ring_unit) = match adjustment_unit {
        AdjustmentUnit::Mil => ("Ring(mil)", RingUnit::Factor(1.0)),
        AdjustmentUnit::Moa => (
            "Ring(moa)",
            RingUnit::Factor(
                ballistics_engine::moving_target::MOA_PER_UNIT_RATIO
                    / ballistics_engine::moving_target::MIL_PER_UNIT_RATIO,
            ),
        ),
        // MBA-1355: SMOA/IPHY are numerically identical (exact inches-per-hundred-yards);
        // only the header text differs, so they get their own labels but share the ratio.
        AdjustmentUnit::Smoa => ("Ring(smoa)", RingUnit::Factor(smoa_per_mil())),
        AdjustmentUnit::Iphy => ("Ring(iphy)", RingUnit::Factor(smoa_per_mil())),
        AdjustmentUnit::Clicks => (
            "Ring(clicks)",
            RingUnit::Clicks(elevation_click.expect(
                "adjustment_unit == Clicks implies elevation_click was resolved in main()'s \
                 Trajectory dispatch before run_trajectory was ever called",
            )),
        ),
    };

    // MBA-1135: track whether the twist is a synthesized default (shooter omitted --twist-rate)
    // so the stability summary can be honest about it rather than presenting an assumed-twist Sg
    // as a hard "STABLE" / "UNSTABLE" verdict.
    let twist_assumed = twist_rate.is_none();

    // Create ballistic inputs with all required fields
    let drag_model_enum = drag_model;
    let wind_direction_rad = wind_direction.to_radians();

    let mut inputs = BallisticInputs {
        // Core ballistics parameters
        bc_value: bc,
        bc_type: drag_model_enum,
        bc_reference_standard,
        bullet_mass: mass,
        muzzle_velocity: velocity,
        bullet_diameter: diameter,
        bullet_length,

        // Targeting and positioning
        muzzle_angle: angle.to_radians(),
        target_distance: max_range,
        azimuth_angle: 0.0,
        shot_azimuth: shot_direction.map(|d| d.to_radians()).unwrap_or(0.0),
        shooting_angle: shooting_angle.to_radians(),
        cant_angle: cant.to_radians(),
        sight_height,
        sight_offset_lateral_m,
        muzzle_height: bore_height, // Bore height above ground from --bore-height CLI option
        target_height: 0.0,
        zero_poi_vertical_m,
        zero_poi_horizontal_m,
        ground_threshold: if ignore_ground_impact {
            f64::NEG_INFINITY
        } else {
            0.0
        },

        // Environmental conditions
        altitude,
        temperature,
        pressure,
        humidity,
        latitude,

        // Wind conditions
        wind_speed,
        wind_angle: wind_direction_rad,

        // Bullet characteristics
        // MBA-1135: caliber/weight-aware default twist (Miller-inverse) instead of a fixed 1:12"
        // when the shooter omits --twist-rate. `twist_assumed` (above) records that this happened.
        twist_rate: twist_rate.unwrap_or_else(|| {
            ballistics_engine::stability::default_twist_inches(diameter, mass, velocity)
        }),
        is_twist_right: twist_right,
        caliber_inches: diameter / 0.0254,
        weight_grains: mass / GRAINS_TO_KG,
        manufacturer: None,
        bullet_model: None,
        bullet_id: None,
        bullet_cluster: None,

        // Integration method selection
        use_rk4,
        use_adaptive_rk45: use_rk45,

        // Advanced effects
        enable_advanced_effects: enable_magnus || enable_coriolis, // Either one enables the system
        enable_magnus,
        enable_coriolis,
        use_powder_sensitivity,
        powder_temp_sensitivity: if use_powder_sensitivity {
            // Convert (velocity / degree) to SI: velocity per a 1-degree DELTA.
            // The denominator must be a temperature delta, not the absolute-point
            // conversion of 1 F (which is -17.2 C) — that was MBA-963.
            UnitConverter::velocity_to_metric(powder_temp_sensitivity, units)
                / UnitConverter::temperature_delta_to_metric(1.0, units)
        } else {
            0.0
        },
        powder_temp: UnitConverter::temperature_to_metric(powder_temp, units),
        powder_temp_curve: powder_temp_curve.clone(),
        powder_curve_temp_c,
        tipoff_yaw: 0.0,
        cd_delta2: 7.5,
        tipoff_decay_distance: 50.0,
        // The schedule was resolved once before auto-zero and is shared by every local path.
        use_bc_segments,
        bc_segments: None,
        bc_segments_data: bc_segments_data.clone(),
        use_enhanced_spin_drift: enable_spin_drift,
        enable_aerodynamic_jump,
        use_form_factor: false,
        enable_wind_shear,
        // Forward the user's --wind-shear-model (MBA-965) instead of hardcoding
        // a single profile. "none" when shear is disabled so the engine skips it.
        wind_shear_model: if enable_wind_shear {
            wind_shear_model.as_engine_str().to_string()
        } else {
            "none".to_string()
        },
        enable_trajectory_sampling: sample_trajectory,
        sample_interval,
        drops_reference: drops_reference.to_engine(),
        enable_pitch_damping,
        enable_precession_nutation: enable_precession,
        use_cluster_bc,

        // Optional data
        bc_type_str: None,
        custom_drag_table: custom_drag_table.clone(),
        cd_scale,
    };

    // MBA-1359: when the dispatch solved a zero, the muzzle angle above already carries the
    // vertical POI bias (the zero solve returned it biased), but an angle copy cannot carry
    // the horizontal bias — re-derive the azimuth term here, exactly as
    // calculate_and_set_zero_angle applies it to its own solver. Exact no-op when the
    // offset is 0.0 or no zero was solved.
    if let Some(zero_distance_m) = zero_solve_distance_m {
        inputs.azimuth_angle += inputs.windage_zero_bias_rad(zero_distance_m);
    }

    // Set up wind conditions
    let wind = WindConditions {
        speed: wind_speed,
        direction: wind_direction_rad,
        vertical_speed: wind_vertical,
    };

    // MBA-1397: resolve station temperature/pressure once, honoring pressure_type. Absolute is
    // byte-identical to the legacy default-sentinel resolution TrajectorySolver::new performs
    // internally (same underlying functions, same inputs); Qnh reduces a declared altimeter
    // setting to station pressure. Reused below for the solver, the custom-drag-table
    // Mach-range warning, and the stability summary, so all three agree with what the
    // trajectory actually flew under.
    //
    // MBA-1366: when `--density-altitude` (or a CSV DA/DENSITY_ALTITUDE column) was used,
    // `temperature`/`pressure` are ALREADY the fully-resolved station values (the CLI dispatch
    // computed them via `atmosphere::resolve_atmosphere_for_density_altitude` before this
    // function ever ran) — skip re-deriving through the default-sentinel heuristic a second
    // time, which could otherwise misinterpret an already-resolved value that happens to land
    // near the sea-level standard as "omitted" and silently re-derive it from `altitude`
    // instead (the same class of bug the QNH Authoritative bypass above exists to prevent).
    let (resolved_temperature, resolved_pressure) = if density_altitude_active {
        (temperature, pressure)
    } else {
        resolve_station_conditions_with_pressure_mode(
            temperature,
            pressure,
            altitude,
            pressure_type,
        )
    };

    // Set up atmospheric conditions
    let atmosphere = AtmosphericConditions {
        temperature: resolved_temperature,
        pressure: resolved_pressure,
        humidity,
        altitude,
    };

    // MBA-1420: WHICH OF THE TWO IS AUTHORITATIVE. From here on `atmosphere` holds the resolved
    // station values, while `inputs.temperature`/`inputs.pressure` still hold the RAW figures the
    // user typed -- pre-QNH-reduction. Only `atmosphere` reaches the trajectory: it is handed to
    // `new_with_resolved_station_atmosphere` below, and `fast_integrate` overwrites the inputs'
    // copies from its own atmo params. Every reader of `inputs.pressure` on this path was traced
    // and none is reachable from the solve, so the stale copies are inert today.
    //
    // They are still a trap for the next reader, and they are inconsistent with the
    // density-altitude path above, where those same input fields ARE the resolved values (which
    // is exactly why `density_altitude_active` has to short-circuit the resolution). `wasm.rs`
    // carries the identical split. Treat `atmosphere` as the answer to "what did it fly under";
    // do not reach for `inputs.pressure` here without re-checking which of the two you have.

    // Create solver. Authoritative: `atmosphere` above is already fully resolved (including
    // the QNH reduction, when applicable), so it is trusted as-is rather than re-derived
    // through the legacy default-sentinel heuristic a second time.
    let mut solver = TrajectorySolver::new_with_resolved_station_atmosphere(
        inputs.clone(),
        wind,
        atmosphere.clone(),
    );
    solver.set_max_range(max_range);
    solver.set_time_step(time_step);

    // Downrange-segmented wind (overrides the scalar wind when present).
    if !wind_segments.is_empty() {
        if enable_wind_shear {
            return Err(
                "--wind-segment cannot be combined with --enable-wind-shear \
                (downrange segments + altitude shear is not yet a defined model)"
                    .into(),
            );
        }
        // Note when a non-zero scalar wind is also set, since segments take precedence.
        if wind_speed != 0.0 || wind_vertical != 0.0 {
            eprintln!(
                "note: --wind-segment overrides --wind-speed/--wind-direction/--wind-vertical \
                 (scalar wind ignored)"
            );
        }
        // Warn if the segments don't cover the whole trajectory (wind is zero beyond
        // the last segment's until-distance). A 1 m epsilon avoids float-noise warnings
        // when a segment is set right at max_range.
        let coverage_m = wind_segments
            .iter()
            .map(|seg| seg.until_m)
            .fold(0.0_f64, f64::max);
        if coverage_m < max_range - 1.0 {
            let (cov_disp, max_disp, unit) = match units {
                UnitSystem::Imperial => (coverage_m / 0.9144, max_range / 0.9144, "yd"),
                UnitSystem::Metric => (coverage_m, max_range, "m"),
            };
            eprintln!(
                "warning: wind segments cover only {cov_disp:.0} {unit} of the {max_disp:.0} {unit} \
                trajectory; wind is treated as zero beyond {cov_disp:.0} {unit}"
            );
        }
        solver.set_wind_segments(wind_segments.clone());
    }

    // Solve trajectory
    let mut result = solver.solve()?;

    // MBA-1357: apply the saved profile's DSF table (if any), IN PLACE, before any output
    // format below reads `result` — this is a drop-only correction (see apply_dsf's doc
    // comment for the invariant: velocity/energy/TOF/windage untouched), so it must run
    // identically ahead of JSON/CSV/Table/PDF rather than only for one format.
    if let Some(table) = dsf_table.as_ref() {
        apply_dsf(&mut result, table);
    }

    // MBA-1285: when a custom drag table is in play, warn (best-effort, stderr) if the
    // shot's Mach range runs outside the table's measured domain. The engine already
    // holds the nearest endpoint Cd out there; this just flags that as approximate.
    if let Some(table) = custom_drag_table.as_ref() {
        let (_, sos) = ballistics_engine::atmosphere::calculate_atmosphere(
            altitude,
            Some(resolved_temperature),
            Some(resolved_pressure),
            humidity,
        );
        if sos.is_finite() && sos > 0.0 {
            let muzzle_mach = velocity / sos;
            let impact_mach = result.impact_velocity / sos;
            if let (Some(&lo), Some(&hi)) = (table.mach_values.first(), table.mach_values.last()) {
                if muzzle_mach > hi || impact_mach < lo {
                    eprintln!(
                        "Warning: shot Mach range [{impact_mach:.2}, {muzzle_mach:.2}] extends beyond \
                         the drag table domain [{lo:.2}, {hi:.2}]; the nearest tabulated Cd is held \
                         outside that range (approximate)."
                    );
                }
            }
        }
    }

    // Report the summary using the SAME twist the integration path actually
    // used (MBA-964). The path builds BallisticInputs with
    // `twist_rate.unwrap_or(12.0)`, so it always flies with a real twist; the
    // summary must therefore compute stability/spin-drift from that effective
    // twist rather than only when `--twist-rate` was explicitly supplied,
    // otherwise the JSON/table reports null while drift is silently applied.
    let effective_twist_rate = inputs.twist_rate;

    // Calculate stability coefficient if twist rate is provided
    let stability = if effective_twist_rate > 0.0 {
        ballistics_engine::stability::compute_stability_coefficient(
            &inputs,
            (altitude, resolved_temperature, resolved_pressure, 1.0),
        )
    } else {
        0.0
    };

    // Report the same canonical Litz spin drift applied to the trajectory points. The
    // empirical t^1.83 fit already reflects real spin history, so layering a retained-spin
    // multiplier on top would double-count decay and diverge from every solver path.
    let spin_drift = if enable_spin_drift && effective_twist_rate > 0.0 && stability > 0.0 {
        ballistics_engine::spin_drift::litz_drift_meters(
            stability,
            result.time_of_flight,
            twist_right,
        )
    } else {
        0.0
    };

    // Detect runs that ended because the integrator hit its 100 s time cap
    // rather than at a real impact or the requested range (MBA-969). This
    // happens for steep --ignore-ground-impact shots: ground termination is
    // disabled, so the bullet keeps "falling" past the ground and the only
    // terminator left is the time cap. Without this the summary prints the
    // capped state as a bogus ground impact (e.g. y = -12390 yd at t = 99.99 s).
    const INTEGRATION_TIME_CAP_S: f64 = 100.0;
    let reached_max_range = result.max_range >= max_range - (max_range.abs() * 1e-3).max(1e-6);
    let reached_time_cap = result
        .points
        .last()
        .map(|p| p.time >= INTEGRATION_TIME_CAP_S - 0.05)
        .unwrap_or(false)
        && !reached_max_range;

    // Format output
    match output {
        OutputFormat::Json => {
            // Honor --units like the table/csv branches do (MBA-962): convert
            // all distance/velocity/energy fields to the user's unit system and
            // record which system the numbers are in.
            let units_label = match units {
                UnitSystem::Metric => "metric",
                UnitSystem::Imperial => "imperial",
            };
            let trajectory_result = TrajectoryResult {
                units: units_label.to_string(),
                max_range: UnitConverter::distance_from_metric(result.max_range, units),
                max_height: UnitConverter::distance_from_metric(result.max_height, units),
                time_of_flight: result.time_of_flight,
                impact_velocity: UnitConverter::velocity_from_metric(result.impact_velocity, units),
                impact_energy: UnitConverter::energy_from_metric(result.impact_energy, units),
                stability_coefficient: if stability > 0.0 {
                    Some(stability)
                } else {
                    None
                },
                spin_drift: if spin_drift.abs() > 0.0001 {
                    Some(UnitConverter::distance_from_metric(spin_drift, units))
                } else {
                    None
                },
                zero_angle_degrees: solved_zero_angle_deg,
                // Pitch-damping diagnostics (MBA-966), only present when
                // --enable-pitch-damping populated them on the engine result.
                min_pitch_damping: result.min_pitch_damping,
                transonic_mach: result.transonic_mach,
                // Precession/nutation diagnostics (MBA-966), only present when
                // --enable-precession populated them. Angles stay in radians,
                // matching the table output.
                max_yaw_angle: result.max_yaw_angle,
                max_precession_angle: result.max_precession_angle,
                final_pitch_angle: result.angular_state.as_ref().map(|s| s.pitch_angle),
                final_yaw_angle: result.angular_state.as_ref().map(|s| s.yaw_angle),
                trajectory: if full {
                    result
                        .points
                        .into_iter()
                        .map(|p| {
                            // Mover ring (MBA-1325), additive: only populated when
                            // --target-speed enabled it; None/None serialize to "absent"
                            // (skip_serializing_if) so JSON without the flag is unchanged.
                            let (mover_ring_m, mover_ring_mil) = if ring_enabled {
                                let (ring_m, ring_mil) = ballistics_engine::mover_ring(
                                    target_speed_mps,
                                    p.time,
                                    p.position.x,
                                );
                                // MBA-1358: mover lead is a dialed quantity — the mil
                                // field is divided by the windage CF (scope units);
                                // ring_m stays raw meters.
                                (Some(ring_m), ring_mil.map(|mil| mil / windage_cf))
                            } else {
                                (None, None)
                            };
                            TrajectoryPoint {
                                time: p.time,
                                // Output contract is unchanged: the `x` field is lateral
                                // (drift), `z` is downrange. With McCoy internals these map
                                // to position.z (lateral) and position.x (downrange).
                                x: UnitConverter::distance_from_metric(p.position.z, units),
                                y: UnitConverter::distance_from_metric(p.position.y, units),
                                z: UnitConverter::distance_from_metric(p.position.x, units),
                                velocity: UnitConverter::velocity_from_metric(
                                    p.velocity_magnitude,
                                    units,
                                ),
                                energy: UnitConverter::energy_from_metric(p.kinetic_energy, units),
                                mover_ring_m,
                                mover_ring_mil,
                                // MBA-1423: dimensionless, so no unit conversion — it means the
                                // same thing under --units metric and imperial.
                                drag_coefficient: if with_drag_coefficient {
                                    p.drag_coefficient
                                } else {
                                    None
                                },
                            }
                        })
                        .collect()
                } else {
                    vec![]
                },
                legend: TrajectoryLegend::for_units(units),
            };
            println!("{}", serde_json::to_string_pretty(&trajectory_result)?);
        }

        OutputFormat::Csv => {
            // Determine unit labels for CSV header
            let (dist_unit, vel_unit, energy_unit) = match units {
                UnitSystem::Metric => ("m", "m/s", "J"),
                UnitSystem::Imperial => ("yd", "fps", "ft-lb"),
            };

            if full {
                // Check if we have sampled points (from --sample-trajectory)
                if let Some(ref sampled) = result.sampled_points {
                    // Output sampled trajectory at regular distance intervals
                    // Drop/drift use the same small-deflection units as the table/API
                    // (inches for Imperial, meters for Metric), NOT the range unit (MBA-950).
                    let defl_unit = match units {
                        UnitSystem::Metric => "m",
                        UnitSystem::Imperial => "in",
                    };
                    // MBA-1403: the drop column header carries the active drops
                    // reference (drop_target_in vs drop_in); drift is untouched. The
                    // Los arm formats byte-identically to the historical header.
                    let drop_col = match drops_reference {
                        DropsReferenceArg::Los => format!("drop_{}", defl_unit),
                        DropsReferenceArg::Target => format!("drop_target_{}", defl_unit),
                    };
                    let header = format!(
                        "distance_{},{},drift_{},velocity_{},energy_{},time_s",
                        dist_unit, drop_col, defl_unit, vel_unit, energy_unit
                    );
                    // Mover ring (MBA-1325): extra column, header carries the unit; only
                    // emitted when --target-speed enabled it (additive, matches JSON).
                    if ring_enabled {
                        println!("{},ring_mil", header);
                    } else {
                        println!("{}", header);
                    }
                    for s in sampled {
                        let distance = UnitConverter::distance_from_metric(s.distance_m, units);
                        // Imperial drop/drift in inches (meters * 39.3701); Metric in meters.
                        let (drop, drift) = match units {
                            UnitSystem::Imperial => (s.drop_m * 39.3701, s.wind_drift_m * 39.3701),
                            UnitSystem::Metric => (s.drop_m, s.wind_drift_m),
                        };
                        let vel = UnitConverter::velocity_from_metric(s.velocity_mps, units);
                        let energy = UnitConverter::energy_from_metric(s.energy_j, units);
                        let row = format!(
                            "{:.2},{:.2},{:.2},{:.2},{:.2},{:.4}",
                            distance, drop, drift, vel, energy, s.time_s
                        );
                        if ring_enabled {
                            let (_, ring_mil) = ballistics_engine::mover_ring(
                                target_speed_mps,
                                s.time_s,
                                s.distance_m,
                            );
                            match ring_mil {
                                // MBA-1358: dialed quantity — divided by the windage
                                // CF (scope units; /1.0 is exact).
                                Some(mil) => println!("{},{:.3}", row, mil / windage_cf),
                                None => println!("{},", row),
                            }
                        } else {
                            println!("{}", row);
                        }
                    }
                } else {
                    // Output raw trajectory points (all integration steps)
                    let header = format!(
                        "time_s,x_{},y_{},z_{},velocity_{},energy_{}",
                        dist_unit, dist_unit, dist_unit, vel_unit, energy_unit
                    );
                    if ring_enabled {
                        println!("{},ring_mil", header);
                    } else {
                        println!("{}", header);
                    }
                    for p in result.points {
                        // Output contract unchanged: x column is lateral, z is downrange.
                        // McCoy internals: lateral=position.z, downrange=position.x.
                        let x = UnitConverter::distance_from_metric(p.position.z, units);
                        let y = UnitConverter::distance_from_metric(p.position.y, units);
                        let z = UnitConverter::distance_from_metric(p.position.x, units);
                        let vel = UnitConverter::velocity_from_metric(p.velocity_magnitude, units);
                        let energy = UnitConverter::energy_from_metric(p.kinetic_energy, units);
                        let row = format!(
                            "{:.4},{:.2},{:.2},{:.2},{:.2},{:.2}",
                            p.time, x, y, z, vel, energy
                        );
                        if ring_enabled {
                            // Downrange is position.x (McCoy frame) regardless of the CSV's
                            // lateral/downrange column swap above.
                            let (_, ring_mil) = ballistics_engine::mover_ring(
                                target_speed_mps,
                                p.time,
                                p.position.x,
                            );
                            match ring_mil {
                                // MBA-1358: dialed quantity — divided by the windage
                                // CF (scope units; /1.0 is exact).
                                Some(mil) => println!("{},{:.3}", row, mil / windage_cf),
                                None => println!("{},", row),
                            }
                        } else {
                            println!("{}", row);
                        }
                    }
                }
            } else {
                println!("metric,value,unit");
                println!(
                    "max_range,{:.2},{}",
                    UnitConverter::distance_from_metric(result.max_range, units),
                    dist_unit
                );
                println!(
                    "max_height,{:.2},{}",
                    UnitConverter::distance_from_metric(result.max_height, units),
                    dist_unit
                );
                println!("time_of_flight,{:.4},s", result.time_of_flight);
                println!(
                    "impact_velocity,{:.2},{}",
                    UnitConverter::velocity_from_metric(result.impact_velocity, units),
                    vel_unit
                );
                println!(
                    "impact_energy,{:.2},{}",
                    UnitConverter::energy_from_metric(result.impact_energy, units),
                    energy_unit
                );
                if stability > 0.0 {
                    println!("stability_coefficient,{:.2},", stability);
                }
                if spin_drift.abs() > 0.0001 {
                    println!(
                        "spin_drift,{:.4},{}",
                        UnitConverter::distance_from_metric(spin_drift, units),
                        dist_unit
                    );
                }
                if let Some(zero_deg) = solved_zero_angle_deg {
                    println!("zero_angle_degrees,{:.4},degrees", zero_deg);
                }
            }
        }

        OutputFormat::Table => {
            // Convert outputs to user's units
            let range_display = UnitConverter::distance_from_metric(result.max_range, units);
            let height_display = UnitConverter::distance_from_metric(result.max_height, units);
            let velocity_display =
                UnitConverter::velocity_from_metric(result.impact_velocity, units);
            let energy_display = UnitConverter::energy_from_metric(result.impact_energy, units);

            let (range_unit, velocity_unit, energy_unit) = match units {
                UnitSystem::Metric => ("m", "m/s", "J"),
                UnitSystem::Imperial => ("yd", "fps", "ft-lb"),
            };

            println!("╔════════════════════════════════════════╗");
            println!("║         TRAJECTORY RESULTS             ║");
            println!("╠════════════════════════════════════════╣");
            println!(
                "║ Max Range:         {:>8.2} {:3}       ║",
                range_display, range_unit
            );
            println!(
                "║ Max Height:        {:>8.2} {:3}       ║",
                height_display, range_unit
            );
            if let Some(zero_deg) = solved_zero_angle_deg {
                println!("║ Zero Angle:        {:>8.4}°          ║", zero_deg);
            }
            if reached_time_cap {
                // Integration stopped at the time cap, not at an impact: the
                // "impact" velocity/energy/ToF are the capped state, not a real
                // terminal-ballistics result, so don't label them as impact.
                println!(
                    "║ Final Velocity:    {:>8.2} {:3}       ║",
                    velocity_display, velocity_unit
                );
                println!(
                    "║ Time at Cap:       {:>8.3} s          ║",
                    result.time_of_flight
                );
                println!("║ Impact:            No impact (cap)     ║");
            } else {
                println!(
                    "║ Time of Flight:    {:>8.3} s          ║",
                    result.time_of_flight
                );
                println!(
                    "║ Impact Velocity:   {:>8.2} {:3}       ║",
                    velocity_display, velocity_unit
                );
                println!(
                    "║ Impact Energy:     {:>8.2} {:5}     ║",
                    energy_display, energy_unit
                );
            }
            if stability > 0.0 {
                println!("╠════════════════════════════════════════╣");
                println!("║ Stability (SG):    {:>8.2}            ║", stability);
                if twist_assumed {
                    // MBA-1135: the twist was synthesized (shooter omitted --twist-rate), so this
                    // Sg is essentially the design target of the assumed twist. Do NOT present a
                    // hard STABLE/UNSTABLE verdict; a note after the box explains the assumption.
                    println!("║ Status:            {:>8}            ║", "assumed");
                } else {
                    let stability_status = if stability < 1.0 {
                        "UNSTABLE"
                    } else if stability < 1.5 {
                        "MARGINAL"
                    } else {
                        "STABLE  "
                    };
                    println!("║ Status:            {:>8}            ║", stability_status);
                }
            }
            if spin_drift.abs() > 0.0001 {
                let drift_display = UnitConverter::distance_from_metric(spin_drift.abs(), units);
                let direction = if spin_drift > 0.0 { "Right" } else { "Left" };
                println!("╠════════════════════════════════════════╣");
                println!(
                    "║ Spin Drift:        {:>8.2} {:3}       ║",
                    drift_display, range_unit
                );
                println!("║ Direction:         {:>8}            ║", direction);
            }

            // Display pitch damping analysis if available
            if let Some(min_damping) = result.min_pitch_damping {
                println!("╠════════════════════════════════════════╣");
                println!("║ Min Pitch Damping: {:>8.3}            ║", min_damping);
                let stability_warning = if min_damping > 0.0 {
                    "UNSTABLE" // Positive damping in transonic can cause instability
                } else if min_damping > -2.0 {
                    "MARGINAL"
                } else {
                    "STABLE  "
                };
                println!("║ Transonic Status:  {:>8}            ║", stability_warning);
                if let Some(mach) = result.transonic_mach {
                    println!("║ Entered at Mach:   {:>8.2}            ║", mach);
                }
            }

            // Display angular motion analysis if available
            if let Some(ref angular_state) = result.angular_state {
                println!("╠════════════════════════════════════════╣");
                println!("║       Angular Motion Analysis          ║");
                println!("╠════════════════════════════════════════╣");
                println!(
                    "║ Final Pitch Angle: {:>8.4} rad        ║",
                    angular_state.pitch_angle
                );
                println!(
                    "║ Final Yaw Angle:   {:>8.4} rad        ║",
                    angular_state.yaw_angle
                );
                if let Some(max_yaw) = result.max_yaw_angle {
                    println!("║ Max Yaw Angle:     {:>8.4} rad        ║", max_yaw);
                    println!(
                        "║                   ({:>8.2}°)          ║",
                        max_yaw.to_degrees()
                    );
                }
                if let Some(max_prec) = result.max_precession_angle {
                    println!("║ Max Precession:    {:>8.4} rad        ║", max_prec);
                }
                println!(
                    "║ Nutation Phase:    {:>8.2} rad        ║",
                    angular_state.nutation_phase
                );
            }

            println!("╚════════════════════════════════════════╝");

            // MBA-1135: be explicit when the twist was synthesized rather than supplied. The Sg
            // (and any spin-drift) above are estimates computed from an assumed twist, not values
            // derived from a real barrel; do not read the Sg as an evaluated stability verdict.
            if twist_assumed && stability > 0.0 {
                let twist_note = match units {
                    UnitSystem::Imperial => format!("1:{:.1}\"", effective_twist_rate),
                    UnitSystem::Metric => format!("1:{:.1}mm", effective_twist_rate * 25.4),
                };
                println!(
                    "note: twist rate not supplied; assumed {} for the stability/spin-drift \
                     estimate — Sg shown is not an evaluated stability verdict.",
                    twist_note
                );
            }

            // MBA-1357: table-output-only note that a saved profile's DSF table was applied
            // (the drop above is already corrected). JSON/CSV get no equivalent text or
            // top-level field — see apply_dsf's call above, which already ran for every
            // output format; this is purely a display note for the human-facing table.
            if let Some(table) = dsf_table.as_ref() {
                println!("DSF table active ({})", dsf_table_summary(table.points()));
            }

            // Report termination. A run that ran out the integration time cap
            // (MBA-969) is NOT a ground impact even though its capped y is far
            // below zero, so flag it explicitly instead of claiming an impact.
            if reached_time_cap {
                println!();
                println!(
                    "No impact: integration reached the {:.0} s time cap (use a shorter --max-range \
                     or remove --ignore-ground-impact).",
                    INTEGRATION_TIME_CAP_S
                );
            } else if let Some(last_point) = result.points.last() {
                let last_height = last_point.position.y;
                let last_range = last_point.position.x;

                // Ground threshold is typically around 0, so if y is close to or below 0, it hit ground
                if last_height <= 0.001 {
                    println!();
                    let range_display = UnitConverter::distance_from_metric(last_range, units);
                    println!(
                        "Bullet struck ground at {:.0} {}",
                        range_display, range_unit
                    );
                }
            }

            // MBA-1395: equivalent horizontal range (BDC shoot-to) for inclined shots —
            // the flat range whose angular correction, against the SAME zero, matches
            // the inclined solution's. Printed only when a look angle is set AND a zero
            // was solved (a BDC shoot-to is meaningless without a zero); inside the zero
            // range or with a negative correction the inverse is ill-defined and the
            // line is deliberately omitted. Flat shots emit nothing — byte-identical.
            if shooting_angle != 0.0 {
                if let Some(zero_m) = zero_solve_distance_m {
                    if let Some(ehr_m) =
                        solver.equivalent_horizontal_range(result.max_range, zero_m)
                    {
                        let ehr_display = UnitConverter::distance_from_metric(ehr_m, units);
                        println!();
                        println!(
                            "Equivalent horizontal range: {:.0} {} (shoot-to for BDC)",
                            ehr_display, range_unit
                        );
                    }
                }
            }

            if full && !result.points.is_empty() {
                println!();
                println!("Trajectory Points:");
                let (dist_hdr, vel_hdr, energy_hdr) = match units {
                    UnitSystem::Metric => ("(m)", "(m/s)", "(J)"),
                    UnitSystem::Imperial => ("(yd)", "(fps)", "(ft-lb)"),
                };

                let step = if result.points.len() > 20 {
                    result.points.len() / 20
                } else {
                    1
                };

                // Mover ring (MBA-1325) is a whole extra column, so the table is rendered
                // as two distinct layouts rather than splicing a conditional cell into a
                // fixed format string — this keeps the ring_enabled == false path (the
                // default) byte-identical to the pre-MBA-1325 table.
                if ring_enabled {
                    println!("┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐");
                    println!(
                        "│ Time (s) │  X {:5} │  Y {:5} │ Vel{:5} │Energy{:5}│ {}│",
                        dist_hdr, dist_hdr, vel_hdr, energy_hdr, ring_hdr
                    );
                    println!("├──────────┼──────────┼──────────┼──────────┼──────────┼──────────┤");

                    for (i, p) in result.points.iter().enumerate() {
                        if i % step == 0 || i == result.points.len() - 1 {
                            let x_display =
                                UnitConverter::distance_from_metric(p.position.x, units); // X column = downrange (position.x; McCoy frame)
                            let y_display =
                                UnitConverter::distance_from_metric(p.position.y, units);
                            let vel_display =
                                UnitConverter::velocity_from_metric(p.velocity_magnitude, units);
                            let energy_display =
                                UnitConverter::energy_from_metric(p.kinetic_energy, units);
                            let (_, ring_mil) = ballistics_engine::mover_ring(
                                target_speed_mps,
                                p.time,
                                p.position.x,
                            );
                            // MBA-1358: dialed quantity — divide the mil angle by the
                            // windage CF BEFORE unit/click conversion (/1.0 is exact).
                            let ring_cell = match ring_mil.map(|mil| mil / windage_cf) {
                                Some(mil) => match ring_unit {
                                    RingUnit::Factor(f) => format!("{:>8.2}", mil * f),
                                    // clicks_for(drop_yd, range_yd, click) only needs the
                                    // drop_yd/range_yd RATIO — passing (mil, 1000.0) reuses
                                    // it directly on an already-computed mil angle (ring_mil
                                    // is `ring_m / downrange_m * 1000`), same trick as
                                    // smoa_per_mil()'s factor-ratio reuse just above.
                                    RingUnit::Clicks(click) => {
                                        format!("{:>8}", clicks_for(mil, 1000.0, &click))
                                    }
                                },
                                None => format!("{:>8}", "-"),
                            };

                            println!(
                                "│ {:>8.3} │ {:>8.2} │ {:>8.2} │ {:>8.2} │ {:>8.2} │ {} │",
                                p.time,
                                x_display,
                                y_display,
                                vel_display,
                                energy_display,
                                ring_cell
                            );
                        }
                    }
                    println!("└──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘");
                } else {
                    println!("┌──────────┬──────────┬──────────┬──────────┬──────────┐");
                    println!(
                        "│ Time (s) │  X {:5} │  Y {:5} │ Vel{:5} │Energy{:5}│",
                        dist_hdr, dist_hdr, vel_hdr, energy_hdr
                    );
                    println!("├──────────┼──────────┼──────────┼──────────┼──────────┤");

                    for (i, p) in result.points.iter().enumerate() {
                        if i % step == 0 || i == result.points.len() - 1 {
                            let x_display =
                                UnitConverter::distance_from_metric(p.position.x, units); // X column = downrange (position.x; McCoy frame)
                            let y_display =
                                UnitConverter::distance_from_metric(p.position.y, units);
                            let vel_display =
                                UnitConverter::velocity_from_metric(p.velocity_magnitude, units);
                            let energy_display =
                                UnitConverter::energy_from_metric(p.kinetic_energy, units);

                            println!(
                                "│ {:>8.3} │ {:>8.2} │ {:>8.2} │ {:>8.2} │ {:>8.2} │",
                                p.time, x_display, y_display, vel_display, energy_display
                            );
                        }
                    }
                    println!("└──────────┴──────────┴──────────┴──────────┴──────────┘");
                }
            }

            // Display sampled trajectory points if available
            if let Some(ref samples) = result.sampled_points {
                if !samples.is_empty() {
                    println!();
                    println!(
                        "Sampled Trajectory (every {:.0} {})",
                        UnitConverter::distance_from_metric(sample_interval, units),
                        match units {
                            UnitSystem::Metric => "m",
                            UnitSystem::Imperial => "yd",
                        }
                    );

                    let (dist_hdr, drop_hdr, drift_hdr, vel_hdr) = match units {
                        UnitSystem::Metric => ("(m)", "(m)", "(m)", "(m/s)"),
                        UnitSystem::Imperial => ("(yd)", "(in)", "(in)", "(fps)"),
                    };

                    // MBA-1403: label the drop column with the active drops reference.
                    // The target-plane variant needs a wider column for its label; the
                    // LOS branch prints the historical header byte-identically.
                    let target_drops = drops_reference == DropsReferenceArg::Target;
                    if target_drops {
                        println!(
                            "┌──────────┬───────────────────┬──────────┬──────────┬──────────┐"
                        );
                        println!(
                            "│ Dist{:4} │ {:>17} │Drift{:4} │ Vel{:5} │  Flags   │",
                            dist_hdr,
                            format!("Drop (target){}", drop_hdr),
                            drift_hdr,
                            vel_hdr
                        );
                        println!(
                            "├──────────┼───────────────────┼──────────┼──────────┼──────────┤"
                        );
                    } else {
                        println!("┌──────────┬──────────┬──────────┬──────────┬──────────┐");
                        println!(
                            "│ Dist{:4} │ Drop{:4} │Drift{:4} │ Vel{:5} │  Flags   │",
                            dist_hdr, drop_hdr, drift_hdr, vel_hdr
                        );
                        println!("├──────────┼──────────┼──────────┼──────────┼──────────┤");
                    }

                    for sample in samples.iter() {
                        let dist_display =
                            UnitConverter::distance_from_metric(sample.distance_m, units);
                        let drop_display = if units == UnitSystem::Imperial {
                            sample.drop_m * 39.3701 // Convert to inches for imperial
                        } else {
                            sample.drop_m
                        };
                        let drift_display = if units == UnitSystem::Imperial {
                            sample.wind_drift_m * 39.3701 // Convert to inches for imperial
                        } else {
                            sample.wind_drift_m
                        };
                        let vel_display =
                            UnitConverter::velocity_from_metric(sample.velocity_mps, units);

                        let flags_str = sample
                            .flags
                            .iter()
                            .map(|f| match f {
                                trajectory_sampling::TrajectoryFlag::ZeroCrossing => "Zero",
                                trajectory_sampling::TrajectoryFlag::MachTransition => "Mach",
                                trajectory_sampling::TrajectoryFlag::Apex => "Apex",
                            })
                            .collect::<Vec<_>>()
                            .join(",");

                        if target_drops {
                            println!(
                                "│ {:>8.1} │ {:>17.2} │ {:>8.2} │ {:>8.1} │ {:8} │",
                                dist_display,
                                drop_display,
                                drift_display,
                                vel_display,
                                if flags_str.is_empty() {
                                    "-"
                                } else {
                                    &flags_str
                                }
                            );
                        } else {
                            println!(
                                "│ {:>8.1} │ {:>8.2} │ {:>8.2} │ {:>8.1} │ {:8} │",
                                dist_display,
                                drop_display,
                                drift_display,
                                vel_display,
                                if flags_str.is_empty() {
                                    "-"
                                } else {
                                    &flags_str
                                }
                            );
                        }
                    }

                    if target_drops {
                        println!(
                            "└──────────┴───────────────────┴──────────┴──────────┴──────────┘"
                        );
                    } else {
                        println!("└──────────┴──────────┴──────────┴──────────┴──────────┘");
                    }
                }
            }

            // Inline terminal charts (MBA-1320): four stacked charts -- drop, lateral drift,
            // velocity and energy, each vs. range -- from the SAME per-point data the "Trajectory
            // Points:" table above prints — result.points, McCoy frame (x=downrange,
            // y=vertical, z=lateral) — converted through the same UnitConverter calls and
            // the same range_unit as that table's X/Y columns. This intentionally reuses
            // the raw, non-LOS-adjusted vertical/lateral values (the table's "Y" column),
            // NOT the sight-line-relative "drop"/"wind_drift" computed by
            // --sample-trajectory (TrajectorySample::drop_m/wind_drift_m, which needs
            // sight-height/target-height geometry this code path doesn't have and displays
            // in inches/mm rather than the range unit) — the two are different, deliberate
            // vertical conventions; don't conflate them.
            //
            // Independent of --full: result.points already holds every raw integration
            // point regardless of whether the table above printed them, so --plot works
            // standalone without needing --full too.
            if let Some(plot_style) = plot {
                if !result.points.is_empty() {
                    let drop_label = format!("drop ({})", range_unit);
                    let drop_points: Vec<(f64, f64)> = result
                        .points
                        .iter()
                        .map(|p| {
                            (
                                UnitConverter::distance_from_metric(p.position.x, units),
                                UnitConverter::distance_from_metric(p.position.y, units),
                            )
                        })
                        .collect();
                    println!();
                    println!("Drop vs Range:");
                    println!(
                        "{}",
                        terminal_plot::render_chart(
                            &[(drop_label.as_str(), drop_points.as_slice())],
                            72,
                            12,
                            plot_style.as_canvas_style(),
                        )
                    );

                    let drift_label = format!("drift ({})", range_unit);
                    let drift_points: Vec<(f64, f64)> = result
                        .points
                        .iter()
                        .map(|p| {
                            (
                                UnitConverter::distance_from_metric(p.position.x, units),
                                UnitConverter::distance_from_metric(p.position.z, units),
                            )
                        })
                        .collect();
                    println!();
                    println!("Lateral Drift vs Range:");
                    println!(
                        "{}",
                        terminal_plot::render_chart(
                            &[(drift_label.as_str(), drift_points.as_slice())],
                            72,
                            12,
                            plot_style.as_canvas_style(),
                        )
                    );

                    // Velocity and energy panels (MBA-1394): same treatment as
                    // drop/drift above, reusing result.points' raw per-step
                    // velocity_magnitude/kinetic_energy (McCoy SI values) converted
                    // through the same UnitConverter calls and unit labels
                    // (velocity_unit/energy_unit) as the summary box above and the
                    // --full CSV/JSON trajectory columns, so labels always match
                    // --units.
                    let velocity_label = format!("velocity ({})", velocity_unit);
                    let velocity_points: Vec<(f64, f64)> = result
                        .points
                        .iter()
                        .map(|p| {
                            (
                                UnitConverter::distance_from_metric(p.position.x, units),
                                UnitConverter::velocity_from_metric(p.velocity_magnitude, units),
                            )
                        })
                        .collect();
                    println!();
                    println!("Velocity vs Range:");
                    println!(
                        "{}",
                        terminal_plot::render_chart(
                            &[(velocity_label.as_str(), velocity_points.as_slice())],
                            72,
                            12,
                            plot_style.as_canvas_style(),
                        )
                    );

                    let energy_label = format!("energy ({})", energy_unit);
                    let energy_points: Vec<(f64, f64)> = result
                        .points
                        .iter()
                        .map(|p| {
                            (
                                UnitConverter::distance_from_metric(p.position.x, units),
                                UnitConverter::energy_from_metric(p.kinetic_energy, units),
                            )
                        })
                        .collect();
                    println!();
                    println!("Energy vs Range:");
                    println!(
                        "{}",
                        terminal_plot::render_chart(
                            &[(energy_label.as_str(), energy_points.as_slice())],
                            72,
                            12,
                            plot_style.as_canvas_style(),
                        )
                    );
                }
            }
        }

        #[cfg(feature = "pdf")]
        OutputFormat::Pdf => {
            // PDF output requires metadata and output file
            let pdf_meta = pdf_metadata.as_ref().ok_or(
                "PDF output requires metadata (use --target-speed, --powder, --bullet-name, etc.)",
            )?;
            let output_path = pdf_meta
                .output_file
                .as_ref()
                .ok_or("PDF output requires --output-file")?;

            // Get sampled trajectory points (required for dope card)
            let sampled = result
                .sampled_points
                .as_ref()
                .ok_or("PDF output requires --sample-trajectory flag for trajectory data")?;

            // Calculate density altitude
            let da_ft = calculate_density_altitude(
                pdf_meta.altitude_ft,
                pdf_meta.pressure_inhg,
                pdf_meta.temperature_f,
            );

            // Build PDF config
            let pdf_config = DopeCardConfig {
                rifle_name: pdf_meta.rifle_name.clone(),
                location: pdf_meta.location_name.clone(),
                density_altitude_ft: da_ft,
                pressure_inhg: pdf_meta.pressure_inhg,
                pressure_hpa: pdf_meta.pressure_inhg * 33.8639,
                temperature_f: pdf_meta.temperature_f,
                altitude_ft: pdf_meta.altitude_ft,
                wind_speed_mph: pdf_meta.wind_speed_mph,
                target_speed_mph: pdf_meta.target_speed_mph,
                solver_mode: if cfg!(feature = "online") {
                    "online".to_string()
                } else {
                    "offline".to_string()
                },
                powder: pdf_meta.powder.clone(),
                bullet: pdf_meta.bullet_name.clone(),
                weight_gr: pdf_meta.weight_gr,
                bc,
                drag_model: drag_model.to_string(),
                velocity_fps: pdf_meta.velocity_fps,
                font_scale: pdf_meta.font_scale,
                bold_data: pdf_meta.bold_data,
                // MBA-1410: independent per-axis labels — Drop renders in the elevation
                // unit, Wind/Lead in the (possibly different) windage unit.
                elevation_unit_label: adjustment_unit_label(pdf_meta.adjustment_unit),
                windage_unit_label: adjustment_unit_label(pdf_meta.windage_unit),
                // Provenance in the footer: which build printed these numbers. No
                // correction-table version is knowable here, so none is claimed.
                engine_version: env!("CARGO_PKG_VERSION").to_string(),
                table_version: String::new(),
                // `trajectory -o pdf` prints the sampled points the solve produced, from the
                // zero range out to wherever the flight ended — there is no requested last
                // row for it to fall short of, so there is nothing to declare.
                truncation_note: String::new(),
            };

            // Convert sampled trajectory to dope card rows
            // Filter from zero range onwards (typically 100 yards)
            let rows: Vec<CardRow> = sampled
                .iter()
                .filter(|s| {
                    s.distance_m >= UnitConverter::distance_to_metric(100.0, UnitSystem::Imperial)
                })
                .map(|s| {
                    dope_card_row_from_sample(
                        s,
                        pdf_meta,
                        elevation_click,
                        windage_click,
                        zero_set_elevation_bias_mil,
                        zero_set_windage_bias_mil,
                        elevation_cf,
                        windage_cf,
                    )
                })
                .collect();

            if rows.is_empty() {
                return Err("No trajectory data available for PDF output. Ensure --sample-trajectory is enabled and range > 100 yards.".into());
            }

            // Generate PDF. Dope-card ranges are always yards (see the range_yd
            // conversion above), regardless of --units.
            let pdf_bytes = ballistics_engine::pdf_dope_card::generate_dope_card_pdf(
                &pdf_config,
                &rows,
                RangeUnit::Yards,
            )?;

            // Write to file
            std::fs::write(output_path, &pdf_bytes)?;
            eprintln!("PDF dope card written to: {}", output_path.display());
            eprintln!(
                "  {} ranges from {} to {} yards",
                rows.len(),
                rows.first().map(|r| r.range.round() as i64).unwrap_or(0),
                rows.last().map(|r| r.range.round() as i64).unwrap_or(0)
            );
        }
        #[cfg(not(feature = "pdf"))]
        OutputFormat::Pdf => {
            return Err("PDF output requires building with the 'pdf' feature (e.g. cargo build --features pdf)".into());
        }
    }

    Ok(())
}

/// Display trajectory results from API response
#[cfg(feature = "online")]
fn display_api_trajectory_result(
    response: &ballistics_engine::api_client::TrajectoryResponse,
    output: OutputFormat,
    units: UnitSystem,
    full: bool,
) -> Result<(), Box<dyn std::error::Error>> {
    match output {
        OutputFormat::Json => {
            // Re-serialize the response as JSON
            let result = serde_json::json!({
                "source": "api",
                "zero_angle_degrees": response.zero_angle.to_degrees(),
                "time_of_flight": response.time_of_flight,
                "bc_confidence": response.bc_confidence,
                "ml_corrections_applied": response.ml_corrections_applied,
                "max_ordinate": response.max_ordinate,
                "impact_velocity": response.impact_velocity,
                "impact_energy": response.impact_energy,
                "trajectory": if full {
                    response.trajectory.iter().map(|p| {
                        serde_json::json!({
                            "range": p.range,
                            "drop": p.drop,
                            "drift": p.drift,
                            "velocity": p.velocity,
                            "energy": p.energy,
                            "time": p.time
                        })
                    }).collect::<Vec<_>>()
                } else {
                    vec![]
                }
            });
            println!("{}", serde_json::to_string_pretty(&result)?);
        }

        OutputFormat::Csv => {
            let (dist_unit, vel_unit, energy_unit) = match units {
                UnitSystem::Metric => ("m", "m/s", "J"),
                UnitSystem::Imperial => ("yd", "fps", "ft-lb"),
            };

            if full {
                println!(
                    "range_{},drop_{},drift_{},velocity_{},energy_{},time_s",
                    dist_unit, dist_unit, dist_unit, vel_unit, energy_unit
                );
                for p in &response.trajectory {
                    let range = UnitConverter::distance_from_metric(p.range, units);
                    let drop = if units == UnitSystem::Imperial {
                        p.drop * 39.3701 // meters to inches
                    } else {
                        p.drop
                    };
                    let drift = if units == UnitSystem::Imperial {
                        p.drift * 39.3701
                    } else {
                        p.drift
                    };
                    let vel = UnitConverter::velocity_from_metric(p.velocity, units);
                    let energy = UnitConverter::energy_from_metric(p.energy, units);
                    println!(
                        "{:.2},{:.2},{:.2},{:.2},{:.2},{:.4}",
                        range, drop, drift, vel, energy, p.time
                    );
                }
            } else {
                println!("metric,value,unit");
                println!("source,api,");
                println!("time_of_flight,{:.4},s", response.time_of_flight);
                println!("zero_angle,{:.4},degrees", response.zero_angle.to_degrees());
                if let Some(confidence) = response.bc_confidence {
                    println!("bc_confidence,{:.2},%", confidence * 100.0);
                }
                if let Some(ref corrections) = response.ml_corrections_applied {
                    println!("ml_corrections,{},", corrections.join(";"));
                }
            }
        }

        OutputFormat::Table => {
            let (range_unit, vel_unit, energy_unit) = match units {
                UnitSystem::Metric => ("m", "m/s", "J"),
                UnitSystem::Imperial => ("yd", "fps", "ft-lb"),
            };

            println!("╔════════════════════════════════════════╗");
            println!("║    TRAJECTORY RESULTS (API/ML)         ║");
            println!("╠════════════════════════════════════════╣");

            // Display ML corrections if available
            if let Some(ref corrections) = response.ml_corrections_applied {
                if !corrections.is_empty() {
                    println!("║ ML Corrections Applied:                ║");
                    for correction in corrections.iter().take(3) {
                        let truncated: String = correction.chars().take(32).collect();
                        println!("║   • {:32} ║", truncated);
                    }
                    println!("╠════════════════════════════════════════╣");
                }
            }

            // Display BC confidence if available
            if let Some(confidence) = response.bc_confidence {
                println!(
                    "║ BC Confidence:     {:>8.1}%           ║",
                    confidence * 100.0
                );
                println!("╠════════════════════════════════════════╣");
            }

            println!(
                "║ Time of Flight:    {:>8.3} s          ║",
                response.time_of_flight
            );
            println!(
                "║ Zero Angle:        {:>8.4}°          ║",
                response.zero_angle.to_degrees()
            );

            if let Some(max_ord) = response.max_ordinate {
                let max_ord_display = UnitConverter::distance_from_metric(max_ord, units);
                println!(
                    "║ Max Ordinate:      {:>8.2} {:3}       ║",
                    max_ord_display, range_unit
                );
            }

            if let Some(impact_vel) = response.impact_velocity {
                let vel_display = UnitConverter::velocity_from_metric(impact_vel, units);
                println!(
                    "║ Impact Velocity:   {:>8.2} {:3}       ║",
                    vel_display, vel_unit
                );
            }

            if let Some(impact_e) = response.impact_energy {
                let energy_display = UnitConverter::energy_from_metric(impact_e, units);
                println!(
                    "║ Impact Energy:     {:>8.2} {:5}     ║",
                    energy_display, energy_unit
                );
            }

            println!("╚════════════════════════════════════════╝");

            // Display trajectory points if full mode
            if full && !response.trajectory.is_empty() {
                println!();
                println!("Trajectory Points (from API):");

                let (dist_hdr, drop_hdr, drift_hdr, vel_hdr) = match units {
                    UnitSystem::Metric => ("(m)", "(m)", "(m)", "(m/s)"),
                    UnitSystem::Imperial => ("(yd)", "(in)", "(in)", "(fps)"),
                };

                println!("┌──────────┬──────────┬──────────┬──────────┬──────────┐");
                println!(
                    "│Range{:4} │ Drop{:4} │Drift{:4} │ Vel{:5} │ Time (s) │",
                    dist_hdr, drop_hdr, drift_hdr, vel_hdr
                );
                println!("├──────────┼──────────┼──────────┼──────────┼──────────┤");

                let step = if response.trajectory.len() > 20 {
                    response.trajectory.len() / 20
                } else {
                    1
                };

                for (i, p) in response.trajectory.iter().enumerate() {
                    if i % step == 0 || i == response.trajectory.len() - 1 {
                        let range_display = UnitConverter::distance_from_metric(p.range, units);
                        let drop_display = if units == UnitSystem::Imperial {
                            p.drop * 39.3701
                        } else {
                            p.drop
                        };
                        let drift_display = if units == UnitSystem::Imperial {
                            p.drift * 39.3701
                        } else {
                            p.drift
                        };
                        let vel_display = UnitConverter::velocity_from_metric(p.velocity, units);

                        println!(
                            "│ {:>8.1} │ {:>8.2} │ {:>8.2} │ {:>8.1} │ {:>8.4} │",
                            range_display, drop_display, drift_display, vel_display, p.time
                        );
                    }
                }
                println!("└──────────┴──────────┴──────────┴──────────┴──────────┘");
            }
        }

        OutputFormat::Pdf => {
            eprintln!("Error: PDF output is not supported for API trajectory results.");
            eprintln!(
                "Hint: Use local calculation (without --online) for PDF dope card generation."
            );
        }
    }

    Ok(())
}

// ============================================================================
// WEZ (Weapon Employment Zone) sweep mode -- MBA-1317
//
// The compute path (target-size parsing, the seeded sweep, and variance attribution) lives in
// ballistics_engine::wez (MBA-1343 Phase B) so non-CLI front ends (e.g. the WASM terminal) can
// reuse it; only the three renderers (summary table / statistics CSV / full JSON) remain here.
// ============================================================================

/// Dominant-bucket label shared by the summary-table and statistics-CSV renderers.
fn wez_dominant_label(row: &WezRow) -> String {
    if row.attribution_unavailable {
        "n/a".to_string()
    } else {
        row.dominant_error_source
            .map(|b| b.to_string())
            .unwrap_or_else(|| "none".to_string())
    }
}

/// `-o full`: the entire [`WezResult`] as pretty JSON (the 0.25.0 JSON contract).
fn print_wez_full(result: &WezResult) -> Result<(), Box<dyn Error>> {
    println!("{}", serde_json::to_string_pretty(result)?);
    Ok(())
}

/// `-o statistics`: one CSV row per range step.
fn print_wez_statistics(result: &WezResult, units: UnitSystem) {
    println!("range,p_hit,dominant_error_source,wind_call_share,mv_sd_share,other_share");
    for row in &result.rows {
        println!(
            "{:.2},{:.4},{},{:.4},{:.4},{:.4}",
            UnitConverter::distance_from_metric(row.range_m, units),
            row.p_hit,
            wez_dominant_label(row),
            row.wind_call_share,
            row.mv_sd_share,
            row.other_share
        );
    }
}

/// Default `-o summary`: the human-readable sweep table.
fn print_wez_summary(result: &WezResult, units: UnitSystem) {
    let dist_unit = match units {
        UnitSystem::Imperial => "yd",
        UnitSystem::Metric => "m",
    };
    let wind_unit = match units {
        UnitSystem::Imperial => "mph",
        UnitSystem::Metric => "m/s",
    };
    println!(
        "WEZ sweep: {} sims/step, wind call {:.2} {wind_unit} + wind std {:.2} {wind_unit} (quadrature) = {:.2} {wind_unit} effective",
        result.num_sims_per_step,
        UnitConverter::wind_from_metric(result.wind_call_error_mps, units),
        UnitConverter::wind_from_metric(result.wind_speed_std_mps, units),
        UnitConverter::wind_from_metric(result.combined_wind_speed_std_mps, units),
    );
    println!("┌────────────┬──────────┬───────────────┬───────────┬───────────┬───────────┐");
    println!(
        "│ Range ({dist_unit:>3}) │  P(hit)  │ Dominant      │ Wind call │  MV SD    │ Other/grp │"
    );
    println!("├────────────┼──────────┼───────────────┼───────────┼───────────┼───────────┤");
    for row in &result.rows {
        println!(
            "│ {:>10.1} │ {:>7.1}% │ {:<13} │ {:>8.1}% │ {:>8.1}% │ {:>8.1}% │",
            UnitConverter::distance_from_metric(row.range_m, units),
            row.p_hit * 100.0,
            wez_dominant_label(row),
            row.wind_call_share * 100.0,
            row.mv_sd_share * 100.0,
            row.other_share * 100.0,
        );
    }
    println!("└────────────┴──────────┴───────────────┴───────────┴───────────┴───────────┘");
}

#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable Monte Carlo CLI command shape (MBA-1317)"
)]
fn run_monte_carlo_wez(
    velocity: f64,
    angle: f64,
    bc: f64,
    mass: f64,
    diameter: f64,
    num_sims: usize,
    velocity_std: f64,
    angle_std: f64,
    bc_std: f64,
    wind_std: f64,
    wind_direction_std: f64,
    wind_speed: f64,
    wind_direction: f64,
    wind_vertical: f64,
    wind_call_error: f64,
    target_size: TargetSizeMetric,
    wez_start: f64,
    wez_end: f64,
    wez_step: f64,
    custom_drag_table: Option<ballistics_engine::drag::DragTable>,
    cd_scale: f64,
    cant: f64,
    // MBA-1396: lateral sight-mount offset, METERS (positive = sight right of bore).
    sight_offset_lateral_m: f64,
    output: MonteCarloOutput,
    units: UnitSystem,
) -> Result<(), Box<dyn Error>> {
    let result = compute_wez(
        velocity,
        angle,
        bc,
        mass,
        diameter,
        num_sims,
        velocity_std,
        angle_std,
        bc_std,
        wind_std,
        wind_direction_std,
        wind_speed,
        wind_direction,
        wind_vertical,
        wind_call_error,
        target_size,
        wez_start,
        wez_end,
        wez_step,
        // The native `monte-carlo` subcommand has no --drag-model flag, so the sweep
        // always runs the G1 default `BallisticInputs` has always used (the WASM
        // terminal's monte-carlo, which does expose --drag-model, passes it through).
        DragModel::G1,
        custom_drag_table,
        cd_scale,
        cant,
        sight_offset_lateral_m,
    )?;

    match output {
        MonteCarloOutput::Full => print_wez_full(&result)?,
        MonteCarloOutput::Statistics => print_wez_statistics(&result, units),
        MonteCarloOutput::Summary => print_wez_summary(&result, units),
    }

    Ok(())
}

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

    // The compute-path tests (parse_target_size, step function, monotonicity, variance shares)
    // moved to ballistics_engine::wez alongside the code they exercise (MBA-1343 Phase B). This
    // one stays: it pins the CLI wrapper `run_monte_carlo_wez` (compute + print dispatch)
    // end-to-end.

    // ---- Solver-invalid input is a clean error, not a panic (MBA-1317) ---------------------

    /// `-v 0` passes clap's own `0.0..=6000` velocity range check (clap permits the lower bound)
    /// but fails `TrajectorySolver::solve()`'s stricter "> 0" gate. Before the fix,
    /// `wez_solve_target_plane`'s `.expect(...)` on that failure turned this into a panic
    /// (exit 101 with a backtrace) instead of the clean `Err` the base (non-WEZ) `monte-carlo`
    /// command already returns for the identical input. This must return `Err`, never panic.
    #[test]
    fn zero_muzzle_velocity_is_a_clean_error_not_a_panic() {
        let result = run_monte_carlo_wez(
            /* velocity */ 0.0,
            /* angle */ 0.0,
            /* bc */ 0.475,
            /* mass */ 0.010_886,
            /* diameter */ 0.007_82,
            /* num_sims */ 10,
            /* velocity_std */ 0.0,
            /* angle_std */ 0.0,
            /* bc_std */ 0.0,
            /* wind_std */ 0.0,
            /* wind_direction_std */ 0.0,
            /* wind_speed */ 0.0,
            /* wind_direction */ 0.0,
            /* wind_vertical */ 0.0,
            /* wind_call_error */ 0.0,
            TargetSizeMetric::Rect {
                width_m: 0.4572,
                height_m: 0.762,
            },
            /* wez_start */ 200.0,
            /* wez_end */ 300.0,
            /* wez_step */ 100.0,
            /* custom_drag_table */ None,
            /* cd_scale */ 1.0,
            /* cant */ 0.0,
            /* sight_offset_lateral_m */ 0.0,
            MonteCarloOutput::Summary,
            UnitSystem::Metric,
        );
        let err = result.expect_err("a zero muzzle velocity must not solve successfully");
        assert!(
            err.to_string().contains("muzzle_velocity"),
            "expected a muzzle_velocity validation error, got: {err}"
        );
    }
}

#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable Monte Carlo CLI command shape"
)]
fn run_monte_carlo(
    velocity: f64,
    angle: f64,
    bc: f64,
    bc_reference_standard: BcReferenceStandard,
    mass: f64,
    diameter: f64,
    num_sims: usize,
    velocity_std: f64,
    angle_std: f64,
    bc_std: f64,
    wind_std: f64,
    wind_direction_std: f64,
    wind_speed: f64,
    wind_direction: f64,
    wind_vertical: f64,
    target_distance: Option<f64>,
    target_radius: f64,
    custom_drag_table: Option<ballistics_engine::drag::DragTable>,
    cd_scale: f64,
    cant: f64,
    // MBA-1396: lateral sight-mount offset, METERS (positive = sight right of bore).
    // monte-carlo solves no zero, so only the physical initial displacement applies.
    sight_offset_lateral_m: f64,
    // MBA-1352: an explicit --seed makes this run reproducible (branches to the `_seeded`
    // entry point below); `None` preserves the exact prior unseeded call, so a run without
    // --seed is byte-for-byte the same code path as before this flag existed.
    seed: Option<u64>,
    // MBA-1352: confidence level for the additive Wilson companion below. Default (95) is
    // ConfidenceLevel::P95, matching `run_monte_carlo_adaptive_seeded`'s own default level.
    confidence: ConfidenceLevel,
    output: MonteCarloOutput,
) -> Result<(), Box<dyn Error>> {
    // Create base inputs. MBA-967: use the same bore-height/ground convention as the
    // `trajectory` subcommand (standard 1.5 m bore height; this helper works in metric) so each
    // simulation stops at a realistic ground impact instead of flying to the integrator's range
    // cap. Without this, "Mean Range" reports the ~1000 m cap rather than the ground-impact range.
    let bore_height_metric = 1.5_f64;
    // The base inputs are what each Monte Carlo sample perturbs, so the drag table must be set
    // here for the deck to apply to every simulated shot (MBA-1285). MBA-1365:
    // `bc_reference_standard` rides the same base_inputs into every per-sample
    // `TrajectorySolver::new` call inside `run_monte_carlo_with_wind_and_direction_std_dev`,
    // so the ASM->ICAO conversion is inherited by every simulation with no separate code path.
    let base_inputs = BallisticInputs {
        muzzle_velocity: velocity,
        muzzle_angle: angle.to_radians(),
        bc_value: bc,
        bc_reference_standard,
        bullet_mass: mass,
        bullet_diameter: diameter,
        muzzle_height: bore_height_metric,
        ground_threshold: 0.0,
        custom_drag_table,
        cd_scale,
        cant_angle: cant.to_radians(),
        sight_offset_lateral_m,
        ..Default::default()
    };

    // Create base wind conditions
    let base_wind = WindConditions {
        speed: wind_speed,
        direction: wind_direction.to_radians(),
        vertical_speed: wind_vertical,
    };

    // Set up Monte Carlo parameters
    let mc_params = MonteCarloParams {
        num_simulations: num_sims,
        velocity_std_dev: velocity_std,
        angle_std_dev: angle_std.to_radians(),
        bc_std_dev: bc_std,
        wind_speed_std_dev: wind_std,
        target_distance,
        base_wind_speed: wind_speed,
        base_wind_direction: wind_direction.to_radians(),
        azimuth_std_dev: angle_std.to_radians() * 0.5, // Use half of elevation std for horizontal spread
    };

    // Run Monte Carlo simulation. MBA-1352: an explicit --seed routes through the `_seeded`
    // entry point for reproducible output; omitting it is the exact call this file made before
    // --seed existed (same function, same argument order), so the no-seed default path is
    // untouched byte-for-byte.
    let results = match seed {
        Some(seed) => ballistics_engine::run_monte_carlo_with_wind_and_direction_std_dev_seeded(
            base_inputs,
            base_wind,
            mc_params,
            wind_direction_std.to_radians(),
            seed,
        )?,
        None => ballistics_engine::run_monte_carlo_with_wind_and_direction_std_dev(
            base_inputs,
            base_wind,
            mc_params,
            wind_direction_std.to_radians(),
        )?,
    };

    // Calculate statistics
    let mean_range = results.ranges.iter().sum::<f64>() / results.ranges.len() as f64;
    let variance_range: f64 = results
        .ranges
        .iter()
        .map(|r| (r - mean_range).powi(2))
        .sum::<f64>()
        / results.ranges.len() as f64;
    let std_range = variance_range.sqrt();

    let mean_velocity =
        results.impact_velocities.iter().sum::<f64>() / results.impact_velocities.len() as f64;
    let variance_velocity: f64 = results
        .impact_velocities
        .iter()
        .map(|v| (v - mean_velocity).powi(2))
        .sum::<f64>()
        / results.impact_velocities.len() as f64;
    let std_velocity = variance_velocity.sqrt();

    // CEP is conditional on actually reaching the target plane. Samples that fall short stay in
    // all result vectors (and in the hit-probability denominator), but their finite -1e9 marker is
    // not a physical target-plane impact and must not become the median (MBA-1159).
    let cep = results.target_plane_cep();
    let target_shortfall_fraction = results.target_shortfall_fraction();

    // Calculate hit probability if target distance specified
    // MBA-971: hit probability is the fraction of samples landing within the hit radius of the
    // point of aim at the target plane (shared MonteCarloResults::hit_probability), matching the
    // FFI. The old range-precision notion (ground-impact range within 1 m of the target) reported
    // 0% for any target short of the impact range.
    let hit_probability = target_distance.map(|_target| results.hit_probability(target_radius));
    // MBA-1352: additive Wilson companion to the point estimate above -- `Some` under the exact
    // same condition as `hit_probability` (only when --target-distance was given), and its
    // `p_hat` is byte-identical to `hit_probability`'s since `hit_probability_wilson` calls the
    // very same `MonteCarloResults::hit_probability` internally (see cli_api.rs). Existing
    // numeric estimates above are computed and printed exactly as before this addition.
    let hit_probability_ci =
        target_distance.map(|_target| results.hit_probability_wilson(target_radius, confidence));

    match output {
        MonteCarloOutput::Summary => {
            println!("╔════════════════════════════════════════╗");
            println!("║      MONTE CARLO RESULTS               ║");
            println!("║      {} simulations                   ║", num_sims);
            println!("╠════════════════════════════════════════╣");
            println!("║ Mean Range:        {:>8.2} m          ║", mean_range);
            println!("║ Std Dev Range:     {:>8.2} m          ║", std_range);
            println!("║ Mean Impact Vel:   {:>8.2} m/s        ║", mean_velocity);
            println!("║ Std Dev Velocity:  {:>8.2} m/s        ║", std_velocity);
            if let Some(cep) = cep {
                println!("║ CEP (arrivals):    {:>8.2} m          ║", cep);
            } else {
                println!("║ CEP (arrivals):         N/A            ║");
            }
            println!(
                "║ Target Shortfall:  {:>8.1} %          ║",
                target_shortfall_fraction * 100.0
            );
            if let Some(prob) = hit_probability {
                println!("║ Hit Probability:   {:>8.1} %          ║", prob * 100.0);
            }
            println!("╚════════════════════════════════════════╝");
            // MBA-1352: additive line, printed after the box (not padded into its fixed-width
            // frame -- [lo, hi] has no fixed width, unlike every field the box itself prints).
            // Probability units throughout, matching --target-ci-half-width's own units rule.
            if let Some((_, (lo, hi), n)) = hit_probability_ci {
                // 4 decimal places, matching the adaptive block's precision (T5-2 review fix):
                // at 3 dp a small-p, large-n interval can round both bounds to the same
                // "[0.000, 0.000]", understating a real (if tiny) width rather than misstating
                // it -- the interval is still narrower than 0.001 whenever that happens, so the
                // reader's conclusion stays correct, but the extra digit keeps it informative.
                println!(
                    "Hit probability {}% CI: [{lo:.4}, {hi:.4}] (Wilson, n={n})",
                    confidence.as_percent()
                );
            }
        }

        MonteCarloOutput::Full => {
            let mc_result = MonteCarloResult {
                mean_range,
                std_range,
                mean_impact_velocity: mean_velocity,
                std_impact_velocity: std_velocity,
                cep,
                target_shortfall_fraction,
                hit_probability,
                hit_probability_ci: hit_probability_ci.map(|(_, (lo, hi), n)| HitProbabilityCi {
                    method: MC_FIXED_COUNT_CI_METHOD.to_string(),
                    confidence_percent: confidence.as_percent(),
                    low: lo,
                    high: hi,
                    samples: n,
                }),
            };
            println!("{}", serde_json::to_string_pretty(&mc_result)?);
        }

        MonteCarloOutput::Statistics => {
            println!("range_min,range_max,range_mean,range_std,vel_min,vel_max,vel_mean,vel_std");
            let range_min = results.ranges.iter().fold(f64::INFINITY, |a, &b| a.min(b));
            let range_max = results
                .ranges
                .iter()
                .fold(f64::NEG_INFINITY, |a, &b| a.max(b));
            let vel_min = results
                .impact_velocities
                .iter()
                .fold(f64::INFINITY, |a, &b| a.min(b));
            let vel_max = results
                .impact_velocities
                .iter()
                .fold(f64::NEG_INFINITY, |a, &b| a.max(b));

            println!(
                "{:.2},{:.2},{:.2},{:.2},{:.2},{:.2},{:.2},{:.2}",
                range_min,
                range_max,
                mean_range,
                std_range,
                vel_min,
                vel_max,
                mean_velocity,
                std_velocity
            );
        }
    }

    Ok(())
}

/// CLI-resolved `--adaptive` controls (MBA-1352), bundled into one argument so
/// [`run_monte_carlo_adaptive`]'s signature does not grow a further trailing scalar parameter
/// for every knob [`McConvergence`] exposes.
///
/// `confidence`/`min_samples`/`max_samples` stay `Option` all the way to
/// [`run_monte_carlo_adaptive`] (rather than being defaulted at the clap layer) so that
/// function can tell a value the user typed from one it didn't -- needed both to name
/// `--max-samples`/`--min-samples` (not the library's `McConvergence` field names) in the
/// cross-field validation error, and to say which side of it is an untouched default
/// (review I3).
struct AdaptiveMcCliControls {
    confidence: Option<ConfidenceLevel>,
    target_half_width: f64,
    min_samples: Option<u64>,
    max_samples: Option<u64>,
    batch_size: u64,
    seed: Option<u64>,
}

/// [`McConvergence::min_samples`]'s default, mirrored here (rather than a clap
/// `default_value`) so [`run_monte_carlo_adaptive`] can state, in its own words, when an
/// out-of-order `--min-samples`/`--max-samples` pair involves a value the user never typed
/// (review I3).
const DEFAULT_MC_MIN_SAMPLES: u64 = 1_000;
/// [`McConvergence::max_samples`]'s default; see [`DEFAULT_MC_MIN_SAMPLES`].
const DEFAULT_MC_MAX_SAMPLES: u64 = 100_000;

#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror run_monte_carlo's stable CLI command shape; the six \
              --adaptive-only knobs are bundled into AdaptiveMcCliControls rather than adding \
              six more trailing scalars"
)]
fn run_monte_carlo_adaptive(
    velocity: f64,
    angle: f64,
    bc: f64,
    bc_reference_standard: BcReferenceStandard,
    mass: f64,
    diameter: f64,
    velocity_std: f64,
    angle_std: f64,
    bc_std: f64,
    wind_std: f64,
    wind_speed: f64,
    wind_direction: f64,
    wind_vertical: f64,
    target_distance: Option<f64>,
    target_radius: f64,
    custom_drag_table: Option<ballistics_engine::drag::DragTable>,
    cd_scale: f64,
    cant: f64,
    // MBA-1396: lateral sight-mount offset, METERS (positive = sight right of bore).
    sight_offset_lateral_m: f64,
    controls: AdaptiveMcCliControls,
    output: MonteCarloOutput,
) -> Result<(), Box<dyn Error>> {
    // Same bore-height/ground convention as run_monte_carlo (MBA-967): a realistic ground
    // impact instead of the integrator's range cap.
    let bore_height_metric = 1.5_f64;
    let base_inputs = BallisticInputs {
        muzzle_velocity: velocity,
        muzzle_angle: angle.to_radians(),
        bc_value: bc,
        bc_reference_standard,
        bullet_mass: mass,
        bullet_diameter: diameter,
        muzzle_height: bore_height_metric,
        ground_threshold: 0.0,
        custom_drag_table,
        cd_scale,
        cant_angle: cant.to_radians(),
        sight_offset_lateral_m,
        ..Default::default()
    };

    let base_wind = WindConditions {
        speed: wind_speed,
        direction: wind_direction.to_radians(),
        vertical_speed: wind_vertical,
    };

    // `num_simulations: 0` makes "ignored by the adaptive driver" visible in the value itself
    // rather than only in a comment: --min-samples is the floor instead (see
    // `run_monte_carlo_adaptive_seeded`'s own doc comment on the library side). There is no
    // --wind-direction-std field here at all -- MonteCarloParams carries no direction-sigma
    // field, and the adaptive driver always passes 0.0 (matching `run_monte_carlo_with_wind`),
    // so that CLI flag has no effect under --adaptive; this is documented on the flag itself
    // rather than silently threaded through to nowhere.
    let mc_params = MonteCarloParams {
        num_simulations: 0,
        velocity_std_dev: velocity_std,
        angle_std_dev: angle_std.to_radians(),
        bc_std_dev: bc_std,
        wind_speed_std_dev: wind_std,
        target_distance,
        base_wind_speed: wind_speed,
        base_wind_direction: wind_direction.to_radians(),
        azimuth_std_dev: angle_std.to_radians() * 0.5,
    };

    let min_samples = controls.min_samples.unwrap_or(DEFAULT_MC_MIN_SAMPLES);
    let max_samples = controls.max_samples.unwrap_or(DEFAULT_MC_MAX_SAMPLES);

    // MBA-1352 review I3: pre-validated here, at the CLI boundary, so an out-of-order pair is a
    // clap-adjacent usage error naming `--max-samples`/`--min-samples` -- not
    // `McConvergence::validate`'s field-qualified "McConvergence.max_samples ... must be at
    // least McConvergence.min_samples ...", which names a library struct the CLI user has never
    // heard of. `McConvergence::validate` itself is untouched and still gives that message to
    // direct library callers; this short-circuits the CLI from ever reaching it for this one
    // case. Each side of the message also states when its value is an untouched default rather
    // than something the user typed, since `--min-samples 200000` alone quotes
    // `DEFAULT_MC_MAX_SAMPLES` in the comparison without that qualifier being confusing about
    // where the number came from.
    if max_samples < min_samples {
        let describe = |flag: &str, value: Option<u64>, default: u64| match value {
            Some(v) => format!("{flag} ({v})"),
            None => format!("{flag} (default {default})"),
        };
        return Err(format!(
            "{} must be at least {}",
            describe(
                "--max-samples",
                controls.max_samples,
                DEFAULT_MC_MAX_SAMPLES
            ),
            describe(
                "--min-samples",
                controls.min_samples,
                DEFAULT_MC_MIN_SAMPLES
            ),
        )
        .into());
    }

    let convergence = McConvergence {
        level: controls.confidence.unwrap_or(ConfidenceLevel::P95),
        target_half_width: controls.target_half_width,
        min_samples,
        max_samples,
        batch_size: controls.batch_size,
    };

    // No --seed: draw one fresh random seed for this run -- the same "unseeded means
    // nondeterministic run to run" contract the fixed-count path keeps.
    // `run_monte_carlo_adaptive_seeded` has no unseeded entry point of its own to delegate to,
    // since every caller (this one included) must supply *some* concrete seed.
    // `RngExt`, not `Rng`: rand 0.10 moved the `random::<T>()` extension method off `Rng` onto
    // `RngExt` (see `mc_stats.rs`'s own tests for the same divergence).
    use rand::RngExt as _;
    let seed = controls.seed.unwrap_or_else(|| rand::rng().random::<u64>());

    let report = run_monte_carlo_adaptive_seeded(
        &base_inputs,
        &base_wind,
        &mc_params,
        &convergence,
        target_radius,
        seed,
    )
    .map_err(|e| format!("--adaptive: {e}"))?;

    match output {
        MonteCarloOutput::Summary => print_adaptive_mc_summary(&report),
        MonteCarloOutput::Full => println!("{}", serde_json::to_string_pretty(&report)?),
        MonteCarloOutput::Statistics => {
            // The adaptive driver retains no per-trial ranges/velocities (that O(1)-memory
            // property is the whole point, see `AdaptiveMcReportV1`'s own doc comment), so
            // there is nothing to tabulate the way the fixed-count path's CSV rows do. An
            // honest usage error naming the flag beats either silently falling back to another
            // format or fabricating a single-row CSV out of the summary statistics.
            return Err(
                "--output statistics is not supported with --adaptive (the adaptive \
                driver retains no per-trial data to tabulate); use --output summary or \
                --output full/json instead"
                    .into(),
            );
        }
    }

    Ok(())
}

/// The `--adaptive` table-output summary block (MBA-1352): p_hit, its interval, the three
/// sample cardinalities, why the run stopped, the method/level, the hit geometry, and the six
/// Welford statistics -- everything [`AdaptiveMcReportV1`] carries except `schema_version` and
/// the `assumptions` sentences (see `-o json`/`-o full` for those verbatim). `stop_reason` is
/// spelled out with the identical snake_case token the JSON wire form serializes
/// ([`McStopReason`]'s `#[serde(rename_all = "snake_case")]`), so the two output formats read
/// as one report told twice, not two reports that happen to agree.
fn print_adaptive_mc_summary(report: &AdaptiveMcReportV1) {
    let stop_reason = match report.stop_reason {
        McStopReason::TargetHalfWidthMet => "target_half_width_met",
        McStopReason::MaxSamplesReached => "max_samples_reached",
    };
    println!("Adaptive Monte Carlo (confidence-controlled sampling, MBA-1352)");
    println!("  method:            {}", report.method);
    println!("  confidence level:  {}%", report.confidence_percent);
    println!(
        "  hit probability:   {:.4}  ({}% CI: [{:.4}, {:.4}])",
        report.hit_probability, report.confidence_percent, report.ci_low, report.ci_high
    );
    println!(
        "  samples:           {}  (attempts: {}, arrivals: {})",
        report.samples, report.attempts, report.arrivals
    );
    println!("  stop reason:       {stop_reason}");
    println!("  hit radius:        {:.4} m", report.hit_radius_m);
    println!("  target distance:   {:.4} m", report.target_distance_m);
    println!(
        "  impact velocity:   mean {:.3} m/s, std {:.3} m/s",
        report.mean_impact_velocity_mps, report.std_impact_velocity_mps
    );
    println!(
        "  drop at target:    mean {:.4} m, std {:.4} m",
        report.mean_drop_at_target_m, report.std_drop_at_target_m
    );
    println!(
        "  drift at target:   mean {:.4} m, std {:.4} m",
        report.mean_wind_drift_at_target_m, report.std_wind_drift_at_target_m
    );
}

#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable zero-calculation CLI command shape"
)]
fn run_zero_calculation(
    velocity: f64,
    bc: f64,
    bc_reference_standard: BcReferenceStandard,
    mass: f64,
    diameter: f64,
    drag_model: DragModel,
    target_distance: f64,
    target_height: f64,
    sight_height: f64,
    temperature: f64,
    pressure: f64,
    pressure_type: PressureReferenceMode,
    humidity: f64,
    altitude: f64,
    custom_drag_table: Option<ballistics_engine::drag::DragTable>,
    cd_scale: f64,
    // MBA-1358: elevation tracking CF — the MOA/mrad dial-unit outputs (zero angle,
    // sight adjustment) are DIVIDED by it exactly once at their emission points
    // (scope units: an under-tracking scope, CF < 1, needs more dial); the degrees
    // echo is a bore angle and never scales. 1.0 (no CF) is bit-exact.
    elevation_cf: f64,
    output: OutputFormat,
    units: UnitSystem,
) -> Result<(), Box<dyn Error>> {
    // Create ballistic inputs
    let inputs = BallisticInputs {
        muzzle_velocity: velocity,
        bc_value: bc,
        bc_type: drag_model,
        bc_reference_standard,
        bullet_mass: mass,
        bullet_diameter: diameter,
        sight_height,
        temperature,
        pressure,
        humidity,
        altitude,
        custom_drag_table,
        cd_scale,
        ..Default::default()
    };

    // MBA-1397: resolve station temperature/pressure once, honoring pressure_type. Absolute is
    // byte-identical to the legacy default-sentinel resolution TrajectorySolver::new performs
    // internally; Qnh reduces a declared altimeter setting to station pressure. Reused for both
    // the zero-angle solve and the follow-up trajectory solve below, so they agree.
    let (resolved_temperature, resolved_pressure) = resolve_station_conditions_with_pressure_mode(
        temperature,
        pressure,
        altitude,
        pressure_type,
    );

    // Set up atmospheric conditions
    let atmosphere = AtmosphericConditions {
        temperature: resolved_temperature,
        pressure: resolved_pressure,
        humidity,
        altitude,
    };

    // The bullet starts at bore height. A same-elevation zero crosses the horizontal line of
    // sight at y = sight_height; target_height is an offset at the target.
    let los_target_height = sight_height + target_height;

    // Calculate zero angle with atmospheric conditions. Authoritative: `atmosphere` above is
    // already fully resolved, so it is trusted as-is rather than re-derived a second time.
    let zero_angle = ballistics_engine::calculate_zero_angle_with_resolved_conditions(
        inputs.clone(),
        target_distance,
        los_target_height,
        WindConditions::default(),
        atmosphere.clone(),
    )?;

    // Calculate trajectory at zero angle to get additional info
    let mut zeroed_inputs = inputs;
    zeroed_inputs.muzzle_angle = zero_angle;

    let mut solver = TrajectorySolver::new_with_resolved_station_atmosphere(
        zeroed_inputs,
        Default::default(),
        atmosphere,
    );
    solver.set_max_range(target_distance * 3.0);
    let trajectory = solver.solve()?;

    // `zero_angle` is the bore angle above horizontal. The sight line runs from
    // (0, sight_height) to (target_distance, sight_height + target_height), so its slope is
    // target_height / target_distance: the sight-height translation cancels between endpoints.
    // MBA-1358: a dialed correction — scope units (÷CF; /1.0 is exact).
    let sight_adjustment_moa = (zero_angle.to_degrees() * 60.0
        - (target_height / target_distance * 3437.75))
        / elevation_cf;
    // The bullet starts below the sight line by `sight_height`, which can already exceed the
    // 5 cm lower bound at the muzzle. Ignore that initial offset and report only a lower-bound
    // exit after the trajectory has first entered the point-blank band.
    let mut entered_point_blank_band = false;
    let point_blank_range = trajectory
        .points
        .iter()
        .find_map(|p| {
            let los_y = sight_height + target_height * (p.position.x / target_distance);
            let height_from_los = p.position.y - los_y;

            if height_from_los >= -0.05 {
                entered_point_blank_band = true;
                None
            } else if entered_point_blank_band {
                Some(p.position.x)
            } else {
                None
            }
        })
        .unwrap_or(trajectory.max_range);

    match output {
        OutputFormat::Json => {
            let units_label = match units {
                UnitSystem::Metric => "metric",
                UnitSystem::Imperial => "imperial",
            };
            let result = serde_json::json!({
                "units": units_label,
                "zero_angle_degrees": zero_angle.to_degrees(),
                "zero_angle_moa": zero_angle.to_degrees() * 60.0 / elevation_cf,
                "zero_angle_mrad": zero_angle * 1000.0 / elevation_cf,
                "sight_adjustment_moa": sight_adjustment_moa,
                "max_ordinate": UnitConverter::distance_from_metric(trajectory.max_height, units),
                "point_blank_range": UnitConverter::distance_from_metric(point_blank_range, units),
            });
            println!("{}", serde_json::to_string_pretty(&result)?);
        }

        OutputFormat::Csv => {
            println!("metric,value,unit");
            println!("zero_angle,{:.4},degrees", zero_angle.to_degrees());
            println!(
                "zero_angle_moa,{:.2},MOA",
                zero_angle.to_degrees() * 60.0 / elevation_cf
            );
            println!(
                "zero_angle_mrad,{:.2},mrad",
                zero_angle * 1000.0 / elevation_cf
            );
            println!("max_ordinate,{:.3},meters", trajectory.max_height);
        }

        OutputFormat::Table => {
            // Convert distances back to display units
            let target_dist_display = UnitConverter::distance_from_metric(target_distance, units);
            let target_height_display = UnitConverter::distance_from_metric(target_height, units);
            let sight_height_display = UnitConverter::distance_from_metric(sight_height, units);
            let max_ordinate_display =
                UnitConverter::distance_from_metric(trajectory.max_height, units);

            let dist_unit = match units {
                UnitSystem::Metric => "m",
                UnitSystem::Imperial => "yd",
            };

            println!("╔════════════════════════════════════════╗");
            println!("║          ZERO CALCULATION              ║");
            println!("╠════════════════════════════════════════╣");
            println!(
                "║ Target Distance:   {:>8.1} {:3}       ║",
                target_dist_display, dist_unit
            );
            println!(
                "║ Target Height:     {:>8.2} {:3}       ║",
                target_height_display, dist_unit
            );
            println!(
                "║ Sight Height:      {:>8.3} {:3}       ║",
                sight_height_display, dist_unit
            );
            println!("╠════════════════════════════════════════╣");
            println!(
                "║ Zero Angle:        {:>8.4}°          ║",
                zero_angle.to_degrees()
            );
            println!(
                "║ Zero Angle (MOA):  {:>8.2} MOA        ║",
                zero_angle.to_degrees() * 60.0 / elevation_cf
            );
            println!(
                "║ Zero Angle (mrad): {:>8.2} mrad       ║",
                zero_angle * 1000.0 / elevation_cf
            );
            println!(
                "║ Max Ordinate:      {:>8.3} {:3}       ║",
                max_ordinate_display, dist_unit
            );
            println!("╚════════════════════════════════════════╝");
        }

        OutputFormat::Pdf => {
            eprintln!("Error: PDF output is not supported for zero calculation.");
            eprintln!("Hint: Use --output json, --output csv, or --output table instead.");
        }
    }

    Ok(())
}

/// Companion of [`run_zero_calculation`] (MBA-1402), corrected by the Tier 2 whole-branch
/// review (C2): given a fixed, previously solved/stored bore angle instead of a target
/// distance, solve the zero RANGE(S) it produces — run the trajectory at that angle and
/// report BOTH line-of-sight crossings found (near, ascending, close to the muzzle; far,
/// descending past the apex), rather than silently picking one. `zero_angle_rad` is the
/// stored angle (e.g. a `zero_angle_degrees` value this same command already printed on an
/// earlier `--target-distance` run, or `trajectory`'s auto-zero echo), already converted to
/// radians by the caller.
///
/// This is NOT the exact inverse of `run_zero_calculation`'s forward solve: a bore angle
/// generally implies two valid zero distances (the classic 25/300-yard battle-zero
/// relationship — a rifle zeroed near 25 yd is, for the same bore angle, also zeroed again
/// near 300 yd), and the forward solver's chosen root depends on the target distance it was
/// asked to hit. Round-tripping a solved angle back through here recovers the original
/// distance as ONE of the two reported crossings, not necessarily the far one.
#[allow(clippy::too_many_arguments)] // Mirrors run_zero_calculation's own parameter list.
fn run_zero_range_calculation(
    velocity: f64,
    bc: f64,
    bc_reference_standard: BcReferenceStandard,
    mass: f64,
    diameter: f64,
    drag_model: DragModel,
    zero_angle_rad: f64,
    target_height: f64,
    sight_height: f64,
    temperature: f64,
    pressure: f64,
    pressure_type: PressureReferenceMode,
    humidity: f64,
    altitude: f64,
    custom_drag_table: Option<ballistics_engine::drag::DragTable>,
    cd_scale: f64,
    // MBA-1358: elevation tracking CF — the MOA/mrad dial-unit outputs (zero angle,
    // sight adjustment) are DIVIDED by it exactly once at their emission points
    // (scope units: an under-tracking scope, CF < 1, needs more dial); the degrees
    // echo is a bore angle and never scales. 1.0 (no CF) is bit-exact.
    elevation_cf: f64,
    output: OutputFormat,
    units: UnitSystem,
) -> Result<(), Box<dyn Error>> {
    // Create ballistic inputs
    let inputs = BallisticInputs {
        muzzle_velocity: velocity,
        bc_value: bc,
        bc_type: drag_model,
        bc_reference_standard,
        bullet_mass: mass,
        bullet_diameter: diameter,
        sight_height,
        temperature,
        pressure,
        humidity,
        altitude,
        custom_drag_table,
        cd_scale,
        ..Default::default()
    };

    // MBA-1397: same resolve-once pattern as run_zero_calculation (Absolute is byte-identical
    // to the legacy default-sentinel resolution TrajectorySolver::new performs internally;
    // Qnh reduces a declared altimeter setting to station pressure). Reused for both the
    // inverse solve and the follow-up trajectory solve below, so they agree.
    let (resolved_temperature, resolved_pressure) = resolve_station_conditions_with_pressure_mode(
        temperature,
        pressure,
        altitude,
        pressure_type,
    );

    let atmosphere = AtmosphericConditions {
        temperature: resolved_temperature,
        pressure: resolved_pressure,
        humidity,
        altitude,
    };

    // Same line-of-sight target height convention as run_zero_calculation's forward solve.
    let los_target_height = sight_height + target_height;

    // Solve the zero RANGE(S) this stored angle produces (Tier 2 review C2: BOTH crossings,
    // not just one). Authoritative: `atmosphere` is already fully resolved, so it is trusted
    // as-is rather than re-derived a second time.
    let crossings = ballistics_engine::calculate_zero_range_from_angle_with_resolved_conditions(
        inputs.clone(),
        zero_angle_rad,
        los_target_height,
        WindConditions::default(),
        atmosphere.clone(),
    )?;

    // A single concrete distance is still needed to size the follow-up trajectory solve and
    // to compute the sight-adjustment/point-blank-range diagnostics below. Prefer the far
    // crossing -- the conventional "sighted in at D yards" meaning -- and fall back to the
    // near one when the far crossing isn't within the solved envelope; either way, both
    // crossings are still reported in full below.
    let primary_range = crossings.far_m.or(crossings.near_m).expect(
        "calculate_zero_range_from_angle_with_resolved_conditions guarantees at least one \
         crossing on Ok",
    );
    // MBA-1419: which of the two roots the single `zero_range` value refers to, reported rather
    // than left for a caller to re-derive from the near/far pair.
    let primary_crossing = if crossings.far_m.is_some() {
        "far"
    } else {
        "near"
    };

    // Calculate trajectory at the given angle to get additional info, mirroring the forward
    // command's own follow-up solve.
    let mut zeroed_inputs = inputs;
    zeroed_inputs.muzzle_angle = zero_angle_rad;

    let mut solver = TrajectorySolver::new_with_resolved_station_atmosphere(
        zeroed_inputs,
        Default::default(),
        atmosphere,
    );
    // MBA-1419: 3x the primary crossing normally contains the apex, since the apex always lies
    // between the two crossings and the far one is preferred. When only the NEAR crossing exists
    // the far root is beyond the search envelope, so 3x a short near zero can truncate the
    // trajectory before its apex and yield a degenerate solve. Floor the envelope at the
    // distance the crossing search itself covered, so the diagnostics see everything the search
    // saw. Ground impact still stops the solve well before this in the ordinary case.
    let diagnostics_envelope = if crossings.far_m.is_some() {
        primary_range * 3.0
    } else {
        (primary_range * 3.0).max(ballistics_engine::ZERO_RANGE_FROM_ANGLE_MAX_RANGE_M)
    };
    solver.set_max_range(diagnostics_envelope);
    let trajectory = solver.solve()?;

    // Same sight-adjustment/point-blank-range diagnostics as the forward command, now
    // referenced against the primary crossing rather than a supplied target distance.
    // MBA-1358: a dialed correction — scope units (÷CF; /1.0 is exact).
    let sight_adjustment_moa = (zero_angle_rad.to_degrees() * 60.0
        - (target_height / primary_range * 3437.75))
        / elevation_cf;
    let mut entered_point_blank_band = false;
    let point_blank_range = trajectory
        .points
        .iter()
        .find_map(|p| {
            let los_y = sight_height + target_height * (p.position.x / primary_range);
            let height_from_los = p.position.y - los_y;

            if height_from_los >= -0.05 {
                entered_point_blank_band = true;
                None
            } else if entered_point_blank_band {
                Some(p.position.x)
            } else {
                None
            }
        })
        .unwrap_or(trajectory.max_range);

    // MBA-1419 item 3, resolved: report the apex if and only if the diagnostics trajectory
    // actually TURNED OVER inside its envelope — peak strictly before the final point and
    // strictly above it. This replaces 0.30.0's "was a far crossing found?" proxy, which was
    // over-conservative: a 45-degree G1 launch turns over at ~2040 yd inside the 2000 m floor
    // and has a perfectly real ~1432 yd apex that the proxy withheld. (0.30.0's comment here
    // claimed the direct tests had mis-reported containment at steep angles; investigation
    // showed the tests were right and the claim was wrong — the "obviously bogus" 45-degree
    // apex was a genuine G1 apex all along. The far-crossing case is a subset: an apex between
    // two crossings has, by construction, turned over.)
    let apex_is_contained = {
        let ys: Vec<f64> = trajectory.points.iter().map(|p| p.position.y).collect();
        match (
            ys.iter()
                .cloned()
                .enumerate()
                .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal)),
            ys.last(),
        ) {
            (Some((peak_index, peak_y)), Some(&last_y)) => {
                peak_index + 1 < ys.len() && peak_y > last_y + 1e-9
            }
            _ => false,
        }
    };

    let dist_unit = match units {
        UnitSystem::Metric => "m",
        UnitSystem::Imperial => "yd",
    };

    let near_range_display = crossings
        .near_m
        .map(|m| UnitConverter::distance_from_metric(m, units));
    let far_range_display = crossings
        .far_m
        .map(|m| UnitConverter::distance_from_metric(m, units));
    let primary_range_display = UnitConverter::distance_from_metric(primary_range, units);

    match output {
        OutputFormat::Json => {
            let units_label = match units {
                UnitSystem::Metric => "metric",
                UnitSystem::Imperial => "imperial",
            };
            let mut result = serde_json::json!({
                "units": units_label,
                "zero_angle_degrees": zero_angle_rad.to_degrees(),
                "zero_angle_moa": zero_angle_rad.to_degrees() * 60.0 / elevation_cf,
                "zero_angle_mrad": zero_angle_rad * 1000.0 / elevation_cf,
                // Kept for continuity with the primary (far-preferred) crossing; see
                // "near_zero_range"/"far_zero_range" for both crossings explicitly.
                "zero_range": primary_range_display,
                // MBA-1419: which root `zero_range` is. A bore angle generally crosses the line
                // of sight twice, and this value is far-when-present-else-near; without this key
                // a consumer cannot tell which of two valid answers it received.
                "primary_crossing": primary_crossing,
                "sight_adjustment_moa": sight_adjustment_moa,
                "point_blank_range": UnitConverter::distance_from_metric(point_blank_range, units),
            });
            // MBA-1419 item 3: absent — not null, and not a fabrication — when the diagnostics
            // solve was still climbing at its envelope. Previously this key carried the height
            // at the truncation point in that case, which is not a max ordinate.
            if apex_is_contained {
                result["max_ordinate"] = serde_json::json!(UnitConverter::distance_from_metric(
                    trajectory.max_height,
                    units
                ));
            }
            // Tier 2 review C2: additive, skip-when-absent keys for both crossings (mirrors
            // MBA-1402's skip_serializing_if pattern) -- a bore angle generally implies two
            // zero ranges and both are reported rather than silently picked between.
            if let Some(near) = near_range_display {
                result["near_zero_range"] = serde_json::json!(near);
            }
            if let Some(far) = far_range_display {
                result["far_zero_range"] = serde_json::json!(far);
            }
            println!("{}", serde_json::to_string_pretty(&result)?);
        }

        OutputFormat::Csv => {
            println!("metric,value,unit");
            println!("zero_angle,{:.4},degrees", zero_angle_rad.to_degrees());
            println!(
                "zero_angle_moa,{:.2},MOA",
                zero_angle_rad.to_degrees() * 60.0 / elevation_cf
            );
            println!(
                "zero_angle_mrad,{:.2},mrad",
                zero_angle_rad * 1000.0 / elevation_cf
            );
            println!("zero_range,{:.2},{}", primary_range_display, dist_unit);
            // MBA-1419: same disclosure as JSON — which of the two crossings zero_range is.
            println!("primary_crossing,{},crossing", primary_crossing);
            if let Some(near) = near_range_display {
                println!("near_zero_range,{:.2},{}", near, dist_unit);
            }
            if let Some(far) = far_range_display {
                println!("far_zero_range,{:.2},{}", far, dist_unit);
            }
            // MBA-1419 item 3: row omitted when the solve was still climbing at its envelope.
            if apex_is_contained {
                println!("max_ordinate,{:.3},meters", trajectory.max_height);
            }
        }

        OutputFormat::Table => {
            let target_height_display = UnitConverter::distance_from_metric(target_height, units);
            let sight_height_display = UnitConverter::distance_from_metric(sight_height, units);
            let max_ordinate_display =
                UnitConverter::distance_from_metric(trajectory.max_height, units);

            println!("╔════════════════════════════════════════╗");
            println!("║     ZERO RANGE FROM STORED ANGLE       ║");
            println!("╠════════════════════════════════════════╣");
            println!(
                "║ Input Zero Angle:  {:>8.4}°          ║",
                zero_angle_rad.to_degrees()
            );
            // MBA-1358: the MOA/mrad representations are dial units and scale with the
            // CF, matching this path's own JSON/CSV zero_angle_moa/mrad; the degrees
            // echo above stays the raw stored bore angle.
            println!(
                "║ Input Zero Angle:  {:>8.2} MOA        ║",
                zero_angle_rad.to_degrees() * 60.0 / elevation_cf
            );
            println!(
                "║ Input Zero Angle:  {:>8.2} mrad       ║",
                zero_angle_rad * 1000.0 / elevation_cf
            );
            println!("╠════════════════════════════════════════╣");
            // Tier 2 review C2: a bore angle generally crosses the line of sight twice --
            // report both, clearly labelled, rather than silently picking one.
            match near_range_display {
                Some(near) => {
                    println!("║ Near Zero (ascending): {:>8.1} {:3}   ║", near, dist_unit)
                }
                None => println!("║ Near Zero:  not in solved range        ║"),
            }
            match far_range_display {
                Some(far) => println!("║ Far Zero (descending): {:>8.1} {:3}   ║", far, dist_unit),
                None => println!("║ Far Zero:   not in solved range        ║"),
            }
            println!(
                "║ Target Height:     {:>8.2} {:3}       ║",
                target_height_display, dist_unit
            );
            println!(
                "║ Sight Height:      {:>8.3} {:3}       ║",
                sight_height_display, dist_unit
            );
            // Tier 2 re-review N2: the diagnostics solve is sized off the primary crossing, so
            // a truncated solve reports the height at the truncation point rather than the real
            // apex -- a 5 deg launch reported 0.167 yd.
            //
            // MBA-1419 item 3: gate on the trajectory itself (see `apex_is_contained` above).
            // The 0.30.0 comment that stood here claimed the direct turn-over tests had
            // mis-reported containment at steep angles; they had not — the 45-degree value they
            // accepted was a real G1 apex, not truncation. The proxy it defended withheld real
            // apexes in every near-only case that turned over.
            if apex_is_contained {
                println!(
                    "║ Max Ordinate:      {:>8.3} {:3}       ║",
                    max_ordinate_display, dist_unit
                );
            } else {
                println!("║ Max Ordinate:  still climbing at limit ║");
            }
            println!("╚════════════════════════════════════════╝");
        }

        OutputFormat::Pdf => {
            eprintln!("Error: PDF output is not supported for zero calculation.");
            eprintln!("Hint: Use --output json, --output csv, or --output table instead.");
        }
    }

    Ok(())
}

fn run_bc_segment_generation(
    bc: f64,
    mass: f64,
    diameter: f64,
    model: &str,
    drag_model: &str,
    output: OutputFormat,
    units: UnitSystem,
) -> Result<(), Box<dyn Error>> {
    use ballistics_engine::bc_estimation::BCSegmentEstimator;

    // Convert mass to grains and diameter to inches for the estimation
    let weight_grains = mass / GRAINS_TO_KG;
    let caliber_inches = diameter / 0.0254;

    // 0.28.1 sweep: `estimate_bc_segments` only understands G1/G7 (anything else is
    // silently typed as G1 -- see its `eq_ignore_ascii_case("G7")` check), same family of
    // coercion as the `--bc-table`/BC5D/`--online`/`--use-bc-segments` auxiliary paths
    // `warn_aux_g1_coercion` already covers (MBA-1386). This was the one aux site still
    // missing the warning. An unparseable `--drag-model` string is left alone here -- it
    // already fell through to G1 silently before this fix, and warning about it is a
    // separate concern from the *family-coercion* warning this call adds.
    if let Some(parsed) = DragModel::from_str(drag_model) {
        warn_aux_g1_coercion("generate-bc-segments", parsed);
    }

    // Generate BC segments
    let segments = BCSegmentEstimator::estimate_bc_segments(
        bc,
        caliber_inches,
        weight_grains,
        model,
        drag_model,
    );

    match output {
        OutputFormat::Json => {
            let segments_json: Vec<_> = segments
                .iter()
                .map(|s| {
                    serde_json::json!({
                        "velocity_min_fps": s.velocity_min,
                        "velocity_max_fps": s.velocity_max,
                        "bc": s.bc_value
                    })
                })
                .collect();

            let result = serde_json::json!({
                "base_bc": bc,
                "mass_grains": weight_grains,
                "caliber_inches": caliber_inches,
                "model": model,
                "drag_model": drag_model,
                "segments": segments_json
            });

            println!("{}", serde_json::to_string_pretty(&result)?);
        }

        OutputFormat::Csv => {
            println!("velocity_min_fps,velocity_max_fps,bc");
            for segment in &segments {
                println!(
                    "{},{},{:.4}",
                    segment.velocity_min, segment.velocity_max, segment.bc_value
                );
            }
        }

        OutputFormat::Table => {
            println!("╔════════════════════════════════════════╗");
            println!("║        BC SEGMENT GENERATION           ║");
            println!("╠════════════════════════════════════════╣");
            println!("║ Base BC:         {:.3}                 ║", bc);
            println!("║ Caliber:         {:.3} inches          ║", caliber_inches);
            println!("║ Weight:          {:.1} grains          ║", weight_grains);
            if !model.is_empty() {
                println!("║ Model:           {:20}  ║", model);
            }
            println!("║ Drag Model:      {:20}  ║", drag_model);
            println!("╠════════════════════════════════════════╣");
            println!("║         VELOCITY SEGMENTS              ║");
            println!("╠════════════════════════════════════════╣");

            for segment in &segments {
                let vel_display = if units == UnitSystem::Imperial {
                    format!(
                        "{:.0}-{:.0} fps",
                        segment.velocity_min, segment.velocity_max
                    )
                } else {
                    format!(
                        "{:.0}-{:.0} m/s",
                        segment.velocity_min / 3.28084,
                        segment.velocity_max / 3.28084
                    )
                };
                println!("║ {:18} → BC: {:.4}     ║", vel_display, segment.bc_value);
            }

            println!("╚════════════════════════════════════════╝");
        }

        OutputFormat::Pdf => {
            eprintln!("Error: PDF output is not supported for BC segment generation.");
            eprintln!("Hint: Use --output json, --output csv, or --output table instead.");
        }
    }

    Ok(())
}

/// Parse a `"d,v;d,v;..."` data string into `(f64, f64)` pairs, tolerating surrounding
/// quotes and whitespace. Errors on any malformed pair.
fn parse_data_pairs(s: &str) -> Result<Vec<(f64, f64)>, Box<dyn Error>> {
    let cleaned = s.trim().trim_matches('\'').trim_matches('"');
    let mut out = Vec::new();
    for pair in cleaned.split(';') {
        let pair = pair.trim();
        if pair.is_empty() {
            continue;
        }
        let parts: Vec<&str> = pair.split(',').collect();
        if parts.len() != 2 {
            return Err(format!(
                "Malformed data pair '{}': expected \"distance,value\".",
                pair
            )
            .into());
        }
        let d: f64 = parts[0]
            .trim()
            .parse()
            .map_err(|_| format!("Invalid distance '{}'.", parts[0].trim()))?;
        let v: f64 = parts[1]
            .trim()
            .parse()
            .map_err(|_| format!("Invalid value '{}'.", parts[1].trim()))?;
        out.push((d, v));
    }
    if out.is_empty() {
        return Err("No valid data pairs found.".into());
    }
    Ok(out)
}

/// Parse the `--drag-model` selector into the list of drag models to estimate. Accepts
/// `both`/`all` (G1 + G7) or any single drag-model family name (MBA-1386 widened
/// `DragModel` past the scalar G1/G7 pair to the full G1/G2/G5/G6/G7/G8/GI/GS/RA4 family --
/// the BC-fit path fits and reports any of them individually, not just G1/G7).
fn parse_drag_models(s: &str) -> Result<Vec<DragModel>, Box<dyn Error>> {
    let trimmed = s.trim();
    match trimmed.to_lowercase().as_str() {
        "both" | "all" | "g1,g7" | "g1g7" => Ok(vec![DragModel::G1, DragModel::G7]),
        other => DragModel::from_str(other).map(|m| vec![m]).ok_or_else(|| {
            format!(
                "Unknown --drag-model '{}'; use g1, g7, both, or a specific drag family (g2, g5, g6, g8, gi, gs, ra4).",
                other
            )
            .into()
        }),
    }
}

/// Estimate BC for every (drag model × available data basis) combination and print the
/// results. `drop_points` are `(m, m)`, `vel_points` are `(m, m/s)`.
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments preserve the existing BC-estimation compatibility helper"
)]
fn run_bc_estimation_multi(
    velocity: f64,
    mass: f64,
    diameter: f64,
    drop_points: &[(f64, f64)],
    vel_points: &[(f64, f64)],
    models: &[DragModel],
    atmosphere: AtmosphericConditions,
    zero_range: Option<f64>,
    sight_height: f64,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    use ballistics_engine::{estimate_bc_fit, BcFitMode};

    // The data bases we can fit against, in a stable order (drop first, then velocity).
    struct Basis<'a> {
        mode: BcFitMode,
        points: &'a [(f64, f64)],
    }
    let mut bases: Vec<Basis> = Vec::new();
    if !drop_points.is_empty() {
        bases.push(Basis {
            mode: BcFitMode::Drop,
            points: drop_points,
        });
    }
    if !vel_points.is_empty() {
        bases.push(Basis {
            mode: BcFitMode::Velocity,
            points: vel_points,
        });
    }

    struct Variant {
        model: DragModel,
        mode: BcFitMode,
        bc: f64,
        rms_user: f64,
        rms_unit: &'static str,
        n: usize,
        at_bound: bool,
    }
    let mut variants: Vec<Variant> = Vec::new();
    for &model in models {
        for basis in &bases {
            // Zero range only shapes a drop fit; a velocity fit is frame-independent.
            let zr = match basis.mode {
                BcFitMode::Drop => zero_range,
                BcFitMode::Velocity => None,
            };
            let est = estimate_bc_fit(
                velocity,
                mass,
                diameter,
                basis.points,
                model,
                basis.mode,
                atmosphere.clone(),
                zr,
                sight_height,
            )?;
            // Convert the RMS residual back to user units for a readable fit-quality column.
            let (rms_user, rms_unit) = match basis.mode {
                BcFitMode::Drop => match units {
                    UnitSystem::Imperial => (est.rms_error / 0.0254, "in"),
                    UnitSystem::Metric => (est.rms_error, "m"),
                },
                BcFitMode::Velocity => match units {
                    UnitSystem::Imperial => (est.rms_error / 0.3048, "fps"),
                    UnitSystem::Metric => (est.rms_error, "m/s"),
                },
            };
            variants.push(Variant {
                model,
                mode: basis.mode,
                bc: est.bc,
                rms_user,
                rms_unit,
                n: basis.points.len(),
                at_bound: est.at_bound,
            });
        }
    }

    // 0.28.1 sweep: every DragModel family (including RA4/G2/G5/GI/GS) now has a real
    // fit/report path -- label it by its actual name (DragModel's Display is exactly its
    // variant name) instead of collapsing anything past G1/G7 into a generic "G?".
    let model_name = |m: DragModel| m.to_string();
    let basis_name = |mode: BcFitMode| match mode {
        BcFitMode::Drop => "drop",
        BcFitMode::Velocity => "velocity",
    };

    match output {
        OutputFormat::Json => {
            let vs: Vec<_> = variants
                .iter()
                .map(|v| {
                    serde_json::json!({
                        "drag_model": model_name(v.model),
                        "fit_basis": basis_name(v.mode),
                        "estimated_bc": (v.bc * 1000.0).round() / 1000.0,
                        "fit_rms": (v.rms_user * 1000.0).round() / 1000.0,
                        "fit_rms_unit": v.rms_unit,
                        "n_points": v.n,
                        "reliable": !v.at_bound,
                    })
                })
                .collect();
            let result = serde_json::json!({
                "velocity": velocity,
                "mass": mass,
                "diameter": diameter,
                "variants": vs,
            });
            println!("{}", serde_json::to_string_pretty(&result)?);
        }

        OutputFormat::Csv => {
            println!("drag_model,fit_basis,estimated_bc,fit_rms,fit_rms_unit,n_points,reliable");
            for v in &variants {
                println!(
                    "{},{},{:.4},{:.3},{},{},{}",
                    model_name(v.model),
                    basis_name(v.mode),
                    v.bc,
                    v.rms_user,
                    v.rms_unit,
                    v.n,
                    !v.at_bound
                );
            }
        }

        OutputFormat::Table => {
            println!("BC Estimation");
            println!(
                "  {:<6} {:<20} {:>12}   {:<10} ",
                "Model", "Fit basis", "Estimated BC", "Fit RMS"
            );
            println!("  {:-<6} {:-<20} {:->12}   {:-<10}", "", "", "", "");
            for v in &variants {
                println!(
                    "  {:<6} {:<20} {:>12.3}   {:>6.2} {:<4}{}",
                    model_name(v.model),
                    format!("{} ({} pts)", basis_name(v.mode), v.n),
                    v.bc,
                    v.rms_user,
                    v.rms_unit,
                    if v.at_bound {
                        " ⚠ UNRELIABLE (hit BC limit)"
                    } else {
                        ""
                    }
                );
            }
            if variants.iter().any(|v| v.at_bound) {
                println!();
                println!("  ⚠ One or more fits ran to the BC search limit — the data did not");
                println!("    determine a real value. Add more (and longer-range) points, and");
                println!("    check --zero-range / --temperature / --pressure match the data.");
            }
        }

        OutputFormat::Pdf => {
            eprintln!("Error: PDF output is not supported for BC estimation.");
            eprintln!("Hint: Use --output json, --output csv, or --output table instead.");
        }
    }

    Ok(())
}

/// Display velocity truing results in the specified format
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments preserve the existing velocity-truing display helper"
)]
fn display_true_velocity_result(
    effective_vel: f64,
    vel_unit: &str,
    velocity_adjustment: Option<f64>,
    adjustment_percent: Option<f64>,
    confidence: &str,
    iterations: i32,
    final_error_mil: f64,
    calculated_drop_mil: f64,
    measured_drop: f64,
    units: UnitSystem,
    output: OutputFormat,
    used_bc_table: bool,
) -> Result<(), Box<dyn Error>> {
    match output {
        OutputFormat::Json => {
            let mut json_output = serde_json::json!({
                "effective_velocity": effective_vel,
                "velocity_unit": vel_unit,
                "confidence": confidence,
                "iterations": iterations,
                "final_error_mil": final_error_mil,
                "calculated_drop_mil": calculated_drop_mil,
                "measured_drop_mil": measured_drop,
                "used_bc_table": used_bc_table,
            });
            if let Some(adj) = velocity_adjustment {
                let adj_display = match units {
                    UnitSystem::Imperial => adj,
                    UnitSystem::Metric => adj * 0.3048,
                };
                json_output["velocity_adjustment"] = serde_json::json!(adj_display);
            }
            if let Some(pct) = adjustment_percent {
                json_output["adjustment_percent"] = serde_json::json!(pct);
            }
            println!("{}", serde_json::to_string_pretty(&json_output)?);
        }
        OutputFormat::Csv => {
            println!("effective_velocity,unit,adjustment,adjustment_pct,confidence,iterations,final_error_mil,calculated_drop_mil,used_bc_table");
            println!(
                "{:.1},{},{},{},{},{},{:.4},{:.2},{}",
                effective_vel,
                vel_unit,
                velocity_adjustment
                    .map(|v| {
                        let adj = match units {
                            UnitSystem::Imperial => v,
                            UnitSystem::Metric => v * 0.3048,
                        };
                        format!("{:.1}", adj)
                    })
                    .unwrap_or_default(),
                adjustment_percent
                    .map(|v| format!("{:.2}", v))
                    .unwrap_or_default(),
                confidence,
                iterations,
                final_error_mil,
                calculated_drop_mil,
                used_bc_table,
            );
        }
        OutputFormat::Table => {
            println!();
            println!("╔════════════════════════════════════════════════════════════╗");
            println!("║           VELOCITY TRUING RESULTS                          ║");
            println!("╠════════════════════════════════════════════════════════════╣");
            println!(
                "║  Effective Muzzle Velocity: {:>8.1} {:>4}                 ║",
                effective_vel, vel_unit
            );
            if let Some(adj) = velocity_adjustment {
                let adj_display = match units {
                    UnitSystem::Imperial => adj,
                    UnitSystem::Metric => adj * 0.3048,
                };
                println!(
                    "║  Adjustment from Chrono:    {:>+8.1} {:>4}                 ║",
                    adj_display, vel_unit
                );
                if let Some(pct) = adjustment_percent {
                    println!(
                        "║  Adjustment Percentage:     {:>+8.2}%                      ║",
                        pct
                    );
                }
            }
            println!("╠════════════════════════════════════════════════════════════╣");
            println!(
                "║  Confidence:                {:>8}                        ║",
                confidence
            );
            println!(
                "║  Iterations:                {:>8}                        ║",
                iterations
            );
            println!(
                "║  Final Error:               {:>8.4} MIL                  ║",
                final_error_mil
            );
            println!(
                "║  Calculated Drop:           {:>8.2} MIL                  ║",
                calculated_drop_mil
            );
            println!(
                "║  Measured Drop:             {:>8.2} MIL                  ║",
                measured_drop
            );
            if used_bc_table {
                println!("╠════════════════════════════════════════════════════════════╣");
                println!("║  BC5D Table:                     Yes                       ║");
            }
            println!("╚════════════════════════════════════════════════════════════╝");
            println!();
        }

        OutputFormat::Pdf => {
            eprintln!("Error: PDF output is not supported for velocity truing results.");
            eprintln!("Hint: Use --output json, --output csv, or --output table instead.");
        }
    }

    Ok(())
}

// calculate_drop_at_velocity, TrueVelocityLocalResult, and calculate_true_velocity_local
// moved to ballistics_engine::truing (MBA-1343 Phase C), completing the truing lib surface
// (single-observation binary search + multi-observation joint fit) so the WASM terminal can
// reuse the exact compute paths. solve_trajectory_drop moved earlier (Phase A).

// ============================================================================
// MBA-1316: multi-observation joint MV + BC calibration (truing v2)
// ============================================================================
//
// The compute core (constants, TruingObservation, TruingForwardModel, the
// fitters, identifiability gates and MultiTruingReport) moved to
// ballistics_engine::truing (MBA-1343) so the WASM terminal can reuse it.
// Only the thin CLI wrapper and the rendering stay here.

/// Parse an uncertainty-aware additional observation.  The optional third
/// component is a per-observation 1-sigma override; otherwise `default_sigma`
/// is used.  This parser is reached only when the opt-in uncertainty surface is
/// active, leaving the legacy RANGE:DROP parser and its error contract intact.
fn parse_uncertain_truing_observation(
    token: &str,
    units: UnitSystem,
    default_sigma: f64,
) -> Result<(TruingObservation, f64), String> {
    let parts: Vec<&str> = token.split(':').collect();
    if !(2..=3).contains(&parts.len()) {
        return Err(format!(
            "invalid --observed '{token}': expected RANGE:DROP or RANGE:DROP:SIGMA"
        ));
    }
    let base = format!("{}:{}", parts[0], parts[1]);
    let observation = parse_truing_observation(&base, units)?;
    let sigma = if parts.len() == 3 {
        parts[2]
            .trim()
            .parse::<f64>()
            .map_err(|_| format!("invalid --observed sigma '{}' in '{token}'", parts[2]))?
    } else {
        default_sigma
    };
    if !sigma.is_finite() || sigma <= 0.0 {
        return Err(format!(
            "invalid --observed sigma in '{token}': sigma must be positive and finite"
        ));
    }
    Ok((observation, sigma))
}

/// Parse an explicit normal prior token as `(mean, one_sigma)`.
fn parse_normal_prior(token: &str, flag: &str) -> Result<(f64, f64), String> {
    let (mean, sigma) = token
        .split_once(':')
        .ok_or_else(|| format!("{flag} expects MEAN:SIGMA"))?;
    let mean = mean
        .trim()
        .parse::<f64>()
        .map_err(|_| format!("{flag} has an invalid mean in '{token}'"))?;
    let sigma = sigma
        .trim()
        .parse::<f64>()
        .map_err(|_| format!("{flag} has an invalid sigma in '{token}'"))?;
    if !mean.is_finite() {
        return Err(format!("{flag} mean must be finite"));
    }
    if !sigma.is_finite() || sigma <= 0.0 {
        return Err(format!("{flag} sigma must be positive and finite"));
    }
    Ok((mean, sigma))
}

/// Expand the explicit `START:END:STEP` planner grid.  The grid is never
/// inferred: the end is included only when it lies on a generated step (within
/// floating-point tolerance), and the hard cap keeps accidental CLI input from
/// launching an unbounded number of trajectory solves.
fn parse_truing_range_grid(token: &str) -> Result<Vec<f64>, String> {
    let parts: Vec<&str> = token.split(':').collect();
    if parts.len() != 3 {
        return Err(format!(
            "--range-grid expects START:END:STEP (got '{token}')"
        ));
    }
    let mut values = [0.0_f64; 3];
    for (i, part) in parts.iter().enumerate() {
        values[i] = part
            .trim()
            .parse::<f64>()
            .map_err(|_| format!("--range-grid contains an invalid number in '{token}'"))?;
    }
    let [start, end, step] = values;
    if !start.is_finite() || !end.is_finite() || !step.is_finite() {
        return Err("--range-grid values must be finite".to_string());
    }
    if start <= 0.0 || end < start || step <= 0.0 {
        return Err("--range-grid requires 0 < START <= END and STEP > 0".to_string());
    }
    let count = ((end - start) / step + 1e-12).floor() as usize + 1;
    if count > 1_000 {
        return Err(format!(
            "--range-grid expands to {count} candidates; maximum is 1000"
        ));
    }
    Ok((0..count).map(|i| start + i as f64 * step).collect())
}

/// Orchestrate the multi-observation joint MV+BC calibration and print the
/// result. `measured_drop`/`range_yd` are the primary observation (drop already
/// in `drop_unit`); `observed` holds the additional `RANGE:DROP` tokens.
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable true-velocity CLI command shape"
)]
fn run_multi_observation_truing(
    measured_drop: f64,
    range_yd: f64,
    observed: &[String],
    drop_unit: DropUnit,
    // MBA-1358: elevation tracking CF for dialed observations. The primary
    // (`measured_drop`) arrives ALREADY multiplied by it (scope-dial -> true angular);
    // parsed `--observed` drops are multiplied here (exactly once each), and dial-unit
    // report values are converted back to scope units (÷CF) for display. 1.0 = no
    // correction, and the caller passes 1.0 for --drop-unit in (linear tape
    // measurements never scale).
    observation_cf: f64,
    bc_input: f64,
    drag_model: DragModelArg,
    mass_gr: f64,
    diameter_in: f64,
    zero_yd: f64,
    sight_in: f64,
    temp_f: f64,
    press_inhg: f64,
    humidity: f64,
    alt_ft: f64,
    bc_segments: &Option<Vec<BCSegmentData>>,
    chrono_fps: Option<f64>,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    // Assemble the observation set: primary (--range/--measured-drop) first,
    // then every --observed token (the typed core takes parsed observations;
    // MBA-1343 review).
    let mut observations: Vec<TruingObservation> = Vec::with_capacity(observed.len() + 1);
    observations.push(TruingObservation {
        range_yd,
        drop: measured_drop,
    });
    for token in observed {
        let mut observation = parse_truing_observation(token, units)?;
        // MBA-1358: dialed observations multiply by the tracking CF (scope-dial ->
        // true angular) before the fit consumes them (the primary above was converted
        // by the caller). *1.0 is exact.
        observation.drop *= observation_cf;
        observations.push(observation);
    }

    // Pre-validate before announcing the fit: the core validates again (cheaply),
    // but running the same check here first keeps the historical stderr contract —
    // an invalid set (e.g. duplicate ranges) errors WITHOUT a "Fitting ..."
    // progress line, exactly as it always has.
    validate_truing_observations(&observations)?;

    eprintln!(
        "Fitting {} observations (joint MV+BC calibration)...",
        observations.len()
    );

    let report = run_multi_observation_truing_core(
        &observations,
        drop_unit,
        bc_input,
        drag_model,
        mass_gr,
        diameter_in,
        zero_yd,
        sight_in,
        temp_f,
        press_inhg,
        humidity,
        alt_ft,
        bc_segments,
    )?;
    // MBA-1358: dial-unit report values are shown back in scope units (÷CF); the shared
    // helper is a no-op (/1.0 exact) without a CF, keeping output byte-identical.
    let display_report =
        ballistics_engine::truing::scale_report_dial_values(&report, observation_cf);
    display_multi_truing_result(&display_report, drop_unit, units, chrono_fps, output);
    Ok(())
}

// rms_at and truing_quality_line moved to ballistics_engine::truing (MBA-1343).

/// Render a multi-observation truing report as table / JSON / CSV.
fn display_multi_truing_result(
    report: &MultiTruingReport,
    drop_unit: DropUnit,
    units: UnitSystem,
    chrono_fps: Option<f64>,
    output: OutputFormat,
) {
    let vel_unit = match units {
        UnitSystem::Imperial => "fps",
        UnitSystem::Metric => "m/s",
    };
    let range_unit = match units {
        UnitSystem::Imperial => "yd",
        UnitSystem::Metric => "m",
    };
    let drop_label = drop_unit.label();
    let mv_display = match units {
        UnitSystem::Imperial => report.fitted_mv_fps,
        UnitSystem::Metric => report.fitted_mv_fps * 0.3048,
    };
    let range_display = |range_yd: f64| match units {
        UnitSystem::Imperial => range_yd,
        UnitSystem::Metric => range_yd * 0.9144,
    };
    // Chrono comparison (chrono_fps is already in fps).
    let (adj_display, adj_pct) = match chrono_fps {
        Some(c) => {
            let adj_fps = report.fitted_mv_fps - c;
            let adj_disp = match units {
                UnitSystem::Imperial => adj_fps,
                UnitSystem::Metric => adj_fps * 0.3048,
            };
            let pct = if c != 0.0 { adj_fps / c * 100.0 } else { 0.0 };
            (Some(adj_disp), Some(pct))
        }
        None => (None, None),
    };

    // MBA-1405 Task 2: the MV-calibration window (90-100% of the downward Mach 1.2
    // crossing) and its per-observation out-of-window warning. The warning is a
    // stderr diagnostic independent of --output, so it fires once here regardless
    // of which branch below actually renders; the window itself is otherwise
    // table-only (see the `OutputFormat::Table` arm) and JSON gets only the
    // additive numeric fields, never this warning text (purity rule).
    let mv_window = mv_calibration_window(report.mach_1_2_distance_m);
    if let Some((lo_m, hi_m)) = mv_window {
        let lo = UnitConverter::distance_from_metric(lo_m, units);
        let hi = UnitConverter::distance_from_metric(hi_m, units);
        for o in &report.observations {
            let range_m = o.range_yd * 0.9144;
            if range_m < lo_m || range_m > hi_m {
                let r = range_display(o.range_yd);
                eprintln!(
                    "warning: observation at {r:.1} is outside the MV-calibration window \
                     ({lo:.1}-{hi:.1}); MV fits from this range are weakly identified"
                );
            }
        }
    }

    match output {
        OutputFormat::Json => {
            let obs_json: Vec<serde_json::Value> = report
                .observations
                .iter()
                .enumerate()
                .map(|(i, o)| {
                    serde_json::json!({
                        format!("range_{range_unit}"): range_display(o.range_yd),
                        format!("observed_drop_{drop_label}"): o.drop,
                        format!("predicted_drop_{drop_label}"): report.predicted[i],
                        format!("residual_{drop_label}"): report.residuals[i],
                    })
                })
                .collect();

            let mut json_output = serde_json::json!({
                "mode": if report.bc_fitted { "joint_mv_bc" } else { "mv_only" },
                "fitted_muzzle_velocity": mv_display,
                "velocity_unit": vel_unit,
                "bc_fitted": report.bc_fitted,
                "fitted_bc": report.fitted_bc,
                "input_bc": report.bc_input,
                "observations": obs_json,
                format!("rms_residual_{drop_label}"): report.rms,
                "iterations": report.iterations,
                "converged": report.converged,
                "bc_sensitivity_ratio": report.sensitivity_ratio,
                "condition_number": if report.condition_number.is_finite() {
                    serde_json::json!(report.condition_number)
                } else {
                    serde_json::Value::Null
                },
                "quality": report.quality,
                "legend": {
                    "units": {
                        "range": range_unit,
                        "drop": drop_label,
                        "velocity": vel_unit,
                    },
                },
            });
            if !report.reason.is_empty() {
                json_output["bc_hold_reason"] = serde_json::json!(report.reason);
            }
            if let Some(adj) = adj_display {
                json_output["velocity_adjustment"] = serde_json::json!(adj);
            }
            if let Some(pct) = adj_pct {
                json_output["adjustment_percent"] = serde_json::json!(pct);
            }
            // MBA-1405 Task 2: additive-only fields (meters, unit-invariant); null when
            // the trajectory never crosses Mach 1.2. No note text ever accompanies these
            // in JSON (purity rule) — the human-readable window/no-window lines are
            // table-only, above.
            json_output["mv_window_start_m"] = match mv_window {
                Some((lo_m, _)) => serde_json::json!(lo_m),
                None => serde_json::Value::Null,
            };
            json_output["mv_window_end_m"] = match mv_window {
                Some((_, hi_m)) => serde_json::json!(hi_m),
                None => serde_json::Value::Null,
            };
            match serde_json::to_string_pretty(&json_output) {
                Ok(s) => println!("{s}"),
                Err(e) => eprintln!("Error serializing JSON: {e}"),
            }
        }
        OutputFormat::Csv => {
            println!("range_{range_unit},observed_drop_{drop_label},predicted_drop_{drop_label},residual_{drop_label}");
            for (i, o) in report.observations.iter().enumerate() {
                println!(
                    "{:.1},{:.4},{:.4},{:+.4}",
                    range_display(o.range_yd),
                    o.drop,
                    report.predicted[i],
                    report.residuals[i]
                );
            }
            println!();
            println!("fitted_muzzle_velocity_{vel_unit},bc_fitted,fitted_bc,input_bc,rms_residual_{drop_label},iterations,converged,bc_sensitivity_ratio,condition_number");
            println!(
                "{:.1},{},{:.4},{:.4},{:.4},{},{},{:.4},{}",
                mv_display,
                report.bc_fitted,
                report.fitted_bc,
                report.bc_input,
                report.rms,
                report.iterations,
                report.converged,
                report.sensitivity_ratio,
                if report.condition_number.is_finite() {
                    format!("{:.1}", report.condition_number)
                } else {
                    "inf".to_string()
                },
            );
        }
        OutputFormat::Table => {
            println!();
            println!("=== VELOCITY + BC TRUING (multi-observation) ===");
            println!();
            println!("  Fitted muzzle velocity: {:>9.1} {}", mv_display, vel_unit);
            if report.bc_fitted {
                println!(
                    "  Fitted BC:              {:>9.4}  (input {:.4})",
                    report.fitted_bc, report.bc_input
                );
            } else {
                println!(
                    "  BC:                     {:>9.4}  (held; not fitted)",
                    report.fitted_bc
                );
            }
            if let Some(adj) = adj_display {
                println!("  Adjustment from chrono: {:>+9.1} {}", adj, vel_unit);
                if let Some(pct) = adj_pct {
                    println!("  Adjustment percentage:  {:>+9.2}%", pct);
                }
            }
            println!();
            println!(
                "  {:>10}  {:>14}  {:>14}  {:>12}",
                format!("Range ({range_unit})"),
                format!("Observed ({drop_label})"),
                format!("Predicted ({drop_label})"),
                format!("Resid ({drop_label})"),
            );
            println!("  {}", "-".repeat(56));
            for (i, o) in report.observations.iter().enumerate() {
                println!(
                    "  {:>10.1}  {:>14.3}  {:>14.3}  {:>+12.3}",
                    range_display(o.range_yd),
                    o.drop,
                    report.predicted[i],
                    report.residuals[i]
                );
            }
            println!("  {}", "-".repeat(56));
            println!(
                "  RMS residual: {:.3} {}   |   iterations: {}{}",
                report.rms,
                drop_label,
                report.iterations,
                if report.converged {
                    ""
                } else {
                    " (not fully converged)"
                }
            );
            println!();
            println!("  {}", report.quality);
            if !report.reason.is_empty() {
                println!("  Note: {}", report.reason);
            }
            println!(
                "  Diagnostics: BC sensitivity ratio {:.4}, conditioning {}",
                report.sensitivity_ratio,
                if report.condition_number.is_finite() {
                    format!("{:.0}", report.condition_number)
                } else {
                    "inf".to_string()
                }
            );
            // MBA-1405 Task 2: MV-calibration window / no-window note, table only.
            match mv_window {
                Some((lo_m, hi_m)) => {
                    let lo = UnitConverter::distance_from_metric(lo_m, units);
                    let hi = UnitConverter::distance_from_metric(hi_m, units);
                    println!(
                        "  MV-calibration window: {lo:.1}-{hi:.1} {range_unit} (90-100% of the Mach 1.2 distance)"
                    );
                }
                None if report.muzzle_mach >= 1.2 => {
                    let max_display =
                        UnitConverter::distance_from_metric(report.window_solved_range_m, units);
                    println!(
                        "  note: no MV window: trajectory is supersonic through {max_display:.1} \
                         {range_unit}; MV is identifiable at any range"
                    );
                }
                None => {
                    println!(
                        "  note: no MV window: trajectory never reaches Mach 1.2; calibrate \
                         muzzle velocity with a chronograph, then collect DSF points"
                    );
                }
            }
            println!("  for optimal observation ranges run: ballistics plan-truing");
            println!();
        }
        OutputFormat::Pdf => {
            eprintln!("Error: PDF output is not supported for velocity truing results.");
            eprintln!("Hint: Use --output json, --output csv, or --output table instead.");
        }
    }
}

/// Convert a Rust enum's stable CamelCase variant name into the snake_case code
/// used by the uncertainty JSON/CSV contracts.  Keeping this generic makes a
/// newly added warning/failure code visible instead of silently dropping it.
fn enum_variant_code(value: &impl std::fmt::Debug) -> String {
    let name = format!("{value:?}");
    let mut code = String::with_capacity(name.len() + 4);
    for (index, ch) in name.chars().enumerate() {
        if ch.is_ascii_uppercase() && index > 0 {
            code.push('_');
        }
        code.push(ch.to_ascii_lowercase());
    }
    code
}

/// Render MBA-1346's deterministic pre-shoot observation-range design.
fn display_truing_experiment_plan(
    plan: &TruingExperimentPlanV1,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    let range_scale = match units {
        UnitSystem::Imperial => 1.0,
        UnitSystem::Metric => 0.9144,
    };
    let range_unit = match units {
        UnitSystem::Imperial => "yd",
        UnitSystem::Metric => "m",
    };
    let range = |yards: f64| yards * range_scale;
    let mode = match plan.mode {
        TruingPlanModeV1::JointMvBc => "joint_mv_bc",
        TruingPlanModeV1::MvOnly => "mv_only",
    };

    match output {
        OutputFormat::Json => {
            let selected: Vec<serde_json::Value> = plan
                .selected_stations
                .iter()
                .map(|station| {
                    serde_json::json!({
                        "input_index": station.input_index,
                        format!("range_{range_unit}"): range(station.range_yd),
                        format!("predicted_drop_{}", plan.measurement_drop_unit): station.predicted_drop,
                        "scaled_mv_sensitivity": station.scaled_mv_sensitivity,
                        "scaled_bc_sensitivity": station.scaled_bc_sensitivity,
                        "leave_one_out_information_gain_nats": station.leave_one_out_information_gain_nats,
                    })
                })
                .collect();
            let rejected: Vec<serde_json::Value> = plan
                .rejected_candidates
                .iter()
                .map(|candidate| {
                    serde_json::json!({
                        "input_index": candidate.input_index,
                        format!("range_{range_unit}"): if candidate.range_yd.is_finite() {
                            serde_json::json!(range(candidate.range_yd))
                        } else {
                            serde_json::Value::Null
                        },
                        "reason": enum_variant_code(&candidate.reason),
                        "detail": candidate.detail,
                    })
                })
                .collect();
            let info = &plan.information;
            let value = serde_json::json!({
                "schema_version": "truing-experiment-plan-v1",
                "mode": mode,
                "requested_observation_count": plan.requested_observation_count,
                format!("minimum_separation_{range_unit}"): range(plan.minimum_separation_yd),
                "measurement_model": {
                    "sigma_1sd": plan.measurement_sigma_1sd,
                    "drop_unit": plan.measurement_drop_unit,
                    "assumption": "independent Gaussian impact-reading error at every station",
                },
                "selected_stations": selected,
                format!("unselected_candidate_ranges_{range_unit}"): plan
                    .unselected_candidate_ranges_yd
                    .iter()
                    .map(|value| range(*value))
                    .collect::<Vec<_>>(),
                "rejected_candidates": rejected,
                "information": {
                    "bc_sensitivity_ratio": info.sensitivity_ratio,
                    "condition_number": info.condition_number,
                    "minimum_singular_value": info.minimum_singular_value,
                    "maximum_singular_value": info.maximum_singular_value,
                    "weak_axis_fractional_sigma_1sd": info.weak_axis_fractional_sigma_1sd,
                    "log_determinant": info.log_determinant,
                    "expected_information_gain_nats": info.expected_information_gain_nats,
                },
                "optimizer": {
                    "search_strategy": enum_variant_code(&plan.search_strategy),
                    "eligible_candidate_count": plan.eligible_candidate_count,
                    "raw_combination_count": plan.raw_combination_count,
                    "evaluated_design_count": plan.evaluated_design_count,
                },
                "warnings": plan.warnings,
                "legend": {
                    "range_unit": range_unit,
                    "drop_unit": plan.measurement_drop_unit,
                    "scaled_sensitivity": "predicted drop change in declared observation sigmas for a unit fractional parameter change",
                    "information_gain": "0.5 log det(I + F), where I is the disclosed identity reference information in fractional MV/BC coordinates; design score only",
                },
            });
            println!("{}", serde_json::to_string_pretty(&value)?);
        }
        OutputFormat::Csv => {
            println!("plan_mode,measurement_sigma_1sd,measurement_drop_unit,requested_observation_count,minimum_separation_{range_unit},bc_sensitivity_ratio,condition_number,minimum_singular_value,maximum_singular_value,weak_axis_fractional_sigma_1sd,log_determinant,expected_information_gain_nats");
            println!(
                "{mode},{:.8},{},{},{:.8},{:.10},{},{:.10},{:.10},{},{},{:.10}",
                plan.measurement_sigma_1sd,
                plan.measurement_drop_unit,
                plan.requested_observation_count,
                range(plan.minimum_separation_yd),
                plan.information.sensitivity_ratio,
                plan.information
                    .condition_number
                    .map(|value| format!("{value:.10}"))
                    .unwrap_or_default(),
                plan.information.minimum_singular_value,
                plan.information.maximum_singular_value,
                plan.information
                    .weak_axis_fractional_sigma_1sd
                    .map(|value| format!("{value:.10}"))
                    .unwrap_or_default(),
                plan.information
                    .log_determinant
                    .map(|value| format!("{value:.10}"))
                    .unwrap_or_default(),
                plan.information.expected_information_gain_nats,
            );
            println!();
            println!("range_{range_unit},status,predicted_drop_{},scaled_mv_sensitivity,scaled_bc_sensitivity,information_gain_nats,detail", plan.measurement_drop_unit);
            for station in &plan.selected_stations {
                println!(
                    "{:.6},selected,{:.8},{:.8},{:.8},{:.8},",
                    range(station.range_yd),
                    station.predicted_drop,
                    station.scaled_mv_sensitivity,
                    station.scaled_bc_sensitivity,
                    station.leave_one_out_information_gain_nats,
                );
            }
            for candidate in &plan.unselected_candidate_ranges_yd {
                println!("{:.6},eligible_not_selected,,,,,", range(*candidate));
            }
            for candidate in &plan.rejected_candidates {
                let display_range = if candidate.range_yd.is_finite() {
                    range(candidate.range_yd).to_string()
                } else {
                    String::new()
                };
                println!(
                    "{},rejected:{},,,,,{}",
                    display_range,
                    enum_variant_code(&candidate.reason),
                    candidate.detail.replace(',', ";")
                );
            }
            if !plan.warnings.is_empty() {
                println!();
                println!("warning");
                for warning in &plan.warnings {
                    println!("{}", warning.replace(',', ";").replace('\n', " "));
                }
            }
        }
        OutputFormat::Table => {
            println!();
            println!("=== TRUING EXPERIMENT PLAN ===");
            println!(
                "  Recommendation: {}",
                if plan.mode == TruingPlanModeV1::JointMvBc {
                    "joint MV + BC"
                } else {
                    "MV only (available ranges do not identify BC)"
                }
            );
            println!(
                "  Measurement assumption: independent 1-sigma reading error = {:.4} {}",
                plan.measurement_sigma_1sd, plan.measurement_drop_unit
            );
            println!(
                "  Selected ranges: {} {range_unit}",
                plan.selected_stations
                    .iter()
                    .map(|station| format!("{:.1}", range(station.range_yd)))
                    .collect::<Vec<_>>()
                    .join(", ")
            );
            println!(
                "  Constraints: {} stations, minimum separation {:.1} {range_unit}",
                plan.requested_observation_count,
                range(plan.minimum_separation_yd)
            );
            println!();
            println!(
                "  BC sensitivity ratio: {:.5}",
                plan.information.sensitivity_ratio
            );
            println!(
                "  Condition number: {}",
                plan.information
                    .condition_number
                    .map(|value| format!("{value:.2}"))
                    .unwrap_or_else(|| "unbounded".to_string())
            );
            println!(
                "  Singular values: min {:.5}, max {:.5}; weak-axis fractional 1-sigma: {}",
                plan.information.minimum_singular_value,
                plan.information.maximum_singular_value,
                plan.information
                    .weak_axis_fractional_sigma_1sd
                    .map(|value| format!("{value:.4}"))
                    .unwrap_or_else(|| "unbounded".to_string())
            );
            println!();
            println!(
                "  {:>10}  {:>12}  {:>13}  {:>13}  {:>12}",
                format!("Range ({range_unit})"),
                format!("Drop ({})", plan.measurement_drop_unit),
                "MV sensitivity",
                "BC sensitivity",
                "Info (nats)",
            );
            for station in &plan.selected_stations {
                println!(
                    "  {:>10.1}  {:>12.4}  {:>13.5}  {:>13.5}  {:>12.5}",
                    range(station.range_yd),
                    station.predicted_drop,
                    station.scaled_mv_sensitivity,
                    station.scaled_bc_sensitivity,
                    station.leave_one_out_information_gain_nats,
                );
            }
            println!();
            println!(
                "  Search: {} ({} of {} candidate sets evaluated)",
                enum_variant_code(&plan.search_strategy),
                plan.evaluated_design_count,
                plan.raw_combination_count,
            );
            if !plan.rejected_candidates.is_empty() {
                println!("  Rejected candidates:");
                for candidate in &plan.rejected_candidates {
                    let display_range = if candidate.range_yd.is_finite() {
                        format!("{:.1} {range_unit}", range(candidate.range_yd))
                    } else {
                        "non-finite range".to_string()
                    };
                    println!(
                        "    - {display_range}: {} ({})",
                        enum_variant_code(&candidate.reason),
                        candidate.detail
                    );
                }
            }
            if !plan.warnings.is_empty() {
                println!("  Notes:");
                for warning in &plan.warnings {
                    println!("    - {warning}");
                }
            }
            println!();
        }
        OutputFormat::Pdf => {
            return Err("PDF output is not supported for truing experiment plans".into());
        }
    }
    Ok(())
}

/// Render the opt-in MBA-1353 weighted MAP and local Gaussian approximation.
/// The legacy renderer above is deliberately not reused or modified: callers
/// reach this function only after explicitly declaring observation sigma.
fn display_uncertainty_truing_result(
    report: &UncertaintyTruingReportV1,
    units: UnitSystem,
    chrono_fps: Option<f64>,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    let velocity_scale = match units {
        UnitSystem::Imperial => 1.0,
        UnitSystem::Metric => 0.3048,
    };
    let velocity_unit = match units {
        UnitSystem::Imperial => "fps",
        UnitSystem::Metric => "m/s",
    };
    let range_scale = match units {
        UnitSystem::Imperial => 1.0,
        UnitSystem::Metric => 0.9144,
    };
    let range_unit = match units {
        UnitSystem::Imperial => "yd",
        UnitSystem::Metric => "m",
    };
    let drop_unit = report.drop_unit.label();
    let velocity = |fps: f64| fps * velocity_scale;
    let range = |yards: f64| yards * range_scale;

    match output {
        OutputFormat::Json => {
            let observations: Vec<serde_json::Value> = report
                .observations
                .iter()
                .map(|observation| {
                    serde_json::json!({
                        format!("range_{range_unit}"): range(observation.range_yd),
                        format!("observed_drop_{drop_unit}"): observation.observed_drop,
                        format!("sigma_1sd_{drop_unit}"): observation.sigma,
                        format!("predicted_drop_{drop_unit}"): observation.predicted_drop,
                        format!("residual_{drop_unit}"): observation.residual,
                        "standardized_residual": observation.standardized_residual,
                    })
                })
                .collect();
            let priors = serde_json::json!({
                "muzzle_velocity": report.priors.muzzle_velocity_fps.map(|prior| serde_json::json!({
                    "mean": velocity(prior.mean),
                    "sigma_1sd": velocity(prior.sigma),
                    "unit": velocity_unit,
                })),
                "ballistic_coefficient": report.priors.ballistic_coefficient.map(|prior| serde_json::json!({
                    "mean": prior.mean,
                    "sigma_1sd": prior.sigma,
                })),
            });
            let approximation = match &report.approximation {
                TruingApproximationV1::Available(approximation) => {
                    let mv_interval = approximation.muzzle_velocity_interval_95;
                    let bc_interval = approximation.ballistic_coefficient_interval_95;
                    serde_json::json!({
                        "available": true,
                        "method": "laplace_gauss_newton_known_sigma",
                        "interval_probability": mv_interval.probability,
                        "muzzle_velocity": {
                            "estimate": velocity(mv_interval.estimate),
                            "standard_deviation": velocity(mv_interval.standard_deviation),
                            "lower": velocity(mv_interval.lower),
                            "upper": velocity(mv_interval.upper),
                            "unit": velocity_unit,
                        },
                        "ballistic_coefficient": {
                            "estimate": bc_interval.estimate,
                            "standard_deviation": bc_interval.standard_deviation,
                            "lower": bc_interval.lower,
                            "upper": bc_interval.upper,
                        },
                        "covariance": {
                            format!("mv_variance_{velocity_unit}2"): approximation.covariance.mv_variance_fps2 * velocity_scale * velocity_scale,
                            format!("mv_bc_covariance_{velocity_unit}"): approximation.covariance.mv_bc_covariance_fps * velocity_scale,
                            "bc_variance": approximation.covariance.bc_variance,
                        },
                        "mv_bc_correlation": approximation.mv_bc_correlation,
                        "scaled_information_condition_number": approximation.scaled_information_condition_number,
                    })
                }
                TruingApproximationV1::Unavailable(failure) => serde_json::json!({
                    "available": false,
                    "method": "laplace_gauss_newton_known_sigma",
                    "failure": {
                        "code": enum_variant_code(&failure.code),
                        "message": failure.message,
                    },
                }),
            };
            let predictive_bands: Vec<serde_json::Value> = report
                .predictive_bands
                .iter()
                .map(|band| {
                    let interval = |value: ballistics_engine::truing_uncertainty::GaussianIntervalV1| {
                        serde_json::json!({
                            "standard_deviation": value.standard_deviation,
                            "lower": value.lower,
                            "upper": value.upper,
                            "probability": value.probability,
                        })
                    };
                    serde_json::json!({
                        format!("range_{range_unit}"): range(band.range_yd),
                        format!("predicted_drop_{drop_unit}"): band.predicted_drop,
                        "latent_model_drop_interval": band.latent_interval_95.map(interval),
                        "future_observation_interval": band.future_observation_interval_95.map(interval),
                    })
                })
                .collect();
            let warnings: Vec<serde_json::Value> = report
                .warnings
                .iter()
                .map(|warning| {
                    serde_json::json!({
                        "code": enum_variant_code(&warning.code),
                        "message": warning.message,
                    })
                })
                .collect();
            let diagnostics = &report.diagnostics;
            let mut value = serde_json::json!({
                "schema_version": "truing-uncertainty-v1",
                "mode": "joint_mv_bc_map",
                "fitted_muzzle_velocity": velocity(report.map_muzzle_velocity_fps),
                "velocity_unit": velocity_unit,
                "fitted_bc": report.map_ballistic_coefficient,
                "iterations": report.iterations,
                "converged": report.converged,
                "observations": observations,
                "priors": priors,
                "diagnostics": {
                    "chi_square": diagnostics.chi_square,
                    "prior_penalty": diagnostics.prior_penalty,
                    "penalized_chi_square": diagnostics.penalized_chi_square,
                    "effective_parameter_count": diagnostics.effective_parameter_count,
                    "effective_degrees_of_freedom": diagnostics.effective_degrees_of_freedom,
                    "reduced_chi_square": diagnostics.reduced_chi_square,
                    "bc_sensitivity_ratio": diagnostics.bc_sensitivity_ratio,
                    "data_condition_number": if diagnostics.data_condition_number.is_finite() {
                        serde_json::json!(diagnostics.data_condition_number)
                    } else {
                        serde_json::Value::Null
                    },
                    "map_scaled_gradient_inf_norm": diagnostics.map_scaled_gradient_inf_norm,
                    "map_convergence_criterion": diagnostics
                        .map_convergence_criterion
                        .map(|criterion| enum_variant_code(&criterion)),
                    "map_objective_poll_radius": diagnostics.map_objective_poll_radius,
                    "map_max_objective_poll_improvement": diagnostics
                        .map_max_objective_poll_improvement,
                    "map_objective_poll_evaluations": diagnostics
                        .map_objective_poll_evaluations,
                },
                "approximation": approximation,
                "predictive_bands": predictive_bands,
                "warnings": warnings,
                "legend": {
                    "units": {
                        "range": range_unit,
                        "drop": drop_unit,
                        "velocity": velocity_unit,
                    },
                    "observation_sigma": "absolute known one-standard-deviation reading error",
                    "latent_model_drop_interval": "parameter uncertainty only",
                    "future_observation_interval": "parameter uncertainty plus explicitly declared future reading error",
                },
            });
            if let Some(chrono) = chrono_fps {
                value["velocity_adjustment"] =
                    serde_json::json!(velocity(report.map_muzzle_velocity_fps - chrono));
                value["adjustment_percent"] = if chrono != 0.0 {
                    serde_json::json!((report.map_muzzle_velocity_fps - chrono) / chrono * 100.0)
                } else {
                    serde_json::Value::Null
                };
            }
            println!("{}", serde_json::to_string_pretty(&value)?);
        }
        OutputFormat::Csv => {
            let convergence_criterion = report
                .diagnostics
                .map_convergence_criterion
                .map(|criterion| enum_variant_code(&criterion))
                .unwrap_or_default();
            println!("range_{range_unit},observed_drop_{drop_unit},sigma_1sd_{drop_unit},predicted_drop_{drop_unit},residual_{drop_unit},standardized_residual");
            for observation in &report.observations {
                println!(
                    "{:.6},{:.8},{:.8},{:.8},{:.8},{:.8}",
                    range(observation.range_yd),
                    observation.observed_drop,
                    observation.sigma,
                    observation.predicted_drop,
                    observation.residual,
                    observation.standardized_residual,
                );
            }
            println!();
            println!("fitted_muzzle_velocity_{velocity_unit},fitted_bc,chi_square,prior_penalty,penalized_chi_square,effective_parameter_count,effective_degrees_of_freedom,reduced_chi_square,bc_sensitivity_ratio,data_condition_number,converged,map_convergence_criterion,map_scaled_gradient_inf_norm,map_objective_poll_radius,map_max_objective_poll_improvement,map_objective_poll_evaluations");
            println!(
                "{:.8},{:.10},{:.8},{:.8},{:.8},{},{},{},{:.8},{},{},{},{:.10},{},{},{}",
                velocity(report.map_muzzle_velocity_fps),
                report.map_ballistic_coefficient,
                report.diagnostics.chi_square,
                report.diagnostics.prior_penalty,
                report.diagnostics.penalized_chi_square,
                report
                    .diagnostics
                    .effective_parameter_count
                    .map(|value| format!("{value:.8}"))
                    .unwrap_or_default(),
                report
                    .diagnostics
                    .effective_degrees_of_freedom
                    .map(|value| format!("{value:.8}"))
                    .unwrap_or_default(),
                report
                    .diagnostics
                    .reduced_chi_square
                    .map(|value| format!("{value:.8}"))
                    .unwrap_or_default(),
                report.diagnostics.bc_sensitivity_ratio,
                if report.diagnostics.data_condition_number.is_finite() {
                    format!("{:.8}", report.diagnostics.data_condition_number)
                } else {
                    "inf".to_string()
                },
                report.converged,
                convergence_criterion,
                report.diagnostics.map_scaled_gradient_inf_norm,
                report
                    .diagnostics
                    .map_objective_poll_radius
                    .map(|value| format!("{value:.10}"))
                    .unwrap_or_default(),
                report
                    .diagnostics
                    .map_max_objective_poll_improvement
                    .map(|value| format!("{value:.10}"))
                    .unwrap_or_default(),
                report.diagnostics.map_objective_poll_evaluations,
            );
            println!();
            println!("prior_parameter,mean,sigma_1sd,unit");
            if let Some(prior) = report.priors.muzzle_velocity_fps {
                println!(
                    "muzzle_velocity,{:.8},{:.8},{velocity_unit}",
                    velocity(prior.mean),
                    velocity(prior.sigma)
                );
            }
            if let Some(prior) = report.priors.ballistic_coefficient {
                println!(
                    "ballistic_coefficient,{:.10},{:.10},dimensionless",
                    prior.mean, prior.sigma
                );
            }
            println!();
            match &report.approximation {
                TruingApproximationV1::Available(approximation) => {
                    println!("parameter,estimate,standard_deviation,interval_95_lower,interval_95_upper,interval_probability,unit");
                    let mv = approximation.muzzle_velocity_interval_95;
                    let bc = approximation.ballistic_coefficient_interval_95;
                    println!(
                        "muzzle_velocity,{:.8},{:.8},{:.8},{:.8},{:.6},{velocity_unit}",
                        velocity(mv.estimate),
                        velocity(mv.standard_deviation),
                        velocity(mv.lower),
                        velocity(mv.upper),
                        mv.probability,
                    );
                    println!(
                        "ballistic_coefficient,{:.10},{:.10},{:.10},{:.10},{:.6},dimensionless",
                        bc.estimate, bc.standard_deviation, bc.lower, bc.upper, bc.probability,
                    );
                    println!();
                    println!("covariance_component,value");
                    println!(
                        "mv_variance_{velocity_unit}2,{:.12}",
                        approximation.covariance.mv_variance_fps2 * velocity_scale * velocity_scale
                    );
                    println!(
                        "mv_bc_covariance_{velocity_unit},{:.12}",
                        approximation.covariance.mv_bc_covariance_fps * velocity_scale
                    );
                    println!("bc_variance,{:.12}", approximation.covariance.bc_variance);
                    println!("mv_bc_correlation,{:.12}", approximation.mv_bc_correlation);
                    println!(
                        "scaled_information_condition_number,{:.12}",
                        approximation.scaled_information_condition_number
                    );
                }
                TruingApproximationV1::Unavailable(failure) => {
                    println!("approximation_failure_code,message");
                    println!(
                        "{},{}",
                        enum_variant_code(&failure.code),
                        failure.message.replace(',', ";").replace('\n', " ")
                    );
                }
            }
            if !report.predictive_bands.is_empty() {
                println!();
                println!("prediction_range_{range_unit},predicted_drop_{drop_unit},latent_lower_{drop_unit},latent_upper_{drop_unit},future_lower_{drop_unit},future_upper_{drop_unit}");
                for band in &report.predictive_bands {
                    println!(
                        "{:.6},{:.8},{},{},{},{}",
                        range(band.range_yd),
                        band.predicted_drop,
                        band.latent_interval_95
                            .map(|interval| format!("{:.8}", interval.lower))
                            .unwrap_or_default(),
                        band.latent_interval_95
                            .map(|interval| format!("{:.8}", interval.upper))
                            .unwrap_or_default(),
                        band.future_observation_interval_95
                            .map(|interval| format!("{:.8}", interval.lower))
                            .unwrap_or_default(),
                        band.future_observation_interval_95
                            .map(|interval| format!("{:.8}", interval.upper))
                            .unwrap_or_default(),
                    );
                }
            }
            if !report.warnings.is_empty() {
                println!();
                println!("warning_code,message");
                for warning in &report.warnings {
                    println!(
                        "{},{}",
                        enum_variant_code(&warning.code),
                        warning.message.replace(',', ";").replace('\n', " ")
                    );
                }
            }
        }
        OutputFormat::Table => {
            println!();
            println!("=== UNCERTAINTY-AWARE MV + BC TRUING ===");
            println!("  Method: weighted joint MAP + local Gaussian approximation");
            println!("  Observation errors: absolute known 1-sigma ({drop_unit})");
            println!();
            println!(
                "  MAP muzzle velocity: {:>10.2} {velocity_unit}",
                velocity(report.map_muzzle_velocity_fps)
            );
            println!(
                "  MAP ballistic coefficient: {:>8.5}",
                report.map_ballistic_coefficient
            );
            match &report.approximation {
                TruingApproximationV1::Available(approximation) => {
                    let mv = approximation.muzzle_velocity_interval_95;
                    let bc = approximation.ballistic_coefficient_interval_95;
                    println!(
                        "  MV 95% interval: [{:.2}, {:.2}] {velocity_unit} (SD {:.2})",
                        velocity(mv.lower),
                        velocity(mv.upper),
                        velocity(mv.standard_deviation)
                    );
                    println!(
                        "  BC 95% interval: [{:.5}, {:.5}] (SD {:.5})",
                        bc.lower, bc.upper, bc.standard_deviation
                    );
                    println!(
                        "  MV/BC correlation: {:+.5}",
                        approximation.mv_bc_correlation
                    );
                }
                TruingApproximationV1::Unavailable(failure) => {
                    println!(
                        "  Gaussian approximation: unavailable ({})",
                        enum_variant_code(&failure.code)
                    );
                    println!("    {}", failure.message);
                }
            }
            println!();
            println!(
                "  {:>10}  {:>12}  {:>9}  {:>12}  {:>10}",
                format!("Range ({range_unit})"),
                format!("Observed ({drop_unit})"),
                "Sigma",
                format!("Predicted ({drop_unit})"),
                "Std resid",
            );
            for observation in &report.observations {
                println!(
                    "  {:>10.1}  {:>12.4}  {:>9.4}  {:>12.4}  {:>+10.3}",
                    range(observation.range_yd),
                    observation.observed_drop,
                    observation.sigma,
                    observation.predicted_drop,
                    observation.standardized_residual,
                );
            }
            println!();
            println!(
                "  Chi-square: {:.3}; effective DOF: {}; reduced chi-square: {}",
                report.diagnostics.chi_square,
                report
                    .diagnostics
                    .effective_degrees_of_freedom
                    .map(|value| format!("{value:.3}"))
                    .unwrap_or_else(|| "unavailable".to_string()),
                report
                    .diagnostics
                    .reduced_chi_square
                    .map(|value| format!("{value:.3}"))
                    .unwrap_or_else(|| "unavailable".to_string()),
            );
            if !report.predictive_bands.is_empty() {
                println!();
                println!("  Predictive drop bands (95%):");
                for band in &report.predictive_bands {
                    let latent = band
                        .latent_interval_95
                        .map(|interval| format!("[{:.4}, {:.4}]", interval.lower, interval.upper))
                        .unwrap_or_else(|| "unavailable".to_string());
                    let future = band
                        .future_observation_interval_95
                        .map(|interval| {
                            format!("; future [{:.4}, {:.4}]", interval.lower, interval.upper)
                        })
                        .unwrap_or_default();
                    println!(
                        "    {:>8.1} {range_unit}: mean {:.4} {drop_unit}; model {latent}{future}",
                        range(band.range_yd),
                        band.predicted_drop,
                    );
                }
            }
            if !report.warnings.is_empty() {
                println!();
                println!("  Warnings:");
                for warning in &report.warnings {
                    println!(
                        "    - {}: {}",
                        enum_variant_code(&warning.code),
                        warning.message
                    );
                }
            }
            println!();
        }
        OutputFormat::Pdf => {
            return Err("PDF output is not supported for uncertainty-aware truing".into());
        }
    }
    Ok(())
}

// ============================================================================
// MPBR, Come-Ups, Wind Card Handler Functions
// ============================================================================

/// MBA-1359: convert a `--zero-poi-up`/`--zero-poi-right` CLI value (inches for imperial,
/// centimeters for metric — Kestrel-style small POI offsets) to meters.
fn zero_poi_display_to_metric(value: f64, units: UnitSystem) -> f64 {
    match units {
        UnitSystem::Imperial => value * 0.0254, // inches -> meters
        UnitSystem::Metric => value * 0.01,     // centimeters -> meters
    }
}

/// MBA-1396: convert a `--sight-offset` CLI value (inches for imperial, millimeters for
/// metric — mount geometry, same units as `--sight-height`) to meters.
fn sight_offset_display_to_metric(value: f64, units: UnitSystem) -> f64 {
    match units {
        UnitSystem::Imperial => value * 0.0254, // inches -> meters
        UnitSystem::Metric => value * 0.001,    // millimeters -> meters
    }
}

/// Resolve bullet parameters: CLI arg overrides profile value
fn resolve_param(
    cli_val: Option<f64>,
    profile: &Option<ProfileData>,
    getter: fn(&ProfileData) -> f64,
) -> Option<f64> {
    cli_val.or_else(|| profile.as_ref().map(getter))
}

/// MPBR handler
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable MPBR CLI command shape"
)]
fn handle_mpbr(
    velocity: f64,
    bc: f64,
    mass: f64,
    diameter: f64,
    drag_model: DragModel,
    vital_zone: f64,   // in user units (inches or cm)
    sight_height: f64, // in user units
    // MBA-1359: deliberate POI offset at the zero range, METERS (already resolved
    // CLI-over-profile and converted by the dispatch). Biases every candidate zero.
    zero_poi_vertical_m: f64,
    zero_poi_horizontal_m: f64,
    // MBA-1396: lateral sight-mount offset, METERS (y-uncoupled physical geometry; rides
    // through the vertical vital-zone analysis unchanged).
    sight_offset_lateral_m: f64,
    temperature: f64,
    pressure: f64,
    humidity: f64,
    altitude: f64,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    // Convert everything to metric
    let velocity_m = UnitConverter::velocity_to_metric(velocity, units);
    let mass_kg = UnitConverter::mass_to_metric(mass, units);
    let diameter_m = UnitConverter::diameter_to_metric(diameter, units);
    let sight_height_m = UnitConverter::sight_height_to_metric(sight_height, units);
    let temperature_c = UnitConverter::temperature_to_metric(temperature, units);
    let pressure_hpa = UnitConverter::pressure_to_metric(pressure, units);
    let altitude_m = UnitConverter::altitude_to_metric(altitude, units);

    // Vital zone to meters
    let vital_zone_m = match units {
        UnitSystem::Imperial => vital_zone * 0.0254, // inches to meters
        UnitSystem::Metric => vital_zone * 0.01,     // cm to meters
    };
    let half_vital_m = vital_zone_m / 2.0;

    // Binary search on zero distance to find the one where max ordinate ≈ half vital zone
    let mut zero_low_m = UnitConverter::distance_to_metric(50.0, units);
    let mut zero_high_m = UnitConverter::distance_to_metric(2000.0, units);
    let tolerance_m = 0.001; // ~0.04 inches
    let max_iter = 60;

    let mut best_zero_m = 0.0;
    let mut best_max_ord_m = 0.0;
    let mut best_max_ord_dist_m = 0.0;

    for _ in 0..max_iter {
        let test_zero_m = (zero_low_m + zero_high_m) / 2.0;

        // Create inputs for zero calculation at test_zero_m
        let drag_model_enum = drag_model;

        let zero_inputs = BallisticInputs {
            bc_value: bc,
            bc_type: drag_model_enum,
            bullet_mass: mass_kg,
            muzzle_velocity: velocity_m,
            bullet_diameter: diameter_m,
            bullet_length: fallback_bullet_length_m(diameter_m, mass_kg),
            sight_height: sight_height_m,
            use_rk4: true,
            zero_poi_vertical_m,
            zero_poi_horizontal_m,
            sight_offset_lateral_m,
            ..Default::default()
        };

        let atmosphere = AtmosphericConditions {
            temperature: temperature_c,
            pressure: pressure_hpa,
            humidity,
            altitude: altitude_m,
        };

        let zero_angle = match ballistics_engine::calculate_zero_angle_with_conditions(
            zero_inputs,
            test_zero_m,
            sight_height_m,
            WindConditions::default(),
            atmosphere,
        ) {
            Ok(a) => a,
            Err(_) => {
                zero_high_m = test_zero_m;
                continue;
            }
        };

        // Run trajectory with this zero, sampling every ~1 yard
        let samples = match run_sampled_trajectory(
            velocity_m,
            bc,
            mass_kg,
            diameter_m,
            drag_model,
            sight_height_m,
            temperature_c,
            pressure_hpa,
            humidity,
            altitude_m,
            0.0,
            0.0,
            test_zero_m * 1.5, // max range past zero
            UnitConverter::distance_to_metric(1.0, UnitSystem::Imperial), // ~1 yd sample interval
            zero_angle,
            // MPBR does not yet consume saved-profile bc_segments/drag_curve (MBA-1323
            // Phase 2 follow-up) — see CLI_USAGE.md's a7p import section.
            None,
            None,
            None,
            zero_poi_vertical_m,
            zero_poi_horizontal_m,
            sight_offset_lateral_m,
            Some(test_zero_m),
        ) {
            Ok(s) => s,
            Err(_) => {
                zero_high_m = test_zero_m;
                continue;
            }
        };

        // Find max ordinate (highest point above LOS)
        // drop_m in samples is relative to LOS (negative = below LOS, but in the coordinate system
        // the y-position grows then drops, so we need to find max height above LOS)
        // Actually, drop_m is the height of the bullet relative to line of sight at that distance
        // At the zero crossing: drop_m ≈ 0. Between muzzle and zero, drop_m > 0 (above LOS).
        // Beyond zero, drop_m < 0 (below LOS).
        // NOTE: In the sampling system, drop_m is defined as bullet_y - los_y, so positive = above LOS
        let mut max_ord_m: f64 = 0.0;
        let mut max_ord_dist_m: f64 = 0.0;
        for s in &samples {
            // drop_m is the drop value; when bullet is above LOS, this value represents height above LOS
            // In the sampling code, drop_m = bullet_y - line_of_sight_y
            // When zeroed, the bullet rises above LOS then falls back.
            // A negative drop_m means below LOS. We want the max POSITIVE value (highest above LOS).
            let height_above_los = -s.drop_m; // drop_m is negative when above LOS in standard convention
            if height_above_los > max_ord_m {
                max_ord_m = height_above_los;
                max_ord_dist_m = s.distance_m;
            }
        }

        // Check: if max_ord is 0 but we have points above bore, try the other sign convention
        if max_ord_m < 0.001 {
            // Try positive drop_m as "above LOS"
            for s in &samples {
                if s.drop_m > max_ord_m {
                    max_ord_m = s.drop_m;
                    max_ord_dist_m = s.distance_m;
                }
            }
        }

        best_zero_m = test_zero_m;
        best_max_ord_m = max_ord_m;
        best_max_ord_dist_m = max_ord_dist_m;

        let diff = max_ord_m - half_vital_m;
        if diff.abs() < tolerance_m {
            break;
        }

        if max_ord_m > half_vital_m {
            // Max ordinate too high → zero closer (reduce zero distance)
            zero_high_m = test_zero_m;
        } else {
            // Max ordinate too low → zero farther (increase zero distance)
            zero_low_m = test_zero_m;
        }
    }

    // Now run the final trajectory at optimal zero to find MPBR, near zero, far zero
    let drag_model_enum = drag_model;

    let final_inputs = BallisticInputs {
        bc_value: bc,
        bc_type: drag_model_enum,
        bullet_mass: mass_kg,
        muzzle_velocity: velocity_m,
        bullet_diameter: diameter_m,
        bullet_length: fallback_bullet_length_m(diameter_m, mass_kg),
        sight_height: sight_height_m,
        use_rk4: true,
        zero_poi_vertical_m,
        zero_poi_horizontal_m,
        sight_offset_lateral_m,
        ..Default::default()
    };

    let atmosphere = AtmosphericConditions {
        temperature: temperature_c,
        pressure: pressure_hpa,
        humidity,
        altitude: altitude_m,
    };

    let final_zero_angle = ballistics_engine::calculate_zero_angle_with_conditions(
        final_inputs,
        best_zero_m,
        sight_height_m,
        WindConditions::default(),
        atmosphere,
    )?;

    let final_samples = run_sampled_trajectory(
        velocity_m,
        bc,
        mass_kg,
        diameter_m,
        drag_model,
        sight_height_m,
        temperature_c,
        pressure_hpa,
        humidity,
        altitude_m,
        0.0,
        0.0,
        best_zero_m * 2.0,
        UnitConverter::distance_to_metric(1.0, UnitSystem::Imperial),
        final_zero_angle,
        None,
        None,
        None,
        zero_poi_vertical_m,
        zero_poi_horizontal_m,
        sight_offset_lateral_m,
        Some(best_zero_m),
    )?;

    // Find near zero crossing (first time trajectory crosses from below LOS to above)
    // Find far zero crossing (where trajectory drops back to LOS)
    // Find MPBR (where drop exceeds -half_vital_m)
    let mut near_zero_m: f64 = 0.0;
    let mut far_zero_m: f64 = 0.0;
    let mut mpbr_m: f64 = 0.0;
    let mut impact_vel_mps: f64 = 0.0;
    let mut impact_energy_j: f64 = 0.0;
    let mut found_near = false;
    let mut found_far = false;

    // Determine sign convention by checking if samples near the midpoint are positive or negative
    // The bullet should be ABOVE LOS in the middle of the trajectory
    let sign_flip = if final_samples.len() > 10 {
        let mid = &final_samples[final_samples.len() / 3];
        mid.drop_m < 0.0 // if drop_m is negative in the middle, we need to flip sign
    } else {
        false
    };

    for i in 1..final_samples.len() {
        let prev_drop = if sign_flip {
            -final_samples[i - 1].drop_m
        } else {
            final_samples[i - 1].drop_m
        };
        let curr_drop = if sign_flip {
            -final_samples[i].drop_m
        } else {
            final_samples[i].drop_m
        };

        // Near zero: trajectory goes from negative/zero to positive (crossing LOS upward)
        if !found_near && prev_drop <= 0.0 && curr_drop > 0.0 && final_samples[i].distance_m > 5.0 {
            // Interpolate
            let frac = (-prev_drop) / (curr_drop - prev_drop);
            near_zero_m = final_samples[i - 1].distance_m
                + frac * (final_samples[i].distance_m - final_samples[i - 1].distance_m);
            found_near = true;
        }

        // Far zero: trajectory goes from positive to negative (crossing LOS downward)
        if found_near && !found_far && prev_drop > 0.0 && curr_drop <= 0.0 {
            let frac = prev_drop / (prev_drop - curr_drop);
            far_zero_m = final_samples[i - 1].distance_m
                + frac * (final_samples[i].distance_m - final_samples[i - 1].distance_m);
            found_far = true;
        }

        // MPBR: where drop goes below -half_vital_m
        if found_far && curr_drop < -half_vital_m && mpbr_m == 0.0 {
            let frac = (-half_vital_m - prev_drop) / (curr_drop - prev_drop);
            mpbr_m = final_samples[i - 1].distance_m
                + frac * (final_samples[i].distance_m - final_samples[i - 1].distance_m);
            impact_vel_mps = final_samples[i].velocity_mps;
            impact_energy_j = final_samples[i].energy_j;
        }
    }

    // Convert outputs for display
    let mpbr_display = UnitConverter::distance_from_metric(mpbr_m, units);
    let optimal_zero_display = UnitConverter::distance_from_metric(best_zero_m, units);
    let near_zero_display = UnitConverter::distance_from_metric(near_zero_m, units);
    let far_zero_display = UnitConverter::distance_from_metric(far_zero_m, units);
    let max_ord_display = match units {
        UnitSystem::Imperial => best_max_ord_m / 0.0254, // meters to inches
        UnitSystem::Metric => best_max_ord_m * 100.0,    // meters to cm
    };
    let max_ord_dist_display = UnitConverter::distance_from_metric(best_max_ord_dist_m, units);
    let impact_vel_display = UnitConverter::velocity_from_metric(impact_vel_mps, units);
    let impact_energy_display = UnitConverter::energy_from_metric(impact_energy_j, units);

    let (dist_unit, vel_unit, energy_unit, size_unit) = match units {
        UnitSystem::Imperial => ("yd", "fps", "ft-lb", "in"),
        UnitSystem::Metric => ("m", "m/s", "J", "cm"),
    };

    let vital_zone_display = match units {
        UnitSystem::Imperial => vital_zone, // already in inches
        UnitSystem::Metric => vital_zone,   // already in cm
    };

    match output {
        OutputFormat::Json => {
            let json = serde_json::json!({
                "mpbr": mpbr_display,
                "mpbr_unit": dist_unit,
                "optimal_zero": optimal_zero_display,
                "near_zero": near_zero_display,
                "far_zero": far_zero_display,
                "max_ordinate": max_ord_display,
                "max_ordinate_unit": size_unit,
                "max_ordinate_distance": max_ord_dist_display,
                "impact_velocity": impact_vel_display,
                "impact_velocity_unit": vel_unit,
                "impact_energy": impact_energy_display,
                "impact_energy_unit": energy_unit,
                "vital_zone": vital_zone_display,
                "vital_zone_unit": size_unit,
            });
            println!("{}", serde_json::to_string_pretty(&json)?);
        }
        OutputFormat::Csv => {
            println!("metric,value,unit");
            println!("mpbr,{:.1},{}", mpbr_display, dist_unit);
            println!("optimal_zero,{:.1},{}", optimal_zero_display, dist_unit);
            println!("near_zero,{:.1},{}", near_zero_display, dist_unit);
            println!("far_zero,{:.1},{}", far_zero_display, dist_unit);
            println!("max_ordinate,{:.1},{}", max_ord_display, size_unit);
            println!(
                "max_ordinate_distance,{:.1},{}",
                max_ord_dist_display, dist_unit
            );
            println!("impact_velocity,{:.0},{}", impact_vel_display, vel_unit);
            println!("impact_energy,{:.0},{}", impact_energy_display, energy_unit);
        }
        OutputFormat::Table | OutputFormat::Pdf => {
            println!();
            println!(
                "MPBR Analysis (vital zone: {:.1} {})",
                vital_zone_display, size_unit
            );
            println!("╔════════════════════════════════════════╗");
            println!(
                "║  MPBR:            {:>6.0} {:<14}║",
                mpbr_display, dist_unit
            );
            println!(
                "║  Optimal zero:    {:>6.0} {:<14}║",
                optimal_zero_display, dist_unit
            );
            println!(
                "║  Near zero:       {:>6.0} {:<14}║",
                near_zero_display, dist_unit
            );
            println!(
                "║  Far zero:        {:>6.0} {:<14}║",
                far_zero_display, dist_unit
            );
            println!(
                "║  Max ordinate:    {:>6.1} {} at {:.0} {}  ║",
                max_ord_display, size_unit, max_ord_dist_display, dist_unit
            );
            println!(
                "║  Impact velocity: {:>6.0} {:<14}║",
                impact_vel_display, vel_unit
            );
            println!(
                "║  Impact energy:   {:>6.0} {:<14}║",
                impact_energy_display, energy_unit
            );
            println!("╚════════════════════════════════════════╝");
        }
    }

    Ok(())
}

/// Read one card row's sample off a solved flight, or fail loudly (MBA-1476).
///
/// The four card surfaces (`come-ups`, `range-table`, `wind-card`, `compare`) used to pick
/// the sample NEAREST the requested range out of a grid whose spacing was the card's own
/// `--step`, accepting anything within one and a half whole steps. That grid is anchored at
/// zero, so any card whose `--start` was not a multiple of its `--step` had every row sitting
/// between two samples, and the row then reported a neighbouring range's drop, drift,
/// velocity and time with nothing in the output to say so. Sampling is now on the engine's
/// own [`CARD_SAMPLE_INTERVAL_M`] grid, independent of the requested rows, and the value at a
/// range is interpolated exactly at that range — so a range's row is the same row on every
/// card that contains it, whatever `--start`, `--end` and `--step` were.
///
/// A range the solved flight does not span yields `None`: never a substitution, and never a
/// row quietly dropped. The card ends there, prints the rows it does have, and says so — see
/// [`CardTruncation`] and `warn_card_truncated`.
fn card_row_sample(
    samples: &[trajectory_sampling::TrajectorySample],
    range_display: f64,
    units: UnitSystem,
) -> Option<trajectory_sampling::TrajectorySample> {
    sample_at_range(
        samples,
        UnitConverter::distance_to_metric(range_display, units),
    )
}

/// The label a card prints its ranges in.
fn card_distance_unit(units: UnitSystem) -> &'static str {
    match units {
        UnitSystem::Imperial => "yd",
        UnitSystem::Metric => "m",
    }
}

/// Build the truncation record for a card whose row loop stopped early (MBA-1476 follow-up).
///
/// `reach_m` is the solved flight's own terminal distance, so the figure the shooter is told
/// is a property of the load and not of the `--end` they happened to type.
fn card_truncation(
    requested_end: f64,
    last_row: f64,
    reach_m: f64,
    units: UnitSystem,
) -> CardTruncation {
    CardTruncation {
        requested_end,
        last_row,
        reach: UnitConverter::distance_from_metric(reach_m, units),
    }
}

/// A card whose flight reaches NONE of its rows has nothing to print, so it stays a refusal
/// (MBA-1476 follow-up) — naming the first row it could not supply and how far the load flew.
fn card_no_rows_error(first_row: f64, reach_m: f64, units: UnitSystem) -> Box<dyn Error> {
    Box::<dyn Error>::from(range_not_sampled_message(
        first_row,
        UnitConverter::distance_from_metric(reach_m, units),
        card_distance_unit(units),
    ))
}

/// Tell a CLI reader, visibly, that the card they are looking at stops short of what they
/// asked for. stderr keeps `-o csv`/`-o json` stdout machine-clean; those two formats also
/// carry the same facts as structured data (`card_truncation_json`), because a truncation a
/// caller cannot detect is its own silent failure.
fn warn_card_truncated(truncation: &CardTruncation, units: UnitSystem) {
    eprintln!("warning: {}", truncation.message(card_distance_unit(units)));
}

/// The machine-readable half of the same notice, for the JSON card surfaces. Emitted ONLY on
/// a truncated card, so an untruncated one is byte-identical to before.
fn card_truncation_json(truncation: &CardTruncation, units: UnitSystem) -> serde_json::Value {
    serde_json::json!({
        "requested_end": truncation.requested_end,
        "last_row": truncation.last_row,
        "reach": truncation.reach,
        "message": truncation.message(card_distance_unit(units)),
    })
}

/// Come-ups handler
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable come-ups CLI command shape"
)]
fn handle_come_ups(
    velocity: f64,
    bc: f64,
    mass: f64,
    diameter: f64,
    drag_model: DragModel,
    zero_distance: f64,
    start: f64,
    end: f64,
    step: f64,
    adjustment_unit: AdjustmentUnit,
    // Resolved turret elevation click graduation for `--adjustment-unit clicks` (MBA-1355):
    // Some(...) iff adjustment_unit == Clicks (resolved once, eagerly, in the ComeUps
    // command's dispatch — see resolve_click_values); None otherwise.
    elevation_click: Option<ClickValue>,
    // MBA-1358: elevation-axis tracking CF (resolved flag-over-profile by the
    // dispatch); the come-up column's dial values are divided by it exactly once via
    // adjustment_display.
    elevation_cf: f64,
    // MBA-1360: the selected zero set's elevation dial correction (MILs; 0.0 = no set),
    // added to the true angular need BEFORE the CF division, at the same shared
    // adjustment_display boundary.
    zero_set_elevation_bias_mil: f64,
    sight_height: f64,
    // MBA-1359: deliberate POI offset at the zero range, METERS (already resolved
    // CLI-over-profile and converted by the dispatch).
    zero_poi_vertical_m: f64,
    zero_poi_horizontal_m: f64,
    // MBA-1396: lateral sight-mount offset, METERS (lateral-only; the elevation table is
    // unaffected, but the solve carries the true geometry).
    sight_offset_lateral_m: f64,
    temperature: f64,
    pressure: f64,
    humidity: f64,
    altitude: f64,
    wind_speed: f64,
    wind_direction: f64,
    units: UnitSystem,
    output: OutputFormat,
    // MBA-1323 Phase 2: saved-profile velocity-BC segments / Mach-Cd drag curve, already
    // resolved to engine shapes by the caller. See build_trajectory_components's doc comment.
    bc_segments_data: Option<Vec<BCSegmentData>>,
    custom_drag_table: Option<ballistics_engine::drag::DragTable>,
    // MBA-1357: saved profile's DSF table, already validated by the caller. `Some` only
    // when --profile pointed at a profile carrying dsf_points.
    dsf_table: Option<DsfTable>,
) -> Result<(), Box<dyn Error>> {
    // Convert to metric
    let velocity_m = UnitConverter::velocity_to_metric(velocity, units);
    let mass_kg = UnitConverter::mass_to_metric(mass, units);
    let diameter_m = UnitConverter::diameter_to_metric(diameter, units);
    let sight_height_m = UnitConverter::sight_height_to_metric(sight_height, units);
    let zero_distance_m = UnitConverter::distance_to_metric(zero_distance, units);
    let temperature_c = UnitConverter::temperature_to_metric(temperature, units);
    let pressure_hpa = UnitConverter::pressure_to_metric(pressure, units);
    let altitude_m = UnitConverter::altitude_to_metric(altitude, units);
    let wind_speed_m = UnitConverter::wind_to_metric(wind_speed, units);
    let end_m = UnitConverter::distance_to_metric(end, units);

    // Calculate zero angle
    let drag_model_enum = drag_model;

    // The zero-angle solve must use the SAME velocity-keyed BC / drag curve as the flight
    // below it (otherwise a segment or curve that changes early-flight drag would mis-zero
    // the shot) — same reasoning as the `trajectory` command's shared resolution.
    let zero_inputs = BallisticInputs {
        bc_value: bc,
        bc_type: drag_model_enum,
        bullet_mass: mass_kg,
        muzzle_velocity: velocity_m,
        bullet_diameter: diameter_m,
        bullet_length: fallback_bullet_length_m(diameter_m, mass_kg),
        sight_height: sight_height_m,
        use_rk4: true,
        use_bc_segments: bc_segments_data.is_some(),
        bc_segments_data: bc_segments_data.clone(),
        custom_drag_table: custom_drag_table.clone(),
        zero_poi_vertical_m,
        zero_poi_horizontal_m,
        sight_offset_lateral_m,
        ..Default::default()
    };

    let atmosphere = AtmosphericConditions {
        temperature: temperature_c,
        pressure: pressure_hpa,
        humidity,
        altitude: altitude_m,
    };

    let zero_angle = ballistics_engine::calculate_zero_angle_with_conditions(
        zero_inputs,
        zero_distance_m,
        sight_height_m,
        WindConditions::default(),
        atmosphere,
    )?;

    // Run trajectory with sampling
    let flight = run_sampled_flight(
        velocity_m,
        bc,
        mass_kg,
        diameter_m,
        drag_model,
        sight_height_m,
        temperature_c,
        pressure_hpa,
        humidity,
        altitude_m,
        wind_speed_m,
        wind_direction, // degrees, converted internally
        // MBA-1476: at least one whole grid cell past the last row asked for — see
        // card_sample_max_range_m for why that headroom decides reachability.
        card_sample_max_range_m(end_m),
        // MBA-1476: the engine's own card grid, never the requested row spacing.
        CARD_SAMPLE_INTERVAL_M,
        zero_angle,
        bc_segments_data,
        custom_drag_table,
        dsf_table.as_ref(),
        zero_poi_vertical_m,
        zero_poi_horizontal_m,
        sight_offset_lateral_m,
        Some(zero_distance_m),
    )?;

    // Build output rows at the requested range intervals
    let adj_label = match adjustment_unit {
        AdjustmentUnit::Mil => "MIL",
        AdjustmentUnit::Moa => "MOA",
        AdjustmentUnit::Smoa => "SMOA",
        AdjustmentUnit::Iphy => "IPHY",
        AdjustmentUnit::Clicks => "CLICKS",
    };

    let (dist_unit, vel_unit, energy_unit) = match units {
        UnitSystem::Imperial => ("yd", "fps", "ft-lb"),
        UnitSystem::Metric => ("m", "m/s", "J"),
    };

    let mut rows: Vec<CardRow> = Vec::new();
    let mut truncation: Option<CardTruncation> = None;
    let mut current_range = start;
    let mut prev_drop_adj: f64 = 0.0;

    while current_range <= end + 0.1 {
        let Some(sample) = card_row_sample(&flight.samples, current_range, units) else {
            // MBA-1476 follow-up: the rows the flight DOES reach are still the shooter's
            // card. Stop here, print them, and say what was left out.
            let Some(last) = rows.last() else {
                return Err(card_no_rows_error(current_range, flight.reach_m, units));
            };
            truncation = Some(card_truncation(end, last.range, flight.reach_m, units));
            break;
        };
        let drop_yd = UnitConverter::distance_from_metric(sample.drop_m, units);
        // MBA-1476: the row's OWN range — the angular conversion divides by the distance
        // the row is labelled with, not by some nearby sample's.
        let drop_adj = adjustment_display(
            drop_yd,
            current_range,
            adjustment_unit,
            elevation_click,
            zero_set_elevation_bias_mil,
            elevation_cf,
        )
        .value;
        let come_up = drop_adj - prev_drop_adj;

        rows.push(CardRow {
            range: current_range,
            drop_linear: None,
            drop_adj: Some(drop_adj),
            come_up: Some(come_up),
            wind_linear: None,
            wind_adj: None,
            velocity: Some(UnitConverter::velocity_from_metric(
                sample.velocity_mps,
                units,
            )),
            energy: Some(UnitConverter::energy_from_metric(sample.energy_j, units)),
            time: Some(sample.time_s),
            lead_adj: None,
            wind_columns: Vec::new(),
        });

        prev_drop_adj = drop_adj;
        current_range += step;
    }

    match output {
        OutputFormat::Json => {
            let json_rows: Vec<serde_json::Value> = rows
                .iter()
                .map(|r| {
                    serde_json::json!({
                        "range": r.range,
                        "drop": r.drop_adj,
                        "come_up": r.come_up,
                        "velocity": r.velocity,
                        "energy": r.energy,
                        "time": r.time,
                    })
                })
                .collect();
            let mut json = serde_json::json!({
                "zero_distance": zero_distance,
                "adjustment_unit": adj_label,
                "distance_unit": dist_unit,
                "velocity_unit": vel_unit,
                "energy_unit": energy_unit,
                "data": json_rows,
            });
            if let Some(truncation) = &truncation {
                json["truncated"] = card_truncation_json(truncation, units);
            }
            println!("{}", serde_json::to_string_pretty(&json)?);
        }
        OutputFormat::Csv => {
            println!(
                "range_{},drop_{},come_up_{},velocity_{},energy_{},time_s",
                dist_unit,
                adj_label.to_lowercase(),
                adj_label.to_lowercase(),
                vel_unit,
                energy_unit
            );
            // MBA-1355: clicks are whole numbers — drop the 3-decimal formatting used by
            // every angular unit so a clicks CSV doesn't print "10.000".
            let is_clicks = matches!(adjustment_unit, AdjustmentUnit::Clicks);
            for r in &rows {
                if is_clicks {
                    println!(
                        "{:.0},{:.0},{:.0},{:.0},{:.0},{:.3}",
                        r.range,
                        r.drop_adj.unwrap(),
                        r.come_up.unwrap(),
                        r.velocity.unwrap(),
                        r.energy.unwrap(),
                        r.time.unwrap()
                    );
                } else {
                    println!(
                        "{:.0},{:.3},{:.3},{:.0},{:.0},{:.3}",
                        r.range,
                        r.drop_adj.unwrap(),
                        r.come_up.unwrap(),
                        r.velocity.unwrap(),
                        r.energy.unwrap(),
                        r.time.unwrap()
                    );
                }
            }
        }
        OutputFormat::Table | OutputFormat::Pdf => {
            println!();
            println!(
                "Come-Up Table (zero: {:.0} {}, {})",
                zero_distance, dist_unit, adj_label
            );
            // MBA-1355 Task 2 fix pass: the Drop column's border/data width grows with
            // the adjustment label so "Drop (SMOA)"/"Drop (IPHY)" (4 chars) and
            // "Drop (CLICKS)" (6 chars) no longer overflow the original 3-char-label
            // (MIL/MOA) column. MIL/MOA keep the original 10-wide column exactly —
            // `come_up_drop_label_width` floors at 3 — so `default_trajectory_header_is_stable`
            // stays byte-identical.
            let drop_label_w = come_up_drop_label_width(adj_label);
            let drop_dashes = "─".repeat(drop_label_w + 7);
            let ten = "─".repeat(10);
            println!("┌{ten}┬{drop_dashes}┬{ten}┬{ten}┬{ten}┬{ten}┐");
            println!("{}", come_up_header_line(dist_unit, adj_label, vel_unit));
            println!("├{ten}┼{drop_dashes}┼{ten}┼{ten}┼{ten}┼{ten}┤");
            // MBA-1355: clicks are whole numbers — the Drop/Come-Up columns drop the
            // 3-decimal formatting used by every angular unit so the table shows clean
            // integer click counts instead of e.g. "10.000".
            let is_clicks = matches!(adjustment_unit, AdjustmentUnit::Clicks);
            let drop_field_w = drop_label_w + 6;
            for (i, r) in rows.iter().enumerate() {
                println!("{}", come_up_row_line(r, i, is_clicks, drop_field_w));
            }
            println!("└{ten}┴{drop_dashes}┴{ten}┴{ten}┴{ten}┴{ten}┘");

            // MBA-1357: table-output-only note that a saved profile's DSF table was
            // applied — the Drop/Come-Up columns above already reflect it (scaled inside
            // run_sampled_trajectory, for every output format). JSON/CSV get no
            // equivalent text or top-level field (purity rule).
            if let Some(table) = dsf_table.as_ref() {
                println!("DSF table active ({})", dsf_table_summary(table.points()));
            }
        }
    }

    if let Some(truncation) = &truncation {
        warn_card_truncated(truncation, units);
    }

    Ok(())
}

/// Width of the Drop column's `(LABEL)` slot: the original 3-char assumption (MIL/MOA)
/// floors it, so those two keep the exact pre-existing 10-wide column; SMOA/IPHY (4
/// chars) and CLICKS (6 chars) widen it so the label doesn't overflow the border
/// (MBA-1355 Task 2 fix pass).
fn come_up_drop_label_width(adj_label: &str) -> usize {
    adj_label.len().max(3)
}

/// Come-ups Table header line, extracted so its exact text for the default unit can be
/// pinned by a test without spinning up the whole CLI (MBA-1355 regression guard: a
/// future Clicks-formatting change must not silently reformat the existing MIL/MOA/
/// SMOA/IPHY header).
fn come_up_header_line(dist_unit: &str, adj_label: &str, vel_unit: &str) -> String {
    let w = come_up_drop_label_width(adj_label);
    format!(
        "│Range ({:>2})|Drop ({:>w$})|Come-Up   │ Vel ({:>3})│Energy    │ Time (s) │",
        dist_unit,
        adj_label,
        vel_unit,
        w = w
    )
}

/// Come-ups Table data row, extracted (0.33.0 decision-support Task 9) so the
/// range/drop/come-up/velocity/energy/time column wiring is unit-testable without
/// spinning up the whole CLI -- see `card_row_sentinel_tests` for the anti-transposition
/// regression guard this enables. `i == 0` prints the em-dash placeholder in the Come-Up
/// column (there is no prior row to compute a come-up from).
fn come_up_row_line(r: &CardRow, i: usize, is_clicks: bool, drop_field_w: usize) -> String {
    let drop_adj = r.drop_adj.unwrap();
    let drop_str = if is_clicks {
        format!("{:>drop_field_w$.0}", drop_adj)
    } else {
        format!("{:>drop_field_w$.3}", drop_adj)
    };
    // `come_up` is only unwrapped in the branches that actually read it: the i == 0 row has
    // no prior row to compute a come-up from and never touches the value, so a `None` there
    // (unlike every other row, which `adaptive_card`/the come-ups loop always populates) must
    // not panic on a value this branch is about to discard anyway.
    let come_up_str = if i == 0 {
        "    —     ".to_string()
    } else if is_clicks {
        format!("{:>9.0} ", r.come_up.unwrap())
    } else {
        format!("{:>9.3} ", r.come_up.unwrap())
    };
    format!(
        "│{:>9.0} │{} │{}│{:>9.0} │{:>9.0} │{:>9.3} │",
        r.range,
        drop_str,
        come_up_str,
        r.velocity.unwrap(),
        r.energy.unwrap(),
        r.time.unwrap()
    )
}

/// Standalone powder-temperature velocity resolution (MBA-737) — no trajectory solve.
/// Delegates to the same `resolve_powder_adjusted_velocity` the trajectory and lead
/// solvers call. NOTE: this command always applies the linear model, while
/// trajectory/lead gate it behind --use-powder-sensitivity (a curve applies there
/// unconditionally).
#[allow(clippy::too_many_arguments)]
fn handle_powder(
    velocity: Option<f64>,
    temperature: Option<f64>,
    powder_temp_sensitivity: Option<f64>,
    powder_temp: Option<f64>,
    powder_temp_curve_si: Option<Vec<(f64, f64)>>,
    sweep: Option<String>,
    mass: Option<f64>,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), String> {
    use ballistics_engine::cli_api::parse_powder_sweep;
    use ballistics_engine::resolve_powder_adjusted_velocity;

    let has_curve = powder_temp_curve_si.as_ref().is_some_and(|c| !c.is_empty());
    let curve_ref = powder_temp_curve_si.as_deref();

    // Display-unit defaults identical to the trajectory/lead commands.
    let sens_display = powder_temp_sensitivity.unwrap_or(match units {
        UnitSystem::Imperial => 1.0,
        UnitSystem::Metric => 0.3048 / (5.0 / 9.0),
    });
    let sens_si = UnitConverter::velocity_to_metric(sens_display, units)
        / UnitConverter::temperature_delta_to_metric(1.0, units);
    // Linear model: --powder-temp is the reference temperature the stated velocity
    // was measured at (70F equivalent when omitted). Curve: it is the lookup temp.
    let ref_temp_c = powder_temp
        .map(|t| UnitConverter::temperature_to_metric(t, units))
        .unwrap_or(DEFAULT_POWDER_REFERENCE_TEMP_C);
    let powder_curve_temp_c: Option<f64> =
        powder_temp.map(|t| UnitConverter::temperature_to_metric(t, units));
    let ambient_c: Option<f64> =
        temperature.map(|t| UnitConverter::temperature_to_metric(t, units));
    let velocity_si: Option<f64> = velocity.map(|v| UnitConverter::velocity_to_metric(v, units));
    let mass_kg: Option<f64> = mass.map(|m| UnitConverter::mass_to_metric(m, units));

    // Validation: the linear model needs a nominal velocity; a single (non-sweep)
    // resolution additionally needs a temperature to resolve at.
    if !has_curve && velocity.is_none() {
        return Err(
            "--velocity is required for the linear model (or supply --powder-temp-curve)"
                .to_string(),
        );
    }
    let sweep_temps: Option<Vec<f64>> = match sweep.as_deref() {
        Some(s) => Some(parse_powder_sweep(s)?),
        None => None,
    };
    if sweep_temps.is_none() {
        if !has_curve && temperature.is_none() {
            return Err(
                "--temperature is required (the shot-day air temperature), or use --sweep"
                    .to_string(),
            );
        }
        if has_curve && powder_temp.is_none() && temperature.is_none() {
            return Err(
                "--powder-temp or --temperature is required with --powder-temp-curve, or use --sweep"
                    .to_string(),
            );
        }
    }

    // Resolve one velocity (m/s) at a display-unit temperature. For the linear model
    // the temperature is the shot-day ambient; for a curve it is the powder
    // temperature the curve is interpolated at.
    let resolve_at_c = |temp_c: f64| -> f64 {
        resolve_powder_adjusted_velocity(
            velocity_si.unwrap_or(0.0),
            temp_c,
            !has_curve, // linear model implied by running this command without a curve
            sens_si,
            ref_temp_c,
            curve_ref,
            None, // per-row lookup IS temp_c; never pin sweep rows to one powder temp
        )
    };

    let energy_at = |v_mps: f64| -> Option<f64> {
        mass_kg.map(|m| UnitConverter::energy_from_metric(0.5 * m * v_mps * v_mps, units))
    };
    let (vel_unit, temp_unit, energy_unit) = match units {
        UnitSystem::Imperial => ("fps", "°F", "ft·lb"),
        UnitSystem::Metric => ("m/s", "°C", "J"),
    };

    struct PowderRow {
        temp_display: f64,
        velocity_display: f64,
        shift_display: Option<f64>,
        energy_display: Option<f64>,
    }
    let row_at = |temp_display: f64, temp_c: f64| -> PowderRow {
        let v_mps = resolve_at_c(temp_c);
        let v_display = UnitConverter::velocity_from_metric(v_mps, units);
        PowderRow {
            temp_display,
            velocity_display: v_display,
            shift_display: velocity.map(|nominal| v_display - nominal),
            energy_display: energy_at(v_mps),
        }
    };

    let rows: Vec<PowderRow> = match &sweep_temps {
        Some(temps) => temps
            .iter()
            .map(|&t| row_at(t, UnitConverter::temperature_to_metric(t, units)))
            .collect(),
        None => {
            // Single resolution. Linear: at the ambient temperature. Curve: at the
            // powder temperature (falling back to ambient), matching the solver.
            let (t_display, t_c) = if has_curve {
                match (powder_temp, powder_curve_temp_c, temperature, ambient_c) {
                    (Some(td), Some(tc), _, _) => (td, tc),
                    (_, _, Some(td), Some(tc)) => (td, tc),
                    _ => unreachable!("validated above"),
                }
            } else {
                (
                    temperature.expect("validated above"),
                    ambient_c.expect("validated above"),
                )
            };
            vec![row_at(t_display, t_c)]
        }
    };

    let model_desc = if has_curve {
        let curve = curve_ref.expect("has_curve");
        let lo = UnitConverter::temperature_from_metric(curve[0].0, units);
        let hi = UnitConverter::temperature_from_metric(curve[curve.len() - 1].0, units);
        format!(
            "measured curve, {} points ({:.1}\u{2013}{:.1} {})",
            curve.len(),
            lo,
            hi,
            temp_unit
        )
    } else {
        format!("linear, {:.2} {}/{}", sens_display, vel_unit, temp_unit)
    };

    match output {
        OutputFormat::Table => {
            println!("Powder Temperature Velocity");
            println!("===========================");
            println!("  Model:              {}", model_desc);
            if !has_curve {
                println!(
                    "  Reference temp:     {:.1} {}",
                    UnitConverter::temperature_from_metric(ref_temp_c, units),
                    temp_unit
                );
            }
            if let Some(v) = velocity {
                println!("  Nominal velocity:   {:.1} {}", v, vel_unit);
            }
            println!();
            if rows.len() == 1 {
                let r = &rows[0];
                let temp_label = if has_curve {
                    "Powder temp:"
                } else {
                    "Shot temp:"
                };
                println!("  {:<20}{:.1} {}", temp_label, r.temp_display, temp_unit);
                match r.shift_display {
                    Some(s) => println!(
                        "  Resolved velocity:  {:.1} {}  ({:+.1})",
                        r.velocity_display, vel_unit, s
                    ),
                    None => println!(
                        "  Resolved velocity:  {:.1} {}",
                        r.velocity_display, vel_unit
                    ),
                }
                if let Some(e) = r.energy_display {
                    println!("  Muzzle energy:      {:.0} {}", e, energy_unit);
                }
            } else {
                let has_shift = rows.first().is_some_and(|r| r.shift_display.is_some());
                let has_energy = rows.first().is_some_and(|r| r.energy_display.is_some());
                print!(
                    "  {:>10}  {:>14}",
                    format!("Temp ({})", temp_unit),
                    format!("Velocity ({})", vel_unit)
                );
                if has_shift {
                    print!("  {:>12}", format!("Shift ({})", vel_unit));
                }
                if has_energy {
                    print!("  {:>15}", format!("Energy ({})", energy_unit));
                }
                println!();
                for r in &rows {
                    print!("  {:>10.1}  {:>14.1}", r.temp_display, r.velocity_display);
                    if let Some(s) = r.shift_display {
                        print!("  {:>12.1}", s);
                    }
                    if let Some(e) = r.energy_display {
                        print!("  {:>15.0}", e);
                    }
                    println!();
                }
            }
        }
        OutputFormat::Json => {
            let round1 = |x: f64| (x * 10.0).round() / 10.0;
            let rows_json: Vec<serde_json::Value> = rows
                .iter()
                .map(|r| {
                    let mut o = serde_json::json!({
                        "temperature": round1(r.temp_display),
                        "velocity": round1(r.velocity_display),
                    });
                    if let Some(s) = r.shift_display {
                        o["shift"] = serde_json::json!(round1(s));
                    }
                    if let Some(e) = r.energy_display {
                        o["energy"] = serde_json::json!(e.round());
                    }
                    o
                })
                .collect();
            let mut result = serde_json::json!({
                "command": "powder",
                "units": match units {
                    UnitSystem::Imperial => "imperial",
                    UnitSystem::Metric => "metric",
                },
                "model": if has_curve { "curve" } else { "linear" },
            });
            if !has_curve {
                result["sensitivity"] = serde_json::json!(sens_display);
                result["reference_temp"] = serde_json::json!(round1(
                    UnitConverter::temperature_from_metric(ref_temp_c, units)
                ));
            } else {
                result["curve_points"] = serde_json::json!(curve_ref.expect("has_curve").len());
            }
            if let Some(v) = velocity {
                result["nominal_velocity"] = serde_json::json!(v);
            }
            if let Some(m) = mass {
                result["mass"] = serde_json::json!(m);
            }
            if sweep_temps.is_some() {
                result["sweep"] = serde_json::json!(rows_json);
            } else {
                result["resolved"] = rows_json
                    .into_iter()
                    .next()
                    .unwrap_or(serde_json::json!(null));
            }
            println!(
                "{}",
                serde_json::to_string_pretty(&result).map_err(|e| e.to_string())?
            );
        }
        OutputFormat::Csv => {
            let has_shift = rows.first().is_some_and(|r| r.shift_display.is_some());
            let has_energy = rows.first().is_some_and(|r| r.energy_display.is_some());
            let mut header = format!(
                "temperature_{},velocity_{}",
                temp_unit_ascii(units),
                vel_unit_ascii(units)
            );
            if has_shift {
                header.push_str(&format!(",shift_{}", vel_unit_ascii(units)));
            }
            if has_energy {
                header.push_str(&format!(",energy_{}", energy_unit_ascii(units)));
            }
            println!("{}", header);
            for r in &rows {
                let mut line = format!("{:.1},{:.1}", r.temp_display, r.velocity_display);
                if let Some(s) = r.shift_display {
                    line.push_str(&format!(",{:.1}", s));
                }
                if let Some(e) = r.energy_display {
                    line.push_str(&format!(",{:.0}", e));
                }
                println!("{}", line);
            }
        }
        OutputFormat::Pdf => {
            return Err("PDF output is not supported for the powder command".to_string());
        }
    }
    Ok(())
}

/// ASCII (CSV-header-safe) unit suffixes for the powder command's CSV output.
fn temp_unit_ascii(units: UnitSystem) -> &'static str {
    match units {
        UnitSystem::Imperial => "f",
        UnitSystem::Metric => "c",
    }
}
fn vel_unit_ascii(units: UnitSystem) -> &'static str {
    match units {
        UnitSystem::Imperial => "fps",
        UnitSystem::Metric => "mps",
    }
}
fn energy_unit_ascii(units: UnitSystem) -> &'static str {
    match units {
        UnitSystem::Imperial => "ftlb",
        UnitSystem::Metric => "j",
    }
}

/// 1 lbf in newtons, exact by definition (1 lbf = 1 lb-mass * standard gravity
/// 9.80665 m/s^2 = 4.4482216152605 N). Used only to display the SAAMI recoil impulse
/// (a genuine N*s / kg*m/s quantity) in pound-seconds for imperial output.
const LBF_TO_N: f64 = 4.4482216152605;

/// Free-recoil handler (MBA-1372). Converts the CLI's display-unit inputs (imperial:
/// grains for bullet/charge, pounds for firearm weight, fps; metric: grams, kilograms,
/// m/s) into `ballistics_engine::recoil`'s SI inputs, resolves the propellant gas
/// velocity from whichever override is given (`--gas-velocity` > `--gas-velocity-factor`
/// > `--firearm-type`), and renders energy/velocity/impulse back in display units.
#[allow(clippy::too_many_arguments)]
fn handle_recoil(
    bullet_weight: f64,
    charge_weight: f64,
    velocity: f64,
    firearm_weight: f64,
    firearm_type: FirearmType,
    gas_velocity_factor: Option<f64>,
    gas_velocity: Option<f64>,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), String> {
    let bullet_mass_kg = match units {
        UnitSystem::Imperial => bullet_weight * GRAINS_TO_KG,
        UnitSystem::Metric => bullet_weight * 0.001, // grams -> kg
    };
    let charge_mass_kg = match units {
        UnitSystem::Imperial => charge_weight * GRAINS_TO_KG,
        UnitSystem::Metric => charge_weight * 0.001, // grams -> kg
    };
    let firearm_mass_kg = match units {
        UnitSystem::Imperial => firearm_weight * POUNDS_TO_KG,
        UnitSystem::Metric => firearm_weight, // already kg
    };
    let muzzle_velocity_mps = match units {
        UnitSystem::Imperial => velocity * FPS_TO_MPS,
        UnitSystem::Metric => velocity,
    };

    // Precedence: --gas-velocity (absolute) > --gas-velocity-factor (override ratio)
    // > --firearm-type (SAAMI default). See CLI_USAGE.md.
    let (gas_model, gas_model_desc): (GasVelocityModel, String) = if let Some(v) = gas_velocity {
        let v_mps = match units {
            UnitSystem::Imperial => v * FPS_TO_MPS,
            UnitSystem::Metric => v,
        };
        (GasVelocityModel::Fixed(v_mps), "fixed".to_string())
    } else if let Some(f) = gas_velocity_factor {
        (GasVelocityModel::Factor(f), format!("factor({f:.3})"))
    } else {
        let name = match firearm_type {
            FirearmType::Rifle => "saami-rifle",
            FirearmType::Pistol => "saami-pistol",
            FirearmType::ShotgunAverage => "saami-shotgun-average",
            FirearmType::ShotgunLong => "saami-shotgun-long",
        };
        (GasVelocityModel::Saami(firearm_type), name.to_string())
    };
    let gas_velocity_mps = gas_model.resolve_mps(muzzle_velocity_mps);

    let result = free_recoil(FreeRecoilInputs {
        bullet_mass_kg,
        charge_mass_kg,
        muzzle_velocity_mps,
        firearm_mass_kg,
        gas_velocity_mps,
    })?;

    let (weight_unit, firearm_weight_unit, vel_unit, energy_unit, impulse_unit) = match units {
        UnitSystem::Imperial => ("gr", "lb", "fps", "ft-lb", "lb-s"),
        UnitSystem::Metric => ("g", "kg", "m/s", "J", "N-s"),
    };
    let gas_velocity_display = match units {
        UnitSystem::Imperial => gas_velocity_mps / FPS_TO_MPS,
        UnitSystem::Metric => gas_velocity_mps,
    };
    let recoil_velocity_display = match units {
        UnitSystem::Imperial => result.recoil_velocity_mps / FPS_TO_MPS,
        UnitSystem::Metric => result.recoil_velocity_mps,
    };
    let recoil_energy_display = match units {
        UnitSystem::Imperial => result.recoil_energy_j * 0.737562, // J -> ft-lb
        UnitSystem::Metric => result.recoil_energy_j,
    };
    let impulse_display = match units {
        UnitSystem::Imperial => result.impulse_ns / LBF_TO_N, // N*s -> lbf*s
        UnitSystem::Metric => result.impulse_ns,
    };

    match output {
        OutputFormat::Table => {
            println!("Free Recoil (SAAMI Momentum Balance)");
            println!("=====================================");
            println!(
                "  Firearm weight:      {:.2} {}",
                firearm_weight, firearm_weight_unit
            );
            println!(
                "  Bullet weight:       {:.1} {}",
                bullet_weight, weight_unit
            );
            println!(
                "  Charge weight:       {:.1} {}",
                charge_weight, weight_unit
            );
            println!("  Muzzle velocity:     {:.1} {}", velocity, vel_unit);
            println!(
                "  Gas velocity model:  {}  ({:.1} {})",
                gas_model_desc, gas_velocity_display, vel_unit
            );
            println!();
            println!(
                "  Recoil velocity:     {:.2} {}",
                recoil_velocity_display, vel_unit
            );
            println!(
                "  Recoil energy:       {:.2} {}",
                recoil_energy_display, energy_unit
            );
            println!(
                "  Recoil impulse:      {:.3} {}",
                impulse_display, impulse_unit
            );
        }
        OutputFormat::Json => {
            let result_json = serde_json::json!({
                "command": "recoil",
                "units": match units {
                    UnitSystem::Imperial => "imperial",
                    UnitSystem::Metric => "metric",
                },
                "inputs": {
                    "bullet_weight": bullet_weight,
                    "charge_weight": charge_weight,
                    "velocity": velocity,
                    "firearm_weight": firearm_weight,
                },
                "gas_velocity_model": gas_model_desc,
                "gas_velocity": gas_velocity_display,
                "recoil_velocity": recoil_velocity_display,
                "recoil_energy": recoil_energy_display,
                "impulse": impulse_display,
            });
            println!(
                "{}",
                serde_json::to_string_pretty(&result_json).map_err(|e| e.to_string())?
            );
        }
        OutputFormat::Csv => {
            println!(
                "bullet_weight_{w},charge_weight_{w},velocity_{v},firearm_weight_{fw},gas_velocity_{v},recoil_velocity_{v},recoil_energy_{e},impulse_{i}",
                w = weight_unit,
                v = vel_unit_ascii(units),
                fw = match units { UnitSystem::Imperial => "lb", UnitSystem::Metric => "kg" },
                e = energy_unit_ascii(units),
                i = match units { UnitSystem::Imperial => "lbs", UnitSystem::Metric => "ns" },
            );
            println!(
                "{:.2},{:.2},{:.2},{:.2},{:.2},{:.3},{:.3},{:.4}",
                bullet_weight,
                charge_weight,
                velocity,
                firearm_weight,
                gas_velocity_display,
                recoil_velocity_display,
                recoil_energy_display,
                impulse_display,
            );
        }
        OutputFormat::Pdf => {
            return Err("PDF output is not supported for the recoil command".to_string());
        }
    }
    Ok(())
}

/// Power-factor handler (MBA-1372). PF is intrinsically defined in grains/fps by every
/// rulebook, so the input weight/velocity are converted to grains/fps regardless of
/// `--units` before calling into `ballistics_engine::power_factor`; the echoed
/// weight/velocity stay in the caller's own display units.
fn handle_power_factor(
    weight: f64,
    velocity: f64,
    organization: Option<String>,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), String> {
    let weight_gr = match units {
        UnitSystem::Imperial => weight,
        UnitSystem::Metric => weight * GRAINS_PER_GRAM,
    };
    let velocity_fps = match units {
        UnitSystem::Imperial => velocity,
        UnitSystem::Metric => velocity / FPS_TO_MPS,
    };

    let raw_pf = weight_gr * velocity_fps / 1000.0;
    let scored_pf = scored_power_factor(weight_gr, velocity_fps);
    let mut rows = pf_evaluate_all(weight_gr, velocity_fps);
    if let Some(org) = organization.as_deref() {
        let org_lower = org.to_ascii_lowercase();
        rows.retain(|r| r.organization.eq_ignore_ascii_case(&org_lower));
        if rows.is_empty() {
            return Err(format!(
                "--organization '{org}' matched nothing; expected uspsa, idpa, or sass"
            ));
        }
    }

    let (weight_unit, vel_unit) = match units {
        UnitSystem::Imperial => ("gr", "fps"),
        UnitSystem::Metric => ("g", "m/s"),
    };

    match output {
        OutputFormat::Table => {
            println!("Power Factor");
            println!("============");
            println!("  Weight:              {:.1} {}", weight, weight_unit);
            println!("  Velocity:            {:.1} {}", velocity, vel_unit);
            println!("  Power factor (raw):  {:.2}", raw_pf);
            println!("  Power factor (scored): {:.0}", scored_pf);
            println!();
            println!(
                "  {:<8}  {:<26}  {:>8}  {:>6}  {:>18}",
                "Org", "Class", "Min PF", "Pass", "Velocity limit"
            );
            for r in &rows {
                let vel_limit = match (r.min_velocity_fps, r.max_velocity_fps) {
                    (Some(min), Some(max)) => format!("{:.0}-{:.0} fps", min, max),
                    (Some(min), None) => format!(">= {:.0} fps", min),
                    (None, Some(max)) => format!("<= {:.0} fps", max),
                    (None, None) => "-".to_string(),
                };
                println!(
                    "  {:<8}  {:<26}  {:>8.0}  {:>6}  {:>18}",
                    r.organization,
                    r.class,
                    r.min_pf,
                    if r.pass { "PASS" } else { "FAIL" },
                    vel_limit,
                );
            }
        }
        OutputFormat::Json => {
            let rows_json: Vec<serde_json::Value> = rows
                .iter()
                .map(|r| {
                    serde_json::json!({
                        "organization": r.organization,
                        "class": r.class,
                        "min_pf": r.min_pf,
                        "pf_pass": r.pf_pass,
                        "min_velocity_fps": r.min_velocity_fps,
                        "max_velocity_fps": r.max_velocity_fps,
                        "velocity_pass": r.velocity_pass,
                        "pass": r.pass,
                    })
                })
                .collect();
            let result_json = serde_json::json!({
                "command": "power-factor",
                "units": match units {
                    UnitSystem::Imperial => "imperial",
                    UnitSystem::Metric => "metric",
                },
                "weight": weight,
                "velocity": velocity,
                "power_factor_raw": raw_pf,
                "power_factor_scored": scored_pf,
                "thresholds": rows_json,
            });
            println!(
                "{}",
                serde_json::to_string_pretty(&result_json).map_err(|e| e.to_string())?
            );
        }
        OutputFormat::Csv => {
            println!("organization,class,min_pf,pf_pass,min_velocity_fps,max_velocity_fps,velocity_pass,pass");
            for r in &rows {
                println!(
                    "{},{},{:.0},{},{},{},{},{}",
                    r.organization,
                    r.class,
                    r.min_pf,
                    r.pf_pass,
                    r.min_velocity_fps
                        .map(|v| format!("{v:.0}"))
                        .unwrap_or_default(),
                    r.max_velocity_fps
                        .map(|v| format!("{v:.0}"))
                        .unwrap_or_default(),
                    r.velocity_pass.map(|b| b.to_string()).unwrap_or_default(),
                    r.pass,
                );
            }
        }
        OutputFormat::Pdf => {
            return Err("PDF output is not supported for the power-factor command".to_string());
        }
    }
    Ok(())
}

/// Moving-target lead table handler (MBA-1287).
///
/// Runs `ballistics_engine::calculate_lead` once per range in the sweep. A single
/// out-of-domain range (e.g. an inbound target that overtakes the shooter) must not
/// abort the whole table: the error is captured per-row and rendered as a dashed row
/// (table) or an `"error"` field (JSON), and the sweep continues.
#[allow(clippy::too_many_arguments)]
fn handle_lead(
    velocity: f64,
    bc: f64,
    mass: f64,
    diameter: f64,
    drag_model: DragModel,
    sight_height: f64,
    temperature: f64,
    pressure: f64,
    humidity: f64,
    altitude: f64,
    wind_speed: f64,
    wind_direction: f64,
    use_powder_sensitivity: bool,
    powder_temp_sensitivity: f64,
    powder_temp: f64,
    powder_temp_curve: Option<Vec<(f64, f64)>>,
    powder_curve_temp_c: Option<f64>,
    target_speed: f64,
    target_angle: f64,
    target_length: Option<f64>,
    start: f64,
    end: f64,
    step: f64,
    adjustment_unit: AdjustmentUnit,
    // MBA-1410: resolved turret click graduation for `--adjustment-unit clicks`. `lead`
    // has a single (windage-like) angular column, so this is always the windage
    // resolution (`resolve_single_axis_click_value`), never an elevation one -- Some(...)
    // iff adjustment_unit == Clicks (resolved eagerly by the caller, same "fail fast on a
    // missing graduation" shape as trajectory/come-ups's elevation_click).
    windage_click: Option<ClickValue>,
    // MBA-1358: windage-axis tracking CF (mover lead is a dialed quantity): every
    // dial-unit lead output (mil/moa/smoa/iphy/clicks/hold strings) is divided by it
    // exactly once at its emission point; the linear lead distance is never scaled.
    windage_cf: f64,
    units: UnitSystem,
    output: OutputFormat,
    // MBA-1323 Phase 2: saved-profile velocity-BC segments / Mach-Cd drag curve, already
    // resolved to engine shapes by the caller. See build_trajectory_components's doc comment.
    bc_segments_data: Option<Vec<BCSegmentData>>,
    custom_drag_table: Option<ballistics_engine::drag::DragTable>,
) -> Result<(), Box<dyn Error>> {
    // Convert to metric
    let velocity_m = UnitConverter::velocity_to_metric(velocity, units);
    let mass_kg = UnitConverter::mass_to_metric(mass, units);
    let diameter_m = UnitConverter::diameter_to_metric(diameter, units);
    let sight_height_m = UnitConverter::sight_height_to_metric(sight_height, units);
    let temperature_c = UnitConverter::temperature_to_metric(temperature, units);
    let pressure_hpa = UnitConverter::pressure_to_metric(pressure, units);
    let altitude_m = UnitConverter::altitude_to_metric(altitude, units);
    let wind_speed_m = UnitConverter::wind_to_metric(wind_speed, units);
    let target_speed_mps = UnitConverter::wind_to_metric(target_speed, units);
    let target_length_m = target_length.map(|l| match units {
        UnitSystem::Imperial => l * 0.0254, // inches to meters
        UnitSystem::Metric => l / 1000.0,   // mm to meters
    });
    let end_m = UnitConverter::distance_to_metric(end, units);
    let step_m = UnitConverter::distance_to_metric(step, units);

    let (mut inputs, wind, atmosphere) = build_trajectory_components(
        velocity_m,
        bc,
        mass_kg,
        diameter_m,
        drag_model,
        sight_height_m,
        temperature_c,
        pressure_hpa,
        humidity,
        altitude_m,
        wind_speed_m,
        wind_direction,
        end_m,
        step_m,
        bc_segments_data,
        custom_drag_table,
        // MBA-1359: `lead` solves no zero, so a zero POI offset has nothing to bias here.
        0.0,
        0.0,
        // MBA-1396: lead exposes no --sight-offset flag (not a zero-solving command).
        0.0,
    );

    // Powder temperature (MBA-1325): identical resolution to `run_trajectory` so a
    // powder-temp-curve/-sensitivity muzzle-velocity correction reproduces exactly —
    // TrajectorySolver::new (invoked inside calculate_lead) resolves the correction from
    // these BallisticInputs fields, so setting them here is the entire plumbing needed.
    inputs.use_powder_sensitivity = use_powder_sensitivity;
    inputs.powder_temp_sensitivity = if use_powder_sensitivity {
        UnitConverter::velocity_to_metric(powder_temp_sensitivity, units)
            / UnitConverter::temperature_delta_to_metric(1.0, units)
    } else {
        0.0
    };
    inputs.powder_temp = UnitConverter::temperature_to_metric(powder_temp, units);
    inputs.powder_temp_curve = powder_temp_curve;
    inputs.powder_curve_temp_c = powder_curve_temp_c;

    // MBA-1410: `lead`'s single angular column is fundamentally a windage-type hold (the
    // horizontal lead ahead of a moving target), so `--adjustment-unit clicks` resolves
    // through `windage_click` (the caller's `resolve_single_axis_click_value`), same as
    // wind-card.
    let adj_label = adjustment_unit_label(adjustment_unit);
    let (dist_unit, speed_unit) = match units {
        UnitSystem::Imperial => ("yd", "mph"),
        UnitSystem::Metric => ("m", "m/s"),
    };
    let has_bodies = target_length_m.is_some();

    struct LeadRow {
        range: f64,
        result: Result<ballistics_engine::LeadSolution, ballistics_engine::LeadError>,
        bodies: Option<f64>,
    }

    let mut rows: Vec<LeadRow> = Vec::new();
    let mut current_range = start;
    while current_range <= end + 0.1 {
        let range_m = UnitConverter::distance_to_metric(current_range, units);

        let result = ballistics_engine::calculate_lead(
            inputs.clone(),
            wind.clone(),
            atmosphere.clone(),
            target_speed_mps,
            target_angle,
            range_m,
        );

        let bodies = match (&result, target_length_m) {
            (Ok(sol), Some(len_m)) if len_m > 0.0 => Some(sol.lead_m / len_m),
            _ => None,
        };

        rows.push(LeadRow {
            range: current_range,
            result,
            bodies,
        });

        current_range += step;
    }

    match output {
        OutputFormat::Json => {
            let json_rows: Vec<serde_json::Value> = rows
                .iter()
                .map(|r| match &r.result {
                    Ok(sol) => {
                        let mut row = serde_json::json!({
                            "range": r.range,
                            "tof_s": sol.time_of_flight_s,
                            "lead": UnitConverter::distance_from_metric(sol.lead_m, units),
                            // MBA-1358: dial-unit lead is divided by the windage CF
                            // (scope units; /1.0 exact); the linear lead above never is.
                            "lead_mil": sol.lead_mil / windage_cf,
                            "lead_moa": sol.lead_moa / windage_cf,
                            "intercept_range": UnitConverter::distance_from_metric(
                                sol.corrected_range_m,
                                units
                            ),
                            "iterations": sol.iterations,
                        });
                        if let Some(bodies) = r.bodies {
                            row["bodies"] = serde_json::json!(bodies);
                        }
                        row
                    }
                    Err(e) => serde_json::json!({
                        "range": r.range,
                        "error": e.to_string(),
                    }),
                })
                .collect();

            let json = serde_json::json!({
                "target_speed": target_speed,
                "target_speed_unit": speed_unit,
                "target_angle": target_angle,
                "units": match units {
                    UnitSystem::Imperial => "imperial",
                    UnitSystem::Metric => "metric",
                },
                "distance_unit": dist_unit,
                "adjustment_unit": adj_label,
                "rows": json_rows,
            });
            println!("{}", serde_json::to_string_pretty(&json)?);
        }
        OutputFormat::Csv => {
            if has_bodies {
                println!(
                    "range_{dist_unit},tof_s,lead_{dist_unit},lead_{unit},intercept_{dist_unit},iterations,bodies,error",
                    dist_unit = dist_unit,
                    unit = adj_label.to_lowercase()
                );
            } else {
                println!(
                    "range_{dist_unit},tof_s,lead_{dist_unit},lead_{unit},intercept_{dist_unit},iterations,error",
                    dist_unit = dist_unit,
                    unit = adj_label.to_lowercase()
                );
            }
            for r in &rows {
                match &r.result {
                    Ok(sol) => {
                        let lead_disp = UnitConverter::distance_from_metric(sol.lead_m, units);
                        // MBA-1358: mover lead is a dialed quantity — every dial-unit
                        // form is divided by the windage CF exactly once (clicks correct
                        // the input angle before quantization). /1.0 exact when no CF.
                        let lead_adj = match adjustment_unit {
                            AdjustmentUnit::Mil => sol.lead_mil / windage_cf,
                            AdjustmentUnit::Moa => sol.lead_moa / windage_cf,
                            AdjustmentUnit::Smoa | AdjustmentUnit::Iphy => {
                                sol.lead_mil * smoa_per_mil() / windage_cf
                            }
                            AdjustmentUnit::Clicks => windage_click
                                .map(|c| clicks_for(lead_disp / windage_cf, r.range, &c) as f64)
                                .unwrap_or(sol.lead_mil / windage_cf),
                        };
                        let intercept_disp =
                            UnitConverter::distance_from_metric(sol.corrected_range_m, units);
                        if has_bodies {
                            println!(
                                "{:.0},{:.3},{:.2},{:.3},{:.1},{},{},",
                                r.range,
                                sol.time_of_flight_s,
                                lead_disp,
                                lead_adj,
                                intercept_disp,
                                sol.iterations,
                                r.bodies.map(|b| format!("{:.2}", b)).unwrap_or_default()
                            );
                        } else {
                            println!(
                                "{:.0},{:.3},{:.2},{:.3},{:.1},{},",
                                r.range,
                                sol.time_of_flight_s,
                                lead_disp,
                                lead_adj,
                                intercept_disp,
                                sol.iterations
                            );
                        }
                    }
                    Err(e) => {
                        if has_bodies {
                            println!("{:.0},,,,,,,{}", r.range, e);
                        } else {
                            println!("{:.0},,,,,,{}", r.range, e);
                        }
                    }
                }
            }
        }
        OutputFormat::Table | OutputFormat::Pdf => {
            println!();
            println!(
                "Moving-Target Lead Table (target speed: {:.1} {}, angle: {:.0}\u{b0}, {})",
                target_speed, speed_unit, target_angle, adj_label
            );
            println!("Positive lead = hold in the direction of target travel.");
            println!();

            if has_bodies {
                println!("┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐");
                println!(
                    "│Range ({:>2})│TOF (s)   │Lead ({:>3})│Lead ({:>3})│Intercept │Bodies    │",
                    dist_unit, dist_unit, adj_label
                );
                println!("├──────────┼──────────┼──────────┼──────────┼──────────┼──────────┤");
                for r in &rows {
                    match &r.result {
                        Ok(sol) => {
                            let lead_disp = UnitConverter::distance_from_metric(sol.lead_m, units);
                            // MBA-1358: dialed quantity — divided by the windage CF,
                            // exactly once.
                            let lead_adj = match adjustment_unit {
                                AdjustmentUnit::Mil => sol.lead_mil / windage_cf,
                                AdjustmentUnit::Moa => sol.lead_moa / windage_cf,
                                AdjustmentUnit::Smoa | AdjustmentUnit::Iphy => {
                                    sol.lead_mil * smoa_per_mil() / windage_cf
                                }
                                AdjustmentUnit::Clicks => windage_click
                                    .map(|c| clicks_for(lead_disp / windage_cf, r.range, &c) as f64)
                                    .unwrap_or(sol.lead_mil / windage_cf),
                            };
                            let intercept_disp =
                                UnitConverter::distance_from_metric(sol.corrected_range_m, units);
                            println!(
                                "│{:>9.0} │{:>9.3} │{:>9.2} │{:>9.3} │{:>9.1} │{:>9.2} │",
                                r.range,
                                sol.time_of_flight_s,
                                lead_disp,
                                lead_adj,
                                intercept_disp,
                                r.bodies.unwrap_or(0.0)
                            );
                        }
                        Err(e) => {
                            println!(
                                "│{:>9.0} │{:>9} │{:>9} │{:>9} │{:>9} │{:>9} │  {}",
                                r.range, "--", "--", "--", "--", "--", e
                            );
                        }
                    }
                }
                println!("└──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘");
            } else {
                println!("┌──────────┬──────────┬──────────┬──────────┬──────────┐");
                println!(
                    "│Range ({:>2})│TOF (s)   │Lead ({:>3})│Lead ({:>3})│Intercept │",
                    dist_unit, dist_unit, adj_label
                );
                println!("├──────────┼──────────┼──────────┼──────────┼──────────┤");
                for r in &rows {
                    match &r.result {
                        Ok(sol) => {
                            let lead_disp = UnitConverter::distance_from_metric(sol.lead_m, units);
                            // MBA-1358: dialed quantity — divided by the windage CF,
                            // exactly once.
                            let lead_adj = match adjustment_unit {
                                AdjustmentUnit::Mil => sol.lead_mil / windage_cf,
                                AdjustmentUnit::Moa => sol.lead_moa / windage_cf,
                                AdjustmentUnit::Smoa | AdjustmentUnit::Iphy => {
                                    sol.lead_mil * smoa_per_mil() / windage_cf
                                }
                                AdjustmentUnit::Clicks => windage_click
                                    .map(|c| clicks_for(lead_disp / windage_cf, r.range, &c) as f64)
                                    .unwrap_or(sol.lead_mil / windage_cf),
                            };
                            let intercept_disp =
                                UnitConverter::distance_from_metric(sol.corrected_range_m, units);
                            println!(
                                "│{:>9.0} │{:>9.3} │{:>9.2} │{:>9.3} │{:>9.1} │",
                                r.range, sol.time_of_flight_s, lead_disp, lead_adj, intercept_disp
                            );
                        }
                        Err(e) => {
                            println!(
                                "│{:>9.0} │{:>9} │{:>9} │{:>9} │{:>9} │  {}",
                                r.range, "--", "--", "--", "--", e
                            );
                        }
                    }
                }
                println!("└──────────┴──────────┴──────────┴──────────┴──────────┘");
            }
        }
    }

    Ok(())
}

/// Wind card handler
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable wind-card CLI command shape"
)]
fn handle_wind_card(
    velocity: f64,
    bc: f64,
    mass: f64,
    diameter: f64,
    drag_model: DragModel,
    zero_distance: f64,
    wind_speeds: &[f64],
    wind_angles: &[f64],
    legacy_labels: bool,
    start: f64,
    end: f64,
    step: f64,
    adjustment_unit: AdjustmentUnit,
    // MBA-1410: resolved windage click graduation for `--adjustment-unit clicks` (wind
    // card's whole table is a windage quantity — crosswind drift). Some(...) iff
    // adjustment_unit == Clicks, resolved eagerly by the caller via
    // `resolve_single_axis_click_value`.
    windage_click: Option<ClickValue>,
    // MBA-1358: windage-axis tracking CF; the drift dial values are divided by it
    // exactly once via adjustment_display (the wind card's whole table is a windage
    // quantity).
    windage_cf: f64,
    // MBA-1360: the selected zero set's windage dial correction (MILs; 0.0 = no set),
    // added to the true angular need before the CF division at the same boundary.
    zero_set_windage_bias_mil: f64,
    sight_height: f64,
    // MBA-1359: deliberate POI offset at the zero range, METERS (already resolved
    // CLI-over-profile and converted by the dispatch).
    zero_poi_vertical_m: f64,
    zero_poi_horizontal_m: f64,
    // MBA-1396: lateral sight-mount offset, METERS (drift starts offset left of the LOS
    // and converges to it at the zero distance).
    sight_offset_lateral_m: f64,
    temperature: f64,
    pressure: f64,
    humidity: f64,
    altitude: f64,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    // Convert to metric
    let velocity_m = UnitConverter::velocity_to_metric(velocity, units);
    let mass_kg = UnitConverter::mass_to_metric(mass, units);
    let diameter_m = UnitConverter::diameter_to_metric(diameter, units);
    let sight_height_m = UnitConverter::sight_height_to_metric(sight_height, units);
    let zero_distance_m = UnitConverter::distance_to_metric(zero_distance, units);
    let temperature_c = UnitConverter::temperature_to_metric(temperature, units);
    let pressure_hpa = UnitConverter::pressure_to_metric(pressure, units);
    let altitude_m = UnitConverter::altitude_to_metric(altitude, units);
    let end_m = UnitConverter::distance_to_metric(end, units);

    // Calculate zero angle (no wind)
    let drag_model_enum = drag_model;

    let zero_inputs = BallisticInputs {
        bc_value: bc,
        bc_type: drag_model_enum,
        bullet_mass: mass_kg,
        muzzle_velocity: velocity_m,
        bullet_diameter: diameter_m,
        bullet_length: fallback_bullet_length_m(diameter_m, mass_kg),
        sight_height: sight_height_m,
        use_rk4: true,
        zero_poi_vertical_m,
        zero_poi_horizontal_m,
        sight_offset_lateral_m,
        ..Default::default()
    };

    let atmosphere = AtmosphericConditions {
        temperature: temperature_c,
        pressure: pressure_hpa,
        humidity,
        altitude: altitude_m,
    };

    let zero_angle = ballistics_engine::calculate_zero_angle_with_conditions(
        zero_inputs,
        zero_distance_m,
        sight_height_m,
        WindConditions::default(),
        atmosphere,
    )?;

    let adj_label = adjustment_unit_label(adjustment_unit);

    let (dist_unit, wind_unit) = match units {
        UnitSystem::Imperial => ("yd", "mph"),
        UnitSystem::Metric => ("m", "m/s"),
    };

    // For each wind angle (wind-FROM degrees, matches --wind-direction), run
    // trajectory at each wind speed and collect drift. Legacy default is a
    // single 90° (full-value crosswind from the right) angle.
    //
    // Collect data: rows = ranges, columns = wind speeds (CardRow::wind_columns holds the
    // drift-in-adjustment-units-per-wind-speed vector; every other CardRow field is unused
    // by this surface and stays None/empty).
    let mut ranges: Vec<f64> = Vec::new();
    let mut current = start;
    while current <= end + 0.1 {
        ranges.push(current);
        current += step;
    }

    let mut json_cards: Vec<serde_json::Value> = Vec::new();

    // Every angle/speed cell is its own flight and they do not all reach equally far (a
    // crosswind bleeds a little velocity), but the matrix has ONE range axis. So the card runs
    // to the shortest of them: solve them all first, tracking the number of leading ranges
    // EVERY flight supplies, then render once that is known (MBA-1476 follow-up).
    let mut reachable = ranges.len();
    let mut reach_m = f64::INFINITY;
    let mut per_angle_drifts: Vec<Vec<Vec<f64>>> = Vec::new();

    for &angle_deg in wind_angles.iter() {
        let mut all_drifts: Vec<Vec<f64>> = vec![Vec::new(); ranges.len()];

        for &ws in wind_speeds {
            let ws_m = UnitConverter::wind_to_metric(ws, units);

            let flight = run_sampled_flight(
                velocity_m,
                bc,
                mass_kg,
                diameter_m,
                drag_model,
                sight_height_m,
                temperature_c,
                pressure_hpa,
                humidity,
                altitude_m,
                ws_m,
                angle_deg,
                // MBA-1476: at least one whole grid cell past the last row asked for — see
                // card_sample_max_range_m for why that headroom decides reachability.
                card_sample_max_range_m(end_m),
                // MBA-1476: the engine's own card grid, never the requested row spacing.
                CARD_SAMPLE_INTERVAL_M,
                zero_angle,
                // wind-card does not yet consume saved-profile bc_segments/drag_curve
                // (MBA-1323 Phase 2 follow-up) — see CLI_USAGE.md's a7p import section.
                None,
                None,
                None,
                zero_poi_vertical_m,
                zero_poi_horizontal_m,
                sight_offset_lateral_m,
                Some(zero_distance_m),
            )?;

            reach_m = reach_m.min(flight.reach_m);

            for (ri, &range_display) in ranges.iter().enumerate().take(reachable) {
                // MBA-1476: a range the flight cannot supply used to become a 0.0 cell —
                // indistinguishable from "no drift at all" on a wind card. It is now the end
                // of the card instead, for every column at once.
                let Some(sample) = card_row_sample(&flight.samples, range_display, units) else {
                    reachable = ri;
                    break;
                };
                let drift_yd = UnitConverter::distance_from_metric(sample.wind_drift_m, units);
                // MBA-1358: windage CF applied once at the conversion boundary.
                // MBA-1360: zero-set windage bias added before that division.
                let drift_adj = adjustment_display(
                    drift_yd,
                    range_display,
                    adjustment_unit,
                    windage_click,
                    zero_set_windage_bias_mil,
                    windage_cf,
                )
                .value;

                all_drifts[ri].push(drift_adj);
            }
        }

        per_angle_drifts.push(all_drifts);
    }

    // The ragged tails left by the columns that ran short are trimmed once, here, so every
    // printed row carries a cell from every wind speed.
    let truncation = if reachable < ranges.len() {
        if reachable == 0 {
            return Err(card_no_rows_error(ranges[0], reach_m, units));
        }
        let last_row = ranges[reachable - 1];
        ranges.truncate(reachable);
        Some(card_truncation(end, last_row, reach_m, units))
    } else {
        None
    };

    for (angle_idx, &angle_deg) in wind_angles.iter().enumerate() {
        let all_drifts = &per_angle_drifts[angle_idx];

        let wind_rows: Vec<CardRow> = ranges
            .iter()
            .enumerate()
            .map(|(i, &range)| CardRow {
                range,
                drop_linear: None,
                drop_adj: None,
                come_up: None,
                wind_linear: None,
                wind_adj: None,
                velocity: None,
                energy: None,
                time: None,
                lead_adj: None,
                wind_columns: all_drifts[i].clone(),
            })
            .collect();

        match output {
            OutputFormat::Json => {
                let json_rows: Vec<serde_json::Value> = wind_rows
                    .iter()
                    .map(|r| {
                        let mut row = serde_json::json!({ "range": r.range });
                        for (j, &ws) in wind_speeds.iter().enumerate() {
                            row[format!("wind_{}", ws)] =
                                serde_json::json!(r.wind_columns.get(j).unwrap_or(&0.0));
                        }
                        row
                    })
                    .collect();
                let mut card = serde_json::json!({
                    "zero_distance": zero_distance,
                    "adjustment_unit": adj_label,
                    "distance_unit": dist_unit,
                    "wind_unit": wind_unit,
                    "wind_speeds": wind_speeds,
                    "data": json_rows,
                });
                if legacy_labels {
                    card["crosswind"] = serde_json::json!("full-value (90°)");
                } else {
                    card["wind_angle"] = serde_json::json!(angle_deg);
                }
                if let Some(truncation) = &truncation {
                    card["truncated"] = card_truncation_json(truncation, units);
                }
                json_cards.push(card);
            }
            OutputFormat::Csv => {
                if !legacy_labels {
                    if angle_idx > 0 {
                        println!();
                    }
                    println!("# wind_angle={}", angle_deg);
                }
                let ws_headers: Vec<String> = wind_speeds
                    .iter()
                    .map(|ws| format!("wind_{}_{}", ws, wind_unit))
                    .collect();
                println!("range_{},{}", dist_unit, ws_headers.join(","));
                for r in &wind_rows {
                    let drift_strs: Vec<String> = r
                        .wind_columns
                        .iter()
                        .map(|d| {
                            let d = if d.abs() < 1e-9 { 0.0 } else { *d };
                            format!("{:.1}", d)
                        })
                        .collect();
                    println!("{:.0},{}", r.range, drift_strs.join(","));
                }
            }
            OutputFormat::Table | OutputFormat::Pdf => {
                println!();
                if legacy_labels {
                    println!(
                        "Wind Card (zero: {:.0} {}, {}, full-value crosswind)",
                        zero_distance, dist_unit, adj_label
                    );
                } else {
                    println!(
                        "Wind Card (zero: {:.0} {}, {}) — wind angle {}° (wind-FROM: 0=head, 90=right, 180=tail, 270=left)",
                        zero_distance, dist_unit, adj_label, angle_deg
                    );
                }

                // Header
                let col_width = 10;
                let range_header = format!("Range ({:>2})", dist_unit);
                let mut header = format!("┌{:─>w$}", "", w = col_width);
                for _ in wind_speeds {
                    header += &format!("┬{:─>w$}", "", w = col_width);
                }
                header += "┐";
                println!("{}", header);

                let mut label_row = format!("│{:<w$}", range_header, w = col_width);
                for ws in wind_speeds {
                    label_row += &format!("│{:>8} {} ", ws, wind_unit);
                }
                label_row += "│";
                println!("{}", label_row);

                let mut sep = format!("├{:─>w$}", "", w = col_width);
                for _ in wind_speeds {
                    sep += &format!("┼{:─>w$}", "", w = col_width);
                }
                sep += "┤";
                println!("{}", sep);

                for r in &wind_rows {
                    let mut row_str = format!("│{:>9.0} ", r.range);
                    for d in &r.wind_columns {
                        let d = if d.abs() < 1e-9 { 0.0 } else { *d };
                        row_str += &format!("│{:>9.1} ", d);
                    }
                    row_str += "│";
                    println!("{}", row_str);
                }

                let mut footer = format!("└{:─>w$}", "", w = col_width);
                for _ in wind_speeds {
                    footer += &format!("┴{:─>w$}", "", w = col_width);
                }
                footer += "┘";
                println!("{}", footer);
            }
        }
    }

    if let OutputFormat::Json = output {
        if json_cards.len() == 1 {
            println!("{}", serde_json::to_string_pretty(&json_cards[0])?);
        } else {
            let array = serde_json::Value::Array(json_cards);
            println!("{}", serde_json::to_string_pretty(&array)?);
        }
    }

    if let Some(truncation) = &truncation {
        warn_card_truncated(truncation, units);
    }

    Ok(())
}

// ============================================================================
// Stability Analysis Handler (MBA-734)
// ============================================================================

/// Calculate the Miller stability factor and minimum twist rates
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable stability CLI command shape"
)]
fn handle_stability(
    mass: f64,
    diameter: f64,
    length: f64,
    twist_rate: f64,
    velocity: f64,
    temperature: f64,
    pressure: f64,
    altitude: f64,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    // Convert to metric (SI) for the stability calculation
    let mass_kg = UnitConverter::mass_to_metric(mass, units);
    let diameter_m = UnitConverter::diameter_to_metric(diameter, units);
    let length_m = UnitConverter::sight_height_to_metric(length, units); // inches/mm to meters
    let velocity_m = UnitConverter::velocity_to_metric(velocity, units);
    let temperature_c = UnitConverter::temperature_to_metric(temperature, units);
    let pressure_hpa = UnitConverter::pressure_to_metric(pressure, units);
    let altitude_m = UnitConverter::altitude_to_metric(altitude, units);

    // Twist rate: for imperial it's inches/turn, for metric it's mm/turn
    // compute_stability_coefficient expects twist_rate in inches/turn
    let twist_rate_inches = match units {
        UnitSystem::Imperial => twist_rate,
        UnitSystem::Metric => twist_rate / 25.4, // mm to inches
    };

    // Build BallisticInputs for the stability calculation
    let inputs = BallisticInputs {
        bullet_mass: mass_kg,
        bullet_diameter: diameter_m,
        bullet_length: length_m,
        muzzle_velocity: velocity_m,
        twist_rate: twist_rate_inches,
        ..Default::default()
    };

    let atmo_params = (altitude_m, temperature_c, pressure_hpa, 1.0);

    // Calculate stability factor
    let sg = ballistics_engine::stability::compute_stability_coefficient(&inputs, atmo_params);

    let status = if sg >= 1.5 {
        "Fully Stable"
    } else if sg >= 1.0 {
        "Marginally Stable"
    } else {
        "UNSTABLE"
    };

    // Calculate minimum twist rate for Sg=1.5 and Sg=1.0 by binary search.
    // Lower twist number = faster spin = higher Sg.
    let find_twist_for_sg = |target_sg: f64| -> f64 {
        let mut low = 1.0_f64; // 1 inch/turn (extremely fast)
        let mut high = 40.0_f64; // 40 inches/turn (very slow)

        for _ in 0..100 {
            let mid = (low + high) / 2.0;
            let test_inputs = BallisticInputs {
                bullet_mass: mass_kg,
                bullet_diameter: diameter_m,
                bullet_length: length_m,
                muzzle_velocity: velocity_m,
                twist_rate: mid,
                ..Default::default()
            };
            let test_sg = ballistics_engine::stability::compute_stability_coefficient(
                &test_inputs,
                atmo_params,
            );
            if test_sg > target_sg {
                low = mid;
            } else {
                high = mid;
            }
            if (test_sg - target_sg).abs() < 0.001 {
                break;
            }
        }
        (low + high) / 2.0
    };

    let min_twist_1_5 = find_twist_for_sg(1.5);
    let min_twist_1_0 = find_twist_for_sg(1.0);

    // min_twist_* are in INCHES (compute_stability_coefficient treats twist_rate as inches/turn);
    // convert to mm for metric so the JSON/CSV values match their labeled unit (the Table path
    // already converts). Imperial is unchanged.
    let (min15_out, min10_out) = match units {
        UnitSystem::Imperial => (min_twist_1_5, min_twist_1_0),
        UnitSystem::Metric => (min_twist_1_5 * 25.4, min_twist_1_0 * 25.4),
    };

    // Display units
    let (len_unit, vel_unit, twist_display, min15_display, min10_display) = match units {
        UnitSystem::Imperial => (
            "\"",
            "fps",
            format!("1:{:.0}\" RH", twist_rate),
            format!("1:{:.1}\"", min_twist_1_5),
            format!("1:{:.1}\"", min_twist_1_0),
        ),
        UnitSystem::Metric => (
            "mm",
            "m/s",
            format!("1:{:.0}mm RH", twist_rate),
            format!("1:{:.1}mm", min_twist_1_5 * 25.4),
            format!("1:{:.1}mm", min_twist_1_0 * 25.4),
        ),
    };

    match output {
        OutputFormat::Json => {
            let json = serde_json::json!({
                "stability_factor": (sg * 100.0).round() / 100.0,
                "status": status,
                "twist_rate": twist_rate,
                "twist_rate_unit": if units == UnitSystem::Imperial { "in/turn" } else { "mm/turn" },
                "min_twist_sg_1_5": (min15_out * 100.0).round() / 100.0,
                "min_twist_sg_1_0": (min10_out * 100.0).round() / 100.0,
                "bullet_length": length,
                "bullet_diameter": diameter,
                "bullet_mass": mass,
                "muzzle_velocity": velocity,
                "units": if units == UnitSystem::Imperial { "imperial" } else { "metric" },
            });
            println!("{}", serde_json::to_string_pretty(&json)?);
        }
        OutputFormat::Csv => {
            println!("sg,status,twist_rate,min_twist_sg1.5,min_twist_sg1.0,length,velocity");
            println!(
                "{:.2},{},{:.1},{:.1},{:.1},{:.3},{:.0}",
                sg, status, twist_rate, min15_out, min10_out, length, velocity
            );
        }
        OutputFormat::Table | OutputFormat::Pdf => {
            println!();
            println!("╔════════════════════════════════════════╗");
            println!("║         Stability Analysis            ║");
            println!("╠════════════════════════════════════════╣");
            println!("║ Stability Factor (Sg):  {:>12.2}  ║", sg);
            println!("║ Status:              {:>14}  ║", status);
            println!("║ Twist Rate:          {:>14}  ║", twist_display);
            println!("║ Min Twist (Sg=1.5):  {:>14}  ║", min15_display);
            println!("║ Min Twist (Sg=1.0):  {:>14}  ║", min10_display);
            println!("║ Bullet Length:     {:>12.3}{:>4}  ║", length, len_unit);
            println!(
                "║ Muzzle Velocity:     {:>10.0} {:<3}  ║",
                velocity, vel_unit
            );
            println!("╚════════════════════════════════════════╝");
        }
    }

    Ok(())
}

// ============================================================================
// Range Table Handler (MBA-733)
// ============================================================================

/// Generate a comprehensive range table combining drop, wind, velocity, energy, and ToF
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable range-table CLI command shape"
)]
fn handle_range_table(
    velocity: f64,
    bc: f64,
    mass: f64,
    diameter: f64,
    drag_model: DragModel,
    zero_distance: f64,
    start: f64,
    end: f64,
    step: f64,
    wind_speed: f64,
    wind_direction: f64,
    adjustment_unit: AdjustmentUnit,
    // MBA-1410: independent windage-axis unit for the Wind column (Drop stays on
    // `adjustment_unit`, the elevation axis) — already resolved/validated by the caller
    // (`resolve_windage_unit`).
    windage_unit: AdjustmentUnit,
    // Resolved turret click graduations for `--adjustment-unit clicks`: Some(...) iff
    // that axis's own unit is Clicks (see the caller's `resolve_click_values` +
    // `resolve_windage_unit` gating), None otherwise.
    elevation_click: Option<ClickValue>,
    windage_click: Option<ClickValue>,
    // MBA-1358: per-axis tracking CFs (flag-over-profile, resolved by the caller):
    // Drop dial values ÷elevation_cf, Wind dial values ÷windage_cf, exactly once each
    // via the shared adjustment_display boundary. Raw inches never scale.
    elevation_cf: f64,
    windage_cf: f64,
    // MBA-1360: the selected zero set's per-axis dial corrections (MILs; 0.0 = no
    // set), added to the true angular need before each CF division above.
    zero_set_elevation_bias_mil: f64,
    zero_set_windage_bias_mil: f64,
    sight_height: f64,
    // MBA-1359: deliberate POI offset at the zero range, METERS (already resolved
    // CLI-over-profile and converted by the dispatch).
    zero_poi_vertical_m: f64,
    zero_poi_horizontal_m: f64,
    // MBA-1396: lateral sight-mount offset, METERS.
    sight_offset_lateral_m: f64,
    temperature: f64,
    pressure: f64,
    humidity: f64,
    altitude: f64,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    // Convert to metric
    let velocity_m = UnitConverter::velocity_to_metric(velocity, units);
    let mass_kg = UnitConverter::mass_to_metric(mass, units);
    let diameter_m = UnitConverter::diameter_to_metric(diameter, units);
    let sight_height_m = UnitConverter::sight_height_to_metric(sight_height, units);
    let zero_distance_m = UnitConverter::distance_to_metric(zero_distance, units);
    let temperature_c = UnitConverter::temperature_to_metric(temperature, units);
    let pressure_hpa = UnitConverter::pressure_to_metric(pressure, units);
    let altitude_m = UnitConverter::altitude_to_metric(altitude, units);
    let wind_speed_m = UnitConverter::wind_to_metric(wind_speed, units);
    let end_m = UnitConverter::distance_to_metric(end, units);

    // Calculate zero angle (no wind for clean zero)
    let drag_model_enum = drag_model;

    let zero_inputs = BallisticInputs {
        bc_value: bc,
        bc_type: drag_model_enum,
        bullet_mass: mass_kg,
        muzzle_velocity: velocity_m,
        bullet_diameter: diameter_m,
        bullet_length: fallback_bullet_length_m(diameter_m, mass_kg),
        sight_height: sight_height_m,
        use_rk4: true,
        zero_poi_vertical_m,
        zero_poi_horizontal_m,
        sight_offset_lateral_m,
        ..Default::default()
    };

    let atmosphere = AtmosphericConditions {
        temperature: temperature_c,
        pressure: pressure_hpa,
        humidity,
        altitude: altitude_m,
    };

    let zero_angle = ballistics_engine::calculate_zero_angle_with_conditions(
        zero_inputs,
        zero_distance_m,
        sight_height_m,
        WindConditions::default(),
        atmosphere,
    )?;

    // Run trajectory WITH wind (for wind drift values)
    // range-table does not yet consume saved-profile bc_segments/drag_curve (MBA-1323
    // Phase 2 follow-up) — see CLI_USAGE.md's a7p import section.
    let wind_flight = run_sampled_flight(
        velocity_m,
        bc,
        mass_kg,
        diameter_m,
        drag_model,
        sight_height_m,
        temperature_c,
        pressure_hpa,
        humidity,
        altitude_m,
        wind_speed_m,
        wind_direction,
        // MBA-1476: at least one whole grid cell past the last row asked for — see
        // card_sample_max_range_m for why that headroom decides reachability.
        card_sample_max_range_m(end_m),
        // MBA-1476: the engine's own card grid, never the requested row spacing.
        CARD_SAMPLE_INTERVAL_M,
        zero_angle,
        None,
        None,
        None,
        zero_poi_vertical_m,
        zero_poi_horizontal_m,
        sight_offset_lateral_m,
        Some(zero_distance_m),
    )?;

    // Run trajectory WITHOUT wind (for pure drop)
    let no_wind_flight = run_sampled_flight(
        velocity_m,
        bc,
        mass_kg,
        diameter_m,
        drag_model,
        sight_height_m,
        temperature_c,
        pressure_hpa,
        humidity,
        altitude_m,
        0.0,
        0.0,
        // MBA-1476: at least one whole grid cell past the last row asked for — see
        // card_sample_max_range_m for why that headroom decides reachability.
        card_sample_max_range_m(end_m),
        // MBA-1476: the engine's own card grid, never the requested row spacing.
        CARD_SAMPLE_INTERVAL_M,
        zero_angle,
        None,
        None,
        None,
        zero_poi_vertical_m,
        zero_poi_horizontal_m,
        sight_offset_lateral_m,
        Some(zero_distance_m),
    )?;

    // Build output rows. MBA-1410: Drop is the elevation axis, Wind the (possibly
    // different) windage axis.
    let elev_label = adjustment_unit_label(adjustment_unit);
    let wind_label = adjustment_unit_label(windage_unit);

    let (dist_unit, vel_unit, energy_unit, drop_unit, wind_unit_label) = match units {
        UnitSystem::Imperial => ("yd", "fps", "ft-lb", "in", "mph"),
        UnitSystem::Metric => ("m", "m/s", "J", "mm", "m/s"),
    };

    // Both flights feed every row, so the card can only run as far as the shorter of them.
    let reach_m = wind_flight.reach_m.min(no_wind_flight.reach_m);

    let mut rows: Vec<CardRow> = Vec::new();
    let mut truncation: Option<CardTruncation> = None;
    let mut current_range = start;

    while current_range <= end + 0.1 {
        let (Some(nw), Some(w)) = (
            card_row_sample(&no_wind_flight.samples, current_range, units),
            card_row_sample(&wind_flight.samples, current_range, units),
        ) else {
            // MBA-1476 follow-up: the rows the flight DOES reach are still the shooter's
            // card. Stop here, print them, and say what was left out.
            let Some(last) = rows.last() else {
                return Err(card_no_rows_error(current_range, reach_m, units));
            };
            truncation = Some(card_truncation(end, last.range, reach_m, units));
            break;
        };
        // MBA-1476: the row's OWN range on both axes.
        let range_display = current_range;

        let drop_linear = match units {
            UnitSystem::Imperial => nw.drop_m / 0.0254,
            UnitSystem::Metric => nw.drop_m * 1000.0,
        };

        let drop_yd = UnitConverter::distance_from_metric(nw.drop_m, units);
        let drop_adj = adjustment_display(
            drop_yd,
            range_display,
            adjustment_unit,
            elevation_click,
            zero_set_elevation_bias_mil,
            elevation_cf,
        )
        .value;

        let wind_linear = match units {
            UnitSystem::Imperial => w.wind_drift_m / 0.0254,
            UnitSystem::Metric => w.wind_drift_m * 1000.0,
        };

        let drift_yd = UnitConverter::distance_from_metric(w.wind_drift_m, units);
        let wind_adj = windage_adjustment_display(
            drift_yd,
            range_display,
            windage_unit,
            windage_click,
            zero_set_windage_bias_mil,
            windage_cf,
        )
        .value;

        rows.push(CardRow {
            range: current_range,
            drop_linear: Some(drop_linear),
            drop_adj: Some(drop_adj),
            come_up: None,
            wind_linear: Some(wind_linear),
            wind_adj: Some(wind_adj),
            velocity: Some(UnitConverter::velocity_from_metric(nw.velocity_mps, units)),
            energy: Some(UnitConverter::energy_from_metric(nw.energy_j, units)),
            time: Some(nw.time_s),
            lead_adj: None,
            wind_columns: Vec::new(),
        });

        current_range += step;
    }

    match output {
        OutputFormat::Json => {
            let json_rows: Vec<serde_json::Value> = rows
                .iter()
                .map(|r| {
                    serde_json::json!({
                        "range": r.range,
                        "drop": r.drop_linear,
                        "drop_adj": r.drop_adj,
                        "wind_drift": r.wind_linear,
                        "wind_adj": r.wind_adj,
                        "velocity": r.velocity,
                        "energy": r.energy,
                        "time": r.time,
                    })
                })
                .collect();
            let mut json = serde_json::json!({
                "zero_distance": zero_distance,
                "wind_speed": wind_speed,
                "wind_direction": wind_direction,
                // "adjustment_unit" kept for backward compatibility (== the elevation
                // axis, i.e. byte-identical to pre-MBA-1410 output).
                "adjustment_unit": elev_label,
                "distance_unit": dist_unit,
                "velocity_unit": vel_unit,
                "energy_unit": energy_unit,
                "drop_unit": drop_unit,
                "data": json_rows,
            });
            // Tier 2 review I2 fix: "windage_unit" is additive and must only appear when
            // --windage-unit actually diverged from the elevation axis, matching
            // MBA-1402's skip_serializing_if pattern -- otherwise every default-path
            // range-table run (no --windage-unit) would gain an unconditional new key
            // relative to the merge base.
            if windage_unit != adjustment_unit {
                json["windage_unit"] = serde_json::json!(wind_label);
            }
            if let Some(truncation) = &truncation {
                json["truncated"] = card_truncation_json(truncation, units);
            }
            println!("{}", serde_json::to_string_pretty(&json)?);
        }
        OutputFormat::Csv => {
            println!(
                "range_{},drop_{},drop_{},wind_{},wind_{},velocity_{},energy_{},tof_s",
                dist_unit,
                drop_unit,
                elev_label.to_lowercase(),
                drop_unit,
                wind_label.to_lowercase(),
                vel_unit,
                energy_unit
            );
            for r in &rows {
                println!(
                    "{:.0},{:.1},{:.3},{:.1},{:.2},{:.0},{:.0},{:.2}",
                    r.range,
                    r.drop_linear.unwrap(),
                    r.drop_adj.unwrap(),
                    r.wind_linear.unwrap(),
                    r.wind_adj.unwrap(),
                    r.velocity.unwrap(),
                    r.energy.unwrap(),
                    r.time.unwrap()
                );
            }
        }
        OutputFormat::Table | OutputFormat::Pdf => {
            println!();
            println!(
                "Range Table (zero: {:.0} {}, {:.0} {} crosswind)",
                zero_distance, dist_unit, wind_speed, wind_unit_label
            );
            println!(
                "┌───────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬───────┐"
            );
            println!(
                "│Range  │Drop     │Drop     │Wind     │Wind     │Vel      │Energy   │ToF    │"
            );
            println!("│({:>2})   │({:>2})     │({:>3})    │({:>2})     │({:>3})    │({:>3})    │({:>4})   │(s)    │",
                     dist_unit, drop_unit, elev_label, drop_unit, wind_label, vel_unit, energy_unit);
            println!(
                "├───────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼───────┤"
            );
            for r in &rows {
                println!("{}", range_table_row_line(r));
            }
            println!(
                "└───────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴───────┘"
            );
        }
    }

    if let Some(truncation) = &truncation {
        warn_card_truncated(truncation, units);
    }

    Ok(())
}

/// Range Table data row, extracted (0.33.0 decision-support Task 9) so the range/drop-
/// linear/drop-adj/wind-linear/wind-adj/velocity/energy/time column wiring is
/// unit-testable without spinning up the whole CLI -- see `card_row_sentinel_tests` for
/// the anti-transposition regression guard this enables (a `drop_adj`<->`wind_adj` swap
/// here must fail that test, since the two columns sit right next to each other).
fn range_table_row_line(r: &CardRow) -> String {
    format!(
        "│{:>6.0} │{:>8.1} │{:>8.3} │{:>8.1} │{:>8.2} │{:>8.0} │{:>8.0} │{:>6.2} │",
        r.range,
        r.drop_linear.unwrap(),
        r.drop_adj.unwrap(),
        r.wind_linear.unwrap(),
        r.wind_adj.unwrap(),
        r.velocity.unwrap(),
        r.energy.unwrap(),
        r.time.unwrap()
    )
}

/// One load's CLI/profile SPEC in a `compare` run, in DISPLAY units per the session
/// `--units`. `bc_segments_data`/`custom_drag_table` come only from saved profiles
/// (inline `--load` specs are scalar-BC by design) and are threaded into BOTH the zero
/// solve and the sampled runs so the zero uses the same drag physics (MBA-735).
///
/// Named `CompareLoadSpec` (0.33.0 decision-support Task 9) to free the name
/// `CompareLoad` for the thin per-load `{ name, rows: Vec<CardRow> }` result type
/// `handle_compare` builds from it.
struct CompareLoadSpec {
    name: String,
    drag_model: DragModel,
    bc: f64,
    mass: f64,
    velocity: f64,
    diameter: f64,
    bc_segments_data: Option<Vec<BCSegmentData>>,
    custom_drag_table: Option<ballistics_engine::drag::DragTable>,
}

/// Parse a `--load` spec: `NAME:DRAG:BC:MASS:VELOCITY[:DIAMETER]` (MBA-735).
/// Follows the `--wind-segment` colon convention; all numbers are display units.
fn parse_compare_load_spec(
    spec: &str,
    units: UnitSystem,
) -> Result<CompareLoadSpec, Box<dyn Error>> {
    let parts: Vec<&str> = spec.split(':').collect();
    if parts.len() != 5 && parts.len() != 6 {
        return Err(format!(
            "invalid --load '{spec}': expected NAME:DRAG:BC:MASS:VELOCITY[:DIAMETER] \
             (5 or 6 colon-separated fields; NAME must not contain ':')"
        )
        .into());
    }
    let name = parts[0].trim();
    if name.is_empty() {
        return Err(format!("invalid --load '{spec}': NAME is empty").into());
    }
    let drag_model = DragModel::from_str(parts[1].trim()).ok_or_else(|| {
        format!(
            "invalid --load '{spec}': DRAG '{}' is not a recognized drag model \
             (g1, g2, g5, g6, g7, g8, gi, gs, ra4)",
            parts[1].trim()
        )
    })?;
    let num = |i: usize, field: &str| -> Result<f64, Box<dyn Error>> {
        let v: f64 = parts[i].trim().parse().map_err(|_| {
            format!(
                "invalid --load '{spec}': {field} '{}' is not a number",
                parts[i]
            )
        })?;
        if !v.is_finite() || v <= 0.0 {
            return Err(format!("invalid --load '{spec}': {field} must be finite and > 0").into());
        }
        Ok(v)
    };
    let bc = num(2, "BC")?;
    let mass = num(3, "MASS")?;
    let velocity = num(4, "VELOCITY")?;
    let diameter = if parts.len() == 6 {
        num(5, "DIAMETER")?
    } else {
        match units {
            UnitSystem::Imperial => 0.308,
            UnitSystem::Metric => 7.82,
        }
    };
    Ok(CompareLoadSpec {
        name: name.to_string(),
        drag_model,
        bc,
        mass,
        velocity,
        diameter,
        bc_segments_data: None,
        custom_drag_table: None,
    })
}

/// Side-by-side multi-load comparison (MBA-735): every load is zeroed independently at
/// the shared zero distance, then run through identical wind/atmosphere; rows mirror
/// `range-table` semantics (pure drop from a no-wind pass, drift from the wind pass).
/// Like range-table, saved-profile bc_segments/drag_curve are not consumed here.
#[allow(clippy::too_many_arguments)] // mirrors the sibling range-table handler
fn handle_compare(
    loads: Vec<CompareLoadSpec>,
    zero_distance: f64,
    start: f64,
    end: f64,
    step: f64,
    wind_speed: f64,
    wind_direction: f64,
    adjustment_unit: AdjustmentUnit,
    // MBA-1410: independent windage-axis unit for the Wind column (Drop stays on
    // `adjustment_unit`, the elevation axis) — already resolved/validated by the caller.
    windage_unit: AdjustmentUnit,
    // Resolved turret click graduations for `--adjustment-unit clicks`. `compare` has no
    // single `--profile` (it compares multiple loads, each optionally from its own saved
    // profile), so these come ONLY from the explicit CLI flags -- never a per-load
    // profile's own elevation_click/windage_click.
    elevation_click: Option<ClickValue>,
    windage_click: Option<ClickValue>,
    // MBA-1358: per-axis tracking CFs — CLI flags only (compare has no single
    // profile), dividing every load's dial columns identically via adjustment_display.
    elevation_cf: f64,
    windage_cf: f64,
    sight_height: f64,
    // MBA-1359: deliberate POI offset at the zero range, METERS (converted by the
    // dispatch). Shared conditions like sight_height: applied identically to every load.
    zero_poi_vertical_m: f64,
    zero_poi_horizontal_m: f64,
    // MBA-1396: lateral sight-mount offset, METERS; shared across loads like sight_height.
    sight_offset_lateral_m: f64,
    temperature: f64,
    pressure: f64,
    humidity: f64,
    altitude: f64,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    // Shared conditions in metric
    let sight_height_m = UnitConverter::sight_height_to_metric(sight_height, units);
    let zero_distance_m = UnitConverter::distance_to_metric(zero_distance, units);
    let temperature_c = UnitConverter::temperature_to_metric(temperature, units);
    let pressure_hpa = UnitConverter::pressure_to_metric(pressure, units);
    let altitude_m = UnitConverter::altitude_to_metric(altitude, units);
    let wind_speed_m = UnitConverter::wind_to_metric(wind_speed, units);
    let end_m = UnitConverter::distance_to_metric(end, units);

    let atmosphere = AtmosphericConditions {
        temperature: temperature_c,
        pressure: pressure_hpa,
        humidity,
        altitude: altitude_m,
    };

    // Thin per-load result: the shared `ranges` grid below indexes both `rows` here and
    // every other load's `rows` identically, so `results[li].rows[ri]` is load `li` at
    // `ranges[ri]` (used by the delta-vs-baseline JSON and the Table/CSV writers).
    struct CompareLoad {
        name: String,
        rows: Vec<CardRow>,
    }

    // The shared range grid (display units)
    let mut ranges: Vec<f64> = Vec::new();
    let mut r = start;
    while r <= end + 0.1 {
        ranges.push(r);
        r += step;
    }

    let mut results: Vec<CompareLoad> = Vec::new();
    // Parallel to `results`/`loads` (one push per loop iteration below): CardRow has no
    // slot for a per-load scalar like the zero angle, so it stays out-of-band here exactly
    // as it always has, just no longer bundled into the row-collection struct.
    let mut zero_angles_deg: Vec<f64> = Vec::new();
    // Likewise parallel: how far each load's flight actually got (meters), so a card trimmed
    // to the shortest column can quote the reach of the load that set it.
    let mut reaches_m: Vec<f64> = Vec::new();
    for load in &loads {
        let velocity_m = UnitConverter::velocity_to_metric(load.velocity, units);
        let mass_kg = UnitConverter::mass_to_metric(load.mass, units);
        let diameter_m = UnitConverter::diameter_to_metric(load.diameter, units);
        let drag_model_enum = load.drag_model;

        let zero_inputs = BallisticInputs {
            bc_value: load.bc,
            bc_type: drag_model_enum,
            bullet_mass: mass_kg,
            muzzle_velocity: velocity_m,
            bullet_diameter: diameter_m,
            bullet_length: fallback_bullet_length_m(diameter_m, mass_kg),
            sight_height: sight_height_m,
            use_rk4: true,
            // The zero must use the same drag physics as the trajectory runs below.
            use_bc_segments: load.bc_segments_data.is_some(),
            bc_segments_data: load.bc_segments_data.clone(),
            custom_drag_table: load.custom_drag_table.clone(),
            zero_poi_vertical_m,
            zero_poi_horizontal_m,
            sight_offset_lateral_m,
            ..Default::default()
        };
        let zero_angle = ballistics_engine::calculate_zero_angle_with_conditions(
            zero_inputs,
            zero_distance_m,
            sight_height_m,
            WindConditions::default(),
            atmosphere.clone(),
        )
        .map_err(|e| format!("load '{}': zeroing failed: {e}", load.name))?;

        let wind_flight = run_sampled_flight(
            velocity_m,
            load.bc,
            mass_kg,
            diameter_m,
            load.drag_model,
            sight_height_m,
            temperature_c,
            pressure_hpa,
            humidity,
            altitude_m,
            wind_speed_m,
            wind_direction,
            // MBA-1476: at least one whole grid cell past the last row asked for — see
            // card_sample_max_range_m for why that headroom decides reachability.
            card_sample_max_range_m(end_m),
            // MBA-1476: the engine's own card grid, never the requested row spacing.
            CARD_SAMPLE_INTERVAL_M,
            zero_angle,
            load.bc_segments_data.clone(),
            load.custom_drag_table.clone(),
            None,
            zero_poi_vertical_m,
            zero_poi_horizontal_m,
            sight_offset_lateral_m,
            Some(zero_distance_m),
        )
        .map_err(|e| format!("load '{}': {e}", load.name))?;
        let no_wind_flight = run_sampled_flight(
            velocity_m,
            load.bc,
            mass_kg,
            diameter_m,
            load.drag_model,
            sight_height_m,
            temperature_c,
            pressure_hpa,
            humidity,
            altitude_m,
            0.0,
            0.0,
            // MBA-1476: at least one whole grid cell past the last row asked for — see
            // card_sample_max_range_m for why that headroom decides reachability.
            card_sample_max_range_m(end_m),
            // MBA-1476: the engine's own card grid, never the requested row spacing.
            CARD_SAMPLE_INTERVAL_M,
            zero_angle,
            load.bc_segments_data.clone(),
            load.custom_drag_table.clone(),
            None,
            zero_poi_vertical_m,
            zero_poi_horizontal_m,
            sight_offset_lateral_m,
            Some(zero_distance_m),
        )
        .map_err(|e| format!("load '{}': {e}", load.name))?;

        // Both flights feed every row, so this load can only run as far as the shorter.
        let reach_m = wind_flight.reach_m.min(no_wind_flight.reach_m);

        let mut rows: Vec<CardRow> = Vec::new();
        for &range_display in &ranges {
            // MBA-1476: interpolated exactly at the requested range, never the nearest
            // sample. A range this load's flight does not span ends ITS column here; the
            // shared range axis is trimmed to the shortest column once every load is solved.
            let (Some(nw), Some(w)) = (
                card_row_sample(&no_wind_flight.samples, range_display, units),
                card_row_sample(&wind_flight.samples, range_display, units),
            ) else {
                if rows.is_empty() {
                    return Err(format!(
                        "load '{}': {}",
                        load.name,
                        card_no_rows_error(range_display, reach_m, units)
                    )
                    .into());
                }
                break;
            };
            let drop_linear = match units {
                UnitSystem::Imperial => nw.drop_m / 0.0254,
                UnitSystem::Metric => nw.drop_m * 1000.0,
            };
            let drop_yd = UnitConverter::distance_from_metric(nw.drop_m, units);
            // MBA-1360: compare has no --zero-set (multiple loads, no single profile to
            // look a set up in — the MBA-1358 flag-only precedent), so its bias is 0.0.
            let drop_adj = adjustment_display(
                drop_yd,
                range_display,
                adjustment_unit,
                elevation_click,
                0.0,
                elevation_cf,
            )
            .value;
            let wind_linear = match units {
                UnitSystem::Imperial => w.wind_drift_m / 0.0254,
                UnitSystem::Metric => w.wind_drift_m * 1000.0,
            };
            let drift_yd = UnitConverter::distance_from_metric(w.wind_drift_m, units);
            let wind_adj = windage_adjustment_display(
                drift_yd,
                range_display,
                windage_unit,
                windage_click,
                0.0,
                windage_cf,
            )
            .value;
            rows.push(CardRow {
                range: range_display,
                drop_linear: Some(drop_linear),
                drop_adj: Some(drop_adj),
                come_up: None,
                wind_linear: Some(wind_linear),
                wind_adj: Some(wind_adj),
                velocity: Some(UnitConverter::velocity_from_metric(nw.velocity_mps, units)),
                energy: Some(UnitConverter::energy_from_metric(nw.energy_j, units)),
                time: Some(nw.time_s),
                lead_adj: None,
                wind_columns: Vec::new(),
            });
        }
        zero_angles_deg.push(zero_angle.to_degrees());
        reaches_m.push(reach_m);
        results.push(CompareLoad {
            name: load.name.clone(),
            rows,
        });
    }

    // Every load shares one range axis — `results[li].rows[ri]` is load `li` at `ranges[ri]` —
    // so a load whose flight ends early ends the card for all of them. Trim to the shortest
    // column and name the load that set it (MBA-1476 follow-up).
    let shortest = results
        .iter()
        .enumerate()
        .min_by_key(|(_, res)| res.rows.len())
        .map(|(li, res)| (li, res.name.clone(), res.rows.len()));
    let truncation = match shortest {
        Some((li, name, common)) if common < ranges.len() => {
            let last_row = ranges[common - 1];
            ranges.truncate(common);
            for res in &mut results {
                res.rows.truncate(common);
            }
            Some((name, card_truncation(end, last_row, reaches_m[li], units)))
        }
        _ => None,
    };

    // MBA-1410: Drop is the elevation axis, Wind/drift the (possibly different)
    // windage axis.
    let elev_label = adjustment_unit_label(adjustment_unit);
    let wind_label = adjustment_unit_label(windage_unit);
    let (dist_unit, vel_unit, energy_unit, drop_unit, wind_unit_label) = match units {
        UnitSystem::Imperial => ("yd", "fps", "ft-lb", "in", "mph"),
        UnitSystem::Metric => ("m", "m/s", "J", "mm", "m/s"),
    };

    match output {
        OutputFormat::Json => {
            let mut json = serde_json::json!({
                "compare": {
                    "loads": loads.iter().zip(zero_angles_deg.iter()).map(|(l, &zero_angle_deg)| {
                        serde_json::json!({
                            "name": l.name,
                            "drag_model": l.drag_model.to_string(),
                            "bc": l.bc,
                            "mass": l.mass,
                            "velocity": l.velocity,
                            "diameter": l.diameter,
                            "zero_angle_deg": zero_angle_deg,
                            "bc_segments": l.bc_segments_data.is_some(),
                            "custom_drag_curve": l.custom_drag_table.is_some(),
                        })
                    }).collect::<Vec<_>>(),
                    "conditions": {
                        "zero_distance": zero_distance,
                        "wind_speed": wind_speed,
                        "wind_direction": wind_direction,
                        "temperature": temperature,
                        "pressure": pressure,
                        "humidity": humidity,
                        "altitude": altitude,
                        "sight_height": sight_height,
                    },
                    "units": {
                        "distance": dist_unit,
                        "drop": drop_unit,
                        // "adjustment" kept for backward compatibility (== the elevation
                        // axis, byte-identical to pre-MBA-1410 output).
                        "adjustment": elev_label,
                        "velocity": vel_unit,
                        "energy": energy_unit,
                        "wind_speed": wind_unit_label,
                    },
                    "rows": ranges.iter().enumerate().map(|(ri, &range)| {
                        serde_json::json!({
                            "range": range,
                            "loads": results.iter().map(|res| {
                                let row = &res.rows[ri];
                                let baseline = &results[0].rows[ri];
                                serde_json::json!({
                                    "name": res.name,
                                    "drop": row.drop_linear,
                                    "drop_adj": row.drop_adj,
                                    "drift": row.wind_linear,
                                    "drift_adj": row.wind_adj,
                                    "velocity": row.velocity,
                                    "energy": row.energy,
                                    "time": row.time,
                                    // deltas vs load #1 (zero for the baseline itself)
                                    "delta_drop": row.drop_linear.unwrap() - baseline.drop_linear.unwrap(),
                                    "delta_drift": row.wind_linear.unwrap() - baseline.wind_linear.unwrap(),
                                    "delta_velocity": row.velocity.unwrap() - baseline.velocity.unwrap(),
                                    "delta_energy": row.energy.unwrap() - baseline.energy.unwrap(),
                                })
                            }).collect::<Vec<_>>(),
                        })
                    }).collect::<Vec<_>>(),
                }
            });
            // Tier 2 review I2 fix: same additive-only-on-divergence gate as range-table's
            // "windage_unit" -- "windage_adjustment" must not appear on the default path
            // (no --windage-unit), matching MBA-1402's skip_serializing_if pattern.
            if windage_unit != adjustment_unit {
                json["compare"]["units"]["windage_adjustment"] = serde_json::json!(wind_label);
            }
            if let Some((name, truncation)) = &truncation {
                let mut block = card_truncation_json(truncation, units);
                // Which load ran out first — the other loads' columns end here only because
                // the card has one range axis.
                block["load"] = serde_json::json!(name);
                json["compare"]["truncated"] = block;
            }
            println!("{}", serde_json::to_string_pretty(&json)?);
        }
        OutputFormat::Csv => {
            // Sanitize load names for CSV headers (no commas/quotes/newlines)
            let safe: Vec<String> = loads
                .iter()
                .map(|l| {
                    l.name
                        .chars()
                        .map(|c| {
                            if c == ',' || c == '"' || c == '\n' {
                                ' '
                            } else {
                                c
                            }
                        })
                        .collect()
                })
                .collect();
            let mut header = format!("range_{dist_unit}");
            for name in &safe {
                header.push_str(&format!(
                    ",{name}_drop_{drop_unit},{name}_drop_{elev_label},{name}_drift_{drop_unit},\
                     {name}_drift_{wind_label},{name}_velocity_{vel_unit},{name}_energy_{energy_unit},\
                     {name}_tof_s"
                ));
            }
            println!("{header}");
            for (ri, &range) in ranges.iter().enumerate() {
                let mut line = format!("{range:.0}");
                for res in &results {
                    let row = &res.rows[ri];
                    line.push_str(&format!(
                        ",{:.2},{:.2},{:.2},{:.2},{:.0},{:.0},{:.3}",
                        row.drop_linear.unwrap(),
                        row.drop_adj.unwrap(),
                        row.wind_linear.unwrap(),
                        row.wind_adj.unwrap(),
                        row.velocity.unwrap(),
                        row.energy.unwrap(),
                        row.time.unwrap()
                    ));
                }
                println!("{line}");
            }
        }
        OutputFormat::Pdf => {
            return Err("PDF output is not supported for compare (use the card commands)".into());
        }
        OutputFormat::Table => {
            println!("Load Comparison");
            println!(
                "Zero: {zero_distance:.0} {dist_unit} | Wind: {wind_speed:.0} {wind_unit_label} @ {wind_direction:.0}\u{b0} | Sight: {sight_height} {sh_unit} | Alt: {altitude:.0} {alt_unit}",
                sh_unit = match units { UnitSystem::Imperial => "in", UnitSystem::Metric => "mm" },
                alt_unit = match units { UnitSystem::Imperial => "ft", UnitSystem::Metric => "m" }
            );
            println!();
            for (i, l) in loads.iter().enumerate() {
                let physics_tag = match (&l.bc_segments_data, &l.custom_drag_table) {
                    (_, Some(_)) => " [custom drag curve]",
                    (Some(_), None) => " [BC segments]",
                    (None, None) => "",
                };
                println!(
                    "  #{num} {name}: {dm} BC {bc}, {mass} @ {vel} {vel_unit} (dia {dia}){physics_tag}",
                    num = i + 1,
                    name = l.name,
                    dm = l.drag_model,
                    bc = l.bc,
                    mass = l.mass,
                    vel = l.velocity,
                    dia = l.diameter,
                    physics_tag = physics_tag,
                );
            }
            println!();

            // Two-line header: load names over their [Drop Drift Vel] groups
            let trunc = |s: &str| -> String {
                if s.chars().count() > 26 {
                    let t: String = s.chars().take(25).collect();
                    format!("{t}\u{2026}")
                } else {
                    s.to_string()
                }
            };
            let mut h1 = format!("{:>8} ", "Range");
            let mut h2 = format!("{:>8} ", format!("({dist_unit})"));
            for l in &loads {
                h1.push_str(&format!("| {:^26} ", trunc(&l.name)));
                h2.push_str(&format!("| {:>8} {:>8} {:>8} ", "Drop", "Drift", "Vel"));
            }
            println!("{h1}");
            println!("{h2}");
            let width = 9 + loads.len() * 29;
            println!("{}", "-".repeat(width));
            for (ri, &range) in ranges.iter().enumerate() {
                let mut line = format!("{range:>8.0} ");
                for res in &results {
                    let row = &res.rows[ri];
                    line.push_str(&format!(
                        "| {:>8.2} {:>8.2} {:>8.0} ",
                        row.drop_adj.unwrap(),
                        row.wind_adj.unwrap(),
                        row.velocity.unwrap()
                    ));
                }
                println!("{line}");
            }
            println!("{}", "-".repeat(width));
            // MBA-1410: byte-identical to the pre-per-axis phrasing when both axes share a
            // unit (the default, and every run before --windage-unit existed); spells out
            // both units only when they genuinely differ.
            if elev_label == wind_label {
                println!(
                    "Drop/Drift in {elev_label} (- is down/left), Vel in {vel_unit}. \
                     Use -o json or -o csv for linear drop/drift ({drop_unit}), energy \
                     ({energy_unit}), time of flight, and deltas vs load #1."
                );
            } else {
                println!(
                    "Drop in {elev_label}, Drift in {wind_label} (- is down/left), Vel in {vel_unit}. \
                     Use -o json or -o csv for linear drop/drift ({drop_unit}), energy \
                     ({energy_unit}), time of flight, and deltas vs load #1."
                );
            }
        }
    }

    if let Some((name, truncation)) = &truncation {
        // Named, because on a multi-load card the shooter needs to know WHICH load stopped
        // the shared range axis.
        eprintln!(
            "warning: load '{name}': {}",
            truncation.message(card_distance_unit(units))
        );
    }

    Ok(())
}

/// 0.33.0 decision-support Task 9: the anti-transposition lesson from this train. Every
/// `CardRow` field a table renderer reads gets its own DISTINCT sentinel value here, so a
/// renderer that reads the wrong field -- e.g. a `drop_adj`<->`wind_adj` swap in
/// `range_table_row_line`, the two adjacent dial columns that make that mistake easy to
/// make -- prints a different string than the hand-computed `expected`, and this test
/// fails loudly instead of shipping a plausible-looking but silently-wrong card. Covers
/// the two riskiest renderers: come-ups (`drop_adj`/`come_up` side by side) and
/// range-table (four adjacent numeric columns: `drop_linear`/`drop_adj`/`wind_linear`/
/// `wind_adj`).
#[cfg(test)]
mod card_row_sentinel_tests {
    use super::{come_up_drop_label_width, come_up_row_line, range_table_row_line, CardRow};

    /// Every field distinct so a transposition anywhere changes the rendered string.
    fn sentinel_row() -> CardRow {
        CardRow {
            range: 111.0,
            drop_linear: Some(222.1),
            drop_adj: Some(333.2),
            come_up: Some(444.3),
            wind_linear: Some(555.4),
            wind_adj: Some(666.5),
            velocity: Some(777.6),
            energy: Some(888.7),
            time: Some(9.123),
            lead_adj: Some(101.0),
            wind_columns: Vec::new(),
        }
    }

    #[test]
    fn come_up_row_line_places_each_sentinel_in_its_own_column() {
        let r = sentinel_row();
        let drop_field_w = come_up_drop_label_width("MIL") + 6;
        // i = 1 (not the first row) so the Come-Up column prints its numeric sentinel
        // instead of the "no prior row" em-dash placeholder.
        let line = come_up_row_line(&r, 1, false, drop_field_w);
        let expected = format!(
            "│{:>9.0} │{:>drop_field_w$.3} │{:>9.3} │{:>9.0} │{:>9.0} │{:>9.3} │",
            r.range,
            r.drop_adj.unwrap(),
            r.come_up.unwrap(),
            r.velocity.unwrap(),
            r.energy.unwrap(),
            r.time.unwrap(),
        );
        assert_eq!(line, expected);
        // A drop_adj<->come_up swap (the two per-row numeric columns) would put "444.300"
        // where "333.200" belongs and vice versa -- pin both independently, not just the
        // whole-line equality above (which a future edit could narrow without noticing a
        // value went missing).
        assert!(
            line.contains("333.200"),
            "drop_adj sentinel missing/misplaced: {line}"
        );
        assert!(
            line.contains("444.300"),
            "come_up sentinel missing/misplaced: {line}"
        );
        assert!(
            !line.contains("666.5"),
            "wind_adj has no come-ups column but its sentinel leaked in: {line}"
        );
    }

    /// The come-ups CLICKS table/CSV numbers are pinned by nothing else: the golden suite
    /// (`tests/card_golden_cli.rs`) is MIL-only, and the CLI's clicks-mode integration tests
    /// only assert stderr, never the rendered numbers. One more sentinel case closes that gap.
    #[test]
    fn come_up_row_line_places_each_sentinel_in_its_own_column_when_clicks() {
        let r = sentinel_row();
        let drop_field_w = come_up_drop_label_width("CLICKS") + 6;
        let line = come_up_row_line(&r, 1, true, drop_field_w);
        let expected = format!(
            "│{:>9.0} │{:>drop_field_w$.0} │{:>9.0} │{:>9.0} │{:>9.0} │{:>9.3} │",
            r.range,
            r.drop_adj.unwrap(),
            r.come_up.unwrap(),
            r.velocity.unwrap(),
            r.energy.unwrap(),
            r.time.unwrap(),
        );
        assert_eq!(line, expected);
        assert!(
            line.contains("333"),
            "drop_adj sentinel missing/misplaced: {line}"
        );
        assert!(
            line.contains("444"),
            "come_up sentinel missing/misplaced: {line}"
        );
    }

    #[test]
    fn range_table_row_line_places_each_sentinel_in_its_own_column() {
        let r = sentinel_row();
        let line = range_table_row_line(&r);
        let expected = format!(
            "│{:>6.0} │{:>8.1} │{:>8.3} │{:>8.1} │{:>8.2} │{:>8.0} │{:>8.0} │{:>6.2} │",
            r.range,
            r.drop_linear.unwrap(),
            r.drop_adj.unwrap(),
            r.wind_linear.unwrap(),
            r.wind_adj.unwrap(),
            r.velocity.unwrap(),
            r.energy.unwrap(),
            r.time.unwrap(),
        );
        assert_eq!(line, expected);
        // A drop_adj<->wind_adj swap (the two dial columns sitting either side of
        // wind_linear) would put "666.50" where "333.200" belongs and vice versa --
        // pin both independently, not just the whole-line equality above.
        assert!(
            line.contains("222.1"),
            "drop_linear sentinel missing/misplaced: {line}"
        );
        assert!(
            line.contains("333.200"),
            "drop_adj sentinel missing/misplaced: {line}"
        );
        assert!(
            line.contains("555.4"),
            "wind_linear sentinel missing/misplaced: {line}"
        );
        assert!(
            line.contains("666.50"),
            "wind_adj sentinel missing/misplaced: {line}"
        );
    }
}

/// Task 10 fix-round, C-1: the review proved by hand that sampled distances are exact
/// multiples of `--sample-interval` IN METRES (default 10.0 m), so their yard conversion
/// is genuinely ~0.3-0.4 yd off an integer -- not "near-exact yards" as the pre-fix code
/// comment claimed. `dope_card_row_from_sample` must round `range` back to whole yards
/// itself so the one shipped dope-card path stays byte-identical to the pre-Task-10
/// `DopeCardRow { range_yd: u32, .. }` cards. Pins both the review's own worked table and
/// the general "integer-valued" property, without spinning up the CLI or parsing PDF bytes.
#[cfg(all(test, feature = "pdf"))]
mod dope_card_row_tests {
    use super::{dope_card_row_from_sample, trajectory_sampling, AdjustmentUnit, PdfMetadata};

    fn sample_at(distance_m: f64) -> trajectory_sampling::TrajectorySample {
        trajectory_sampling::TrajectorySample {
            distance_m,
            drop_m: 0.5,
            wind_drift_m: 0.1,
            velocity_mps: 0.0,
            energy_j: 0.0,
            time_s: 0.3,
            flags: Vec::new(),
        }
    }

    fn pdf_meta_fixture() -> PdfMetadata {
        PdfMetadata {
            rifle_name: "Test".to_string(),
            location_name: "Test".to_string(),
            powder: "Test".to_string(),
            bullet_name: "Test".to_string(),
            target_speed_mph: 0.0,
            output_file: None,
            velocity_fps: 2700.0,
            temperature_f: 59.0,
            pressure_inhg: 29.92,
            altitude_ft: 0.0,
            wind_speed_mph: 0.0,
            weight_gr: 175.0,
            font_scale: 1.0,
            bold_data: false,
            adjustment_unit: AdjustmentUnit::Mil,
            windage_unit: AdjustmentUnit::Mil,
        }
    }

    #[test]
    fn trajectory_built_rows_carry_integer_valued_ranges() {
        let pdf_meta = pdf_meta_fixture();
        // (sample distance_m, legacy DopeCardRow{range_yd: u32} equivalent) -- the exact
        // table the review derived by hand from `val / 0.9144`.
        let expected = [
            (100.0, 109.0),
            (110.0, 120.0),
            (120.0, 131.0),
            (130.0, 142.0),
            (730.0, 798.0),
        ];
        for (distance_m, expected_range_yd) in expected {
            let row = dope_card_row_from_sample(
                &sample_at(distance_m),
                &pdf_meta,
                None,
                None,
                0.0,
                0.0,
                1.0,
                1.0,
            );
            assert_eq!(
                row.range, expected_range_yd,
                "distance_m={distance_m}: expected legacy-rounded range {expected_range_yd}, got {}",
                row.range
            );
            // The reviewer's own phrasing of the required property: range is
            // integer-valued (round-tripping through .round() is a no-op), regardless of
            // which specific integer it is.
            assert_eq!(
                (row.range - row.range.round()).abs(),
                0.0,
                "distance_m={distance_m}: range must be integer-valued, got {}",
                row.range
            );
        }
    }
}

/// MBA-1366: the cross-crate proof that `atmosphere::resolve_atmosphere_for_density_altitude`
/// (library) is the exact algebraic inverse of `pdf_dope_card::calculate_density_altitude`
/// (0.33.0 Task 10: also promoted into the library, gated behind the `pdf` feature) -- the
/// strongest correctness check available, per the task brief: a density altitude fed into the
/// inverse function, then that function's OWN output fed back through the FORWARD function
/// this engine already ships to REPORT density altitude, must reproduce the original number.
#[cfg(all(test, feature = "pdf"))]
mod density_altitude_round_trip_tests {
    use ballistics_engine::atmosphere::resolve_atmosphere_for_density_altitude;
    use ballistics_engine::pdf_dope_card::calculate_density_altitude;

    const FT_TO_M: f64 = 0.3048;

    #[test]
    fn density_altitude_round_trips_through_the_dope_card_formula_default_temperature() {
        for da_ft in [0.0_f64, 500.0, 1500.0, 3000.0, 6000.0, 9000.0] {
            let da_m = da_ft * FT_TO_M;
            let (_altitude_m, temp_c, pressure_hpa) =
                resolve_atmosphere_for_density_altitude(da_m, None);

            let temp_f = temp_c * 9.0 / 5.0 + 32.0;
            let pressure_inhg = pressure_hpa / 33.863_886_666_667; // matches pdf_dope_card::INHG_TO_HPA exactly
                                                                   // calculate_density_altitude's own `_altitude_ft` parameter is unused (its DA model
                                                                   // depends only on pressure and temperature) -- pass a deliberately wrong value (a
                                                                   // large negative sentinel) to prove that at the same time.
            let round_tripped_ft = calculate_density_altitude(-999_999.0, pressure_inhg, temp_f);

            assert!(
                (round_tripped_ft - da_ft).abs() < 1e-6,
                "da_ft={da_ft}: round-tripped {round_tripped_ft} (temp_c={temp_c}, \
                 pressure_hpa={pressure_hpa})"
            );
        }
    }

    #[test]
    fn density_altitude_round_trips_through_the_dope_card_formula_explicit_temperature() {
        for da_ft in [0.0_f64, 1000.0, 4000.0, 8000.0] {
            for explicit_temp_c in [-10.0_f64, 0.0, 25.0, 40.0] {
                let da_m = da_ft * FT_TO_M;
                let (_altitude_m, temp_c, pressure_hpa) =
                    resolve_atmosphere_for_density_altitude(da_m, Some(explicit_temp_c));
                assert_eq!(
                    temp_c, explicit_temp_c,
                    "explicit temperature must be honored exactly"
                );

                let temp_f = temp_c * 9.0 / 5.0 + 32.0;
                let pressure_inhg = pressure_hpa / 33.863_886_666_667; // matches pdf_dope_card::INHG_TO_HPA exactly
                let round_tripped_ft = calculate_density_altitude(0.0, pressure_inhg, temp_f);

                assert!(
                    (round_tripped_ft - da_ft).abs() < 1e-6,
                    "da_ft={da_ft} explicit_temp_c={explicit_temp_c}: round-tripped \
                     {round_tripped_ft} (pressure_hpa={pressure_hpa})"
                );
            }
        }
    }
}

#[cfg(test)]
mod profile_unit_tests {
    use super::*;
    use ballistics_engine::optic::HoldBounds;

    fn metric_profile() -> ProfileData {
        ProfileData {
            name: "metric-exact".to_string(),
            velocity: 762.0,
            bc: 0.243,
            mass: 11.339_809_25,
            diameter: 7.8232,
            drag_model: "G7".to_string(),
            twist_rate: Some(254.0),
            sight_height: Some(50.8),
            zero_distance: Some(91.44),
            units: "metric".to_string(),
            temperature: 15.0,
            pressure: 1_013.207_888,
            humidity: 55.0,
            altitude: 304.8,
            bullet_name: Some("175gr SMK".to_string()),
            created: Some("test".to_string()),
            wind_speed: Some(4.4704),
            wind_direction: Some(90.0),
            shooting_angle: Some(-5.0),
            auto_zero: Some(91.44),
            twist_right: Some(false),
            use_bc_segments: Some(true),
            bullet_length: Some(30.48),
            elevation_click: None,
            windage_click: None,
            bc_segments: None,
            drag_curve: None,
            dsf_points: None,
            bc_reference: None,
            pressure_reference: None,
            density_altitude: None,
            zero_poi_up_m: None,
            zero_poi_right_m: None,
            sight_offset_lateral_m: None,
            elevation_cf: None,
            windage_cf: None,
            zero_sets: None,
            reticle: None,
            clicks_per_revolution: None,
            zero_stop: None,
            elevation_travel_up_mil: None,
            elevation_travel_down_mil: None,
            windage_travel_left_mil: None,
            windage_travel_right_mil: None,
            turret_elevation_dialed_mil: None,
            turret_windage_dialed_mil: None,
            hold_bound_up_mil: None,
            hold_bound_down_mil: None,
            hold_bound_left_mil: None,
            hold_bound_right_mil: None,
        }
    }

    fn assert_close(actual: f64, expected: f64) {
        let tolerance = expected.abs().max(1.0) * 1e-12;
        assert!(
            (actual - expected).abs() <= tolerance,
            "actual={actual} expected={expected}"
        );
    }

    #[test]
    fn profile_conversion_preserves_physics_and_unitless_fields() {
        let metric = metric_profile();
        let imperial = metric.clone().converted_to(UnitSystem::Imperial).unwrap();

        assert_eq!(imperial.units, "imperial");
        assert_close(imperial.velocity, 2500.0);
        assert_close(imperial.mass, 175.0);
        assert_close(imperial.diameter, 0.308);
        assert_close(imperial.twist_rate.unwrap(), 10.0);
        assert_close(imperial.sight_height.unwrap(), 2.0);
        assert_close(imperial.zero_distance.unwrap(), 100.0);
        assert_close(imperial.temperature, 59.0);
        assert_close(imperial.pressure, 29.92);
        assert_close(imperial.altitude, 1000.0);
        assert_close(imperial.wind_speed.unwrap(), 10.0);
        assert_close(imperial.auto_zero.unwrap(), 100.0);
        assert_close(imperial.bullet_length.unwrap(), 1.2);
        assert_eq!(imperial.bc.to_bits(), metric.bc.to_bits());
        assert_eq!(imperial.humidity.to_bits(), metric.humidity.to_bits());
        assert_eq!(imperial.wind_direction, metric.wind_direction);
        assert_eq!(imperial.shooting_angle, metric.shooting_angle);
        assert_eq!(imperial.twist_right, metric.twist_right);
        assert_eq!(imperial.use_bc_segments, metric.use_bc_segments);
        assert_eq!(imperial.bullet_name, metric.bullet_name);

        let round_trip = imperial.converted_to(UnitSystem::Metric).unwrap();
        assert_close(round_trip.velocity, metric.velocity);
        assert_close(round_trip.mass, metric.mass);
        assert_close(round_trip.diameter, metric.diameter);
        assert_close(round_trip.twist_rate.unwrap(), metric.twist_rate.unwrap());
        assert_close(
            round_trip.sight_height.unwrap(),
            metric.sight_height.unwrap(),
        );
        assert_close(round_trip.temperature, metric.temperature);
        assert_close(round_trip.pressure, metric.pressure);
        assert_close(round_trip.altitude, metric.altitude);
    }

    #[test]
    fn bc_segments_and_drag_curve_survive_unit_conversion_untouched() {
        // bc_segments/drag_curve are unit-invariant/SI-pinned (see their doc comments on
        // ProfileBcSegment/ProfileDragPoint) — converted_to must be a bit-exact no-op for
        // them in both directions, never rescaling velocity_mps/mach/cd.
        let base = metric_profile();
        let with_v2_fields = ProfileData {
            bc_segments: Some(vec![
                ProfileBcSegment {
                    bc: 0.243,
                    velocity_mps: 792.0,
                },
                ProfileBcSegment {
                    bc: 0.230,
                    velocity_mps: 400.0,
                },
            ]),
            drag_curve: Some(vec![
                ProfileDragPoint {
                    mach: 0.5,
                    cd: 0.23,
                },
                ProfileDragPoint {
                    mach: 1.2,
                    cd: 0.45,
                },
                ProfileDragPoint {
                    mach: 3.0,
                    cd: 0.28,
                },
            ]),
            ..base
        };

        let imperial = with_v2_fields
            .clone()
            .converted_to(UnitSystem::Imperial)
            .unwrap();
        assert_eq!(imperial.bc_segments, with_v2_fields.bc_segments);
        assert_eq!(imperial.drag_curve, with_v2_fields.drag_curve);

        let round_trip = imperial.converted_to(UnitSystem::Metric).unwrap();
        assert_eq!(round_trip.bc_segments, with_v2_fields.bc_segments);
        assert_eq!(round_trip.drag_curve, with_v2_fields.drag_curve);

        // Same-unit short-circuit path (source == target) must also preserve them.
        let same_unit = with_v2_fields
            .clone()
            .converted_to(UnitSystem::Metric)
            .unwrap();
        assert_eq!(same_unit.bc_segments, with_v2_fields.bc_segments);
        assert_eq!(same_unit.drag_curve, with_v2_fields.drag_curve);
    }

    /// A Phase-1-era profile JSON (no bc_segments/drag_curve keys at all) must still
    /// deserialize cleanly, with both new fields defaulting to None (MBA-1323 Phase 2
    /// backward compatibility).
    #[test]
    fn phase1_profile_json_without_v2_fields_deserializes_with_none() {
        let phase1_json = r#"{
            "name": "phase1-profile",
            "velocity": 2700.0,
            "bc": 0.475,
            "mass": 175.0,
            "diameter": 0.308,
            "drag_model": "G7",
            "units": "imperial",
            "temperature": 59.0,
            "pressure": 29.92,
            "humidity": 50.0,
            "altitude": 0.0
        }"#;
        let profile: ProfileData = serde_json::from_str(phase1_json).unwrap();
        assert_eq!(profile.name, "phase1-profile");
        assert!(profile.bc_segments.is_none());
        assert!(profile.drag_curve.is_none());

        // And re-serializing must NOT introduce the new keys (skip_serializing_if), so a
        // profile untouched by Phase 2 features stays byte-for-byte compatible with tools
        // reading the old schema.
        let reserialized = serde_json::to_string(&profile).unwrap();
        assert!(!reserialized.contains("bc_segments"));
        assert!(!reserialized.contains("drag_curve"));
    }

    /// MBA-1365: a profile saved before `bc_reference` existed (no key at all) must still
    /// deserialize cleanly, defaulting to ICAO, and must NOT gain the key on re-save —
    /// same forward-compat contract as `bc_segments`/`drag_curve` above.
    #[test]
    fn profile_without_bc_reference_key_round_trips_as_icao() {
        let phase1_json = r#"{
            "name": "pre-mba-1365",
            "velocity": 2700.0,
            "bc": 0.475,
            "mass": 175.0,
            "diameter": 0.308,
            "drag_model": "G7",
            "units": "imperial",
            "temperature": 59.0,
            "pressure": 29.92,
            "humidity": 50.0,
            "altitude": 0.0
        }"#;
        let profile: ProfileData = serde_json::from_str(phase1_json).unwrap();
        assert_eq!(profile.bc_reference, None);
        assert_eq!(
            parse_bc_reference_profile_field(profile.bc_reference.as_deref()).unwrap(),
            BcReferenceStandard::Icao
        );

        let reserialized = serde_json::to_string(&profile).unwrap();
        assert!(!reserialized.contains("bc_reference"));
    }

    /// A profile that DOES declare `bc_reference: "army-standard-metro"` must round-trip
    /// through save/load with the declared standard intact.
    #[test]
    fn profile_with_army_standard_metro_bc_reference_round_trips() {
        let profile = ProfileData {
            bc_reference: Some("army-standard-metro".to_string()),
            ..metric_profile()
        };
        let json = serde_json::to_string(&profile).unwrap();
        assert!(json.contains("army-standard-metro"));

        let reloaded: ProfileData = serde_json::from_str(&json).unwrap();
        assert_eq!(
            reloaded.bc_reference.as_deref(),
            Some("army-standard-metro")
        );
        assert_eq!(
            parse_bc_reference_profile_field(reloaded.bc_reference.as_deref()).unwrap(),
            BcReferenceStandard::ArmyStandardMetro
        );
    }

    #[test]
    fn parse_bc_reference_profile_field_rejects_garbage() {
        assert!(parse_bc_reference_profile_field(Some("metro")).is_err());
        assert!(parse_bc_reference_profile_field(Some("ICAO")).is_ok()); // case-insensitive
    }

    /// MBA-1397: a profile saved before `pressure_reference` existed (no key at all) must
    /// still deserialize cleanly, defaulting to Absolute, and must NOT gain the key on
    /// re-save — same forward-compat contract as `bc_reference` above.
    #[test]
    fn profile_without_pressure_reference_key_round_trips_as_absolute() {
        let phase1_json = r#"{
            "name": "pre-mba-1397",
            "velocity": 2700.0,
            "bc": 0.475,
            "mass": 175.0,
            "diameter": 0.308,
            "drag_model": "G7",
            "units": "imperial",
            "temperature": 59.0,
            "pressure": 29.92,
            "humidity": 50.0,
            "altitude": 0.0
        }"#;
        let profile: ProfileData = serde_json::from_str(phase1_json).unwrap();
        assert_eq!(profile.pressure_reference, None);
        assert_eq!(
            parse_pressure_reference_profile_field(profile.pressure_reference.as_deref()).unwrap(),
            PressureReferenceMode::Absolute
        );

        let reserialized = serde_json::to_string(&profile).unwrap();
        assert!(!reserialized.contains("pressure_reference"));
    }

    /// A profile that DOES declare `pressure_reference: "qnh"` must round-trip through
    /// save/load with the declared mode intact.
    #[test]
    fn profile_with_qnh_pressure_reference_round_trips() {
        let profile = ProfileData {
            pressure_reference: Some("qnh".to_string()),
            ..metric_profile()
        };
        let json = serde_json::to_string(&profile).unwrap();
        assert!(json.contains("qnh"));

        let reloaded: ProfileData = serde_json::from_str(&json).unwrap();
        assert_eq!(reloaded.pressure_reference.as_deref(), Some("qnh"));
        assert_eq!(
            parse_pressure_reference_profile_field(reloaded.pressure_reference.as_deref()).unwrap(),
            PressureReferenceMode::Qnh
        );
    }

    #[test]
    fn parse_pressure_reference_profile_field_rejects_garbage() {
        assert!(parse_pressure_reference_profile_field(Some("barometric")).is_err());
        assert!(parse_pressure_reference_profile_field(Some("QNH")).is_ok()); // case-insensitive
    }

    /// MBA-1366: a profile saved before `density_altitude` existed (no key at all) must still
    /// deserialize cleanly as `None`, and must NOT gain the key on re-save — same forward-compat
    /// contract as `bc_reference`/`pressure_reference` above.
    #[test]
    fn profile_without_density_altitude_key_round_trips_as_none() {
        let phase1_json = r#"{
            "name": "pre-mba-1366",
            "velocity": 2700.0,
            "bc": 0.475,
            "mass": 175.0,
            "diameter": 0.308,
            "drag_model": "G7",
            "units": "imperial",
            "temperature": 59.0,
            "pressure": 29.92,
            "humidity": 50.0,
            "altitude": 0.0
        }"#;
        let profile: ProfileData = serde_json::from_str(phase1_json).unwrap();
        assert_eq!(profile.density_altitude, None);

        let reserialized = serde_json::to_string(&profile).unwrap();
        assert!(!reserialized.contains("density_altitude"));
    }

    /// A profile that DOES declare `density_altitude` must round-trip through save/load, and
    /// `converted_to` must rescale it exactly like `altitude` (same feet/meters convention).
    #[test]
    fn profile_with_density_altitude_round_trips_and_converts_like_altitude() {
        let profile = ProfileData {
            density_altitude: Some(3000.0), // feet (this fixture's units are imperial-derived)
            units: "imperial".to_string(),
            altitude: 1000.0,
            ..metric_profile()
        };
        let json = serde_json::to_string(&profile).unwrap();
        assert!(json.contains("density_altitude"));

        let reloaded: ProfileData = serde_json::from_str(&json).unwrap();
        assert_eq!(reloaded.density_altitude, Some(3000.0));

        let metric = reloaded.converted_to(UnitSystem::Metric).unwrap();
        let expected_altitude_m = 1000.0 * 0.3048;
        let expected_da_m = 3000.0 * 0.3048;
        assert!((metric.altitude - expected_altitude_m).abs() < 1e-9);
        assert!(
            (metric.density_altitude.unwrap() - expected_da_m).abs() < 1e-9,
            "density_altitude must convert like altitude: got {:?}",
            metric.density_altitude
        );
    }

    #[test]
    fn same_unit_profile_conversion_is_bit_preserving() {
        let profile = metric_profile();
        let before = serde_json::to_string(&profile).unwrap();
        let after = profile.converted_to(UnitSystem::Metric).unwrap();
        assert_eq!(serde_json::to_string(&after).unwrap(), before);
    }

    /// MBA-1359: the zero POI offset fields are unit-FIXED (always meters, like
    /// `ProfileBcSegment::velocity_mps`), so they must round-trip through serde untouched,
    /// stay omitted when absent, and survive a unit flip bit-identically.
    #[test]
    fn zero_poi_fields_round_trip_and_survive_unit_conversion_untouched() {
        // Absent: old profiles deserialize as None and re-serialize without the keys.
        let profile = metric_profile();
        assert_eq!(profile.zero_poi_up_m, None);
        let json = serde_json::to_string(&profile).unwrap();
        assert!(!json.contains("zero_poi_up_m") && !json.contains("zero_poi_right_m"));

        // Present: round-trips, and converted_to leaves the SI values untouched.
        let profile = ProfileData {
            zero_poi_up_m: Some(0.00254),
            zero_poi_right_m: Some(-0.00508),
            sight_offset_lateral_m: Some(0.0127), // MBA-1396, same unit-fixed contract
            ..metric_profile()
        };
        let reloaded: ProfileData =
            serde_json::from_str(&serde_json::to_string(&profile).unwrap()).unwrap();
        assert_eq!(reloaded.zero_poi_up_m, Some(0.00254));
        assert_eq!(reloaded.zero_poi_right_m, Some(-0.00508));
        assert_eq!(reloaded.sight_offset_lateral_m, Some(0.0127));

        let imperial = reloaded.converted_to(UnitSystem::Imperial).unwrap();
        assert_eq!(imperial.zero_poi_up_m, Some(0.00254));
        assert_eq!(imperial.zero_poi_right_m, Some(-0.00508));
        assert_eq!(imperial.sight_offset_lateral_m, Some(0.0127));
    }

    #[test]
    fn converted_profile_keeps_explicit_cli_precedence() {
        let profile = Some(metric_profile().converted_to(UnitSystem::Imperial).unwrap());
        assert_eq!(
            resolve_param(Some(2600.0), &profile, |p| p.velocity),
            Some(2600.0)
        );
        assert_eq!(resolve_param(None, &profile, |p| p.velocity), Some(2500.0));
        assert_eq!(
            Some(2.5).or_else(|| profile.as_ref().and_then(|p| p.sight_height)),
            Some(2.5)
        );
        assert_eq!(
            None.or_else(|| profile.as_ref().and_then(|p| p.sight_height)),
            Some(2.0)
        );
    }

    #[test]
    fn legacy_profiles_default_to_imperial_and_unknown_units_are_rejected() {
        let legacy: ProfileData = serde_json::from_str(
            r#"{"name":"legacy","velocity":2500.0,"bc":0.243,"mass":175.0,"diameter":0.308,"drag_model":"G7"}"#,
        )
        .unwrap();
        assert_eq!(legacy.units, "imperial");
        let metric = legacy.converted_to(UnitSystem::Metric).unwrap();
        assert_close(metric.velocity, 762.0);
        assert_close(metric.mass, 11.339_809_25);
        assert_close(metric.diameter, 7.8232);

        let mut invalid = metric_profile();
        invalid.units = "si".to_string();
        let error = invalid.converted_to(UnitSystem::Imperial).unwrap_err();
        assert!(error.to_string().contains("unsupported units 'si'"));
    }

    #[test]
    fn profile_click_fields_roundtrip_and_flags_override() {
        let mut profile = metric_profile();
        profile.elevation_click = Some("0.1mil".to_string());
        profile.windage_click = Some("0.2mil".to_string());

        // No flags: the profile's own fields resolve directly.
        let (el, wi) = resolve_click_values(None, None, Some(&profile))
            .unwrap()
            .unwrap();
        assert_eq!(el, parse_click_value("0.1mil").unwrap());
        assert_eq!(wi, parse_click_value("0.2mil").unwrap());

        // An explicit flag beats the saved profile.
        let (el2, wi2) = resolve_click_values(Some("0.25moa"), Some("0.5moa"), Some(&profile))
            .unwrap()
            .unwrap();
        assert_eq!(el2, parse_click_value("0.25moa").unwrap());
        assert_eq!(wi2, parse_click_value("0.5moa").unwrap());

        // Elevation-only profile: windage falls back to the profile's elevation click.
        let mut elev_only = metric_profile();
        elev_only.elevation_click = Some("0.25moa".to_string());
        let (el3, wi3) = resolve_click_values(None, None, Some(&elev_only))
            .unwrap()
            .unwrap();
        assert_eq!(el3, wi3);

        // `elevation_click`/`windage_click` are unit-invariant angular graduations, like
        // bc_segments/drag_curve — converted_to must leave them untouched.
        let imperial = profile.clone().converted_to(UnitSystem::Imperial).unwrap();
        assert_eq!(imperial.elevation_click, profile.elevation_click);
        assert_eq!(imperial.windage_click, profile.windage_click);
    }

    #[test]
    fn parse_angular_mil_converts_suffixed_values_exactly() {
        assert_eq!(parse_angular_mil("28mil").unwrap(), 28.0);
        // Same expression order as the implementation (adjustment_factor(Mil) /
        // adjustment_factor(base)), so this is a bit-exact pin, not just "close enough".
        assert_eq!(
            parse_angular_mil("34.38moa").unwrap(),
            34.38 * 1000.0 / 3438.0
        );
        assert_eq!(parse_angular_mil("3.5smoa").unwrap(), 3.5 * 1000.0 / 3600.0);
        // iphy aliases smoa exactly, like parse_click_value's suffix set.
        assert_eq!(
            parse_angular_mil("3.5iphy").unwrap(),
            parse_angular_mil("3.5smoa").unwrap()
        );
        // Signed and zero values are accepted -- unlike parse_click_value's click
        // GRADUATION rule, an angular value here is not a magnitude (turret dialed
        // state is signed).
        assert_eq!(parse_angular_mil("-5.2mil").unwrap(), -5.2);
        assert_eq!(parse_angular_mil("0mil").unwrap(), 0.0);
    }

    #[test]
    fn parse_angular_mil_requires_a_suffix() {
        let e = parse_angular_mil("5").unwrap_err();
        assert!(
            e.contains("mil") && e.contains("moa") && e.contains("smoa"),
            "{e}"
        );
        assert!(parse_angular_mil("").is_err());
        assert!(parse_angular_mil("mil").is_err()); // no numeric part
        assert!(parse_angular_mil("nanmil").is_err()); // must be finite
        assert!(parse_angular_mil("infmil").is_err()); // must be finite
    }

    /// MBA-1348: all twelve turret/hold fields round-trip through save/load (serde), and
    /// `optic_profile()` assembles + validates a well-formed `OpticProfile` from them —
    /// windage-falls-back-to-elevation is exercised separately below, so here both click
    /// fields are set explicitly.
    #[test]
    fn optic_fields_round_trip_and_assemble_into_a_valid_optic_profile() {
        let profile = ProfileData {
            elevation_click: Some("0.1mil".to_string()),
            windage_click: Some("0.2mil".to_string()),
            clicks_per_revolution: Some(12),
            zero_stop: Some(true),
            elevation_travel_up_mil: Some(28.0),
            elevation_travel_down_mil: Some(5.0),
            windage_travel_left_mil: Some(10.0),
            windage_travel_right_mil: Some(11.0),
            turret_elevation_dialed_mil: Some(3.5),
            turret_windage_dialed_mil: Some(-1.2),
            hold_bound_up_mil: Some(4.0),
            hold_bound_down_mil: Some(12.0),
            hold_bound_left_mil: Some(6.0),
            hold_bound_right_mil: Some(6.5),
            ..metric_profile()
        };

        let json = serde_json::to_string_pretty(&profile).unwrap();
        let reloaded: ProfileData = serde_json::from_str(&json).unwrap();
        assert_eq!(reloaded.clicks_per_revolution, Some(12));
        assert_eq!(reloaded.zero_stop, Some(true));
        assert_eq!(reloaded.elevation_travel_up_mil, Some(28.0));
        assert_eq!(reloaded.elevation_travel_down_mil, Some(5.0));
        assert_eq!(reloaded.windage_travel_left_mil, Some(10.0));
        assert_eq!(reloaded.windage_travel_right_mil, Some(11.0));
        assert_eq!(reloaded.turret_elevation_dialed_mil, Some(3.5));
        assert_eq!(reloaded.turret_windage_dialed_mil, Some(-1.2));
        assert_eq!(reloaded.hold_bound_up_mil, Some(4.0));
        assert_eq!(reloaded.hold_bound_down_mil, Some(12.0));
        assert_eq!(reloaded.hold_bound_left_mil, Some(6.0));
        assert_eq!(reloaded.hold_bound_right_mil, Some(6.5));

        let optic = reloaded
            .optic_profile()
            .unwrap()
            .expect("elevation_click set");
        optic.validate().expect("well-formed optic profile");
        assert_eq!(optic.elevation_click, parse_click_value("0.1mil").unwrap());
        assert_eq!(optic.windage_click, parse_click_value("0.2mil").unwrap());
        assert_eq!(optic.clicks_per_revolution, Some(12));
        assert!(optic.zero_stop);
        assert_eq!(
            optic.elevation_travel,
            Some(TravelLimits {
                up_mil: 28.0,
                down_mil: 5.0
            })
        );
        assert_eq!(
            optic.windage_travel,
            Some(TravelLimits {
                up_mil: 11.0,
                down_mil: 10.0
            })
        );
        assert_eq!(
            optic.turret_state,
            Some(TurretState {
                elevation_mil: 3.5,
                windage_mil: -1.2
            })
        );
        assert_eq!(
            optic.reticle_hold_bounds,
            Some(HoldBounds {
                up_mil: 4.0,
                down_mil: 12.0,
                left_mil: 6.0,
                right_mil: 6.5
            })
        );

        // Unit-invariant (angular turret/reticle geometry, not linear) -- converted_to
        // must leave all twelve untouched, like elevation_click/windage_click.
        let imperial = reloaded.clone().converted_to(UnitSystem::Imperial).unwrap();
        assert_eq!(
            imperial.elevation_travel_up_mil,
            reloaded.elevation_travel_up_mil
        );
        assert_eq!(imperial.hold_bound_right_mil, reloaded.hold_bound_right_mil);
        assert_eq!(
            imperial.turret_windage_dialed_mil,
            reloaded.turret_windage_dialed_mil
        );
    }

    /// Absent fields: `optic_profile()` still assembles (elevation_click alone is
    /// enough), with `None` for everything else and `zero_stop` defaulting to `false`.
    #[test]
    fn optic_profile_with_only_elevation_click_set_has_none_for_the_rest() {
        let profile = ProfileData {
            elevation_click: Some("0.25moa".to_string()),
            ..metric_profile()
        };
        let optic = profile
            .optic_profile()
            .unwrap()
            .expect("elevation_click set");
        assert_eq!(optic.windage_click, optic.elevation_click); // windage falls back
        assert_eq!(optic.clicks_per_revolution, None);
        assert!(!optic.zero_stop); // absent -> false default
        assert_eq!(optic.elevation_travel, None);
        assert_eq!(optic.windage_travel, None);
        assert_eq!(optic.turret_state, None);
        assert_eq!(optic.reticle_hold_bounds, None);
        optic
            .validate()
            .expect("a minimal optic profile is still valid");
    }

    /// `optic_profile()` returns `Ok(None)` only when NONE of the twelve fields are set
    /// -- a completely untouched profile has never been given a turret model, which is a
    /// harmless, common (every pre-MBA-1348 profile) case, not an error.
    #[test]
    fn optic_profile_is_none_for_a_completely_untouched_profile() {
        assert_eq!(metric_profile().optic_profile().unwrap(), None);
    }

    /// `OpticProfile::elevation_click` is mandatory, not `Option` -- so the other eleven
    /// fields are meaningless without it (MBA-1348 review fix): setting any of them
    /// without also setting `elevation_click` is a save-time `Err`, not a silent `Ok(None)`
    /// that would otherwise let turret/hold data no downstream code can use slip through
    /// unvalidated (this was caught by a manual CLI smoke test of `profile save
    /// --travel-up ... --turret-elev ...` with no `--elevation-click`, which saved
    /// successfully despite the dialed state exceeding the declared travel -- the
    /// cross-field check in `OpticProfile::validate()` never ran because assembly bailed
    /// out to `Ok(None)` before reaching it).
    #[test]
    fn optic_profile_errors_when_other_fields_are_set_without_an_elevation_click() {
        let profile = ProfileData {
            elevation_travel_up_mil: Some(10.0),
            elevation_travel_down_mil: Some(10.0),
            ..metric_profile()
        };
        let err = profile.optic_profile().unwrap_err();
        assert!(err.contains("--elevation-click"), "{err}");
    }

    /// The specific scenario the smoke test caught: a complete travel pair AND a
    /// complete (but out-of-range) turret-state pair, with no `elevation_click` at all,
    /// must still be rejected at `optic_profile()` -- not silently accepted because the
    /// state-vs-travel cross-check in `validate()` never got a chance to run.
    #[test]
    fn optic_profile_errors_on_out_of_range_state_even_without_an_elevation_click() {
        let profile = ProfileData {
            elevation_travel_up_mil: Some(10.0),
            elevation_travel_down_mil: Some(10.0),
            turret_elevation_dialed_mil: Some(15.0), // outside +-10, but never checked
            turret_windage_dialed_mil: Some(0.0),
            ..metric_profile()
        };
        let err = profile.optic_profile().unwrap_err();
        assert!(err.contains("--elevation-click"), "{err}");
    }

    /// The save-time guarantee (MBA-1348): a dialed turret state outside its own
    /// declared travel fails `OpticProfile::validate()`, naming the axis -- exactly the
    /// check `profile save` runs (via `optic_profile()` + `validate()`) before writing
    /// anything to disk.
    #[test]
    fn optic_profile_validation_fails_naming_the_axis_when_dialed_state_exceeds_travel() {
        let profile = ProfileData {
            elevation_click: Some("0.1mil".to_string()),
            elevation_travel_up_mil: Some(10.0),
            elevation_travel_down_mil: Some(10.0),
            turret_elevation_dialed_mil: Some(15.0), // outside +-10
            turret_windage_dialed_mil: Some(0.0),
            ..metric_profile()
        };
        let optic = profile
            .optic_profile()
            .unwrap()
            .expect("elevation_click set");
        let err = optic.validate().unwrap_err().to_string();
        assert!(err.contains("elevation"), "{err}");
        assert!(err.contains("outside its travel"), "{err}");
    }

    /// A travel pair set on only one side is a named-field `Err`, not a silent "0.0 on
    /// the other side" guess (see `require_angular_pair`'s own doc comment for why).
    /// Names the FLAG the user would type (MBA-1348 review fix I2) -- `--travel-up`, not
    /// the internal `elevation_travel_up_mil` struct field the flag maps onto -- since
    /// that mapping drops the "elevation" axis prefix and isn't otherwise mechanical.
    #[test]
    fn optic_profile_errors_naming_the_flag_when_a_travel_pair_is_incomplete() {
        let profile = ProfileData {
            elevation_click: Some("0.1mil".to_string()),
            elevation_travel_up_mil: Some(10.0),
            ..metric_profile()
        };
        let err = profile.optic_profile().unwrap_err();
        assert!(err.contains("--travel-up"), "{err}");
        assert!(err.contains("--travel-down"), "{err}");
        assert!(!err.contains("elevation_travel_up_mil"), "{err}");
    }

    /// Same all-or-nothing rule for `HoldBounds`' four fields, naming every FLAG still
    /// missing (MBA-1348 review fix I2), not the internal struct fields (see
    /// `require_hold_bounds`).
    #[test]
    fn optic_profile_errors_naming_missing_flags_when_hold_bounds_are_incomplete() {
        let profile = ProfileData {
            elevation_click: Some("0.1mil".to_string()),
            hold_bound_up_mil: Some(4.0),
            hold_bound_left_mil: Some(6.0),
            ..metric_profile()
        };
        let err = profile.optic_profile().unwrap_err();
        assert!(err.contains("--hold-down"), "{err}");
        assert!(err.contains("--hold-right"), "{err}");
        assert!(!err.contains("hold_bound_down_mil"), "{err}");
    }

    /// Another `OpticProfile::validate()` rule reachable through the save-time wiring
    /// (a manual CLI smoke test of `profile save --clicks-per-rev 0` confirmed this end
    /// to end): `clicks_per_revolution` must be at least 1 when present.
    #[test]
    fn optic_profile_validation_fails_for_zero_clicks_per_revolution() {
        let profile = ProfileData {
            elevation_click: Some("0.1mil".to_string()),
            clicks_per_revolution: Some(0),
            ..metric_profile()
        };
        let optic = profile
            .optic_profile()
            .unwrap()
            .expect("elevation_click set");
        let err = optic.validate().unwrap_err().to_string();
        assert!(err.contains("clicks_per_revolution"), "{err}");
    }

    /// MBA-1360: zero sets round-trip through serde; a profile without the key loads
    /// as `None` (every pre-1360 profile); an untouched profile serializes with no
    /// `zero_sets` key at all.
    #[test]
    fn zero_sets_roundtrip_and_absent_key_stays_absent() {
        let mut profile = metric_profile();
        assert!(!serde_json::to_string(&profile)
            .unwrap()
            .contains("zero_sets"));

        profile.zero_sets = Some(vec![
            ProfileZeroSet {
                name: "suppressed".to_string(),
                zero_distance: Some(200.0),
                poi_up_mil: Some(-0.3),
                poi_right_mil: Some(0.1),
                notes: Some("suppressed load".to_string()),
            },
            ProfileZeroSet {
                name: "match".to_string(),
                zero_distance: None,
                poi_up_mil: Some(0.25),
                poi_right_mil: None,
                notes: None,
            },
        ]);
        let json = serde_json::to_string_pretty(&profile).unwrap();
        let back: ProfileData = serde_json::from_str(&json).unwrap();
        assert_eq!(back.zero_sets, profile.zero_sets);
    }

    /// MBA-1360 forward-compat guard (the ticket's acceptance criterion, bc_segments
    /// pattern): an OLD reader — simulated by a struct lacking the field — loads a
    /// zero-set-bearing profile cleanly and solves with the master zero (identical to a
    /// new reader with no `--zero-set`), and the documented one-way skew is that its
    /// re-save DROPS the key. Requesting a set on an old binary fails loudly at the
    /// unknown `--zero-set` flag; it can never silently select one.
    #[test]
    fn old_reader_drops_zero_sets_on_resave_and_keeps_master_zero() {
        #[derive(serde::Serialize, serde::Deserialize)]
        struct OldProfileData {
            name: String,
            velocity: f64,
            bc: f64,
            mass: f64,
            diameter: f64,
            drag_model: String,
            #[serde(default)]
            zero_distance: Option<f64>,
            #[serde(default)]
            auto_zero: Option<f64>,
        }

        let mut profile = metric_profile();
        profile.zero_sets = Some(vec![ProfileZeroSet {
            name: "alt".to_string(),
            zero_distance: Some(300.0),
            poi_up_mil: Some(-0.5),
            poi_right_mil: None,
            notes: None,
        }]);
        let json = serde_json::to_string_pretty(&profile).unwrap();

        // The old reader loads cleanly (serde's non-deny_unknown_fields default) and
        // sees the untouched MASTER zero, not the alternate set's.
        let old: OldProfileData = serde_json::from_str(&json).expect("old reader loads");
        assert_eq!(old.zero_distance, Some(91.44));
        assert_eq!(old.auto_zero, Some(91.44));

        // Its re-save silently drops the key (the documented bc_segments-class skew)...
        let resaved = serde_json::to_string(&old).unwrap();
        assert!(!resaved.contains("zero_sets"));
        // ...which a new reader then loads as "no zero sets", so a later --zero-set
        // fails loudly instead of silently solving with the master zero.
        let reread: ProfileData = serde_json::from_str(&json).unwrap();
        let err = resolve_zero_selection(Some("gone"), Some(&reread), None, None, None)
            .map(|_| ())
            .unwrap_err();
        assert!(err.contains("available zero sets: alt"), "{err}");
    }

    /// MBA-1360: converted_to rescales each set's zero_distance exactly like the
    /// profile's own zero_distance, and leaves the angular mil corrections untouched.
    #[test]
    fn converted_to_rescales_zero_set_distances_only() {
        let mut profile = metric_profile();
        profile.zero_sets = Some(vec![ProfileZeroSet {
            name: "far".to_string(),
            zero_distance: Some(91.44),
            poi_up_mil: Some(-0.3),
            poi_right_mil: Some(0.15),
            notes: None,
        }]);
        let imperial = profile.converted_to(UnitSystem::Imperial).unwrap();
        let set = &imperial.zero_sets.as_deref().unwrap()[0];
        assert_close(set.zero_distance.unwrap(), 100.0);
        assert_eq!(set.poi_up_mil, Some(-0.3));
        assert_eq!(set.poi_right_mil, Some(0.15));
    }

    /// MBA-1360 resolver: precedence (explicit flag > selected set > legacy chain),
    /// byte-identity shape with no set selected, unknown-name/no-sets hard errors, and
    /// the CSV-derived ephemeral set participating in lookup.
    #[test]
    fn zero_selection_resolver_precedence_and_errors() {
        let mut profile = metric_profile();
        profile.zero_sets = Some(vec![ProfileZeroSet {
            name: "far".to_string(),
            zero_distance: Some(300.0),
            poi_up_mil: Some(0.25),
            poi_right_mil: Some(-0.1),
            notes: None,
        }]);

        // No set selected: exactly the legacy chain, zero biases.
        let sel = resolve_zero_selection(None, Some(&profile), None, None, Some(91.44)).unwrap();
        assert_eq!(sel.zero_distance, Some(91.44));
        assert_eq!(sel.elevation_bias_mil, 0.0);
        assert_eq!(sel.windage_bias_mil, 0.0);

        // Selected: the set's zero_distance beats the legacy chain; biases flow.
        let sel =
            resolve_zero_selection(Some("far"), Some(&profile), None, None, Some(91.44)).unwrap();
        assert_eq!(sel.zero_distance, Some(300.0));
        assert_eq!(sel.elevation_bias_mil, 0.25);
        assert_eq!(sel.windage_bias_mil, -0.1);

        // An explicit CLI zero still wins over the selected set.
        let sel =
            resolve_zero_selection(Some("far"), Some(&profile), None, Some(150.0), None).unwrap();
        assert_eq!(sel.zero_distance, Some(150.0));
        assert_eq!(sel.elevation_bias_mil, 0.25);

        // Unknown name: hard error listing every candidate, including a CSV-derived
        // ephemeral set.
        let mut csv = HashMap::new();
        csv.insert("V_OFFSET_MIL".to_string(), "0.3".to_string());
        csv.insert("H_OFFSET_MIL".to_string(), "-0.1".to_string());
        let csv_set = zero_set_from_profile_csv(&csv, Some("R1")).expect("csv set");
        assert_eq!(csv_set.poi_up_mil, Some(0.3));
        assert_eq!(csv_set.poi_right_mil, Some(-0.1));
        let err = resolve_zero_selection(Some("nope"), Some(&profile), Some(&csv_set), None, None)
            .map(|_| ())
            .unwrap_err();
        assert!(err.contains("available zero sets: far, R1"), "{err}");

        // The CSV set itself is selectable by row name.
        let sel = resolve_zero_selection(Some("R1"), None, Some(&csv_set), None, None).unwrap();
        assert_eq!(sel.elevation_bias_mil, 0.3);
        assert_eq!(sel.windage_bias_mil, -0.1);

        // No profile and no CSV set: hard error naming the requirement.
        let err = resolve_zero_selection(Some("x"), None, None, None, None)
            .map(|_| ())
            .unwrap_err();
        assert!(err.contains("requires a profile"), "{err}");

        // A CSV row without either offset column yields no ephemeral set at all.
        assert!(zero_set_from_profile_csv(&HashMap::new(), Some("R1")).is_none());
    }

    /// MBA-1360 x MBA-1358 ordering pin (the composition rule): the zero-set bias is
    /// added to the TRUE angular need BEFORE the tracking-CF division —
    /// display = (true + bias) / CF — on both the angular and the clicks arms.
    #[test]
    fn zero_set_bias_applies_before_the_cf_division() {
        let drop_yd = 0.2; // 7.2 in at 200 yd = 1.0 mil
        let range_yd = 200.0;
        let base = drop_to_adjustment(drop_yd, range_yd, AdjustmentUnit::Mil);
        assert!((base - 1.0).abs() < 1e-12);

        let cf = 0.95;
        let bias = 0.25;
        let got = adjustment_display(drop_yd, range_yd, AdjustmentUnit::Mil, None, bias, cf).value;
        assert!(
            ((got - (base + bias) / cf).abs()) < 1e-12,
            "expected (true + bias)/cf, got {got}"
        );
        // NOT the other order:
        assert!((got - (base / cf + bias)).abs() > 1e-3);

        // MOA arm gets the same ANGULAR correction, rescaled through the shared factors.
        let moa = adjustment_display(drop_yd, range_yd, AdjustmentUnit::Moa, None, bias, cf).value;
        let base_moa = drop_to_adjustment(drop_yd, range_yd, AdjustmentUnit::Moa);
        let expected_moa = (base_moa + bias * 3.438) / cf;
        assert!((moa - expected_moa).abs() < 1e-12, "moa = {moa}");

        // Clicks arm: (true + bias)/cf first, quantized after.
        let click = parse_click_value("0.1mil").unwrap();
        let clicks = adjustment_display(
            drop_yd,
            range_yd,
            AdjustmentUnit::Clicks,
            Some(click),
            bias,
            cf,
        )
        .value;
        let expected_clicks = (((base + bias) / cf) / 0.1).round();
        assert_eq!(clicks, expected_clicks);

        // Zero bias is an exact no-op on every arm.
        let none = adjustment_display(drop_yd, range_yd, AdjustmentUnit::Mil, None, 0.0, cf).value;
        assert_eq!(none.to_bits(), (base / cf).to_bits());
    }

    /// Delegation-equivalence pin (Plan B Task 2): the clicks arm of `adjustment_display`
    /// now INLINES `clicks_for`'s own guard + angle formula (so it can keep the residual)
    /// instead of calling it — this must not drift from `clicks_for` itself. Checked
    /// across several inputs, including a sub-1-yard range that exercises the short-range
    /// guard (0 clicks).
    #[test]
    fn adjustment_display_clicks_arm_delegates_to_clicks_for() {
        let mil = parse_click_value("0.1mil").unwrap();
        let quarter_moa = parse_click_value("0.25moa").unwrap();
        // (drop_yd, range_yd, unit, click, bias_mil, cf)
        let cases = [
            (0.2, 200.0, AdjustmentUnit::Clicks, mil, 0.0, 1.0),
            (0.2, 200.0, AdjustmentUnit::Clicks, mil, 0.25, 0.95),
            (-0.37, 300.0, AdjustmentUnit::Clicks, quarter_moa, 0.0, 1.0),
            (1.6, 400.0, AdjustmentUnit::Clicks, quarter_moa, -0.5, 1.05),
            // sub-1-yard range: clicks_for's own guard, independent of bias/cf.
            (10.0, 0.5, AdjustmentUnit::Clicks, mil, 1.0, 0.5),
        ];
        for (drop_yd, range_yd, unit, click, bias_mil, cf) in cases {
            let got = adjustment_display(drop_yd, range_yd, unit, Some(click), bias_mil, cf).value;
            let biased_drop_yd = if bias_mil != 0.0 {
                drop_yd + bias_mil / 1000.0 * range_yd
            } else {
                drop_yd
            };
            let want = clicks_for(biased_drop_yd / cf, range_yd, &click) as f64;
            assert_eq!(
                got, want,
                "drop_yd={drop_yd} range_yd={range_yd} bias_mil={bias_mil} cf={cf}"
            );
        }
    }

    /// Order-sensitivity pin (Plan B Task 2) -- THE load-bearing invariant: bias joins the
    /// drop-equivalent FIRST, the tracking CF divides SECOND, and quantization to whole
    /// clicks happens THIRD. Reordering bias/CF changes which click the result rounds to,
    /// so this input is deliberately chosen to be sensitive to that order (a refactor that
    /// silently swaps the order will fail this test, not just move a number slightly).
    ///
    /// Hand derivation, following the actual drop-space formula (bias joins as a
    /// drop-equivalent before the CF division, matching the code -- see
    /// `adjustment_display`'s clicks arm): drop_yd = 0.6, range_yd = 100.0, bias_mil =
    /// 1.0, cf = 0.5, click = 0.1mil.
    /// - CORRECT order (bias first, then /CF, then quantize): `biased_drop_yd = drop_yd +
    ///   bias_mil/1000*range_yd = 0.6 + 0.1 = 0.7`; `drop_for_clicks = biased_drop_yd/cf =
    ///   0.7/0.5 = 1.4`; `angle = drop_for_clicks/range_yd * 1000 = 1.4/100*1000`, which in
    ///   f64 is `13.999999999999998` (not exactly 14.0 -- ordinary floating-point
    ///   representation error from this particular chain of divisions, not a bug) ->
    ///   `clicks = round(angle / 0.1) = round(139.99999999999997) = 140`.
    /// - WRONG order (CF divides only the pre-bias angle, bias added unscaled after -- the
    ///   bug this guards against): `base = drop_yd/range_yd * 1000 = 6.0` mil exactly ->
    ///   `angle_wrong = base/cf + bias_mil = 6.0/0.5 + 1.0 = 13.0` mil exactly ->
    ///   `clicks_wrong = round(13.0 / 0.1) = 130`.
    /// - The two orders disagree by `bias_mil * (1/cf - 1) = 1.0 * 1.0 = 1.0` mil == 10
    ///   clicks (140 vs 130) -- a full 10-click miss, not a rounding-boundary artifact, so
    ///   ordinary float noise cannot make the two orders coincide here. The residual is
    ///   correspondingly NOT exactly 0.0 (it inherits that same ~1.8e-15 deviation from
    ///   14.0); the reconstruction assertion below checks it bit-exactly rather than
    ///   asserting a specific value.
    #[test]
    fn clicks_arm_order_of_operations_is_load_bearing() {
        let click = parse_click_value("0.1mil").unwrap();
        let (drop_yd, range_yd, bias_mil, cf) = (0.6, 100.0, 1.0, 0.5);

        let result = adjustment_display(
            drop_yd,
            range_yd,
            AdjustmentUnit::Clicks,
            Some(click),
            bias_mil,
            cf,
        );

        assert_eq!(
            result.value, 140.0,
            "expected the bias-then-CF order's 140 clicks"
        );
        let wrong_order_clicks = {
            let base = (drop_yd / range_yd) * adjustment_factor(ClickBase::Mil);
            let angle_wrong = base / cf + bias_mil;
            (angle_wrong / click.size).round()
        };
        assert_eq!(
            wrong_order_clicks, 130.0,
            "sanity: the wrong order really does diverge"
        );
        assert_ne!(result.value, wrong_order_clicks);

        // Bit-exact reconstruction: clicks*size + residual == the angle actually
        // quantized (recomputed independently here, the same way the boundary derives it).
        let q = result
            .quantized
            .expect("clicks arm always returns Some(Quantized)");
        assert_eq!(q.clicks, 140);
        let biased_drop_yd = drop_yd + bias_mil / 1000.0 * range_yd;
        let angle = (biased_drop_yd / cf / range_yd) * adjustment_factor(ClickBase::Mil);
        assert_eq!(
            (q.clicks as f64 * click.size + q.residual).to_bits(),
            angle.to_bits(),
            "clicks*size + residual must reconstruct the quantized angle bit-exactly"
        );
    }
}

#[cfg(test)]
#[cfg(feature = "profile-import")]
mod a7p_import_mapping_tests {
    use super::*;
    use ballistics_engine::profile_import::{parse_a7p, wrap_payload};

    // Spec-derived test encoders (kept deliberately independent of the lib).
    fn enc_varint(mut v: u64, out: &mut Vec<u8>) {
        loop {
            let byte = (v & 0x7f) as u8;
            v >>= 7;
            if v == 0 {
                out.push(byte);
                return;
            }
            out.push(byte | 0x80);
        }
    }
    fn enc_i32(number: u32, value: i64, out: &mut Vec<u8>) {
        enc_varint(u64::from(number) << 3, out);
        enc_varint(value as u64, out);
    }
    fn enc_str(number: u32, s: &str, out: &mut Vec<u8>) {
        enc_varint((u64::from(number) << 3) | 2, out);
        enc_varint(s.len() as u64, out);
        out.extend_from_slice(s.as_bytes());
    }
    fn enc_bytes(number: u32, payload: &[u8], out: &mut Vec<u8>) {
        enc_varint((u64::from(number) << 3) | 2, out);
        enc_varint(payload.len() as u64, out);
        out.extend_from_slice(payload);
    }

    fn barnes_338_file(bc_type: i64) -> Vec<u8> {
        let mut p = Vec::new();
        enc_str(1, "338LM/BARNES 300", &mut p); // '/' must be sanitized
        enc_str(3, "BARNES 300GR OTM", &mut p);
        enc_i32(9, 90, &mut p);
        enc_i32(10, 1000, &mut p);
        enc_i32(11, 7920, &mut p);
        enc_i32(12, 15, &mut p);
        enc_i32(13, 1000, &mut p);
        enc_i32(15, 15, &mut p);
        enc_i32(16, 10000, &mut p);
        enc_i32(17, 50, &mut p);
        enc_i32(20, 338, &mut p);
        enc_i32(21, 3000, &mut p);
        enc_i32(22, 1800, &mut p);
        enc_i32(24, bc_type, &mut p);
        let mut packed = Vec::new();
        enc_varint(10_000, &mut packed);
        enc_bytes(26, &packed, &mut p);
        // Three rows, deliberately ordered so max-velocity, max-BC, first-row,
        // and last-row selection strategies all disagree:
        //   (7500, 5000) -> BC 0.750 @ 500 m/s  (highest BC, encoded first)
        //   (7160, 7920) -> BC 0.716 @ 792 m/s  (highest velocity -- the winner)
        //   (6900, 3000) -> BC 0.690 @ 300 m/s  (lowest of everything, encoded last)
        for (bc, mv) in [(7500i64, 5000i64), (7160, 7920), (6900, 3000)] {
            let mut row = Vec::new();
            enc_i32(1, bc, &mut row);
            enc_i32(2, mv, &mut row);
            enc_bytes(27, &row, &mut p);
        }
        let mut payload = Vec::new();
        enc_bytes(1, &p, &mut payload);
        wrap_payload(&payload)
    }

    /// MBA-1359: `--zero-click` converts the file's zero_x/zero_y device click counts
    /// into a stored POI offset — sign conventions per upstream a7p tooling (X negated on
    /// entry: right-clicks = -zero_x/1000; up-clicks = zero_y/1000) — while omitting the
    /// click size keeps the historical unmapped report byte-identical.
    #[test]
    fn zero_click_converts_click_counts_with_correct_signs() {
        // Same fixture plus zeroing state: zero_x = -20_000 (-20.0 raw => 20 clicks
        // RIGHT after upstream's negation), zero_y = 10_000 (10 clicks UP).
        let mut p = Vec::new();
        enc_str(1, "ZEROED", &mut p);
        enc_i32(7, -20_000, &mut p);
        enc_i32(8, 10_000, &mut p);
        enc_i32(11, 7920, &mut p);
        enc_i32(20, 338, &mut p);
        enc_i32(21, 3000, &mut p);
        enc_i32(24, 0, &mut p);
        let mut row = Vec::new();
        enc_i32(1, 7160, &mut row);
        enc_i32(2, 7920, &mut row);
        enc_bytes(27, &row, &mut p);
        let mut packed = Vec::new();
        enc_varint(10_000, &mut packed); // one distance: 100.00 m (zero index defaults 0)
        enc_bytes(26, &packed, &mut p);
        let mut payload = Vec::new();
        enc_bytes(1, &p, &mut payload);
        let doc = parse_a7p(&wrap_payload(&payload)).unwrap();

        // Without --zero-click: the historical unmapped line (reworded by MBA-1348 to
        // say WHY -- no device click size was supplied -- rather than the old blanket
        // "click state is not modeled", now that --zero-click CAN model it) — and no
        // zero set, and no click graduation stored either (MBA-1360/MBA-1348).
        let outcome = map_a7p_to_profile(&doc, None, None).unwrap();
        assert_eq!(outcome.profile.zero_poi_up_m, None);
        assert_eq!(outcome.profile.zero_poi_right_m, None);
        assert_eq!(outcome.profile.zero_sets, None);
        assert_eq!(outcome.profile.elevation_click, None);
        assert_eq!(outcome.profile.windage_click, None);
        assert!(outcome
            .report
            .unmapped
            .iter()
            .any(|(f, msg)| f == "zero_x / zero_y"
                && msg
                    == "scope zeroing click offsets (-20000, 10000) — device click size not \
                        supplied; pass --zero-click to record the profile's turret \
                        graduation and convert this offset"));

        // With --zero-click 0.1mil at a 100 m zero:
        //   up:    10 clicks * 0.1/1000 rad * 100 m = 0.1  m high
        //   right: 20 clicks * 0.1/1000 rad * 100 m = 0.2  m right
        let click = ballistics_engine::adjustment::parse_click_value("0.1mil").unwrap();
        let outcome = map_a7p_to_profile(&doc, None, Some(click)).unwrap();
        let up = outcome.profile.zero_poi_up_m.expect("up mapped");
        let right = outcome.profile.zero_poi_right_m.expect("right mapped");
        assert!((up - 0.1).abs() < 1e-12, "up = {up}");
        assert!((right - 0.2).abs() < 1e-12, "right = {right}");
        assert!(!outcome
            .report
            .unmapped
            .iter()
            .any(|(f, _)| f == "zero_x / zero_y"));
        assert!(outcome
            .report
            .mapped
            .iter()
            .any(|row| row[0] == "zero_x / zero_y"
                && row[3] == "zero_poi_up_m + zero_poi_right_m + zero_sets[a7p-zero]"));

        // MBA-1348: --zero-click is ALSO recorded as the profile's own turret click
        // graduation. Both elevation_click and windage_click are set directly to the
        // identical supplied click (not via optic_profile()'s windage-falls-back-to-
        // elevation precedent, which only applies when windage_click is left unset) --
        // .a7p exposes only one device click size, for one physical turret.
        assert_eq!(
            outcome.profile.elevation_click,
            outcome.profile.windage_click
        );
        assert_eq!(outcome.profile.elevation_click.as_deref(), Some("0.1mil"));
        assert_eq!(outcome.profile.windage_click.as_deref(), Some("0.1mil"));
        assert!(outcome
            .report
            .mapped
            .iter()
            .any(|row| row[0] == "--zero-click" && row[3] == "elevation_click + windage_click"));

        // MBA-1360: the same click state is ALSO recorded as the "a7p-zero" zero set,
        // in DIAL-CORRECTION convention (negated angular POI offset): zeroed 1.0 mil
        // high / 2.0 mil right => dial corrections -1.0 mil up / -2.0 mil right.
        let sets = outcome
            .profile
            .zero_sets
            .as_deref()
            .expect("zero set stored");
        assert_eq!(sets.len(), 1);
        assert_eq!(sets[0].name, "a7p-zero");
        assert_eq!(sets[0].zero_distance, None);
        let up_mil = sets[0].poi_up_mil.expect("up mil");
        let right_mil = sets[0].poi_right_mil.expect("right mil");
        assert!((up_mil - (-1.0)).abs() < 1e-12, "up_mil = {up_mil}");
        assert!(
            (right_mil - (-2.0)).abs() < 1e-12,
            "right_mil = {right_mil}"
        );
    }

    /// MBA-1348: `c_zero_w_pitch` (base pitch established at zeroing) stays unmapped --
    /// `OpticProfile` has no base-pitch concept, it is rifle-mount geometry outside the
    /// turret model -- but the report must now say WHY, not just assert it isn't modeled.
    #[test]
    fn w_pitch_is_reported_unmapped_with_the_reason_it_is_out_of_scope() {
        // Minimal fixture: a bc_type + one coef row is enough for map_a7p_to_profile to
        // reach the honest-unmapped-fields section (see custom_bc_type_rejects_a_degenerate_curve
        // for the same minimal-fixture style), plus field 18 = w_pitch_raw.
        let mut p = Vec::new();
        enc_i32(24, 0, &mut p); // G1
        let mut row = Vec::new();
        enc_i32(1, 5000, &mut row);
        enc_i32(2, 5000, &mut row);
        enc_bytes(27, &row, &mut p);
        enc_i32(18, 250, &mut p); // w_pitch_raw
        let mut payload = Vec::new();
        enc_bytes(1, &p, &mut payload);
        let doc = parse_a7p(&wrap_payload(&payload)).unwrap();

        let outcome = map_a7p_to_profile(&doc, None, None).unwrap();
        let (_, msg) = outcome
            .report
            .unmapped
            .iter()
            .find(|(f, _)| f == "c_zero_w_pitch")
            .expect("w_pitch reported unmapped");
        assert!(msg.contains("250"), "{msg}");
        assert!(msg.contains("rifle-mount geometry"), "{msg}");
        assert!(msg.contains("outside the turret model"), "{msg}");
        assert!(msg.contains("absorbed by zeroing"), "{msg}");
    }

    #[test]
    fn maps_g1_profile_to_metric_profiledata() {
        let doc = parse_a7p(&barnes_338_file(0)).unwrap();
        let outcome = map_a7p_to_profile(&doc, None, None).unwrap();
        let p = &outcome.profile;
        assert_eq!(p.name, "338LM_BARNES 300"); // sanitized
        assert_eq!(p.units, "metric");
        assert_eq!(p.drag_model, "G1");
        assert!((p.velocity - 792.0).abs() < 1e-9);
        assert!((p.bc - 0.716).abs() < 1e-9); // highest-velocity row wins
                                              // Independent literal (not GRAIN_TO_GRAM) so this assertion still
                                              // catches a corrupted grain->gram constant in production code.
        assert!((p.mass - 300.0 * 0.06479891).abs() < 1e-9); // grams
        assert!((p.diameter - 0.338 * 25.4).abs() < 1e-9); // mm
        assert!((p.bullet_length.unwrap() - 1.8 * 25.4).abs() < 1e-9); // mm
        assert!((p.twist_rate.unwrap() - 254.0).abs() < 1e-9); // mm/turn
        assert_eq!(p.twist_right, Some(true));
        assert!((p.sight_height.unwrap() - 90.0).abs() < 1e-9);
        assert!((p.zero_distance.unwrap() - 100.0).abs() < 1e-9);
        assert!((p.temperature - 15.0).abs() < 1e-9);
        assert!((p.pressure - 1000.0).abs() < 1e-9);
        assert!((p.humidity - 50.0).abs() < 1e-9);
        assert_eq!(p.bullet_name.as_deref(), Some("BARNES 300GR OTM"));
        assert!(p.created.is_some());

        // All three BC rows are mapped into bc_segments (velocity-banded, descending),
        // not warned away — MBA-1323 Phase 2.
        let segs = p.bc_segments.as_ref().expect("bc_segments populated");
        assert_eq!(segs.len(), 3);
        let velocities: Vec<f64> = segs.iter().map(|s| s.velocity_mps).collect();
        assert_eq!(velocities, vec![792.0, 500.0, 300.0]); // descending
        assert!((segs[0].bc - 0.716).abs() < 1e-9); // fastest row == primary bc
        assert!((segs[1].bc - 0.750).abs() < 1e-9);
        assert!((segs[2].bc - 0.690).abs() < 1e-9);
        assert!(outcome
            .report
            .mapped
            .iter()
            .any(|[field, ..]| field == "coef_rows[all]"));
        // powder temp sensitivity is honestly unmapped, with the converted value shown
        let tcoeff = outcome
            .report
            .unmapped
            .iter()
            .find(|(field, _)| field == "c_t_coeff")
            .expect("c_t_coeff reported");
        // 792 m/s * (1.0/100) / 15 C = 0.528 m/s per degC
        assert!(tcoeff.1.contains("0.528"));
        // zero-condition ambient temperature (field 12) is honestly unmapped too
        let zero_temp = outcome
            .report
            .unmapped
            .iter()
            .find(|(field, _)| field == "c_zero_temperature")
            .expect("c_zero_temperature reported");
        assert!(zero_temp.1.contains("15 C"));
    }

    #[test]
    fn name_override_is_applied() {
        let doc = parse_a7p(&barnes_338_file(0)).unwrap();
        let outcome = map_a7p_to_profile(&doc, Some("my-338"), None).unwrap();
        assert_eq!(outcome.profile.name, "my-338");
    }

    #[test]
    fn custom_bc_type_imports_a_drag_curve() {
        // bc_type=2 (CUSTOM) reinterprets the same three coef rows as (Cd, Mach) pairs
        // instead of (BC, velocity m/s) — see barnes_338_file's row comment.
        let doc = parse_a7p(&barnes_338_file(2)).unwrap();
        let outcome = map_a7p_to_profile(&doc, None, None).unwrap();
        let p = &outcome.profile;

        assert_eq!(p.drag_model, "CUSTOM");
        assert_eq!(p.bc, 0.0); // documented inert sentinel, not a real coefficient
        assert!(p.bc_segments.is_none());

        let curve = p.drag_curve.as_ref().expect("drag_curve populated");
        assert_eq!(curve.len(), 3);
        // sorted ascending by Mach (DragTable requirement), NOT file order.
        let machs: Vec<f64> = curve.iter().map(|pt| pt.mach).collect();
        assert_eq!(machs, vec![0.3, 0.5, 0.792]);
        assert!((curve[0].cd - 0.69).abs() < 1e-9);
        assert!((curve[1].cd - 0.75).abs() < 1e-9);
        assert!((curve[2].cd - 0.716).abs() < 1e-9);

        // The curve validates as a real engine DragTable.
        let mach_values: Vec<f64> = curve.iter().map(|pt| pt.mach).collect();
        let cd_values: Vec<f64> = curve.iter().map(|pt| pt.cd).collect();
        assert!(ballistics_engine::drag::DragTable::try_new(mach_values, cd_values).is_ok());

        assert!(outcome
            .report
            .warnings
            .iter()
            .any(|w| w.contains("inert sentinel")));
        assert!(outcome
            .report
            .mapped
            .iter()
            .any(|[field, ..]| field == "coef_rows[custom]"));
    }

    #[test]
    fn custom_bc_type_rejects_a_degenerate_curve() {
        // A single coef row cannot become a 2-point DragTable (try_new requires >= 2).
        let mut p = Vec::new();
        enc_i32(24, 2, &mut p); // CUSTOM
        let mut row = Vec::new();
        enc_i32(1, 5000, &mut row);
        enc_i32(2, 5000, &mut row);
        enc_bytes(27, &row, &mut p);
        let mut payload = Vec::new();
        enc_bytes(1, &p, &mut payload);
        let doc = parse_a7p(&wrap_payload(&payload)).unwrap();
        let err = map_a7p_to_profile(&doc, None, None).unwrap_err();
        assert!(err.contains("CUSTOM drag curve is invalid"), "{err}");
    }

    #[test]
    fn g7_maps_and_report_renders() {
        let doc = parse_a7p(&barnes_338_file(1)).unwrap();
        let outcome = map_a7p_to_profile(&doc, None, None).unwrap();
        assert_eq!(outcome.profile.drag_model, "G7");
        let rendered = render_import_report(&outcome.report);
        assert!(rendered.contains("muzzle velocity"));
        assert!(rendered.contains("NOT imported"));
    }

    #[test]
    fn missing_bc_rows_is_an_error() {
        // A file with no coef_rows cannot become a ProfileData (bc is mandatory).
        let mut p = Vec::new();
        enc_i32(11, 7920, &mut p);
        let mut payload = Vec::new();
        enc_bytes(1, &p, &mut payload);
        let doc = parse_a7p(&wrap_payload(&payload)).unwrap();
        let err = map_a7p_to_profile(&doc, None, None).unwrap_err();
        assert!(err.contains("no BC rows"), "{err}");
    }
}

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

    #[test]
    fn mil_conversion_matches_geometry() {
        // 0.1 yd of drop at 100 yd = 1.0 MIL (1 MIL subtends 0.1 yd at 100 yd).
        assert!((drop_to_adjustment(0.1, 100.0, AdjustmentUnit::Mil) - 1.0).abs() < 1e-9);
        // 1.78 yd at 500 yd ~ 3.56 MIL.
        assert!((drop_to_adjustment(1.78, 500.0, AdjustmentUnit::Mil) - 3.56).abs() < 0.01);
    }

    #[test]
    fn moa_is_3438_thousandths_per_radian_ratio() {
        // MOA uses 3438 (arcminutes per radian) vs MIL's 1000, so MOA/MIL == 3.438.
        let mil = drop_to_adjustment(1.0, 100.0, AdjustmentUnit::Mil);
        let moa = drop_to_adjustment(1.0, 100.0, AdjustmentUnit::Moa);
        assert!((moa / mil - 3.438).abs() < 1e-9, "moa={moa} mil={mil}");
        // 0.1 yd at 100 yd -> 3.438 MOA.
        assert!((drop_to_adjustment(0.1, 100.0, AdjustmentUnit::Moa) - 3.438).abs() < 1e-9);
    }

    #[test]
    fn short_range_returns_zero() {
        assert_eq!(drop_to_adjustment(1.0, 0.5, AdjustmentUnit::Moa), 0.0);
        assert_eq!(drop_to_adjustment(1.0, 0.5, AdjustmentUnit::Mil), 0.0);
    }

    #[test]
    fn smoa_iphy_conversion_is_inches_per_hundred_yards() {
        // 3.6 inches of drop at 100 yd = 0.1 yd drop over 100 yd... use exact math:
        // drop_yd/range_yd * 3600 == inches per 100 yd.
        let v = drop_to_adjustment(0.1, 100.0, AdjustmentUnit::Smoa);
        assert!(
            (v - 3.6).abs() < 1e-12,
            "0.1 yd @ 100 yd = 3.6 IPHY, got {v}"
        );
        let i = drop_to_adjustment(0.1, 100.0, AdjustmentUnit::Iphy);
        assert_eq!(v, i, "smoa and iphy are the same unit");
        // sanity vs existing: TMOA value must be larger number x smaller unit
        let t = drop_to_adjustment(0.1, 100.0, AdjustmentUnit::Moa);
        assert!(
            t < v && (v / t - 1.047).abs() < 0.005,
            "tmoa {t} vs smoa {v}"
        );
    }

    #[test]
    fn clicks_unit_requires_elevation_graduation() {
        // resolve_click_values with no flag and no profile must error, naming the flag.
        let e = resolve_click_values(None, None, None).unwrap_err();
        assert!(e.contains("--elevation-click-value"), "{e}");
    }

    #[test]
    fn windage_click_defaults_to_elevation() {
        let (el, wi) = resolve_click_values(Some("0.25moa"), None, None)
            .unwrap()
            .unwrap();
        assert_eq!(el, wi);
    }

    #[test]
    fn explicit_windage_flag_overrides_elevation_fallback() {
        let (el, wi) = resolve_click_values(Some("0.25moa"), Some("0.1mil"), None)
            .unwrap()
            .unwrap();
        assert_ne!(el, wi);
        assert_eq!(wi, parse_click_value("0.1mil").unwrap());
    }

    /// MBA-1410: `--windage-unit` falls back to the elevation unit (`--adjustment-unit`)
    /// when omitted, and genuinely differs from it when supplied -- mirrors
    /// `windage_click_defaults_to_elevation`/`explicit_windage_flag_overrides_elevation_fallback`
    /// above, but for the display UNIT rather than the click graduation.
    #[test]
    fn windage_unit_defaults_to_elevation_and_can_diverge() {
        assert_eq!(
            resolve_windage_unit(AdjustmentUnit::Mil, None).unwrap(),
            AdjustmentUnit::Mil
        );
        assert_eq!(
            resolve_windage_unit(AdjustmentUnit::Mil, Some(AdjustmentUnit::Moa)).unwrap(),
            AdjustmentUnit::Moa,
            "an explicit --windage-unit must genuinely diverge from the elevation unit"
        );
        assert_eq!(
            resolve_windage_unit(AdjustmentUnit::Moa, None).unwrap(),
            AdjustmentUnit::Moa,
            "omitted --windage-unit falls back to whatever --adjustment-unit resolved to"
        );
    }

    #[test]
    fn windage_unit_clicks_requires_elevation_clicks() {
        // Both axes clicks (the pre-MBA-1410 global mode): allowed, explicit or via fallback.
        assert_eq!(
            resolve_windage_unit(AdjustmentUnit::Clicks, None).unwrap(),
            AdjustmentUnit::Clicks
        );
        assert_eq!(
            resolve_windage_unit(AdjustmentUnit::Clicks, Some(AdjustmentUnit::Clicks)).unwrap(),
            AdjustmentUnit::Clicks
        );
        // Elevation clicks + an explicit non-clicks windage override: allowed.
        assert_eq!(
            resolve_windage_unit(AdjustmentUnit::Clicks, Some(AdjustmentUnit::Moa)).unwrap(),
            AdjustmentUnit::Moa
        );
        // Windage clicks without elevation clicks: rejected, naming both flags.
        let e =
            resolve_windage_unit(AdjustmentUnit::Mil, Some(AdjustmentUnit::Clicks)).unwrap_err();
        assert!(e.contains("--windage-unit"), "{e}");
        assert!(e.contains("--adjustment-unit"), "{e}");
    }

    /// MBA-1410: the windage-only single-axis click resolver (`wind-card`/`lead`) falls
    /// back from an explicit flag to the profile's `windage_click`, then its
    /// `elevation_click` -- same precedence order as `resolve_click_values`'s windage arm.
    #[test]
    fn single_axis_click_value_falls_back_windage_then_elevation() {
        let e = resolve_single_axis_click_value(None, None).unwrap_err();
        assert!(e.contains("--windage-click-value"), "{e}");

        let explicit = resolve_single_axis_click_value(Some("0.25moa"), None).unwrap();
        assert_eq!(explicit, parse_click_value("0.25moa").unwrap());

        fn profile_stub() -> ProfileData {
            ProfileData {
                name: "stub".to_string(),
                velocity: 762.0,
                bc: 0.243,
                mass: 11.339_809_25,
                diameter: 7.8232,
                drag_model: "G7".to_string(),
                twist_rate: None,
                sight_height: None,
                zero_distance: None,
                units: "metric".to_string(),
                temperature: 15.0,
                pressure: 1_013.207_888,
                humidity: 55.0,
                altitude: 0.0,
                bullet_name: None,
                created: None,
                wind_speed: None,
                wind_direction: None,
                shooting_angle: None,
                auto_zero: None,
                twist_right: None,
                use_bc_segments: None,
                bullet_length: None,
                elevation_click: None,
                windage_click: None,
                bc_segments: None,
                drag_curve: None,
                dsf_points: None,
                bc_reference: None,
                pressure_reference: None,
                density_altitude: None,
                zero_poi_up_m: None,
                zero_poi_right_m: None,
                sight_offset_lateral_m: None,
                elevation_cf: None,
                windage_cf: None,
                zero_sets: None,
                reticle: None,
                clicks_per_revolution: None,
                zero_stop: None,
                elevation_travel_up_mil: None,
                elevation_travel_down_mil: None,
                windage_travel_left_mil: None,
                windage_travel_right_mil: None,
                turret_elevation_dialed_mil: None,
                turret_windage_dialed_mil: None,
                hold_bound_up_mil: None,
                hold_bound_down_mil: None,
                hold_bound_left_mil: None,
                hold_bound_right_mil: None,
            }
        }

        let mut profile = profile_stub();
        profile.elevation_click = Some("0.1mil".to_string());
        let from_elevation = resolve_single_axis_click_value(None, Some(&profile)).unwrap();
        assert_eq!(from_elevation, parse_click_value("0.1mil").unwrap());

        profile.windage_click = Some("0.2mil".to_string());
        let from_windage = resolve_single_axis_click_value(None, Some(&profile)).unwrap();
        assert_eq!(
            from_windage,
            parse_click_value("0.2mil").unwrap(),
            "profile windage_click must beat profile elevation_click"
        );

        let flag_beats_profile =
            resolve_single_axis_click_value(Some("0.3moa"), Some(&profile)).unwrap();
        assert_eq!(flag_beats_profile, parse_click_value("0.3moa").unwrap());
    }

    #[test]
    fn default_trajectory_header_is_stable() {
        // Pin the come-ups table header line for the default unit (Mil, imperial) so a
        // future change to the Clicks formatting branch can't silently reformat the
        // existing MIL/MOA/SMOA/IPHY header text.
        assert_eq!(
            come_up_header_line("yd", "MIL", "fps"),
            "│Range (yd)|Drop (MIL)|Come-Up   │ Vel (fps)│Energy    │ Time (s) │"
        );
    }
}

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

    #[test]
    fn drag_model_arg_warning_only_flags_truly_unknown_strings() {
        // Every real family (MBA-1386 gave each one a dedicated table) resolves silently.
        for s in ["g1", "G2", "g5", "G6", "g7", "G8", "gi", "GS", "ra4"] {
            assert!(
                drag_model_arg_warning(s).is_none(),
                "{s} should be recognized"
            );
        }
        let w = drag_model_arg_warning("banana").expect("must warn");
        assert!(w.contains("using G1"), "{w}");
    }

    #[test]
    fn parse_drag_model_arg_resolves_the_full_family() {
        assert_eq!(parse_drag_model_arg("G7"), DragModel::G7);
        assert_eq!(parse_drag_model_arg("g5"), DragModel::G5);
        assert_eq!(parse_drag_model_arg("ra4"), DragModel::RA4);
        assert_eq!(parse_drag_model_arg("gi"), DragModel::GI);
        // Still coerces a truly unrecognized string to G1, with a warning.
        assert_eq!(parse_drag_model_arg("banana"), DragModel::G1);
    }

    #[test]
    fn parse_drag_model_arg_for_truing_still_constrains_to_g1_or_g7() {
        // Truing's forward model is deliberately G1/G7-only (see truing::DragModelArg);
        // every other family — including ones the engine now tables for real, like G5 —
        // still coerces to G1 here, same as the whole CLI did before MBA-1386.
        assert_eq!(parse_drag_model_arg_for_truing("G7"), DragModelArg::G7);
        assert_eq!(parse_drag_model_arg_for_truing("g7"), DragModelArg::G7);
        assert_eq!(parse_drag_model_arg_for_truing("G1"), DragModelArg::G1);
        assert_eq!(parse_drag_model_arg_for_truing("G5"), DragModelArg::G1);
        assert_eq!(parse_drag_model_arg_for_truing("banana"), DragModelArg::G1);
    }

    #[test]
    fn aux_g1_coercion_warning_only_flags_families_other_than_g1_g7() {
        // G1/G7 are exactly what the auxiliary paths (BC-segment estimator, --bc-table /
        // BC5D lookups, --online) natively support — no coercion, so no warning text.
        assert!(aux_g1_coercion_warning("--online mode", DragModel::G1).is_none());
        assert!(aux_g1_coercion_warning("--online mode", DragModel::G7).is_none());

        // Every wider family still coerces to G1 here (MBA-1386 gave each one a real
        // table for the *native* solver, but these auxiliary paths remain G1/G7-only),
        // and each now warns, naming both the feature and the coerced model.
        for (model, tag) in [
            (DragModel::G2, "G2"),
            (DragModel::G5, "G5"),
            (DragModel::G6, "G6"),
            (DragModel::G8, "G8"),
            (DragModel::GI, "GI"),
            (DragModel::GS, "GS"),
            (DragModel::RA4, "RA4"),
        ] {
            let w = aux_g1_coercion_warning("--bc-table correction", model)
                .unwrap_or_else(|| panic!("{tag} must warn"));
            assert!(w.contains(tag), "{w}");
            assert!(w.contains("--bc-table correction"), "{w}");
            assert!(w.contains("G1/G7 only"), "{w}");
        }
    }

    #[test]
    fn warn_aux_g1_coercion_returns_the_bc_type_string_the_estimator_accepts() {
        assert_eq!(warn_aux_g1_coercion("test", DragModel::G1), "G1");
        assert_eq!(warn_aux_g1_coercion("test", DragModel::G7), "G7");
        // Any other family still resolves to "G1" for the auxiliary path's BC-type
        // argument (in addition to the stderr warning `aux_g1_coercion_warning` covers).
        assert_eq!(warn_aux_g1_coercion("test", DragModel::G5), "G1");
        assert_eq!(warn_aux_g1_coercion("test", DragModel::RA4), "G1");
    }
}

/// MBA-1356: `--cd-scale` — the pairing requirement with `--drag-table` and the
/// out-of-typical-range nudge, both shared by the trajectory/monte-carlo/zero commands.
#[cfg(test)]
mod cd_scale_tests {
    use super::*;

    #[test]
    fn range_warning_is_none_inside_the_typical_truing_band() {
        for v in [0.90, 1.0, 1.10, 0.5, 2.0] {
            assert!(
                cd_scale_range_warning(v).is_none(),
                "cd_scale={v} is within [0.5, 2.0] and must not warn"
            );
        }
    }

    #[test]
    fn range_warning_fires_outside_the_typical_truing_band() {
        for v in [0.49, 2.01, 0.1, 5.0, 3.0] {
            let w = cd_scale_range_warning(v).unwrap_or_else(|| panic!("cd_scale={v} must warn"));
            assert!(w.contains("--cd-scale"), "{w}");
            assert!(w.contains("typical truing range (0.90-1.10)"), "{w}");
            assert!(w.contains(&format!("{v}")), "{w}");
        }
    }

    #[test]
    fn resolve_defaults_to_the_neutral_scale_when_omitted() {
        assert_eq!(resolve_cd_scale(None, false, true), Ok(1.0));
        assert_eq!(resolve_cd_scale(None, true, true), Ok(1.0));
    }

    #[test]
    fn resolve_passes_through_the_scale_when_a_table_is_present() {
        assert_eq!(resolve_cd_scale(Some(1.10), true, true), Ok(1.10));
        assert_eq!(resolve_cd_scale(Some(3.0), true, true), Ok(3.0));
    }

    #[test]
    fn resolve_errors_naming_the_pairing_requirement_without_a_table() {
        let err = resolve_cd_scale(Some(1.10), false, true)
            .expect_err("--cd-scale without a table must be rejected");
        assert!(err.contains("--cd-scale requires --drag-table"), "{err}");
        assert!(err.contains("--bc-adjustment"), "{err}");
    }

    /// 0.28.1 sweep: MonteCarlo and Zero have no `--bc-adjustment` flag at all -- the
    /// pairing error must not send a shooter looking for a flag that surface doesn't
    /// accept. `has_bc_adjustment = false` must drop the suggestion entirely rather than
    /// print it unconditionally.
    #[test]
    fn resolve_omits_the_bc_adjustment_suggestion_on_a_surface_without_it() {
        let err = resolve_cd_scale(Some(1.10), false, false)
            .expect_err("--cd-scale without a table must be rejected");
        assert!(err.contains("--cd-scale requires --drag-table"), "{err}");
        assert!(
            !err.contains("--bc-adjustment"),
            "surface has no --bc-adjustment flag to suggest: {err}"
        );
    }
}

/// MBA-1414: `--adjustment-unit` reaches only the mover Ring column and the PDF dope
/// card, so a run with neither gets told the flag changed nothing.
#[cfg(test)]
mod adjustment_unit_noop_tests {
    use super::*;

    #[test]
    fn warns_for_a_non_default_unit_with_no_ring_and_no_pdf() {
        for unit in [
            AdjustmentUnit::Moa,
            AdjustmentUnit::Smoa,
            AdjustmentUnit::Iphy,
            AdjustmentUnit::Clicks,
        ] {
            let warning = adjustment_unit_noop_warning(unit, None, 0.0, false)
                .unwrap_or_else(|| panic!("{unit:?} without --target-speed or -o pdf must warn"));
            assert!(warning.contains("--adjustment-unit"), "{warning}");
            assert!(warning.contains("--target-speed"), "{warning}");
            assert!(warning.contains("-o pdf"), "{warning}");
        }
    }

    #[test]
    fn silent_when_the_ring_column_or_the_dope_card_consumes_the_unit() {
        // A mover ring is requested: the Ring column renders in the chosen unit.
        assert!(adjustment_unit_noop_warning(AdjustmentUnit::Moa, None, 10.0, false).is_none());
        // PDF dope card: Drop/Wind/Lead columns render in the chosen unit even with no ring.
        assert!(adjustment_unit_noop_warning(AdjustmentUnit::Moa, None, 0.0, true).is_none());
        assert!(adjustment_unit_noop_warning(AdjustmentUnit::Clicks, None, 0.0, true).is_none());
    }

    #[test]
    fn silent_for_the_default_unit() {
        // `mil` is clap's `default_value`, so an explicit `--adjustment-unit mil` cannot be
        // told apart from never passing the flag — warning there would fire on the common
        // case for nothing.
        assert!(adjustment_unit_noop_warning(AdjustmentUnit::Mil, None, 0.0, false).is_none());
    }

    /// MBA-1410: a fallback windage unit (no explicit `--windage-unit`) is never itself a
    /// no-op signal -- only an EXPLICIT non-mil `--windage-unit` is, and only without PDF
    /// (the Ring column never shows the windage axis, so `target_speed` cannot excuse it).
    #[test]
    fn explicit_windage_unit_alone_warns_without_pdf_and_is_silent_with_it() {
        // Tier 2 review M7: elevation is consumed here (Mil is the default -- never a
        // no-op signal by itself), so the ONLY inert flag is --windage-unit; the message
        // must name it, not --adjustment-unit.
        let warning = adjustment_unit_noop_warning(
            AdjustmentUnit::Mil,
            Some(AdjustmentUnit::Moa),
            0.0,
            false,
        )
        .unwrap();
        assert!(warning.contains("--windage-unit"), "{warning}");
        assert!(!warning.contains("--adjustment-unit"), "{warning}");
        // Even a nonzero target_speed doesn't excuse it -- the Ring column is elevation-only.
        assert!(adjustment_unit_noop_warning(
            AdjustmentUnit::Mil,
            Some(AdjustmentUnit::Moa),
            10.0,
            false
        )
        .is_some());
        assert!(adjustment_unit_noop_warning(
            AdjustmentUnit::Mil,
            Some(AdjustmentUnit::Moa),
            0.0,
            true
        )
        .is_none());
        // An explicit `--windage-unit mil` matches the default and never warns by itself.
        assert!(adjustment_unit_noop_warning(
            AdjustmentUnit::Mil,
            Some(AdjustmentUnit::Mil),
            0.0,
            false
        )
        .is_none());
    }

    /// Tier 2 review M7: when BOTH axes are inert, the message names both flags rather
    /// than only ever blaming --adjustment-unit.
    #[test]
    fn both_axes_inert_names_both_flags() {
        let warning = adjustment_unit_noop_warning(
            AdjustmentUnit::Moa,
            Some(AdjustmentUnit::Smoa),
            0.0,
            false,
        )
        .unwrap();
        assert!(warning.contains("--adjustment-unit"), "{warning}");
        assert!(warning.contains("--windage-unit"), "{warning}");
    }
}

/// MBA-1410 fold-in of an MBA-1355 backlog minor: come-ups' `--windage-click-value` was a
/// silent no-op (no windage column exists there); it must now warn.
#[cfg(test)]
mod windage_click_value_noop_tests {
    use super::*;

    #[test]
    fn warns_when_supplied() {
        let w = windage_click_value_noop_warning(Some("0.1mil"))
            .expect("a supplied --windage-click-value on come-ups must warn");
        assert!(w.contains("--windage-click-value"), "{w}");
        assert!(w.contains("come-ups"), "{w}");
        assert!(w.contains("--elevation-click-value"), "{w}");
    }

    #[test]
    fn silent_when_omitted() {
        assert!(windage_click_value_noop_warning(None).is_none());
    }
}

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

    #[test]
    fn resolved_bc_schedule_preserves_explicit_precedence_and_estimator_fallback() {
        let explicit = vec![BCSegmentData {
            velocity_min: 0.0,
            velocity_max: 5_000.0,
            bc_value: 0.42,
        }];
        let provided = resolve_velocity_bc_segments(
            Some(&explicit),
            true,
            0.19,
            0.224 * 0.0254,
            77.0 * GRAINS_TO_KG,
            DragModel::G7,
        )
        .unwrap();
        assert_eq!(provided.len(), 1);
        assert_eq!(provided[0].bc_value.to_bits(), 0.42_f64.to_bits());

        let estimated = resolve_velocity_bc_segments(
            None,
            true,
            0.19,
            0.224 * 0.0254,
            77.0 * GRAINS_TO_KG,
            DragModel::G7,
        )
        .unwrap();
        let expected = ballistics_engine::bc_estimation::BCSegmentEstimator::estimate_bc_segments(
            0.19, 0.224, 77.0, "", "G7",
        );
        assert_eq!(estimated.len(), expected.len());
        for (actual, expected) in estimated.iter().zip(&expected) {
            assert_eq!(
                actual.velocity_min.to_bits(),
                expected.velocity_min.to_bits()
            );
            assert_eq!(
                actual.velocity_max.to_bits(),
                expected.velocity_max.to_bits()
            );
            assert_eq!(actual.bc_value.to_bits(), expected.bc_value.to_bits());
        }

        assert!(resolve_velocity_bc_segments(
            None,
            false,
            0.19,
            0.224 * 0.0254,
            77.0 * GRAINS_TO_KG,
            DragModel::G7,
        )
        .is_none());
    }

    #[test]
    fn parses_valid_imperial_pair_as_fps() {
        let seg = parse_bc_segment("1500:1800:0.243", UnitSystem::Imperial).unwrap();
        assert_eq!(seg.velocity_min, 1500.0);
        assert_eq!(seg.velocity_max, 1800.0);
        assert!((seg.bc_value - 0.243).abs() < 1e-12);
    }

    #[test]
    fn converts_metric_velocity_to_fps() {
        // 305 m/s -> 1000.66 fps, 427 m/s -> 1400.92 fps; BC unchanged.
        let seg = parse_bc_segment("305:427:0.15", UnitSystem::Metric).unwrap();
        assert!((seg.velocity_min - 305.0 * 3.280_839_895).abs() < 1e-6);
        assert!((seg.velocity_max - 427.0 * 3.280_839_895).abs() < 1e-6);
        assert!((seg.bc_value - 0.15).abs() < 1e-12);
    }

    #[test]
    fn rejects_wrong_field_count() {
        assert!(parse_bc_segment("1000:1400", UnitSystem::Imperial).is_err());
        assert!(parse_bc_segment("1000:1400:0.2:extra", UnitSystem::Imperial).is_err());
    }

    #[test]
    fn rejects_vmin_not_less_than_vmax() {
        assert!(parse_bc_segment("1400:1000:0.2", UnitSystem::Imperial).is_err());
        assert!(parse_bc_segment("1400:1400:0.2", UnitSystem::Imperial).is_err());
    }

    #[test]
    fn rejects_nonpositive_bc_and_nonnumeric() {
        assert!(parse_bc_segment("1000:1400:0", UnitSystem::Imperial).is_err());
        assert!(parse_bc_segment("1000:1400:-0.1", UnitSystem::Imperial).is_err());
        assert!(parse_bc_segment("abc:1400:0.2", UnitSystem::Imperial).is_err());
        assert!(parse_bc_segment("1000:xyz:0.2", UnitSystem::Imperial).is_err());
        assert!(parse_bc_segment("1000:1400:bc", UnitSystem::Imperial).is_err());
    }
}

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

    /// bc_segments_from_profile must produce a gapless, non-overlapping partition of
    /// [0, +inf) — the failure mode of an earlier draft was an overlap between the fastest
    /// and slowest bands (each half-open band's [min, max) must exactly abut its neighbors).
    #[test]
    fn bands_are_gapless_and_non_overlapping_for_two_rows() {
        let rows = vec![
            ProfileBcSegment {
                bc: 0.5,
                velocity_mps: 900.0,
            },
            ProfileBcSegment {
                bc: 0.2,
                velocity_mps: 300.0,
            },
        ];
        let segs = bc_segments_from_profile(&rows);
        assert_eq!(segs.len(), 2);

        let fast = &segs[0];
        let slow = &segs[1];
        assert!((fast.bc_value - 0.5).abs() < 1e-9);
        assert!((slow.bc_value - 0.2).abs() < 1e-9);

        // Slowest band starts at absolute zero, not at its own stated velocity.
        assert_eq!(slow.velocity_min, 0.0);
        // The two bands share exactly one boundary (no gap, no overlap).
        assert_eq!(slow.velocity_max, fast.velocity_min);
        // Fastest band's own velocity is its floor (extends up to/above muzzle), not a
        // midpoint or the other row's velocity.
        let expected_floor_fps = 900.0 * 3.280_839_895;
        assert!((fast.velocity_min - expected_floor_fps).abs() < 1e-6);
        assert!(fast.velocity_max > expected_floor_fps);

        // Sample a velocity from each band and confirm exactly one segment claims it.
        for probe in [fast.velocity_min + 10.0, slow.velocity_max - 10.0] {
            let hits = segs
                .iter()
                .filter(|s| probe >= s.velocity_min && probe < s.velocity_max)
                .count();
            assert_eq!(
                hits, 1,
                "velocity {probe} fps must be claimed by exactly one band"
            );
        }
    }

    #[test]
    fn single_row_covers_the_entire_velocity_axis() {
        let rows = vec![ProfileBcSegment {
            bc: 0.3,
            velocity_mps: 800.0,
        }];
        let segs = bc_segments_from_profile(&rows);
        assert_eq!(segs.len(), 1);
        assert_eq!(segs[0].velocity_min, 0.0);
        assert!(segs[0].velocity_max > 800.0 * 3.280_839_895);
    }

    #[test]
    fn unsorted_input_rows_are_sorted_by_velocity() {
        // File order deliberately reversed (slowest first) — output must still be
        // fastest-first with correct banding, independent of input order.
        let rows = vec![
            ProfileBcSegment {
                bc: 0.2,
                velocity_mps: 300.0,
            },
            ProfileBcSegment {
                bc: 0.5,
                velocity_mps: 900.0,
            },
        ];
        let segs = bc_segments_from_profile(&rows);
        assert!((segs[0].bc_value - 0.5).abs() < 1e-9);
        assert!((segs[1].bc_value - 0.2).abs() < 1e-9);
    }

    #[test]
    fn drag_table_from_profile_builds_a_valid_table() {
        let points = vec![
            ProfileDragPoint {
                mach: 0.5,
                cd: 0.23,
            },
            ProfileDragPoint {
                mach: 1.2,
                cd: 0.45,
            },
            ProfileDragPoint {
                mach: 3.0,
                cd: 0.28,
            },
        ];
        let table = drag_table_from_profile(&points).expect("valid table");
        assert_eq!(table.mach_values, vec![0.5, 1.2, 3.0]);
        assert_eq!(table.cd_values, vec![0.23, 0.45, 0.28]);
    }

    #[test]
    fn drag_table_from_profile_rejects_degenerate_input() {
        let points = vec![ProfileDragPoint {
            mach: 0.5,
            cd: 0.23,
        }];
        assert!(drag_table_from_profile(&points).is_err());
    }
}

/// MBA-1409: `--drag-table` extension dispatch. `load_drag_table` is the non-exiting shared
/// implementation behind `load_drag_table_or_exit` (which additionally prints and calls
/// `std::process::exit(1)` on error — not safely callable from a test process).
#[cfg(test)]
mod drg_extension_dispatch_tests {
    use super::*;

    /// A synthetic .drg deck: invented values only, but structurally representative of the
    /// real vendor format (leading name/description line, tab-separated (mach, cd) rows).
    const SYNTH_DRG: &str = "SYN-MBA1409, synthetic test deck (invented values)\n\
                              0.50\t0.230\n\
                              0.80\t0.210\n\
                              1.00\t0.520\n\
                              1.50\t0.400\n\
                              2.50\t0.300\n";

    /// Same "good deck" CSV content already established as a fixture in
    /// tests/custom_drag_table_cli.rs — reused here (rather than inventing new CSV content) to
    /// prove the plain-CSV dispatch path is unchanged by adding the `.drg` extension check.
    const EXISTING_CSV_FIXTURE: &str = "mach,cd\n0.5,0.23\n1.0,0.40\n2.0,0.30\n3.0,0.26\n";

    /// Writes `contents` to a uniquely-named temp file whose name ends in `suffix` (e.g.
    /// `".drg"`, `".csv"`, or `""` for no extension at all) and returns its path.
    fn write_temp(suffix: &str, contents: &str) -> std::path::PathBuf {
        let nonce = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap()
            .as_nanos();
        let path = std::env::temp_dir().join(format!(
            "mba1409_drg_dispatch_{}_{nonce}{suffix}",
            std::process::id()
        ));
        std::fs::write(&path, contents).unwrap();
        path
    }

    #[test]
    fn drg_extension_dispatches_to_the_drg_parser() {
        let path = write_temp(".drg", SYNTH_DRG);
        let table = load_drag_table(&path).expect("valid .drg file should load");
        std::fs::remove_file(&path).ok();

        assert_eq!(table.mach_values, vec![0.50, 0.80, 1.00, 1.50, 2.50]);
        assert_eq!(table.cd_values, vec![0.230, 0.210, 0.520, 0.400, 0.300]);
    }

    #[test]
    fn drg_extension_is_case_insensitive() {
        let path = write_temp(".DRG", SYNTH_DRG);
        let table = load_drag_table(&path).expect("uppercase .DRG extension should load");
        std::fs::remove_file(&path).ok();
        assert_eq!(table.mach_values.len(), 5);
    }

    #[test]
    fn drg_file_with_csv_ish_garbage_errors_naming_the_line_number() {
        let path = write_temp(".drg", "title\n0.5 0.3\nnot two numbers\n1.0 0.31\n");
        let err = load_drag_table(&path).expect_err("garbage row should be rejected");
        std::fs::remove_file(&path).ok();
        assert!(
            err.contains("line 3"),
            "expected the parser's line number in the error, got: {err}"
        );
    }

    #[test]
    fn csv_extension_behavior_is_unchanged() {
        let path = write_temp(".csv", EXISTING_CSV_FIXTURE);
        let table = load_drag_table(&path).expect("existing csv fixture should still load");
        std::fs::remove_file(&path).ok();
        assert_eq!(table.mach_values, vec![0.5, 1.0, 2.0, 3.0]);
        assert_eq!(table.cd_values, vec![0.23, 0.40, 0.30, 0.26]);
    }

    #[test]
    fn no_extension_still_uses_the_csv_path() {
        // A path with no extension at all must not be misrouted to the .drg parser.
        let path = write_temp("", EXISTING_CSV_FIXTURE);
        let table = load_drag_table(&path).expect("extensionless file should still parse as csv");
        std::fs::remove_file(&path).ok();
        assert_eq!(table.mach_values, vec![0.5, 1.0, 2.0, 3.0]);
    }
}

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

    #[test]
    fn trajectory_components_store_wind_direction_in_radians() {
        let (inputs, wind, _) = build_trajectory_components(
            800.0,
            0.4,
            0.01,
            0.00762,
            DragModel::G1,
            0.05,
            15.0,
            1013.25,
            50.0,
            0.0,
            10.0,
            90.0,
            1000.0,
            100.0,
            None,
            None,
            0.0,
            0.0,
            0.0,
        );

        assert!((inputs.wind_angle - std::f64::consts::FRAC_PI_2).abs() < 1e-12);
        assert_eq!(inputs.wind_angle.to_bits(), wind.direction.to_bits());
    }
}

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

    // ---- parse_observed_drop ----

    #[test]
    fn parse_observed_drop_accepts_all_three_suffixes() {
        let (v, u) = parse_observed_drop("5.1mil").unwrap();
        assert!((v - 5.1).abs() < 1e-12);
        assert_eq!(u, DropUnit::Mil);

        let (v, u) = parse_observed_drop("17.4moa").unwrap();
        assert!((v - 17.4).abs() < 1e-12);
        assert_eq!(u, DropUnit::Moa);

        let (v, u) = parse_observed_drop("42.0in").unwrap();
        assert!((v - 42.0).abs() < 1e-12);
        assert_eq!(u, DropUnit::In);
    }

    #[test]
    fn parse_observed_drop_is_case_insensitive_and_trims_whitespace() {
        let (v, u) = parse_observed_drop("  5.1MIL  ").unwrap();
        assert!((v - 5.1).abs() < 1e-12);
        assert_eq!(u, DropUnit::Mil);
    }

    #[test]
    fn parse_observed_drop_rejects_missing_suffix() {
        let e = parse_observed_drop("5.1").unwrap_err();
        assert!(
            e.contains("mil") && e.contains("moa") && e.contains("in"),
            "{e}"
        );
    }

    #[test]
    fn parse_observed_drop_rejects_garbage_number() {
        for bad in ["mil", "abcmil", "", "5.1.2moa"] {
            assert!(
                parse_observed_drop(bad).is_err(),
                "{bad:?} must be rejected"
            );
        }
    }

    #[test]
    fn parse_observed_drop_rejects_non_finite() {
        assert!(parse_observed_drop("nanmil").is_err());
        assert!(parse_observed_drop("infmoa").is_err());
    }

    // ---- gate/warning helper texts (unit-testable pure functions) ----

    #[test]
    fn supersonic_error_text_is_exact() {
        let msg = dsf_supersonic_error(1.35);
        assert_eq!(
            msg,
            "error: observation is supersonic (Mach 1.35); calibrate muzzle velocity first \
             (true-velocity), then collect DSF points at Mach <= 1.2"
        );
    }

    #[test]
    fn beyond_90pct_warning_text_is_exact() {
        let msg = dsf_beyond_90pct_warning(950.0, "yd");
        assert_eq!(
            msg,
            "warning: observation at 950 yd is beyond 90% of the solved range; solution \
             reliability degrades past this point"
        );
    }

    #[test]
    fn beyond_90pct_warning_text_uses_metric_unit_label() {
        let msg = dsf_beyond_90pct_warning(500.0, "m");
        assert_eq!(
            msg,
            "warning: observation at 500 m is beyond 90% of the solved range; solution \
             reliability degrades past this point"
        );
    }

    #[test]
    fn transonic_gap_warning_text_is_exact() {
        assert_eq!(
            dsf_transonic_gap_warning(),
            "warning: no DSF point in the transonic band (Mach 1.2-0.9); transonic drops \
             remain uncorrected"
        );
    }

    // ---- gate boolean logic ----

    #[test]
    fn observation_beyond_90pct_boundary() {
        assert!(!ballistics_engine::truing_dsf::dsf_observation_beyond_90pct(899.9, 1000.0));
        assert!(!ballistics_engine::truing_dsf::dsf_observation_beyond_90pct(900.0, 1000.0)); // exactly 90%: not beyond
        assert!(ballistics_engine::truing_dsf::dsf_observation_beyond_90pct(
            900.1, 1000.0
        ));
        assert!(ballistics_engine::truing_dsf::dsf_observation_beyond_90pct(
            1000.0, 1000.0
        ));
        assert!(!ballistics_engine::truing_dsf::dsf_observation_beyond_90pct(500.0, 0.0));
        // degenerate solved range
    }

    // ---- mach_1_crossing_range_m / dsf_observation_warrants_90pct_warning (Critical #1) ----

    fn traj_point(x: f64, velocity_magnitude: f64) -> ballistics_engine::cli_api::TrajectoryPoint {
        ballistics_engine::cli_api::TrajectoryPoint {
            time: 0.0,
            position: nalgebra::Vector3::new(x, 0.0, 0.0),
            velocity_magnitude,
            kinetic_energy: 0.0,
            drag_coefficient: None,
        }
    }

    fn traj_result_fixture(
        points: Vec<ballistics_engine::cli_api::TrajectoryPoint>,
        station_speed_of_sound_mps: f64,
        max_range: f64,
    ) -> ballistics_engine::cli_api::TrajectoryResult {
        ballistics_engine::cli_api::TrajectoryResult {
            max_range,
            max_height: 0.0,
            time_of_flight: 0.0,
            impact_velocity: 0.0,
            impact_energy: 0.0,
            projectile_mass_kg: 0.01,
            line_of_sight_height_m: 0.05,
            station_speed_of_sound_mps,
            termination: ballistics_engine::trajectory_observation::TrajectoryTermination::MaxRange,
            points,
            sampled_points: None,
            min_pitch_damping: None,
            transonic_mach: None,
            angular_state: None,
            max_yaw_angle: None,
            max_precession_angle: None,
            aerodynamic_jump: None,
            mach_1_2_distance_m: None,
            mach_1_0_distance_m: None,
            mach_0_9_distance_m: None,
        }
    }

    #[test]
    fn mach_1_crossing_range_m_interpolates_the_downward_crossing() {
        let sos = 340.0;
        // Mach: 1.3, 1.1, 0.8 at x = 0, 100, 200 -> crosses 1.0 between x=100 (mach 1.1)
        // and x=200 (mach 0.8): t = (1.1 - 1.0) / (1.1 - 0.8) = 1/3 -> x = 100 + 100/3.
        let result = traj_result_fixture(
            vec![
                traj_point(0.0, 1.3 * sos),
                traj_point(100.0, 1.1 * sos),
                traj_point(200.0, 0.8 * sos),
            ],
            sos,
            500.0,
        );
        let crossing = ballistics_engine::truing_dsf::mach_1_crossing_range_m(&result)
            .expect("must find a crossing");
        assert!(
            (crossing - (100.0 + 100.0 / 3.0)).abs() < 1e-6,
            "{crossing}"
        );
    }

    #[test]
    fn mach_1_crossing_range_m_none_when_trajectory_never_goes_subsonic() {
        let sos = 340.0;
        // Still transonic (Mach 1.05) at the last solved point -> no subsonic crossing yet.
        let result = traj_result_fixture(
            vec![traj_point(0.0, 1.3 * 340.0), traj_point(100.0, 1.05 * sos)],
            sos,
            500.0,
        );
        assert!(ballistics_engine::truing_dsf::mach_1_crossing_range_m(&result).is_none());
    }

    #[test]
    fn mach_1_crossing_range_m_none_for_degenerate_station_speed_of_sound() {
        let result = traj_result_fixture(vec![traj_point(0.0, 300.0)], 0.0, 500.0);
        assert!(ballistics_engine::truing_dsf::mach_1_crossing_range_m(&result).is_none());
    }

    #[test]
    fn warrants_90pct_warning_requires_both_gates() {
        // Beyond 90% of range but still upstream of (or with no) Mach-1.0 crossing: no warning.
        assert!(
            !ballistics_engine::truing_dsf::dsf_observation_warrants_90pct_warning(
                950.0, None, 1000.0
            )
        );
        assert!(
            !ballistics_engine::truing_dsf::dsf_observation_warrants_90pct_warning(
                950.0,
                Some(960.0),
                1000.0
            )
        );

        // Beyond the crossing but NOT beyond 90% of range: no warning.
        assert!(
            !ballistics_engine::truing_dsf::dsf_observation_warrants_90pct_warning(
                500.0,
                Some(400.0),
                1000.0
            )
        );

        // Beyond both: warns.
        assert!(
            ballistics_engine::truing_dsf::dsf_observation_warrants_90pct_warning(
                950.0,
                Some(400.0),
                1000.0
            )
        );
    }

    #[test]
    fn transonic_coverage_gate_checks_highest_point_only() {
        assert!(dsf_table_missing_transonic_coverage(&[]));
        assert!(dsf_table_missing_transonic_coverage(&[DsfPoint {
            mach: 0.5,
            dsf: 1.1
        }]));
        assert!(!dsf_table_missing_transonic_coverage(&[
            DsfPoint {
                mach: 0.5,
                dsf: 1.1
            },
            DsfPoint {
                mach: 0.95,
                dsf: 1.05
            },
        ]));
        // Exactly at the 0.9 boundary counts as covered (< 0.9 is the gate, not <=).
        assert!(!dsf_table_missing_transonic_coverage(&[DsfPoint {
            mach: 0.9,
            dsf: 1.0
        }]));
    }

    // ---- dsf_table_summary ----

    #[test]
    fn table_summary_formats_count_and_mach_span() {
        let points = vec![
            DsfPoint {
                mach: 0.6,
                dsf: 1.1,
            },
            DsfPoint {
                mach: 0.85,
                dsf: 1.02,
            },
        ];
        assert_eq!(dsf_table_summary(&points), "2 points, Mach 0.60-0.85");
    }

    // ---- interpolate_position_and_velocity ----

    fn pt(x: f64, y: f64, v: f64) -> ballistics_engine::cli_api::TrajectoryPoint {
        ballistics_engine::cli_api::TrajectoryPoint {
            time: 0.0,
            position: nalgebra::Vector3::new(x, y, 0.0),
            velocity_magnitude: v,
            kinetic_energy: 0.0,
            drag_coefficient: None,
        }
    }

    #[test]
    fn interpolates_linearly_between_bracketing_points() {
        let points = vec![pt(0.0, 1.0, 800.0), pt(100.0, 0.5, 700.0)];
        let (y, v) =
            ballistics_engine::truing_dsf::interpolate_position_and_velocity(&points, 50.0)
                .unwrap();
        assert!((y - 0.75).abs() < 1e-9);
        assert!((v - 750.0).abs() < 1e-9);
    }

    #[test]
    fn interpolation_returns_none_past_the_last_point() {
        let points = vec![pt(0.0, 1.0, 800.0), pt(100.0, 0.5, 700.0)];
        assert!(
            ballistics_engine::truing_dsf::interpolate_position_and_velocity(&points, 200.0)
                .is_none()
        );
    }

    #[test]
    fn interpolation_at_or_before_the_first_point_returns_its_own_values() {
        let points = vec![pt(0.0, 1.0, 800.0), pt(100.0, 0.5, 700.0)];
        let (y, v) =
            ballistics_engine::truing_dsf::interpolate_position_and_velocity(&points, 0.0).unwrap();
        assert_eq!(y, 1.0);
        assert_eq!(v, 800.0);
    }
}

/// Print one built-in reference drag curve as `(Mach, Cd)` data (MBA-1424).
///
/// The engine already carries these tables; this hands them back so a consumer charting drag
/// does not have to re-vendor the numbers and then drift from the engine as tables are refined.
/// Emitted verbatim from the table — no resampling, no interpolation onto a uniform grid — so
/// what you plot is exactly what the solver interpolates.
/// `hold-corridor` (MBA-1349).
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable Clap command shape"
)]
fn handle_hold_corridor(
    scenarios_path: PathBuf,
    ranges: String,
    target: Option<String>,
    profile: Option<String>,
    velocity: Option<f64>,
    bc: Option<f64>,
    mass: Option<f64>,
    diameter: Option<f64>,
    drag_model: DragModel,
    zero_distance: Option<f64>,
    sight_height: Option<f64>,
    temperature: Option<f64>,
    pressure: Option<f64>,
    pressure_type: Option<PressureReferenceMode>,
    humidity: f64,
    altitude: f64,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    let format = match output {
        OutputFormat::Table => RobustHoldFormat::Table,
        OutputFormat::Json => RobustHoldFormat::Json,
        OutputFormat::Csv => {
            return Err(
                "hold-corridor has no CSV form (a corridor row is a block, not a line); \
                 use -o table or -o json"
                    .into(),
            )
        }
        OutputFormat::Pdf => {
            return Err("hold-corridor has no PDF form; use -o table or -o json".into())
        }
    };

    // File I/O lives here; `wind_scenarios` parses TEXT so it stays wasm32-clean.
    let text = fs::read_to_string(&scenarios_path).map_err(|e| {
        format!(
            "could not read scenario file {}: {e}",
            scenarios_path.display()
        )
    })?;
    // `main` prints errors with Debug, so typed errors are rendered here through
    // Display and handed on as strings — the same shape every other subcommand's
    // messages take.
    let scenario_set = parse_wind_scenario_set(&text, units).map_err(|e| e.to_string())?;

    let ranges_m: Vec<f64> = ranges
        .split(',')
        .map(|token| {
            let value: f64 = token.trim().parse().map_err(|_| {
                format!(
                    "invalid --ranges entry '{}': expected a number",
                    token.trim()
                )
            })?;
            Ok::<f64, String>(UnitConverter::distance_to_metric(value, units))
        })
        .collect::<Result<_, _>>()?;

    let target = match target.as_deref() {
        Some(spec) => Some(parse_target_spec(spec, units).map_err(|e| e.to_string())?),
        None => None,
    };

    let profile_data = match profile.as_deref() {
        Some(name) => Some(load_profile(name)?),
        None => None,
    };
    let require = |value: Option<f64>, flag: &str| -> Result<f64, Box<dyn Error>> {
        value.ok_or_else(|| format!("{flag} is required (directly or from --profile)").into())
    };
    let velocity = require(
        resolve_param(velocity, &profile_data, |p| p.velocity),
        "--velocity",
    )?;
    let bc = require(resolve_param(bc, &profile_data, |p| p.bc), "--bc")?;
    let mass = require(resolve_param(mass, &profile_data, |p| p.mass), "--mass")?;
    let diameter = require(
        resolve_param(diameter, &profile_data, |p| p.diameter),
        "--diameter",
    )?;
    let zero_distance = require(
        zero_distance.or_else(|| profile_data.as_ref().and_then(|p| p.zero_distance)),
        "--zero-distance",
    )?;
    // Same fallback `trajectory --saved-profile`/`come-ups --profile` use.
    let sight_height = sight_height
        .or_else(|| profile_data.as_ref().and_then(|p| p.sight_height))
        .unwrap_or(match units {
            UnitSystem::Imperial => 2.0,
            UnitSystem::Metric => 50.0,
        });
    let temperature = UnitConverter::resolve_temperature(temperature, units)?;
    // MBA-1416: a declared QNH reduces against this command's own --altitude.
    let pressure = apply_pressure_mode(
        UnitConverter::resolve_pressure(pressure, units)?,
        altitude,
        pressure_type,
        units,
    );

    let mass_kg = UnitConverter::mass_to_metric(mass, units);
    let diameter_m = UnitConverter::diameter_to_metric(diameter, units);
    let request = RobustHoldRequest {
        scenarios: scenario_set,
        ranges_m,
        target,
        load: CorridorLoad {
            muzzle_velocity_mps: UnitConverter::velocity_to_metric(velocity, units),
            bc,
            drag_model,
            mass_kg,
            diameter_m,
            bullet_length_m: fallback_bullet_length_m(diameter_m, mass_kg),
            zero_distance_m: UnitConverter::distance_to_metric(zero_distance, units),
            sight_height_m: UnitConverter::sight_height_to_metric(sight_height, units),
            temperature_c: UnitConverter::temperature_to_metric(temperature, units),
            pressure_hpa: UnitConverter::pressure_to_metric(pressure, units),
            humidity_pct: humidity,
            altitude_m: UnitConverter::altitude_to_metric(altitude, units),
        },
    };

    let report = solve_robust_hold(&request).map_err(|e| e.to_string())?;
    print!("{}", format_robust_hold_report(&report, format, units));
    Ok(())
}

/// Golden ratio conjugate, the fixed step constant of the `optimal-zero` search
/// (MBA-1362). Hard-coded rather than derived at run time so the search is bit-for-bit
/// reproducible across builds.
const GOLDEN_SECTION_RATIO: f64 = 0.618_033_988_749_894_9;

/// Iteration cap for the `optimal-zero` golden-section search. Each step shrinks the
/// bracket by [`GOLDEN_SECTION_RATIO`], so a 2000 m bracket reaches the tolerance below in
/// about 25; the rest is runaway guard.
const OPTIMAL_ZERO_MAX_ITERATIONS: u32 = 60;

/// Bracket width (meters) at which the `optimal-zero` search stops. A centimeter of zero
/// distance is far below what anyone can set a zero to.
const OPTIMAL_ZERO_TOLERANCE_M: f64 = 0.01;

/// Smallest and largest zero distance the `optimal-zero` bracket will consider, meters.
const OPTIMAL_ZERO_MIN_M: f64 = 10.0;
const OPTIMAL_ZERO_MAX_M: f64 = 2000.0;

/// Convert one NOMINAL mark subtension to TRUE angular milliradians (MBA-1362).
///
/// The single conversion all three inverse solvers use, so none of them can disagree about
/// what a second-focal-plane mark covers. FFP is an exact identity.
fn true_subtension_mil(nominal_mil: f64, focal_plane: FocalPlane, scale: f64) -> f64 {
    match focal_plane {
        FocalPlane::First => nominal_mil,
        FocalPlane::Second => nominal_mil * scale,
    }
}

/// `mark-to-range` (MBA-1362).
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable Clap command shape"
)]
fn handle_mark_to_range(
    marks: Vec<f64>,
    reticle_json: Option<PathBuf>,
    mag: f64,
    focal_plane: FocalPlaneArg,
    reference_mag: f64,
    zero_distance: Option<f64>,
    max_range: f64,
    load_args: InverseSolverLoadArgs,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    let format = reticle_format(output)?;

    // Subtension source. A reticle file carries its OWN focal plane and reference
    // magnification, which win over the flags — a description that says "SFP at 12x" is
    // authoritative about itself.
    let (nominal_marks, plane, reference_mag, excluded, source_name) = match &reticle_json {
        Some(path) => {
            if !marks.is_empty() {
                return Err("--mark and --reticle-json are mutually exclusive".into());
            }
            let description = load_reticle_description(path)?;
            // Marks on the vertical stadium, INCLUDING any above center: those come back
            // as "not a holdover" rows rather than being quietly dropped. Only genuinely
            // off-axis marks (windage dots) and the optical center itself are excluded,
            // and the count of those is reported.
            let holdovers: Vec<f64> = description
                .marks
                .iter()
                .filter(|m| m.right_mil == 0.0 && m.down_mil != 0.0)
                .map(|m| m.down_mil)
                .collect();
            let excluded = description.marks.len() - holdovers.len();
            if holdovers.is_empty() {
                return Err(format!(
                    "reticle '{}' has no marks on the vertical stadium to map to a range \
                     (only the optical center and off-axis windage marks)",
                    description.name
                )
                .into());
            }
            (
                holdovers,
                description.focal_plane,
                description.reference_magnification,
                excluded,
                description.name,
            )
        }
        None => {
            if marks.is_empty() {
                return Err(
                    "at least one --mark <MIL> is required (or --reticle-json <FILE>)".into(),
                );
            }
            for mark in &marks {
                if !mark.is_finite() {
                    return Err(format!("--mark {mark} must be a finite subtension").into());
                }
            }
            (
                marks,
                focal_plane.into(),
                reference_mag,
                0,
                "supplied marks".to_string(),
            )
        }
    };
    if plane == FocalPlane::Second && (!reference_mag.is_finite() || reference_mag <= 0.0) {
        return Err("an SFP reticle needs a positive reference magnification".into());
    }
    let scale = reference_mag / mag;

    let (load, _) = load_args.resolve(zero_distance, units)?;
    let max_range_m = UnitConverter::distance_to_metric(max_range, units);
    // Search a little past the requested limit so a mark landing exactly at it still
    // brackets.
    let curve = HoldCurve::solve(&load, max_range_m * 1.02)?;

    struct Row {
        nominal_mil: f64,
        true_mil: f64,
        outcome: MarkToRangeOutcome,
    }
    let rows: Vec<Row> = nominal_marks
        .iter()
        .map(|&nominal_mil| {
            let true_mil = true_subtension_mil(nominal_mil, plane, scale);
            Row {
                nominal_mil,
                true_mil,
                outcome: curve.range_for_angular_drop_mil(true_mil),
            }
        })
        .collect();

    let (dist_unit, vel_unit, energy_unit) = match units {
        UnitSystem::Imperial => ("yd", "fps", "ft-lb"),
        UnitSystem::Metric => ("m", "m/s", "J"),
    };

    match format {
        ReticleFormat::Json => {
            let entries: Vec<serde_json::Value> = rows
                .iter()
                .map(|row| match &row.outcome {
                    MarkToRangeOutcome::Reached(point) => serde_json::json!({
                        "nominal_mil": row.nominal_mil,
                        "true_mil": row.true_mil,
                        "status": "reached",
                        "range": UnitConverter::distance_from_metric(point.range_m, units),
                        "time": point.time_s,
                        "velocity": UnitConverter::velocity_from_metric(point.velocity_mps, units),
                        "energy": UnitConverter::energy_from_metric(point.energy_j, units),
                    }),
                    MarkToRangeOutcome::InsideZero { far_zero_range_m } => serde_json::json!({
                        "nominal_mil": row.nominal_mil,
                        "true_mil": row.true_mil,
                        "status": "not_a_holdover",
                        "far_zero_range": UnitConverter::distance_from_metric(*far_zero_range_m, units),
                    }),
                    MarkToRangeOutcome::BeyondSearch { max_range_m, max_drop_mil } => {
                        serde_json::json!({
                            "nominal_mil": row.nominal_mil,
                            "true_mil": row.true_mil,
                            "status": "beyond_max_range",
                            "max_range": UnitConverter::distance_from_metric(*max_range_m, units),
                            "max_drop_mil": max_drop_mil,
                        })
                    }
                })
                .collect();
            let value = serde_json::json!({
                "reticle": source_name,
                "focal_plane": plane.label(),
                "reference_magnification": reference_mag,
                "magnification": mag,
                "mark_scale": if plane == FocalPlane::Second { scale } else { 1.0 },
                "zero_distance": UnitConverter::distance_from_metric(load.zero_distance_m, units),
                "distance_unit": dist_unit,
                "velocity_unit": vel_unit,
                "energy_unit": energy_unit,
                "excluded_marks": excluded,
                "marks": entries,
            });
            println!("{}", serde_json::to_string_pretty(&value)?);
        }
        ReticleFormat::Table => {
            println!("Mark-to-Range");
            println!("=============\n");
            println!("Reticle:      {source_name}");
            println!("Focal plane:  {}", plane.label());
            if plane == FocalPlane::Second {
                println!("Reference:    {reference_mag:.2}x   In use: {mag:.2}x   Subtension scale: {scale:.4}x");
            }
            println!(
                "Zero:         {:.0} {}\n",
                UnitConverter::distance_from_metric(load.zero_distance_m, units),
                dist_unit
            );
            if excluded > 0 {
                println!(
                    "Note: {excluded} mark(s) excluded — the optical center and off-axis \
                     windage marks do not map to a range.\n"
                );
            }
            println!(
                "Mark(mil)  True(mil)  Range({dist_unit})  Time(s)  Vel({vel_unit})  Energy({energy_unit})"
            );
            println!("---------  ---------  ----------  -------  ----------  ------------");
            for row in &rows {
                match &row.outcome {
                    MarkToRangeOutcome::Reached(point) => println!(
                        "{:>9.2}  {:>9.3}  {:>10.0}  {:>7.3}  {:>10.0}  {:>12.0}",
                        row.nominal_mil,
                        row.true_mil,
                        UnitConverter::distance_from_metric(point.range_m, units),
                        point.time_s,
                        UnitConverter::velocity_from_metric(point.velocity_mps, units),
                        UnitConverter::energy_from_metric(point.energy_j, units)
                    ),
                    MarkToRangeOutcome::InsideZero { far_zero_range_m } => println!(
                        "{:>9.2}  {:>9.3}  {:>10}  (not a holdover: drop is 0 at the far zero, {:.0} {}, and only grows past it)",
                        row.nominal_mil,
                        row.true_mil,
                        "-",
                        UnitConverter::distance_from_metric(*far_zero_range_m, units),
                        dist_unit
                    ),
                    MarkToRangeOutcome::BeyondSearch {
                        max_range_m,
                        max_drop_mil,
                    } => println!(
                        "{:>9.2}  {:>9.3}  {:>10}  (never reached: {:.2} mil at {:.0} {} is the most this load drops)",
                        row.nominal_mil,
                        row.true_mil,
                        "-",
                        max_drop_mil,
                        UnitConverter::distance_from_metric(*max_range_m, units),
                        dist_unit
                    ),
                }
            }
        }
    }
    Ok(())
}

/// One `bdc-match --mark-range MIL:RANGE` pair, parsed (MBA-1362).
struct BdcMatchPair {
    nominal_mil: f64,
    range_display: f64,
    range_m: f64,
}

fn parse_bdc_match_pair(token: &str, units: UnitSystem) -> Result<BdcMatchPair, String> {
    let parts: Vec<&str> = token.split(':').collect();
    if parts.len() != 2 {
        return Err(format!(
            "invalid --mark-range '{token}': expected MIL:RANGE (e.g. 2.0:300)"
        ));
    }
    let nominal_mil: f64 = parts[0].trim().parse().map_err(|_| {
        format!(
            "invalid --mark-range subtension '{}' in '{token}'",
            parts[0]
        )
    })?;
    let range: f64 = parts[1]
        .trim()
        .parse()
        .map_err(|_| format!("invalid --mark-range range '{}' in '{token}'", parts[1]))?;
    if !nominal_mil.is_finite() || nominal_mil <= 0.0 {
        return Err(format!(
            "invalid --mark-range '{token}': the subtension must be a positive holdover in \
             milliradians"
        ));
    }
    if !range.is_finite() || range <= 0.0 {
        return Err(format!(
            "invalid --mark-range '{token}': the range must be finite and greater than zero"
        ));
    }
    Ok(BdcMatchPair {
        nominal_mil,
        range_display: range,
        range_m: UnitConverter::distance_to_metric(range, units),
    })
}

/// `bdc-match` (MBA-1362).
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable Clap command shape"
)]
fn handle_bdc_match(
    mark_ranges: Vec<String>,
    reference_mag: f64,
    focal_plane: FocalPlaneArg,
    residual_warn: f64,
    zero_distance: Option<f64>,
    load_args: InverseSolverLoadArgs,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    let format = reticle_format(output)?;
    if FocalPlane::from(focal_plane) == FocalPlane::First {
        return Err(
            "bdc-match applies to SECOND focal plane reticles only: an FFP reticle's \
             subtensions are the same at every magnification, so no magnification makes it \
             match a load better than any other. Use `mark-to-range` to see where its marks \
             land instead."
                .into(),
        );
    }
    let pairs: Vec<BdcMatchPair> = mark_ranges
        .iter()
        .map(|token| parse_bdc_match_pair(token, units))
        .collect::<Result<_, _>>()?;
    if pairs.len() < 2 {
        return Err(
            "bdc-match needs at least two --mark-range MIL:RANGE pairs to fit a magnification \
             (one pair is satisfied exactly by some magnification and says nothing about fit)"
                .into(),
        );
    }

    let (load, _) = load_args.resolve(zero_distance, units)?;
    let furthest_m = pairs.iter().fold(0.0_f64, |acc, p| acc.max(p.range_m));
    let curve = HoldCurve::solve(&load, furthest_m * 1.05)?;

    // Solved angular drop at each mark's nominal range.
    let mut solved_mil = Vec::with_capacity(pairs.len());
    for pair in &pairs {
        let point = curve.at_range(pair.range_m).ok_or_else(|| {
            format!(
                "the trajectory does not reach {:.0} — it was solved only to {:.0}",
                pair.range_display,
                UnitConverter::distance_from_metric(curve.max_sampled_range_m(), units)
            )
        })?;
        solved_mil.push(point.drop_mil);
    }

    // The fit. The apparent subtension of mark i at magnification M is
    //     a_i(M) = s_i * reference_mag / M
    // so substituting u = reference_mag / M makes the residual LINEAR in u:
    //     minimize  sum_i (s_i * u - t_i)^2
    // whose minimizer is the ordinary least-squares slope through the origin,
    //     u* = sum(s_i t_i) / sum(s_i^2),
    // and the fitted magnification is reference_mag / u*. Closed form, so it is exact,
    // deterministic, and cannot depend on a starting guess or an iteration count.
    let sum_st: f64 = pairs
        .iter()
        .zip(&solved_mil)
        .map(|(pair, t)| pair.nominal_mil * t)
        .sum();
    let sum_ss: f64 = pairs.iter().map(|pair| pair.nominal_mil.powi(2)).sum();
    if sum_ss <= 0.0 {
        return Err("the supplied subtensions carry no information to fit".into());
    }
    let u = sum_st / sum_ss;
    if !u.is_finite() || u <= 0.0 {
        return Err(
            "no positive magnification fits these marks: the solved drops and the supplied \
             subtensions disagree in sign (check that the ranges pair with the right marks)"
                .into(),
        );
    }
    let fitted_mag = reference_mag / u;

    struct Residual {
        nominal_mil: f64,
        range_display: f64,
        apparent_mil: f64,
        solved_mil: f64,
        residual_mil: f64,
    }
    let residuals: Vec<Residual> = pairs
        .iter()
        .zip(&solved_mil)
        .map(|(pair, &t)| {
            let apparent = pair.nominal_mil * u;
            Residual {
                nominal_mil: pair.nominal_mil,
                range_display: pair.range_display,
                apparent_mil: apparent,
                solved_mil: t,
                residual_mil: apparent - t,
            }
        })
        .collect();
    let worst = residuals
        .iter()
        .fold(0.0_f64, |acc, r| acc.max(r.residual_mil.abs()));
    let rms = (residuals
        .iter()
        .map(|r| r.residual_mil.powi(2))
        .sum::<f64>()
        / residuals.len() as f64)
        .sqrt();

    let dist_unit = match units {
        UnitSystem::Imperial => "yd",
        UnitSystem::Metric => "m",
    };

    match format {
        ReticleFormat::Json => {
            let value = serde_json::json!({
                "fitted_magnification": fitted_mag,
                "reference_magnification": reference_mag,
                "subtension_scale": u,
                "zero_distance": UnitConverter::distance_from_metric(load.zero_distance_m, units),
                "distance_unit": dist_unit,
                "worst_residual_mil": worst,
                "rms_residual_mil": rms,
                "residual_warn_mil": residual_warn,
                "fit_warning": worst > residual_warn,
                "marks": residuals.iter().map(|r| serde_json::json!({
                    "nominal_mil": r.nominal_mil,
                    "range": r.range_display,
                    "apparent_mil": r.apparent_mil,
                    "solved_drop_mil": r.solved_mil,
                    "residual_mil": r.residual_mil,
                })).collect::<Vec<_>>(),
            });
            println!("{}", serde_json::to_string_pretty(&value)?);
        }
        ReticleFormat::Table => {
            println!("BDC Magnification Match");
            println!("=======================\n");
            println!("Reference magnification: {reference_mag:.2}x");
            println!("Fitted magnification:    {fitted_mag:.3}x");
            println!("Subtension scale at fit: {u:.4}x");
            println!(
                "Zero:                    {:.0} {}\n",
                UnitConverter::distance_from_metric(load.zero_distance_m, units),
                dist_unit
            );
            println!("Mark(mil)  Range({dist_unit})  Apparent(mil)  Drop(mil)  Residual(mil)");
            println!("---------  ----------  -------------  ---------  -------------");
            for r in &residuals {
                println!(
                    "{:>9.2}  {:>10.0}  {:>13.3}  {:>9.3}  {:>13.3}",
                    r.nominal_mil, r.range_display, r.apparent_mil, r.solved_mil, r.residual_mil
                );
            }
            println!("\nWorst residual: {worst:.3} mil   RMS: {rms:.3} mil");
            if worst > residual_warn {
                println!(
                    "\nWARNING: the worst residual exceeds {residual_warn:.3} mil — this reticle \
                     does not fit this load well at ANY magnification. Treat the fitted value as \
                     the least-bad compromise, not a BDC calibration."
                );
            }
        }
    }
    Ok(())
}

/// One `optimal-zero --target RANGE[:HEIGHT]` entry, parsed (MBA-1362).
struct OptimalZeroTarget {
    range_display: f64,
    range_m: f64,
    /// Full vertical size, meters. `None` until `--vital` fills it in.
    height_m: Option<f64>,
}

fn parse_optimal_zero_target(token: &str, units: UnitSystem) -> Result<OptimalZeroTarget, String> {
    let parts: Vec<&str> = token.split(':').collect();
    if parts.len() != 1 && parts.len() != 2 {
        return Err(format!(
            "invalid --target '{token}': expected RANGE or RANGE:HEIGHT (e.g. 400 or 400:12)"
        ));
    }
    let range: f64 = parts[0]
        .trim()
        .parse()
        .map_err(|_| format!("invalid --target range '{}' in '{token}'", parts[0]))?;
    if !range.is_finite() || range <= 0.0 {
        return Err(format!(
            "invalid --target '{token}': the range must be finite and greater than zero"
        ));
    }
    let height = match parts.get(1) {
        Some(token_height) => {
            let value: f64 = token_height
                .trim()
                .parse()
                .map_err(|_| format!("invalid --target height '{token_height}' in '{token}'"))?;
            if !value.is_finite() || value <= 0.0 {
                return Err(format!(
                    "invalid --target '{token}': the height must be finite and greater than zero"
                ));
            }
            Some(value)
        }
        None => None,
    };
    Ok(OptimalZeroTarget {
        range_display: range,
        range_m: UnitConverter::distance_to_metric(range, units),
        // Inches imperial / centimeters metric, matching `mpbr --vital-zone`.
        height_m: height.map(|value| match units {
            UnitSystem::Imperial => value * 0.0254,
            UnitSystem::Metric => value * 0.01,
        }),
    })
}

/// `optimal-zero` (MBA-1362).
fn handle_optimal_zero(
    targets: Vec<String>,
    vital: Option<f64>,
    load_args: InverseSolverLoadArgs,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    const MIN_TARGETS: usize = 2;
    const MAX_TARGETS: usize = 16;

    let format = reticle_format(output)?;
    let mut parsed: Vec<OptimalZeroTarget> = targets
        .iter()
        .map(|token| parse_optimal_zero_target(token, units))
        .collect::<Result<_, _>>()?;
    if parsed.len() < MIN_TARGETS || parsed.len() > MAX_TARGETS {
        return Err(format!(
            "optimal-zero needs {MIN_TARGETS} to {MAX_TARGETS} --target entries (got {}): one \
             target is just a zero distance, and beyond {MAX_TARGETS} the min-max answer is \
             dominated by the extremes anyway",
            parsed.len()
        )
        .into());
    }
    let vital_m = vital.map(|value| match units {
        UnitSystem::Imperial => value * 0.0254,
        UnitSystem::Metric => value * 0.01,
    });
    for target in parsed.iter_mut() {
        if target.height_m.is_none() {
            target.height_m = vital_m;
        }
        if target.height_m.is_none() {
            return Err(format!(
                "--target {} carries no height and no --vital was given; one of the two must \
                 say how big the target is",
                target.range_display
            )
            .into());
        }
    }
    // Sorted by range so the report reads in order regardless of entry order, and so the
    // reported worst-case target is a deterministic choice among ties.
    parsed.sort_by(|a, b| a.range_m.total_cmp(&b.range_m));

    let furthest_m = parsed.iter().fold(0.0_f64, |acc, t| acc.max(t.range_m));
    let nearest_m = parsed
        .iter()
        .fold(f64::INFINITY, |acc, t| acc.min(t.range_m));
    let curve_max_m = furthest_m * 1.05;

    // Resolve the load ONCE, so a missing flag is an error here rather than a mysterious
    // "no zero could be solved" later, and so the saved profile is read once rather than
    // once per search iteration. The zero distance handed in is a placeholder — this
    // command solves for it, and every candidate below overwrites it.
    let (base_load, _) = load_args.resolve(Some(1.0), units)?;

    // Holds at every target for one candidate zero: one solve, read at each range.
    let holds_at = |zero_m: f64| -> Option<Vec<f64>> {
        let mut load = base_load.clone();
        load.zero_distance_m = zero_m;
        let curve = HoldCurve::solve(&load, curve_max_m).ok()?;
        parsed
            .iter()
            .map(|target| curve.at_range(target.range_m).map(|p| p.drop_mil))
            .collect()
    };

    // The objective: the LARGEST hold any target needs. It is quasiconvex in zero
    // distance — increasing the zero shifts every range's required hold by very nearly the
    // same angular amount, and the max of |linear functions| is convex — so golden-section
    // search is valid and, with fixed constants, deterministic.
    let objective = |zero_m: f64| -> f64 {
        match holds_at(zero_m) {
            Some(holds) => holds.iter().fold(0.0_f64, |acc, h| acc.max(h.abs())),
            // An unsolvable candidate is pushed away from rather than crashing the search.
            None => f64::INFINITY,
        }
    };

    let mut lo = (nearest_m * 0.15).max(OPTIMAL_ZERO_MIN_M);
    let mut hi = (furthest_m * 1.05).min(OPTIMAL_ZERO_MAX_M).max(lo + 1.0);
    let mut x1 = hi - GOLDEN_SECTION_RATIO * (hi - lo);
    let mut x2 = lo + GOLDEN_SECTION_RATIO * (hi - lo);
    let mut f1 = objective(x1);
    let mut f2 = objective(x2);
    for _ in 0..OPTIMAL_ZERO_MAX_ITERATIONS {
        if hi - lo <= OPTIMAL_ZERO_TOLERANCE_M {
            break;
        }
        if f1 < f2 {
            hi = x2;
            x2 = x1;
            f2 = f1;
            x1 = hi - GOLDEN_SECTION_RATIO * (hi - lo);
            f1 = objective(x1);
        } else {
            lo = x1;
            x1 = x2;
            f1 = f2;
            x2 = lo + GOLDEN_SECTION_RATIO * (hi - lo);
            f2 = objective(x2);
        }
    }
    let best_zero_m = 0.5 * (lo + hi);
    let holds = holds_at(best_zero_m).ok_or_else(|| {
        format!(
            "no trajectory could be solved at the fitted zero of {:.1} {}",
            UnitConverter::distance_from_metric(best_zero_m, units),
            match units {
                UnitSystem::Imperial => "yd",
                UnitSystem::Metric => "m",
            }
        )
    })?;

    struct TargetRow {
        range_display: f64,
        height_m: f64,
        hold_mil: f64,
        /// Signed vertical displacement of a DEAD-CENTER hold, meters. Positive = the
        /// bullet lands low.
        offset_m: f64,
        fits: bool,
    }
    let rows: Vec<TargetRow> = parsed
        .iter()
        .zip(&holds)
        .map(|(target, &hold_mil)| {
            let height_m = target.height_m.expect("filled in above");
            let offset_m = hold_mil / 1000.0 * target.range_m;
            TargetRow {
                range_display: target.range_display,
                height_m,
                hold_mil,
                offset_m,
                // Boundary contact counts as a fit.
                fits: offset_m.abs() <= height_m / 2.0,
            }
        })
        .collect();
    let max_hold_mil = rows
        .iter()
        .fold(0.0_f64, |acc, r| acc.max(r.hold_mil.abs()));
    let all_fit = rows.iter().all(|r| r.fits);

    let (dist_unit, size_unit) = match units {
        UnitSystem::Imperial => ("yd", "in"),
        UnitSystem::Metric => ("m", "cm"),
    };
    let size_from_m = |value: f64| match units {
        UnitSystem::Imperial => value / 0.0254,
        UnitSystem::Metric => value * 100.0,
    };

    match format {
        ReticleFormat::Json => {
            let value = serde_json::json!({
                "optimal_zero": UnitConverter::distance_from_metric(best_zero_m, units),
                "distance_unit": dist_unit,
                "size_unit": size_unit,
                "max_hold_mil": max_hold_mil,
                "all_targets_fit": all_fit,
                "targets": rows.iter().map(|r| serde_json::json!({
                    "range": r.range_display,
                    "height": size_from_m(r.height_m),
                    "hold_mil": r.hold_mil,
                    "offset": size_from_m(r.offset_m),
                    "fits": r.fits,
                })).collect::<Vec<_>>(),
            });
            println!("{}", serde_json::to_string_pretty(&value)?);
        }
        ReticleFormat::Table => {
            println!("Optimal Zero (min-max hold)");
            println!("===========================\n");
            println!(
                "Optimal zero:  {:.1} {}",
                UnitConverter::distance_from_metric(best_zero_m, units),
                dist_unit
            );
            println!("Largest hold:  {max_hold_mil:.3} mil\n");
            println!(
                "Range({dist_unit})  Target({size_unit})  Hold(mil)  Center-hold miss({size_unit})  Fits"
            );
            println!("----------  ----------  ---------  ---------------------  ----");
            for r in &rows {
                println!(
                    "{:>10.0}  {:>10.1}  {:>9.3}  {:>21.2}  {}",
                    r.range_display,
                    size_from_m(r.height_m),
                    r.hold_mil,
                    size_from_m(r.offset_m),
                    if r.fits { "yes" } else { "NO" }
                );
            }
            println!(
                "\n{}",
                if all_fit {
                    "Every target is inside its vital zone with a dead-center hold."
                } else {
                    "At least one target needs a hold: no single zero keeps them all centered."
                }
            );
            println!(
                "Center-hold miss is signed: positive = the bullet lands LOW of the aim point."
            );
        }
    }
    Ok(())
}

/// Map an `OutputFormat` onto the reticle formatter's two shapes (MBA-1361).
///
/// CSV and PDF are rejected here rather than in the library, because each surface owns its
/// own error convention — the same split `run_drag_curve` uses.
fn reticle_format(output: OutputFormat) -> Result<ReticleFormat, Box<dyn Error>> {
    match output {
        OutputFormat::Table => Ok(ReticleFormat::Table),
        OutputFormat::Json => Ok(ReticleFormat::Json),
        OutputFormat::Csv => Err("reticle output has no CSV form; use -o table or -o json".into()),
        OutputFormat::Pdf => Err("reticle output has no PDF form; use -o table or -o json".into()),
    }
}

/// Most arcs a notice spells out individually before it summarizes the rest. A document with
/// a horseshoe or two wants their coordinates; one with fifty rings wants a count.
const MAX_REPORTED_ARCS: usize = 8;

/// MBA-1441: tell the user, on stderr, what `reticle import` could not represent.
///
/// The complaint the ticket is named for is that a Ventum document with a horseshoe imported
/// as a reticle quietly missing hold points, and nothing said so — a mostly-decorative reticle
/// comes back sparse and looks correct. This is the saying-so. It goes to stderr because this
/// command's stdout is the shared reticle formatter's output verbatim (there is a test that
/// pins that), so a note in it would break `-o json` for anyone piping it.
///
/// Arcs get their resolved apex and tips printed because that is the actionable part: the
/// format cannot declare whether a horseshoe's apex is an aiming point, so the import will not
/// invent a mark there, but a shooter who knows their own reticle can read the coordinates off
/// this notice and add them.
fn print_reticle_import_report(
    file: &std::path::Path,
    report: &ballistics_engine::reticle_import::VentumImportReport,
) {
    if report.is_empty() {
        return;
    }
    eprintln!(
        "note: {}: {} element(s) carry no hold point and were not imported ({})",
        file.display(),
        report.dropped_elements,
        report.tally()
    );
    if report.circle_repeats_unreadable > 0 {
        eprintln!(
            "note: {} circle element(s) declared a `repeat` this importer could not read, so \
             each was counted once; the document may draw more.",
            report.circle_repeats_unreadable
        );
    }
    if report.arcs.is_empty() && report.arcs_unresolved == 0 {
        return;
    }
    eprintln!(
        "note: an arc's aiming points cannot be declared in this format, so none were \
         imported as marks. Add them yourself if your reticle holds on them:"
    );
    for arc in report.arcs.iter().take(MAX_REPORTED_ARCS) {
        eprintln!(
            "        arc {:.0}-{:.0} deg: apex {}, tips {} and {}",
            arc.start_degrees,
            arc.end_degrees,
            format_reticle_arc_point(arc.apex),
            format_reticle_arc_point(arc.start_tip),
            format_reticle_arc_point(arc.end_tip),
        );
    }
    if report.arcs.len() > MAX_REPORTED_ARCS {
        eprintln!(
            "        ... and {} more arc(s)",
            report.arcs.len() - MAX_REPORTED_ARCS
        );
    }
    if report.arcs_unresolved > 0 {
        eprintln!(
            "        {} further arc(s) declared geometry this importer could not read \
             (radius, sweep or center), so their points could not be computed at all",
            report.arcs_unresolved
        );
    }
}

/// One arc point as `1.20 right / 2.00 up mil` — signed milliradians spelled as directions,
/// because "down_mil: -2.0" is exactly the sign the user should not have to reason about.
fn format_reticle_arc_point(point: ballistics_engine::reticle_import::VentumArcPoint) -> String {
    format!(
        "{} / {} mil",
        format_reticle_arc_axis(point.right_mil, "left", "right"),
        format_reticle_arc_axis(point.down_mil, "up", "down")
    )
}

/// One axis of an arc point, named by its sign.
///
/// Rounds BEFORE naming the direction: an apex dead on the vertical axis comes out of
/// `cos(270 deg)` as a tiny NEGATIVE float, and printing "0.00 left" for it is noise the
/// reader has to work out is not real. A value that rounds to zero gets no direction word.
fn format_reticle_arc_axis(value: f64, negative: &str, positive: &str) -> String {
    let rounded = (value * 100.0).round() / 100.0;
    if rounded == 0.0 {
        return "0.00".to_string();
    }
    let direction = if rounded < 0.0 { negative } else { positive };
    format!("{:.2} {}", rounded.abs(), direction)
}

/// Parse one `reticle generate bdc --drop RANGE:DROP_MIL` token into
/// `(range_display, range_m, drop_mil)`.
///
/// RANGE follows `--units`; DROP_MIL is always milliradians (an angle, so unit-invariant —
/// the same reasoning that keeps turret graduations out of `converted_to`). The display
/// range comes back too so the caller can label marks in the units the user typed.
fn parse_reticle_bdc_drop(token: &str, units: UnitSystem) -> Result<(f64, f64, f64), String> {
    let parts: Vec<&str> = token.split(':').collect();
    if parts.len() != 2 {
        return Err(format!(
            "invalid --drop '{token}': expected RANGE:DROP_MIL (e.g. 400:2.7)"
        ));
    }
    let range: f64 = parts[0]
        .trim()
        .parse()
        .map_err(|_| format!("invalid --drop range '{}' in '{token}'", parts[0]))?;
    let drop_mil: f64 = parts[1]
        .trim()
        .parse()
        .map_err(|_| format!("invalid --drop value '{}' in '{token}'", parts[1]))?;
    if !range.is_finite() || range <= 0.0 {
        return Err(format!(
            "invalid --drop '{token}': range must be finite and greater than zero"
        ));
    }
    if !drop_mil.is_finite() {
        return Err(format!("invalid --drop '{token}': drop must be finite"));
    }
    Ok((
        range,
        UnitConverter::distance_to_metric(range, units),
        drop_mil,
    ))
}

/// `reticle` dispatch (MBA-1361).
fn handle_reticle(action: ReticleAction, units: UnitSystem) -> Result<(), Box<dyn Error>> {
    match action {
        ReticleAction::Generate { layout } => {
            let (mut description, common) = match layout {
                ReticleLayout::MilGrid {
                    spacing,
                    extent,
                    common,
                } => (
                    ReticleDescription::mil_grid(spacing, extent).map_err(|e| e.to_string())?,
                    common,
                ),
                ReticleLayout::Tree {
                    rows,
                    row_spacing,
                    spread_step,
                    common,
                } => (
                    ReticleDescription::tree(rows, row_spacing, spread_step)
                        .map_err(|e| e.to_string())?,
                    common,
                ),
                ReticleLayout::Bdc { drops, common } => {
                    let parsed = drops
                        .iter()
                        .map(|token| parse_reticle_bdc_drop(token, units))
                        .collect::<Result<Vec<_>, _>>()?;
                    let metric: Vec<(f64, f64)> = parsed
                        .iter()
                        .map(|&(_, range_m, drop_mil)| (range_m, drop_mil))
                        .collect();
                    let mut description =
                        ReticleDescription::bdc_from_drops(&metric).map_err(|e| e.to_string())?;
                    // The library labels in meters (the schema is SI); this surface knows
                    // the user's display units, so it relabels with what they typed. The
                    // ladder's first mark is the center, hence the 1-offset.
                    let dist_unit = match units {
                        UnitSystem::Imperial => "yd",
                        UnitSystem::Metric => "m",
                    };
                    for (mark, &(range_display, _, _)) in
                        description.marks.iter_mut().skip(1).zip(parsed.iter())
                    {
                        mark.label = Some(format!("{range_display:.0} {dist_unit}"));
                    }
                    (description, common)
                }
            };
            description.focal_plane = common.focal_plane.into();
            description.reference_magnification = common.reference_mag;
            if let Some(name) = common.name {
                description.name = name;
            }
            description.validate().map_err(|e| e.to_string())?;
            print!(
                "{}",
                format_reticle_description(&description, reticle_format(common.output)?)
            );
            Ok(())
        }

        ReticleAction::Import { file, output } => {
            let json = std::fs::read_to_string(&file)
                .map_err(|e| format!("reading reticle file '{}': {e}", file.display()))?;
            let (description, report) =
                ballistics_engine::reticle_import::import_ventum_reticle_with_report(&json)
                    .map_err(|e| e.to_string())?;
            // The converter builds but does not validate (matching `mil_grid`/`tree`/
            // `bdc_from_drops`); validating here surfaces a decoration-only import as a clean
            // `NoMarks` error rather than an empty reticle that silently fails downstream.
            description.validate().map_err(|e| e.to_string())?;
            // MBA-1441: say what the document drew that this import could not represent.
            // stderr, not stdout: `reticle import`'s stdout is the shared formatter's string
            // verbatim, and folding a note into it would break `-o json`/`-o csv` for anyone
            // piping them.
            print_reticle_import_report(&file, &report);
            print!(
                "{}",
                format_reticle_description(&description, reticle_format(output)?)
            );
            Ok(())
        }

        ReticleAction::Hold {
            reticle_json,
            profile,
            drop_mil,
            wind_mil,
            range,
            mag,
            velocity,
            bc,
            mass,
            diameter,
            drag_model,
            zero_distance,
            sight_height,
            temperature,
            pressure,
            pressure_type,
            humidity,
            altitude,
            wind_speed,
            wind_direction,
            output,
        } => {
            let format = reticle_format(output)?;
            let profile_data = match profile.as_deref() {
                Some(name) => Some(load_profile(name)?),
                None => None,
            };

            // Reticle source: an explicit file wins over the profile's attached one.
            let description = match (&reticle_json, profile_data.as_ref()) {
                (Some(path), _) => load_reticle_description(path)?,
                (None, Some(data)) => data.reticle.clone().ok_or_else(|| {
                    format!(
                        "profile '{}' has no attached reticle; attach one with \
                         `profile save {} --reticle-json <FILE>`, or pass --reticle-json here",
                        data.name, data.name
                    )
                })?,
                (None, None) => {
                    return Err(
                        "a reticle is required: pass --reticle-json <FILE> or --profile <NAME>"
                            .into(),
                    )
                }
            };

            // Hold source: an explicit angular solution, or one solved at --range. Never
            // both — silently preferring one would hide a contradictory invocation.
            let (hold_drop_mil, hold_wind_mil, solved) = match (drop_mil, range) {
                (Some(_), Some(_)) => {
                    return Err(
                        "--drop-mil and --range are mutually exclusive: give the angular \
                         hold directly, or let --range solve for it"
                            .into(),
                    )
                }
                (Some(drop), None) => (drop, wind_mil.unwrap_or(0.0), None),
                (None, Some(range)) => {
                    if wind_mil.is_some() {
                        return Err(
                            "--wind-mil applies to --drop-mil only; with --range the wind \
                             deflection comes from --wind-speed/--wind-direction"
                                .into(),
                        );
                    }
                    let require = |value: Option<f64>, flag: &str| -> Result<f64, Box<dyn Error>> {
                        value.ok_or_else(|| {
                            format!("--range requires {flag} (directly or from --profile)").into()
                        })
                    };
                    let velocity = require(
                        resolve_param(velocity, &profile_data, |p| p.velocity),
                        "--velocity",
                    )?;
                    let bc = require(resolve_param(bc, &profile_data, |p| p.bc), "--bc")?;
                    let mass = require(resolve_param(mass, &profile_data, |p| p.mass), "--mass")?;
                    let diameter = require(
                        resolve_param(diameter, &profile_data, |p| p.diameter),
                        "--diameter",
                    )?;
                    let zero_distance = require(
                        zero_distance
                            .or_else(|| profile_data.as_ref().and_then(|p| p.zero_distance)),
                        "--zero-distance",
                    )?;
                    // Same fallback `trajectory --saved-profile`/`come-ups --profile` use.
                    let sight_height = sight_height
                        .or_else(|| profile_data.as_ref().and_then(|p| p.sight_height))
                        .unwrap_or(match units {
                            UnitSystem::Imperial => 2.0,
                            UnitSystem::Metric => 50.0,
                        });
                    let temperature = UnitConverter::resolve_temperature(temperature, units)?;
                    // MBA-1416: a declared QNH reduces against this command's own --altitude.
                    let pressure = apply_pressure_mode(
                        UnitConverter::resolve_pressure(pressure, units)?,
                        altitude,
                        pressure_type,
                        units,
                    );

                    let load = HoldCurveLoad {
                        velocity_mps: UnitConverter::velocity_to_metric(velocity, units),
                        bc,
                        mass_kg: UnitConverter::mass_to_metric(mass, units),
                        diameter_m: UnitConverter::diameter_to_metric(diameter, units),
                        drag_model,
                        sight_height_m: UnitConverter::sight_height_to_metric(sight_height, units),
                        zero_distance_m: UnitConverter::distance_to_metric(zero_distance, units),
                        temperature_c: UnitConverter::temperature_to_metric(temperature, units),
                        pressure_hpa: UnitConverter::pressure_to_metric(pressure, units),
                        humidity,
                        altitude_m: UnitConverter::altitude_to_metric(altitude, units),
                        wind_speed_mps: UnitConverter::wind_to_metric(wind_speed, units),
                        wind_direction_deg: wind_direction.degrees,
                    };
                    let range_m = UnitConverter::distance_to_metric(range, units);
                    let curve = HoldCurve::solve(&load, range_m * 1.05)?;
                    let point = curve.at_range(range_m).ok_or_else(|| {
                        format!(
                            "the trajectory does not reach {range} — it was sampled only to {:.1}",
                            UnitConverter::distance_from_metric(curve.max_sampled_range_m(), units)
                        )
                    })?;
                    (point.drop_mil, point.wind_mil, Some(point))
                }
                (None, None) => {
                    return Err(
                        "a firing solution is required: pass --drop-mil (with optional \
                         --wind-mil) or --range"
                            .into(),
                    )
                }
            };

            let hold = hold_point_in_reticle(hold_drop_mil, hold_wind_mil, mag, &description)
                .map_err(|e| e.to_string())?;
            if let (Some(point), OutputFormat::Table) = (solved, output) {
                let (dist_unit, vel_unit) = match units {
                    UnitSystem::Imperial => ("yd", "fps"),
                    UnitSystem::Metric => ("m", "m/s"),
                };
                println!(
                    "Solved at {:.0} {} — {:.1} {} remaining, {:.3} s time of flight\n",
                    UnitConverter::distance_from_metric(point.range_m, units),
                    dist_unit,
                    UnitConverter::velocity_from_metric(point.velocity_mps, units),
                    vel_unit,
                    point.time_s
                );
            }
            print!("{}", format_reticle_hold(&hold, &description, mag, format));
            Ok(())
        }
    }
}

fn run_drag_curve(
    drag_model: DragModel,
    output: OutputFormat,
) -> Result<(), Box<dyn std::error::Error>> {
    // MBA-1426: formatting lives in the library (`drag::format_reference_drag_curve`) and is
    // shared with the browser terminal, so the two surfaces emit identical bytes. Only the PDF
    // rejection stays here, because each surface owns its error convention.
    let format = match output {
        OutputFormat::Table => ballistics_engine::drag::ReferenceDragCurveFormat::Table,
        OutputFormat::Csv => ballistics_engine::drag::ReferenceDragCurveFormat::Csv,
        OutputFormat::Json => ballistics_engine::drag::ReferenceDragCurveFormat::Json,
        OutputFormat::Pdf => {
            return Err("drag-curve has no PDF form; use -o table, -o csv, or -o json".into());
        }
    };
    print!(
        "{}",
        ballistics_engine::drag::format_reference_drag_curve(&drag_model, format)
    );
    Ok(())
}

#[allow(clippy::too_many_arguments)]
fn run_bc_convert(
    source_model: BcConvertModelArg,
    target_model: BcConvertModelArg,
    bc: Option<f64>,
    mach: Option<f64>,
    velocity: Option<f64>,
    bc_segment: &[String],
    speed_of_sound: Option<f64>,
    output: BcConversionOutputFormat,
    units: UnitSystem,
) -> Result<(), Box<dyn std::error::Error>> {
    use ballistics_engine::bc_conversion::{
        analyze_bc_segments, convert_bc_at_mach, convert_bc_at_velocity,
        format_bc_conversion_report, BcConversionFormat, BcConversionReportV1,
    };

    let format = match output {
        BcConversionOutputFormat::Table => BcConversionFormat::Table,
        BcConversionOutputFormat::Csv => BcConversionFormat::Csv,
        BcConversionOutputFormat::Json => BcConversionFormat::Json,
    };
    let source: DragModel = source_model.into();
    let target: DragModel = target_model.into();

    let report = if let Some(source_bc) = bc {
        let result = match (mach, velocity) {
            (Some(mach), None) => convert_bc_at_mach(source_bc, source, target, mach)
                .map_err(|error| error.to_string())?,
            (None, Some(velocity)) => convert_bc_at_velocity(
                source_bc,
                source,
                target,
                bc_convert_velocity_to_fps(velocity, units),
                bc_convert_speed_of_sound_fps(speed_of_sound, units),
            )
            .map_err(|error| error.to_string())?,
            _ => {
                return Err(
                    "scalar conversion requires exactly one of --mach or --velocity".into(),
                );
            }
        };
        BcConversionReportV1::Scalar { result }
    } else {
        let segments: Vec<BCSegmentData> = bc_segment
            .iter()
            .map(|segment| parse_bc_segment(segment, units))
            .collect::<Result<_, _>>()?;
        let result = analyze_bc_segments(
            &segments,
            source,
            target,
            &[DragModel::G1, DragModel::G7],
            bc_convert_speed_of_sound_fps(speed_of_sound, units),
        )
        .map_err(|error| error.to_string())?;
        BcConversionReportV1::Banded { result }
    };

    print!(
        "{}",
        format_bc_conversion_report(&report, format).map_err(|error| error.to_string())?
    );
    Ok(())
}

/// `BCSegmentData` and the MBA-1375 conversion core use canonical ft/s. Keep this conversion in
/// one place so scalar velocity, every band boundary, and an explicit speed of sound cannot
/// accidentally use different approximations under `--units metric`.
fn bc_convert_velocity_to_fps(value: f64, units: UnitSystem) -> f64 {
    match units {
        UnitSystem::Imperial => value,
        UnitSystem::Metric => value * 3.280_839_895,
    }
}

fn bc_convert_speed_of_sound_fps(value: Option<f64>, units: UnitSystem) -> f64 {
    value.map_or_else(
        || {
            ballistics_engine::constants::SPEED_OF_SOUND_MPS
                / ballistics_engine::constants::FPS_TO_MPS
        },
        |value| bc_convert_velocity_to_fps(value, units),
    )
}

/// Apply a subcommand's `--pressure-type` to its `--pressure` (MBA-1416).
///
/// The calculator subcommands (`mpbr`, `come-ups`, `range-table`, and the rest) do not run
/// `trajectory`'s full station-conditions resolution — they take `--pressure` as given and hand
/// it straight to `AtmosphericConditions`. Before this, that meant they silently treated every
/// pressure as absolute station pressure, so a weather-report barometer value entered at
/// elevation was wrong by the ISA reduction on every command except `trajectory` and `zero`.
///
/// This applies just the QNH reduction, keyed off the command's own `--altitude`, so `qnh` means
/// the same thing everywhere it is accepted. `Absolute` (and an omitted flag) returns the
/// pressure untouched, which keeps every existing invocation byte-identical.
///
/// `pressure_hpa` is already unit-resolved; `altitude_display` is still in the command's display
/// units (feet imperial / meters metric) and is converted here, because feeding feet to a
/// reduction expecting meters would be a large and completely silent error.
fn apply_pressure_mode(
    pressure_hpa: f64,
    altitude_display: f64,
    mode: Option<PressureReferenceMode>,
    units: UnitSystem,
) -> f64 {
    match mode.unwrap_or(PressureReferenceMode::Absolute) {
        PressureReferenceMode::Absolute => pressure_hpa,
        PressureReferenceMode::Qnh => {
            let altitude_m = UnitConverter::altitude_to_metric(altitude_display, units);
            ballistics_engine::atmosphere::reduce_qnh_to_station_pressure(pressure_hpa, altitude_m)
        }
    }
}

// ============================================================================
// `explain` / `tolerance` (0.33.0 decision-support Task 14, MBA-1345 / MBA-1350)
// ============================================================================

/// Render a solve-json v1 protocol error for CLI display.
///
/// `main` prints its top-level error through `Debug`, which for a plain `String` renders far
/// more readably than a nested typed error's own derived `Debug` would -- so, matching every
/// other subcommand's convention (see `handle_hold_corridor`'s identical note), a protocol
/// error is rendered through its own `Display`-ish accessors into a `String` right here, rather
/// than propagated as `SolveErrorEnvelopeV1` itself.
fn describe_solve_error(e: &SolveErrorEnvelopeV1) -> String {
    match e.error.path() {
        Some(path) => format!("{:?} at {path}: {}", e.error.code, e.error.message),
        None => format!("{:?}: {}", e.error.code, e.error.message),
    }
}

/// Read a solve-json v1 request file, decode it, solve it, and return the RESOLVED request --
/// the one entry point `handle_explain`/`handle_tolerance` both use, so a firing solution is
/// only ever described to this CLI surface one way (a solve-json v1 file), never a second
/// flag-based shape.
fn load_resolved_request(path: &Path) -> Result<ResolvedSolveRequestV1, Box<dyn Error>> {
    let text = fs::read_to_string(path).map_err(|e| {
        format!(
            "could not read solve-json request file {}: {e}",
            path.display()
        )
    })?;
    // Every failure mode below is prefixed with `path` too (review I2): `explain` reads TWO
    // files, and without this a decode/solve error is indistinguishable between `--a` and
    // `--b` -- `describe_solve_error` alone has no way to know which file it came from.
    let request = decode_solve_request_v1(&text)
        .map_err(|e| format!("{}: {}", path.display(), describe_solve_error(&e)))?;
    let success = ballistics_engine::solve_v1(request)
        .map_err(|e| format!("{}: {}", path.display(), describe_solve_error(&e)))?;
    Ok(success.resolved_request)
}

/// Canonical kebab-case CLI spelling for one taxonomy axis.
///
/// This is the single source of truth: [`parse_input_axis`] is DERIVED from this match plus
/// [`InputAxis::ALL`], rather than a second, independently hand-maintained match mapping
/// strings back to variants. The match below is exhaustive over `InputAxis`, so a future 33rd
/// variant fails to COMPILE here until it is given a spelling, instead of silently becoming
/// unparseable on the CLI -- see `axis_kebab_names_round_trip_every_member_of_all` below.
fn axis_kebab_name(axis: InputAxis) -> &'static str {
    use InputAxis::*;
    match axis {
        Mass => "mass",
        Diameter => "diameter",
        Length => "length",
        BallisticCoefficient => "ballistic-coefficient",
        TwistRate => "twist-rate",
        TwistDirection => "twist-direction",
        DragModel => "drag-model",
        MuzzleVelocityMps => "muzzle-velocity-mps",
        SightHeight => "sight-height",
        ZeroDistance => "zero-distance",
        ZeroPoiUp => "zero-poi-up",
        ZeroPoiRight => "zero-poi-right",
        SightOffsetLateral => "sight-offset-lateral",
        MuzzleHeight => "muzzle-height",
        MuzzleAngle => "muzzle-angle",
        Altitude => "altitude",
        Temperature => "temperature",
        Pressure => "pressure",
        RelativeHumidity => "relative-humidity",
        Latitude => "latitude",
        WindSpeed => "wind-speed",
        WindDirection => "wind-direction",
        WindVertical => "wind-vertical",
        TargetDistance => "target-distance",
        ShootingAngle => "shooting-angle",
        Cant => "cant",
        ShotAzimuth => "shot-azimuth",
        AimAzimuth => "aim-azimuth",
        TargetHeight => "target-height",
        MagnusEnabled => "magnus-enabled",
        CoriolisEnabled => "coriolis-enabled",
        EnhancedSpinDriftEnabled => "enhanced-spin-drift-enabled",
    }
}

/// Parse one `--axis`/`--domain` axis token (kebab-case) into an [`InputAxis`].
///
/// Derived from [`axis_kebab_name`] plus [`InputAxis::ALL`] rather than a hand-maintained
/// reverse list -- see that function's own doc. An unrecognized name is a hard error listing
/// every accepted spelling, sorted for a stable, greppable message.
fn parse_input_axis(s: &str) -> Result<InputAxis, String> {
    InputAxis::ALL
        .iter()
        .copied()
        .find(|&axis| axis_kebab_name(axis) == s)
        .ok_or_else(|| {
            let mut names: Vec<&str> = InputAxis::ALL
                .iter()
                .copied()
                .map(axis_kebab_name)
                .collect();
            names.sort_unstable();
            format!(
                "unknown axis '{s}'; accepted axis names are: {}",
                names.join(", ")
            )
        })
}

/// The physical unit `axis`'s resolved value (and any `--domain` bound for it) is expressed
/// in on this CLI surface -- `""` for a dimensionless or categorical axis.
fn axis_unit_suffix(axis: InputAxis) -> &'static str {
    match axis_meta(axis).kind {
        AxisKind::Continuous { unit, .. } => unit,
        AxisKind::Categorical => "",
    }
}

/// Parse one `--domain AXIS=LO:HI` token into an axis and its (unconverted, axis-native-unit)
/// bounds. Only shape is validated here (a number on each side of one `:`, one `=`); whether
/// the bounds are finite, ordered, and actually bracket the axis's nominal value is
/// `tolerance_envelope`'s own job (`KernelError::InvalidDomain`).
fn parse_domain_arg(s: &str) -> Result<(InputAxis, (f64, f64)), String> {
    let malformed =
        || format!("invalid --domain '{s}': expected AXIS=LO:HI (e.g. wind-speed=0:20)");
    let (axis_part, range_part) = s.split_once('=').ok_or_else(malformed)?;
    let axis = parse_input_axis(axis_part.trim())?;
    let (lo_str, hi_str) = range_part.split_once(':').ok_or_else(malformed)?;
    let (lo_str, hi_str) = (lo_str.trim(), hi_str.trim());
    let lo: f64 = lo_str
        .parse()
        .map_err(|_| format!("invalid --domain '{s}': lower bound '{lo_str}' is not a number"))?;
    let hi: f64 = hi_str
        .parse()
        .map_err(|_| format!("invalid --domain '{s}': upper bound '{hi_str}' is not a number"))?;
    Ok((axis, (lo, hi)))
}

/// Parse one `error-budget --sigma AXIS=VALUE` token into an axis and its declared one-sigma
/// uncertainty, in the axis's own physical unit.
///
/// The value is validated (finite, non-negative) HERE rather than left to
/// `error_budget_with_target`'s own check: forwarding an invalid sigma to the library would
/// surface `KernelError::NonFinite`'s generic Display text ("axis {axis:?} produced a non-finite
/// result"), which describes a DIFFERENT failure (a computed derivative that came out
/// non-finite) from "the value you typed after '=' is invalid." Naming the flag and the axis
/// directly here avoids that misleading reuse.
fn parse_sigma_arg(s: &str) -> Result<(InputAxis, f64), String> {
    let (axis_part, value_part) = s.split_once('=').ok_or_else(|| {
        format!("invalid --sigma '{s}': expected AXIS=VALUE (e.g. wind-speed=1.5)")
    })?;
    let axis = parse_input_axis(axis_part.trim())?;
    let value_str = value_part.trim();
    let value: f64 = value_str
        .parse()
        .map_err(|_| format!("invalid --sigma '{s}': value '{value_str}' is not a number"))?;
    if !(value.is_finite() && value >= 0.0) {
        return Err(format!(
            "invalid --sigma for axis '{}': {value_str} must be finite and non-negative",
            axis_kebab_name(axis)
        ));
    }
    Ok((axis, value))
}

/// One [`DeltaV1`] as a fixed-width, aligned line -- shared by every group-contribution row,
/// the total, and the interaction remainder so the four numbers line up down the table.
fn format_delta(d: &DeltaV1) -> String {
    format!(
        "drop {:+9.6} m   windage {:+9.6} m   time {:+9.6} s   velocity {:+9.4} m/s",
        d.drop_m, d.windage_m, d.time_s, d.velocity_mps
    )
}

/// Render a [`SolutionDiffReportV1`] as a human-readable table: one block per range, with the
/// interaction remainder on its OWN labelled line (never mistakable for a group's own
/// contribution), then any skipped axes and the report's own stated assumptions.
fn render_explain_table(report: &SolutionDiffReportV1) -> String {
    use std::fmt::Write as _;
    let mut out = String::new();
    let _ = writeln!(out, "explain -- method: {}", report.method);

    for row in &report.rows {
        let _ = writeln!(out);
        let _ = writeln!(out, "range {:.3} m", row.range_m);
        let _ = writeln!(out, "  {:<22} {}", "total", format_delta(&row.total));
        for c in &row.contributions {
            let group_name = format!("{:?}", c.group);
            let _ = writeln!(out, "  {group_name:<22} {}", format_delta(&c.delta));
        }
        // Deliberately its own line, with its own label and a trailing explanation, so it
        // cannot be skimmed as an eighth group contribution.
        let _ = writeln!(
            out,
            "  {:<22} {}   (unexplained by any single group)",
            "interaction remainder",
            format_delta(&row.interaction_remainder)
        );
    }

    if !report.skipped_axes.is_empty() {
        let _ = writeln!(out);
        let _ = writeln!(
            out,
            "skipped axes (excluded from that group's swap on both directions):"
        );
        for s in &report.skipped_axes {
            let direction = format!("{:?}", s.direction);
            let group = format!("{:?}", s.group);
            let axis = axis_kebab_name(s.axis);
            let _ = writeln!(out, "  [{direction}] {group} / {axis} -- {}", s.reason);
        }
    }

    let _ = writeln!(out);
    let _ = writeln!(out, "assumptions:");
    for a in &report.assumptions {
        let _ = writeln!(out, "  - {a}");
    }
    out
}

/// `explain` dispatch (MBA-1345).
fn handle_explain(
    a_path: PathBuf,
    b_path: PathBuf,
    ranges_m: Vec<f64>,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    // Checked before either request is even read: this command runs on the order of 70 solves
    // (see `explain_difference`'s own cost note), so an unsupported output format should fail
    // for free, not after paying for the comparison.
    match output {
        OutputFormat::Csv => return Err("explain has no CSV form; use -o table or -o json".into()),
        OutputFormat::Pdf => return Err("explain has no PDF form; use -o table or -o json".into()),
        OutputFormat::Table | OutputFormat::Json => {}
    }

    let a = load_resolved_request(&a_path)?;
    let b = load_resolved_request(&b_path)?;

    let report = explain_difference(&a, &b, &ranges_m).map_err(|e| e.to_string())?;

    if matches!(output, OutputFormat::Json) {
        println!("{}", serde_json::to_string_pretty(&report)?);
    } else {
        print!("{}", render_explain_table(&report));
    }
    Ok(())
}

/// One axis's near/far search outcome as a table line -- the five situations a shooter must be
/// able to tell apart (an axis unavailable at all is handled by the caller, one level up, since
/// it never reaches a per-direction search): a real bound, no bound within the configured
/// domain, no measurable effect at all, and (via the caller's own early return before this is
/// called) the nominal itself sitting outside the target.
fn render_tolerance_direction(
    bound: Option<f64>,
    has_no_effect: bool,
    boundary: Option<LimitingBoundaryV1>,
    unit: &str,
) -> String {
    let unit_sp = if unit.is_empty() { "" } else { " " };
    if let Some(v) = bound {
        let edge = boundary.expect("a found bound always carries a limiting boundary");
        format!("bound at {v:.6}{unit_sp}{unit} -- crosses the {edge:?} edge")
    } else if has_no_effect {
        "no measurable effect on the impact (this axis is provably irrelevant here)".to_string()
    } else {
        "no bound within the configured domain (the impact stays inside the target)".to_string()
    }
}

/// Render a [`ToleranceReportV1`] as a human-readable table.
fn render_tolerance_table(report: &ToleranceReportV1) -> String {
    use std::fmt::Write as _;
    let mut out = String::new();
    let _ = writeln!(out, "tolerance -- method: {}", report.method);
    let _ = writeln!(out, "range {:.3} m", report.range_m);

    for axis in &report.axes {
        let _ = writeln!(out);
        let name = axis_kebab_name(axis.axis);
        let unit = axis_unit_suffix(axis.axis);
        let unit_sp = if unit.is_empty() { "" } else { " " };
        let _ = writeln!(
            out,
            "axis {name} (nominal {:.6}{unit_sp}{unit}, target margin {:.4} m)",
            axis.nominal, axis.margin_linear_m
        );
        if !axis.nominal_inside_target {
            let _ = writeln!(
                out,
                "  nominal OUTSIDE target -- target has no positive area; no bound was \
                 searched in either direction"
            );
            continue;
        }
        let _ = writeln!(
            out,
            "  near (toward the domain's lower bound): {}",
            render_tolerance_direction(
                axis.near_bound,
                axis.near_has_no_effect,
                axis.near_limiting_boundary,
                unit
            )
        );
        let _ = writeln!(
            out,
            "  far  (toward the domain's upper bound): {}",
            render_tolerance_direction(
                axis.far_bound,
                axis.far_has_no_effect,
                axis.far_limiting_boundary,
                unit
            )
        );
        // Review I1: `near_has_no_effect`/`far_has_no_effect` can each only be `true` when the
        // matching bound is `None` (`ToleranceAxisV1`'s own doc), so an axis with NO EFFECT IN
        // EITHER DIRECTION also reads `unbounded_in_domain == true` -- the exact "no effect" vs.
        // "unbounded" conflation this pair of fields exists to prevent (module doc,
        // "`TargetDistance` cannot answer..."). Printing "stays inside" there would read as
        // reassurance about a change that provably does nothing at all, undoing the very
        // distinction the two lines above it just made. Only print the summary when at least
        // one direction genuinely has an effect; the both-no-effect case is already fully
        // stated by those two per-direction lines and needs no "stays inside" recap.
        if axis.unbounded_in_domain && !(axis.near_has_no_effect && axis.far_has_no_effect) {
            let _ = writeln!(
                out,
                "  unbounded in domain: the impact stays inside the target across the whole \
                 configured domain"
            );
        }
    }

    if !report.unavailable_axes.is_empty() {
        let _ = writeln!(out);
        let _ = writeln!(out, "unavailable axes (could not be searched at all):");
        for u in &report.unavailable_axes {
            let name = axis_kebab_name(u.axis);
            let code = format!("{:?}", u.code);
            let _ = writeln!(out, "  {name} [{code}] -- {}", u.reason);
        }
    }

    let _ = writeln!(out);
    let _ = writeln!(out, "assumptions:");
    for a in &report.assumptions {
        let _ = writeln!(out, "  - {a}");
    }
    out
}

/// `tolerance` dispatch (MBA-1350).
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable Clap command shape"
)]
fn handle_tolerance(
    request_path: PathBuf,
    range_m: f64,
    target: String,
    axes_raw: Vec<String>,
    domains_raw: Vec<String>,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    match output {
        OutputFormat::Csv => {
            return Err("tolerance has no CSV form; use -o table or -o json".into())
        }
        OutputFormat::Pdf => {
            return Err("tolerance has no PDF form; use -o table or -o json".into())
        }
        OutputFormat::Table | OutputFormat::Json => {}
    }

    let axes: Vec<InputAxis> = axes_raw
        .iter()
        .map(|s| parse_input_axis(s))
        .collect::<Result<_, _>>()?;
    for (i, &axis) in axes.iter().enumerate() {
        if axes[..i].contains(&axis) {
            return Err(
                format!("--axis {} was given more than once", axis_kebab_name(axis)).into(),
            );
        }
    }

    let mut domains: Vec<(InputAxis, (f64, f64))> = Vec::with_capacity(domains_raw.len());
    for raw in &domains_raw {
        let (axis, bounds) = parse_domain_arg(raw)?;
        if domains.iter().any(|(a, _)| *a == axis) {
            return Err(format!(
                "--domain for axis '{}' was given more than once",
                axis_kebab_name(axis)
            )
            .into());
        }
        domains.push((axis, bounds));
    }
    // tolerance_envelope never invents a domain (a silent default would misrepresent how far an
    // axis was actually searched), so the CLI insists every --axis has a matching --domain up
    // front, naming the specific axis and the flag syntax -- clearer than forwarding
    // KernelError::InvalidDomain's "no domain was configured for this axis", which cannot
    // mention --domain at all.
    for &axis in &axes {
        if !domains.iter().any(|(a, _)| *a == axis) {
            let unit = axis_unit_suffix(axis);
            let hint = if unit.is_empty() {
                String::new()
            } else {
                format!(" (in {unit})")
            };
            let name = axis_kebab_name(axis);
            return Err(format!(
                "--axis {name} has no matching --domain; supply one as --domain {name}=LO:HI{hint}"
            )
            .into());
        }
    }
    for (axis, _) in &domains {
        if !axes.contains(axis) {
            return Err(format!(
                "--domain was given for axis '{}', which was not requested with --axis",
                axis_kebab_name(*axis)
            )
            .into());
        }
    }

    let resolved = load_resolved_request(&request_path)?;

    let target_spec = parse_target_spec(&target, units).map_err(|e| e.to_string())?;
    let geometry = match target_spec {
        TargetSpec::Rect { width_m, height_m } => TargetGeometryV1::Rect { width_m, height_m },
        TargetSpec::Circle { diameter_m } => TargetGeometryV1::Circle {
            radius_m: diameter_m / 2.0,
        },
    };

    let report = tolerance_envelope(&resolved, &axes, range_m, geometry, &domains)
        .map_err(|e| e.to_string())?;

    if matches!(output, OutputFormat::Json) {
        println!("{}", serde_json::to_string_pretty(&report)?);
    } else {
        print!("{}", render_tolerance_table(&report));
    }
    Ok(())
}

/// Render an [`ErrorBudgetReportV1`] as a human-readable table: one block per range with the
/// impact spread, the ranked source list (variance share as a percentage; the finite-difference
/// scheme is named only when it is NOT the ordinary central one; the per-source hit-probability
/// gain only when the report carries one at all), and the row's own priority statement on its
/// own line -- then, once (the same list applies to every row), any declared source the kernel
/// could not evaluate at all, with its reason, so a source that could not be measured never
/// reads the same as a source that measured zero.
fn render_error_budget_table(report: &ErrorBudgetReportV1) -> String {
    use std::fmt::Write as _;
    let mut out = String::new();
    let _ = writeln!(out, "error-budget -- method: {}", report.method);

    for row in &report.rows {
        let _ = writeln!(out);
        let _ = writeln!(out, "range {:.3} m", row.range_m);
        let _ = writeln!(
            out,
            "  impact spread: sigma_drop {:.6} m   sigma_windage {:.6} m   covariance {:.6} m^2",
            row.sigma_drop_m, row.sigma_windage_m, row.covariance_m2
        );
        let _ = writeln!(
            out,
            "  95% ellipse: semi-major {:.6} m   semi-minor {:.6} m   area {:.6} m^2",
            row.ellipse_95.semi_major_m, row.ellipse_95.semi_minor_m, row.ellipse_95.area_m2
        );
        if let Some(p_hit) = row.p_hit {
            let _ = writeln!(out, "  p_hit: {:.1}%", p_hit * 100.0);
        }
        if !row.sources.is_empty() {
            let _ = writeln!(out, "  ranked sources (share of impact variance):");
            for (i, s) in row.sources.iter().enumerate() {
                let name = axis_kebab_name(s.axis);
                let scheme_note = if s.scheme == DifferenceScheme::Central {
                    String::new()
                } else {
                    format!("   [{:?}]", s.scheme)
                };
                let gain_note = match s.p_hit_gain_if_perfect {
                    Some(gain) => format!("   gain if perfected: p_hit +{:.3}%", gain * 100.0),
                    None => String::new(),
                };
                let _ = writeln!(
                    out,
                    "    {:>2}. {:<28} {:>6.1}%{scheme_note}{gain_note}",
                    i + 1,
                    name,
                    s.variance_share * 100.0
                );
            }
        }
        let _ = writeln!(out, "  priority: {}", row.priority_statement);
    }

    if !report.unavailable_sources.is_empty() {
        let _ = writeln!(out);
        let _ = writeln!(out, "unavailable sources (could not be evaluated at all):");
        for u in &report.unavailable_sources {
            let name = axis_kebab_name(u.axis);
            let code = format!("{:?}", u.code);
            let _ = writeln!(
                out,
                "  {name} (sigma {:.6}) [{code}] -- {}",
                u.sigma, u.reason
            );
        }
    }

    let _ = writeln!(out);
    let _ = writeln!(out, "assumptions:");
    for a in &report.assumptions {
        let _ = writeln!(out, "  - {a}");
    }
    out
}

/// `error-budget` dispatch (MBA-1347).
fn handle_error_budget(
    request_path: PathBuf,
    ranges_m: Vec<f64>,
    sigmas_raw: Vec<String>,
    target: Option<String>,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    match output {
        OutputFormat::Csv => {
            return Err("error-budget has no CSV form; use -o table or -o json".into())
        }
        OutputFormat::Pdf => {
            return Err("error-budget has no PDF form; use -o table or -o json".into())
        }
        OutputFormat::Table | OutputFormat::Json => {}
    }

    // Parsed and de-duplicated up front, before the request is even read -- the same ordering
    // `handle_tolerance` uses for --axis, and for the identical reason: a duplicate declaration
    // would double-count that axis's variance and corrupt its own leave-one-out counterfactual,
    // so it is rejected by name rather than silently accepted (and cheaper to reject before
    // paying for a solve).
    let mut sources: Vec<(InputAxis, f64)> = Vec::with_capacity(sigmas_raw.len());
    for raw in &sigmas_raw {
        let (axis, sigma) = parse_sigma_arg(raw)?;
        if sources.iter().any(|&(a, _)| a == axis) {
            return Err(format!(
                "--sigma for axis '{}' was given more than once",
                axis_kebab_name(axis)
            )
            .into());
        }
        sources.push((axis, sigma));
    }

    let resolved = load_resolved_request(&request_path)?;

    // Mirrors `handle_tolerance`'s ordering: the target spec is parsed after the request is
    // loaded (it does not depend on it, but this keeps both handlers' stage order identical).
    let geometry = target
        .map(|spec| {
            parse_target_spec(&spec, units).map(|target_spec| match target_spec {
                TargetSpec::Rect { width_m, height_m } => {
                    TargetGeometryV1::Rect { width_m, height_m }
                }
                TargetSpec::Circle { diameter_m } => TargetGeometryV1::Circle {
                    radius_m: diameter_m / 2.0,
                },
            })
        })
        .transpose()
        .map_err(|e| e.to_string())?;

    let report = error_budget_with_target(&resolved, &sources, &ranges_m, geometry)
        .map_err(|e| e.to_string())?;

    if matches!(output, OutputFormat::Json) {
        println!("{}", serde_json::to_string_pretty(&report)?);
    } else {
        print!("{}", render_error_budget_table(&report));
    }
    Ok(())
}

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

    /// A future 33rd `InputAxis` variant cannot silently become unparseable: `axis_kebab_name`
    /// is an exhaustive match (a compile error catches an unhandled variant), and this pins
    /// down that `parse_input_axis` -- built from that same function plus `InputAxis::ALL` --
    /// actually round-trips every one of them, not just the ones a hand-picked sample covers.
    #[test]
    fn axis_kebab_names_round_trip_every_member_of_all() {
        for &axis in InputAxis::ALL {
            let name = axis_kebab_name(axis);
            assert_eq!(
                parse_input_axis(name),
                Ok(axis),
                "'{name}' (from {axis:?}) did not parse back to the same axis"
            );
        }
    }

    /// Every accepted name is unique -- otherwise two different axes would silently share one
    /// CLI spelling and `parse_input_axis` would always return whichever comes first in `ALL`.
    #[test]
    fn every_axis_kebab_name_is_unique() {
        let mut names: Vec<&str> = InputAxis::ALL
            .iter()
            .copied()
            .map(axis_kebab_name)
            .collect();
        let before = names.len();
        names.sort_unstable();
        names.dedup();
        assert_eq!(names.len(), before, "two axes share a kebab-case name");
    }

    #[test]
    fn unknown_axis_lists_every_accepted_name() {
        let err = parse_input_axis("not-a-real-axis").unwrap_err();
        assert!(err.contains("unknown axis 'not-a-real-axis'"), "{err}");
        for &axis in InputAxis::ALL {
            assert!(
                err.contains(axis_kebab_name(axis)),
                "error is missing '{}': {err}",
                axis_kebab_name(axis)
            );
        }
    }

    #[test]
    fn domain_arg_parses_axis_and_bounds() {
        assert_eq!(
            parse_domain_arg("wind-speed=0:20"),
            Ok((InputAxis::WindSpeed, (0.0, 20.0)))
        );
        assert_eq!(
            parse_domain_arg("cant=-0.05:0.05"),
            Ok((InputAxis::Cant, (-0.05, 0.05)))
        );
    }

    #[test]
    fn domain_arg_rejects_malformed_tokens() {
        assert!(parse_domain_arg("wind-speed").is_err(), "missing '='");
        assert!(parse_domain_arg("wind-speed=0").is_err(), "missing ':'");
        assert!(
            parse_domain_arg("wind-speed=lo:20").is_err(),
            "non-numeric lower bound"
        );
        assert!(parse_domain_arg("nope=0:20").is_err(), "unknown axis");
    }

    #[test]
    fn sigma_arg_parses_axis_and_value() {
        assert_eq!(
            parse_sigma_arg("wind-speed=1.5"),
            Ok((InputAxis::WindSpeed, 1.5))
        );
        assert_eq!(
            parse_sigma_arg("muzzle-velocity-mps=5.0"),
            Ok((InputAxis::MuzzleVelocityMps, 5.0))
        );
        // A zero sigma is a legitimate declaration (the source is real but currently trusted
        // exactly) -- it must parse, not be rejected as if it were missing.
        assert_eq!(parse_sigma_arg("cant=0"), Ok((InputAxis::Cant, 0.0)));
    }

    #[test]
    fn sigma_arg_rejects_malformed_unknown_or_invalid_tokens() {
        assert!(parse_sigma_arg("wind-speed").is_err(), "missing '='");
        assert!(parse_sigma_arg("nope=1.5").is_err(), "unknown axis");
        assert!(
            parse_sigma_arg("wind-speed=abc").is_err(),
            "non-numeric value"
        );
        let negative = parse_sigma_arg("wind-speed=-1.0").unwrap_err();
        assert!(negative.contains("wind-speed"), "{negative}");
        let non_finite = parse_sigma_arg("wind-speed=NaN").unwrap_err();
        assert!(non_finite.contains("wind-speed"), "{non_finite}");
        let infinite = parse_sigma_arg("wind-speed=inf").unwrap_err();
        assert!(infinite.contains("wind-speed"), "{infinite}");
    }
}

#[cfg(test)]
mod decision_support_render_tests {
    use super::*;
    use ballistics_engine::error_budget::{
        Ellipse95V1, ErrorBudgetRowV1, SourceContributionV1, UnavailableReasonCodeV1,
        UnavailableSourceV1,
    };
    use ballistics_engine::tolerance::{ToleranceAxisV1, UnavailableAxisV1};

    /// Delta #3's "nominal outside target" situation cannot be driven through this CLI's own
    /// `--target` flag at all: `parse_target_spec` (`wind_scenarios.rs`) rejects a non-positive
    /// width/height/diameter at the STRING-parsing stage, before a `TargetGeometryV1` is even
    /// built, and `nominal_inside_target` can only be `false` for a target with no positive
    /// area (`tolerance.rs`'s own module doc, "The central hazard") -- so this CLI can never
    /// hand `tolerance_envelope` a degenerate target to reproduce it end-to-end (see the
    /// task-14 report). The renderer must still get it right, so this builds a
    /// `ToleranceReportV1` by hand -- covering all five situations in one table, with a
    /// distinct marker phrase expected EXACTLY once per situation -- and checks
    /// `render_tolerance_table` directly. A mutation that rendered two situations identically
    /// (e.g. collapsing "no measurable effect" into the generic "no bound" text) would change a
    /// count from 1 to 0 or 2, not just move text around.
    #[test]
    fn table_distinguishes_all_five_axis_situations() {
        let report = ToleranceReportV1 {
            schema_version: 1,
            method: "one_variable_deterministic_bisection".to_string(),
            assumptions: vec!["test assumption".to_string()],
            range_m: 600.0,
            unavailable_axes: vec![UnavailableAxisV1 {
                axis: InputAxis::MagnusEnabled,
                code: UnavailableReasonCodeV1::CategoricalAxis,
                reason: "this axis is categorical and cannot be assigned a domain".to_string(),
            }],
            axes: vec![
                // 1. A real bound in both directions.
                ToleranceAxisV1 {
                    axis: InputAxis::WindSpeed,
                    nominal: 3.0,
                    nominal_inside_target: true,
                    near_bound: Some(1.2),
                    far_bound: Some(5.4),
                    near_limiting_boundary: Some(LimitingBoundaryV1::Left),
                    far_limiting_boundary: Some(LimitingBoundaryV1::Right),
                    unbounded_in_domain: false,
                    near_has_no_effect: false,
                    far_has_no_effect: false,
                    margin_linear_m: 0.15,
                },
                // 2. No bound within the domain, but the axis does move the impact.
                ToleranceAxisV1 {
                    axis: InputAxis::WindVertical,
                    nominal: 0.0,
                    nominal_inside_target: true,
                    near_bound: None,
                    far_bound: None,
                    near_limiting_boundary: None,
                    far_limiting_boundary: None,
                    unbounded_in_domain: true,
                    near_has_no_effect: false,
                    far_has_no_effect: false,
                    margin_linear_m: 0.15,
                },
                // 3. No measurable effect at all -- same `None`/`None` shape as #2, must render
                // differently.
                ToleranceAxisV1 {
                    axis: InputAxis::TargetDistance,
                    nominal: 900.0,
                    nominal_inside_target: true,
                    near_bound: None,
                    far_bound: None,
                    near_limiting_boundary: None,
                    far_limiting_boundary: None,
                    unbounded_in_domain: true,
                    near_has_no_effect: true,
                    far_has_no_effect: true,
                    margin_linear_m: 0.15,
                },
                // 4. Nominal outside the target -- structurally unreachable via the CLI (see
                // this test's own doc comment), but the renderer must still handle it.
                ToleranceAxisV1 {
                    axis: InputAxis::Cant,
                    nominal: 0.01,
                    nominal_inside_target: false,
                    near_bound: None,
                    far_bound: None,
                    near_limiting_boundary: None,
                    far_limiting_boundary: None,
                    unbounded_in_domain: false,
                    near_has_no_effect: false,
                    far_has_no_effect: false,
                    margin_linear_m: 0.0,
                },
            ],
        };

        let table = render_tolerance_table(&report);

        assert_eq!(table.matches("crosses the Left edge").count(), 1, "{table}");
        assert_eq!(
            table.matches("crosses the Right edge").count(),
            1,
            "{table}"
        );
        // Each of these fires once per DIRECTION (near and far), both directions being
        // identical in this synthetic fixture -- so 2, not 1, per axis; the point of the count
        // is that it is the SAME 2 either way, never mixed between the two axes below.
        assert_eq!(
            table
                .matches("no bound within the configured domain")
                .count(),
            2,
            "exactly one axis (wind-vertical), both directions, is merely unbounded: {table}"
        );
        assert_eq!(
            table.matches("no measurable effect on the impact").count(),
            2,
            "exactly one axis (target-distance), both directions, has no effect -- must not \
             share text with the merely-unbounded axis: {table}"
        );
        assert_eq!(
            table.matches("nominal OUTSIDE target").count(),
            1,
            "exactly one axis (cant) has its nominal outside the target: {table}"
        );
        assert_eq!(
            table.matches("could not be searched at all").count(),
            1,
            "exactly one axis (magnus-enabled) is structurally unavailable: {table}"
        );
        // Review I1: the "unbounded in domain" summary is a RECAP of a genuine effect, not a
        // blanket consequence of `unbounded_in_domain` alone -- target-distance is ALSO
        // `unbounded_in_domain: true` (both bounds `None`), but both directions are
        // `*_has_no_effect: true`, so it must NOT get the summary line (that would read as
        // reassurance about a change that provably does nothing). Exactly one summary line is
        // expected: wind-vertical's.
        assert_eq!(
            table.matches("unbounded in domain:").count(),
            1,
            "only wind-vertical (unbounded WITH effect) may print the summary line -- \
             target-distance (unbounded with NO effect) must not: {table}"
        );

        // Each marker attaches to the RIGHT axis, not just somewhere in the output.
        assert!(table.contains("axis wind-speed"), "{table}");
        assert!(table.contains("axis wind-vertical"), "{table}");
        assert!(table.contains("axis target-distance"), "{table}");
        assert!(table.contains("axis cant"), "{table}");
        assert!(table.contains("magnus-enabled ["), "{table}");
    }

    /// Zero-cost (no solve -- the report is built by hand) pin of `render_error_budget_table`'s
    /// MUST-render properties from the task-15 brief's corrections: the ranked list shows
    /// variance share as a percentage and names a scheme only when it is NOT central; the
    /// p_hit/per-source gain columns appear because this report carries a target; and an
    /// unavailable source is named with its reason while staying out of the ranked list.
    #[test]
    fn error_budget_table_renders_ranked_sources_gain_and_unavailable_sources() {
        let report = ErrorBudgetReportV1 {
            schema_version: 1,
            method: "central_difference_first_order_propagation_gl20_panelled_pm6sigma".to_string(),
            assumptions: vec!["Declared sources are treated as independent.".to_string()],
            unavailable_sources: vec![UnavailableSourceV1 {
                axis: InputAxis::Altitude,
                sigma: 50.0,
                code: UnavailableReasonCodeV1::AxisUnsupportedForRequest,
                reason: "the original request declared a QNH pressure_reference".to_string(),
            }],
            rows: vec![ErrorBudgetRowV1 {
                range_m: 600.0,
                sigma_drop_m: 0.2,
                sigma_windage_m: 0.3,
                covariance_m2: 0.01,
                ellipse_95: Ellipse95V1 {
                    semi_major_m: 0.5,
                    semi_minor_m: 0.1,
                    rotation_rad: 0.0,
                    area_m2: 0.157,
                },
                p_hit: Some(0.873),
                sources: vec![
                    SourceContributionV1 {
                        axis: InputAxis::WindSpeed,
                        sigma: 1.5,
                        d_drop_d_x: 0.0,
                        d_windage_d_x: 0.2,
                        scheme: DifferenceScheme::ForwardOneSided,
                        variance_share: 0.623,
                        ellipse_area_reduction_m2: 0.157,
                        p_hit_gain_if_perfect: Some(0.4416),
                    },
                    SourceContributionV1 {
                        axis: InputAxis::MuzzleVelocityMps,
                        sigma: 5.0,
                        d_drop_d_x: 0.001,
                        d_windage_d_x: 0.0,
                        scheme: DifferenceScheme::Central,
                        variance_share: 0.377,
                        ellipse_area_reduction_m2: 0.157,
                        p_hit_gain_if_perfect: Some(0.00008),
                    },
                ],
                priority_statement: "WindSpeed dominates at 600 m (62.3% of impact variance)."
                    .to_string(),
            }],
        };

        let table = render_error_budget_table(&report);

        // The ranked list: both sources present, share rendered as a percentage. This test does
        // not re-sort (that is `error_budget_with_target`'s own job, covered by its library test
        // suite) -- the renderer must not reorder or drop either one.
        assert!(table.contains("wind-speed"), "{table}");
        assert!(table.contains("62.3%"), "{table}");
        assert!(table.contains("muzzle-velocity-mps"), "{table}");
        assert!(table.contains("37.7%"), "{table}");

        // The scheme is named ONLY for the non-central source.
        assert_eq!(table.matches("ForwardOneSided").count(), 1, "{table}");
        assert!(!table.contains("[Central]"), "{table}");

        // p_hit and the per-source gain-if-perfected column are both present because this
        // report carries a target -- including wind-speed's large gain and
        // muzzle-velocity-mps's tiny one, which a coarser percentage format would round to the
        // same "0.0%" and erase the very distinction this column exists to show (see
        // `SourceContributionV1::p_hit_gain_if_perfect`'s own doc comment).
        assert!(table.contains("p_hit: 87.3%"), "{table}");
        assert_eq!(table.matches("gain if perfected").count(), 2, "{table}");
        assert!(
            table.contains("44.160%"),
            "wind-speed's own large gain: {table}"
        );
        assert!(
            table.contains("0.008%"),
            "muzzle-velocity-mps's own tiny gain: {table}"
        );

        // The unavailable source is named, with its reason, and never inside the ranked list.
        assert!(table.contains("unavailable sources"), "{table}");
        assert!(table.contains("altitude"), "{table}");
        assert!(table.contains("QNH"), "{table}");
        let ranked_section = table.split("unavailable sources").next().unwrap();
        assert!(
            !ranked_section.contains("altitude"),
            "an unavailable source must not appear in the ranked list: {table}"
        );

        // The priority statement is rendered on its own line.
        assert!(table.contains("priority: WindSpeed dominates"), "{table}");
    }

    /// A report with no target at all (`error_budget`'s own `None` wrapper) must render NEITHER
    /// `p_hit` NOR any per-source gain -- never a fabricated number standing in for the real
    /// absence. Complements the JSON-shaped check already made by
    /// `error_budget_table_shows_p_hit_and_gain_only_with_a_target` in
    /// `tests/decision_support_cli.rs`.
    #[test]
    fn error_budget_table_omits_p_hit_and_gain_without_a_target() {
        let report = ErrorBudgetReportV1 {
            schema_version: 1,
            method: "central_difference_first_order_propagation".to_string(),
            assumptions: vec!["Declared sources are treated as independent.".to_string()],
            unavailable_sources: vec![],
            rows: vec![ErrorBudgetRowV1 {
                range_m: 600.0,
                sigma_drop_m: 0.2,
                sigma_windage_m: 0.3,
                covariance_m2: 0.01,
                ellipse_95: Ellipse95V1 {
                    semi_major_m: 0.5,
                    semi_minor_m: 0.1,
                    rotation_rad: 0.0,
                    area_m2: 0.157,
                },
                p_hit: None,
                sources: vec![SourceContributionV1 {
                    axis: InputAxis::WindSpeed,
                    sigma: 1.5,
                    d_drop_d_x: 0.0,
                    d_windage_d_x: 0.2,
                    scheme: DifferenceScheme::Central,
                    variance_share: 1.0,
                    ellipse_area_reduction_m2: 0.0,
                    p_hit_gain_if_perfect: None,
                }],
                priority_statement: "WindSpeed dominates at 600 m (100.0% of impact variance)."
                    .to_string(),
            }],
        };

        let table = render_error_budget_table(&report);
        assert!(!table.contains("p_hit:"), "{table}");
        assert!(!table.contains("gain if perfected"), "{table}");
        assert!(table.contains("wind-speed"), "{table}");
        assert!(table.contains("100.0%"), "{table}");
    }
}

// ============================================================================================
// MBA-1348 Plan B Task 6: `dial-plan` -- the `plan_corrections` CLI surface
// ============================================================================================

/// `Axis::Elevation`/`Axis::Windage` as the lowercase word this table uses everywhere else
/// (matches `axis_kebab_name`'s lowercase convention for the unrelated `InputAxis`).
fn dial_plan_axis_label(axis: Axis) -> &'static str {
    match axis {
        Axis::Elevation => "elevation",
        Axis::Windage => "windage",
    }
}

/// `AxisInstruction::direction` as the shouted word a shooter reads off a dial under time
/// pressure -- deliberately uppercase, unlike `dial_plan_axis_label`, so it reads as an
/// instruction rather than a label.
fn dial_plan_direction_word(direction: Direction) -> &'static str {
    match direction {
        Direction::Up => "UP",
        Direction::Down => "DOWN",
        Direction::Left => "LEFT",
        Direction::Right => "RIGHT",
    }
}

/// `Strategy`'s table label -- the same snake_case spelling `#[serde(rename_all =
/// "snake_case")]` gives it on the wire, so the table and `-o json` never disagree about a
/// strategy's name.
fn dial_plan_strategy_label(strategy: Strategy) -> &'static str {
    match strategy {
        Strategy::DialAll => "dial_all",
        Strategy::HoldAll => "hold_all",
        Strategy::Hybrid => "hybrid",
    }
}

/// `LimitKind`'s table label -- the same snake_case spelling `#[serde(rename_all =
/// "snake_case")]` gives it on the wire, so the table and `-o json` never disagree about a
/// limit kind's name (same reasoning, and same fix, as `dial_plan_strategy_label`).
fn dial_plan_limit_kind_label(kind: LimitKind) -> &'static str {
    match kind {
        LimitKind::TravelExceeded => "travel_exceeded",
        LimitKind::HoldBoundExceeded => "hold_bound_exceeded",
        LimitKind::NoTravelData => "no_travel_data",
        LimitKind::NoHoldBoundData => "no_hold_bound_data",
    }
}

/// Render a [`DialPlanReportV1`] as a human-readable table (MBA-1348 Task 6): one block per
/// ranked plan (best first -- see `plan_corrections`' own ranking doc) with a strategy header
/// naming feasibility, one instruction line per axis (direction, delta clicks, a revolution
/// annotation when the turret declares `clicks_per_revolution`, and the TRUE angular hold), a
/// residual line (both axes' angular residual plus the RSS linear miss at range), and any
/// limit violations this plan hit. A violation is disclosed even on a FEASIBLE plan -- a
/// `Hybrid` plan's own travel clamp is recorded but does not gate ITS feasibility, see
/// `plan_corrections`' "Honesty" doc section -- and an infeasible plan is rendered exactly
/// like a feasible one, never hidden: this table (and the command's own exit code) treats a
/// "this doesn't fit" conclusion as a normal, successful result.
fn render_dial_plan_table(report: &DialPlanReportV1) -> String {
    use std::fmt::Write as _;
    let mut out = String::new();
    let _ = writeln!(out, "dial-plan -- method: {}", report.method);
    let _ = writeln!(out, "range {:.3} m", report.range_m);

    for (i, plan) in report.plans.iter().enumerate() {
        let _ = writeln!(out);
        let feasible_word = if plan.feasible {
            "FEASIBLE"
        } else {
            "INFEASIBLE"
        };
        let _ = writeln!(
            out,
            "#{} strategy: {} [{feasible_word}]",
            i + 1,
            dial_plan_strategy_label(plan.strategy)
        );

        for instr in &plan.instructions {
            let axis_label = dial_plan_axis_label(instr.axis);
            let dir_word = dial_plan_direction_word(instr.direction);
            let revolution = match instr.end_revolution {
                Some((revs, clicks_in_rev)) => {
                    format!(" (end at rev {revs} + {clicks_in_rev} clicks)")
                }
                None => String::new(),
            };
            let _ = writeln!(
                out,
                "  {axis_label}: dial {dir_word} {} clicks{revolution}; hold {:.3} mil",
                instr.delta_clicks.abs(),
                instr.hold_mil
            );
        }

        let _ = writeln!(
            out,
            "  residual: elevation {:.3} mil, windage {:.3} mil -> {:.3} m at {:.3} m",
            plan.instructions[0].residual_mil,
            plan.instructions[1].residual_mil,
            plan.residual_linear_at_range_m,
            report.range_m
        );

        for v in &plan.limits_hit {
            let axis_label = dial_plan_axis_label(v.axis);
            let kind = dial_plan_limit_kind_label(v.kind);
            let available = match v.available_mil {
                Some(a) => format!("available {a:.3} mil"),
                None => "no data declared for this axis".to_string(),
            };
            let _ = writeln!(
                out,
                "  limit: {axis_label} {kind} -- needed {:.3} mil, {available}",
                v.needed_mil
            );
        }
    }

    let _ = writeln!(out);
    let _ = writeln!(out, "assumptions:");
    for a in &report.assumptions {
        let _ = writeln!(out, "  - {a}");
    }
    out
}

/// `dial-plan` dispatch (MBA-1348 Task 6): resolves the optic from either `--profile` or the
/// inline turret/hold flags (mutually exclusive), resolves the TRUE angular correction from
/// `--elevation`/`--windage` (at least one required), and hands both to `plan_corrections`.
/// Unlike every calculator subcommand in this file, this runs no solve at all -- the
/// correction is a direct input -- so this handler is pure, instant arithmetic.
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable dial-plan CLI command shape"
)]
fn handle_dial_plan(
    elevation: Option<f64>,
    windage: Option<f64>,
    range: f64,
    profile: Option<String>,
    elevation_click: Option<String>,
    windage_click: Option<String>,
    clicks_per_rev: Option<u32>,
    zero_stop: Option<bool>,
    travel_up: Option<f64>,
    travel_down: Option<f64>,
    windage_travel_left: Option<f64>,
    windage_travel_right: Option<f64>,
    hold_up: Option<f64>,
    hold_down: Option<f64>,
    hold_left: Option<f64>,
    hold_right: Option<f64>,
    turret_elev: Option<f64>,
    turret_wind: Option<f64>,
    prefer_hold: bool,
    max_hold: Option<f64>,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    match output {
        OutputFormat::Csv => {
            return Err("dial-plan has no CSV form; use -o table or -o json".into())
        }
        OutputFormat::Pdf => {
            return Err("dial-plan has no PDF form; use -o table or -o json".into())
        }
        OutputFormat::Table | OutputFormat::Json => {}
    }

    if elevation.is_none() && windage.is_none() {
        return Err("at least one of --elevation or --windage is required".into());
    }

    let inline_flag_given = elevation_click.is_some()
        || windage_click.is_some()
        || clicks_per_rev.is_some()
        || zero_stop.is_some()
        || travel_up.is_some()
        || travel_down.is_some()
        || windage_travel_left.is_some()
        || windage_travel_right.is_some()
        || hold_up.is_some()
        || hold_down.is_some()
        || hold_left.is_some()
        || hold_right.is_some()
        || turret_elev.is_some()
        || turret_wind.is_some();

    if profile.is_some() && inline_flag_given {
        return Err(
            "--profile cannot be combined with inline optic flags (--elevation-click and the \
             rest of the turret/hold flags) -- choose one source for the optic"
                .into(),
        );
    }

    let (optic, elevation_cf, windage_cf) = match profile {
        Some(name) => {
            let data = load_profile(&name)?;
            let optic = data
                .optic_profile()
                .map_err(|e| format!("profile '{name}': {e}"))?
                .ok_or_else(|| {
                    format!(
                        "profile '{name}' has no optic (turret/click) data saved -- save one \
                         with `profile save --elevation-click <SIZE><UNIT>`"
                    )
                })?;
            (
                optic,
                data.elevation_cf.unwrap_or(1.0),
                data.windage_cf.unwrap_or(1.0),
            )
        }
        None => {
            let Some(elev_str) = elevation_click.as_deref() else {
                return Err(
                    "either --profile <NAME> or --elevation-click <SIZE><UNIT> is required to \
                     define the optic"
                        .into(),
                );
            };
            let elevation_click_v = parse_click_value(elev_str)?;
            let windage_click_v = match windage_click.as_deref() {
                Some(s) => parse_click_value(s)?,
                None => elevation_click_v,
            };
            let elevation_travel =
                require_angular_pair("--travel-up", travel_up, "--travel-down", travel_down)?.map(
                    |(up, down)| TravelLimits {
                        up_mil: up,
                        down_mil: down,
                    },
                );
            let windage_travel = require_angular_pair(
                "--windage-travel-left",
                windage_travel_left,
                "--windage-travel-right",
                windage_travel_right,
            )?
            .map(|(left, right)| TravelLimits {
                down_mil: left,
                up_mil: right,
            });
            let turret_state =
                require_angular_pair("--turret-elev", turret_elev, "--turret-wind", turret_wind)?
                    .map(|(elevation_mil, windage_mil)| TurretState {
                        elevation_mil,
                        windage_mil,
                    });
            let reticle_hold_bounds =
                require_hold_bounds(hold_up, hold_down, hold_left, hold_right)?;
            let optic = OpticProfile {
                elevation_click: elevation_click_v,
                windage_click: windage_click_v,
                clicks_per_revolution: clicks_per_rev,
                zero_stop: zero_stop.unwrap_or(false),
                elevation_travel,
                windage_travel,
                turret_state,
                reticle_hold_bounds,
            };
            (optic, 1.0, 1.0)
        }
    };

    let range_m = UnitConverter::distance_to_metric(range, units);
    let correction = AngularCorrection {
        elevation_mil: elevation.unwrap_or(0.0),
        windage_mil: windage.unwrap_or(0.0),
    };
    let prefs = Preferences {
        prefer_hold,
        max_hold_mil: max_hold,
    };

    let report = plan_corrections(
        correction,
        &optic,
        range_m,
        elevation_cf,
        windage_cf,
        &prefs,
    )
    .map_err(|e| e.to_string())?;

    if matches!(output, OutputFormat::Json) {
        println!("{}", serde_json::to_string_pretty(&report)?);
    } else {
        print!("{}", render_dial_plan_table(&report));
    }
    Ok(())
}

// ============================================================================
// Adaptive Range Card (MBA-1351, 0.33.0 decision-support Plan B Task 12)
// ============================================================================

/// Default reconstruction-error budget when `--elevation-budget`/`--windage-budget` is
/// omitted: half the profile's click on that axis -- the honest floor `adaptive_card`'s own
/// assumptions already document (a tighter budget is reported `budget_met: false`, never
/// silently relaxed) -- or 0.1 TRUE mil when no optic click is known. Returned in TRUE mil;
/// the caller scales into the chosen `--adjustment` unit exactly like an explicit
/// `--elevation-budget`/`--windage-budget` value is (parsed by the same `parse_angular_mil`
/// `value_parser`, then the unit factor), so an explicit budget and this default land in the
/// same space.
fn adaptive_card_default_budget_mil(click: Option<&ClickValue>) -> f64 {
    match click {
        Some(c) => click_size_mil(c) / 2.0,
        None => 0.1,
    }
}

/// Converts one adaptive-card row from the engine's native space (metres for `range`,
/// METRIC metres for `drop_linear`/`wind_linear`, metric m/s and J for `velocity`/`energy`)
/// into the run's display units. `drop_adj`/`wind_adj` are already expressed in the chosen
/// `--adjustment` printed unit by `adaptive_card` itself and must NOT be touched here --
/// only the fields `CardRow`'s own "display-ready, do not re-convert" convention has not
/// yet applied to need this. Needed because `range_table_row_line` (Task 9) and the PDF
/// dope card (Task 10) both expect display-ready values per that same convention, while
/// `adaptive_card` works entirely on `HoldCurve`'s native metric grid (Task 11).
fn adaptive_card_display_row(r: &CardRow, units: UnitSystem) -> CardRow {
    let linear_from_meters = |meters: f64| match units {
        UnitSystem::Imperial => meters / 0.0254,
        UnitSystem::Metric => meters * 1000.0,
    };
    CardRow {
        range: UnitConverter::distance_from_metric(r.range, units),
        drop_linear: r.drop_linear.map(linear_from_meters),
        drop_adj: r.drop_adj,
        come_up: r.come_up,
        wind_linear: r.wind_linear.map(linear_from_meters),
        wind_adj: r.wind_adj,
        velocity: r
            .velocity
            .map(|v| UnitConverter::velocity_from_metric(v, units)),
        energy: r
            .energy
            .map(|v| UnitConverter::energy_from_metric(v, units)),
        time: r.time,
        lead_adj: r.lead_adj,
        wind_columns: r.wind_columns.clone(),
    }
}

/// Formats an adaptive-card row's `range` for table/CSV: a bare integer when within floating-
/// point noise of one, one decimal place otherwise (review fix I-1, `4e69435`'s review).
///
/// `HoldCurve::SAMPLE_INTERVAL_M` is 0.9144 m, so under `--units metric` almost every
/// algorithm-chosen interior row is genuinely fractional (and a user's own `--anchor` can be
/// fractional in either unit system) -- `{:.0}` silently rounds it, which made the table and
/// CSV disagree with `-o json`'s exact value and with `-o pdf` (whose `format_range`,
/// `src/pdf_dope_card.rs`, already applies this identical rule). This is a **separate copy**
/// of that same rule, not a shared call: `pdf_dope_card::format_range` is private to a module
/// gated behind the `pdf` feature, while adaptive-card's table/CSV must render with `pdf`
/// disabled too. Keep the two in sync by hand if the rounding rule ever changes.
///
/// Deliberately NOT applied to `range_table_row_line` (Task 9): that function is golden-
/// pinned by `tests/card_golden_cli.rs` and `range-table`'s own display units are always
/// whole, so it is left untouched; adaptive-card gets its own row formatter,
/// `adaptive_card_row_line`, below.
fn format_adaptive_card_range(range: f64) -> String {
    let rounded = range.round();
    if (range - rounded).abs() < 0.05 {
        format!("{:.0}", rounded)
    } else {
        format!("{:.1}", range)
    }
}

/// Adaptive-card's own table row formatter (review fix I-1): byte-identical column layout to
/// `range_table_row_line` (same widths, same separators, same non-Range formats), but the
/// Range cell goes through [`format_adaptive_card_range`] instead of `{:>6.0}` -- formatted to
/// a string first, then right-padded to the same 6-wide field `range_table_row_line` uses, so
/// an integer range (the common case: both domain ends under imperial units, or any range that
/// happens to land on a whole display unit) renders byte-for-byte like before. A fractional
/// range -- ordinary under `--units metric`, or any explicit `--anchor` that doesn't land on a
/// whole unit -- now prints its one decimal place instead of a silently rounded integer, which
/// is what makes it agree with `-o json`/`-o pdf` at last.
///
/// `range_table_row_line` itself is UNTOUCHED (see its own doc comment): golden-pinning it
/// means the hard constraint "the 12 goldens must stay byte-identical" is satisfied by
/// construction, not by proof -- `range-table` never calls this function at all.
fn adaptive_card_row_line(r: &CardRow) -> String {
    format!(
        "│{:>6} │{:>8.1} │{:>8.3} │{:>8.1} │{:>8.2} │{:>8.0} │{:>8.0} │{:>6.2} │",
        format_adaptive_card_range(r.range),
        r.drop_linear.unwrap(),
        r.drop_adj.unwrap(),
        r.wind_linear.unwrap(),
        r.wind_adj.unwrap(),
        r.velocity.unwrap(),
        r.energy.unwrap(),
        r.time.unwrap()
    )
}

/// Maps a [`CardError`] into a CLI-facing message, naming the flag the user typed wherever
/// one exists (`--start`/`--end`/`--anchor`/`--elevation-budget`/`--windage-budget`/
/// `--max-rows`) -- the same "name the flag, not the struct field" convention
/// `require_angular_pair` established (MBA-1348 review fix). `InvalidTrackingCf` has no
/// adaptive-card flag of its own: this command sources the tracking CF only from
/// `--profile`, and `load_profile` already validates `elevation_cf`/`windage_cf` into the
/// identical `(0.5, 1.5)` band on load (MBA-1358), so in practice this arm cannot be
/// reached through this CLI surface today. It is still mapped -- `CardError` is not
/// `#[non_exhaustive]`, and a future direct `--elevation-cf`/`--windage-cf` override (or a
/// hand-edited profile loaded by a path that skips validation) must get a message, not a
/// panic -- so `CardError`'s own `Display` text is used verbatim for it.
fn adaptive_card_error_message(err: CardError, units: UnitSystem) -> String {
    let dist_unit = match units {
        UnitSystem::Imperial => "yd",
        UnitSystem::Metric => "m",
    };
    let disp = |m: f64| UnitConverter::distance_from_metric(m, units);
    match err {
        CardError::EmptyOrInvertedDomain { start_m, end_m } => format!(
            "--start {:.3} {dist_unit} and --end {:.3} {dist_unit} must describe a forward \
             interval with a positive start",
            disp(start_m),
            disp(end_m)
        ),
        CardError::AnchorOutsideDomain {
            anchor_m,
            start_m,
            end_m,
        } => format!(
            "--anchor {:.3} {dist_unit} lies outside --start {:.3} {dist_unit} / --end \
             {:.3} {dist_unit}",
            disp(anchor_m),
            disp(start_m),
            disp(end_m)
        ),
        CardError::NonPositiveBudget { axis, value } => format!(
            "--{axis}-budget must be positive and finite (resolved to {value} in the chosen \
             --adjustment unit)"
        ),
        CardError::ZeroMaxRows => "--max-rows must be at least 1".to_string(),
        CardError::DomainOutsideCurve {
            requested_m,
            curve_max_m,
        } => format!(
            "--end {:.3} {dist_unit} is past the solved trajectory's last reachable point at \
             {:.3} {dist_unit}",
            disp(requested_m),
            disp(curve_max_m)
        ),
        CardError::InvalidTrackingCf { .. } => err.to_string(),
    }
}

/// The footer block every `adaptive-card` output carries: budget met / rows (of the max) /
/// worst measured error and where / the verification grid it was measured on. Printed
/// directly under the table on stdout; written to stderr for csv/pdf so their primary
/// output channel (the CSV data rows; the PDF file) stays exactly that and nothing else.
/// `-o json` carries the identical facts as struct fields instead and gets no footer at all
/// -- see [`AdaptiveCardReportV1`] and the `-o json` arm below.
fn adaptive_card_footer(
    report: &AdaptiveCardReportV1,
    units: UnitSystem,
    unit_label: &str,
    max_rows: usize,
) -> String {
    use std::fmt::Write as _;
    let dist_unit = match units {
        UnitSystem::Imperial => "yd",
        UnitSystem::Metric => "m",
    };
    let mut out = String::new();
    let _ = writeln!(out);
    let _ = writeln!(
        out,
        "budget met: {}",
        if report.budget_met { "yes" } else { "no" }
    );
    let capped = if report.rows_capped {
        " (row cap reached)"
    } else {
        ""
    };
    let _ = writeln!(out, "rows: {} of {max_rows} max{capped}", report.rows.len());
    let _ = writeln!(
        out,
        "worst error: elevation {:.4} {unit_label}, windage {:.4} {unit_label} @ {:.3} {dist_unit}",
        report.worst_elevation_error,
        report.worst_windage_error,
        UnitConverter::distance_from_metric(report.worst_error_range_m, units)
    );
    let _ = writeln!(
        out,
        "verification grid: {:.4} {dist_unit} step",
        UnitConverter::distance_from_metric(report.verification_grid_step_m, units)
    );
    out
}

/// `adaptive-card` dispatch (MBA-1351 Task 12): resolves the load and (optionally) the
/// optic from `--profile` via the same `InverseSolverLoadArgs`/`ProfileData::optic_profile`
/// pattern `dial-plan` uses, solves one `HoldCurve` out past `--end` (mirroring
/// `mark-to-range`'s own 2% search-headroom convention), then hands the resolved budgets
/// and optional click graduations to [`adaptive_card`]. Unlike `dial-plan`, a profile with
/// no optic data is not an error here -- quantization is optional for a range card (the
/// exact unrounded angle is a perfectly good answer), where `dial-plan`'s entire purpose
/// requires one.
#[allow(
    clippy::too_many_arguments,
    reason = "flat arguments mirror the stable adaptive-card CLI command shape"
)]
#[cfg_attr(
    not(feature = "pdf"),
    allow(
        unused_variables,
        reason = "output_file is read only by the pdf-gated OutputFormat::Pdf arm below"
    )
)]
fn handle_adaptive_card(
    load_args: InverseSolverLoadArgs,
    zero_distance: Option<f64>,
    start: f64,
    end: f64,
    anchors: Vec<f64>,
    elevation_budget: Option<f64>,
    windage_budget: Option<f64>,
    max_rows: usize,
    adjustment: AdaptiveCardAdjustmentArg,
    output_file: Option<PathBuf>,
    units: UnitSystem,
    output: OutputFormat,
) -> Result<(), Box<dyn Error>> {
    let (load, profile_data) = load_args.resolve(zero_distance, units)?;

    // Optic is OPTIONAL here (unlike dial-plan): no --profile, or a --profile with no
    // turret/click data saved, both just mean "print exact, unquantized angles."
    let optic = match &profile_data {
        Some(p) => p
            .optic_profile()
            .map_err(|e| format!("profile '{}': {e}", p.name))?,
        None => None,
    };
    // elevation_cf/windage_cf live on ProfileData independently of the twelve turret/optic
    // fields, so they resolve the same way regardless of whether `optic` above is Some or
    // None. load_profile already validates a stored value into the (0.5, 1.5) band
    // (MBA-1358), so this is never an out-of-band value in practice -- adaptive_card's own
    // CardError::InvalidTrackingCf check runs anyway, since this is also a public library
    // entry point other callers reach without the CLI's validation.
    let elevation_cf = profile_data
        .as_ref()
        .and_then(|p| p.elevation_cf)
        .unwrap_or(1.0);
    let windage_cf = profile_data
        .as_ref()
        .and_then(|p| p.windage_cf)
        .unwrap_or(1.0);

    let unit = adjustment.to_engine();
    let unit_label = adjustment.label();
    let unit_factor = unit.from_mil_factor();

    // Budgets parse via the same suffix-mandatory parse_angular_mil rule every other
    // angular CLI flag in this file uses -- as a clap value_parser on the field itself (see
    // the AdaptiveCard variant above), exactly like dial-plan's angular flags, so a missing
    // suffix is a clap usage error naming this flag ("invalid value '...' for
    // '--elevation-budget <VALUEUNIT>'") rather than an unnamed one. What's left here is
    // only the TRUE-mil -> --adjustment-unit conversion, applied identically to an explicit
    // value and the profile-derived default so the two paths cannot silently diverge.
    let elevation_budget_printed = match elevation_budget {
        Some(v) => v * unit_factor,
        None => {
            adaptive_card_default_budget_mil(optic.as_ref().map(|o| &o.elevation_click))
                * unit_factor
        }
    };
    let windage_budget_printed = match windage_budget {
        Some(v) => v * unit_factor,
        None => {
            adaptive_card_default_budget_mil(optic.as_ref().map(|o| &o.windage_click)) * unit_factor
        }
    };

    let start_m = UnitConverter::distance_to_metric(start, units);
    let end_m = UnitConverter::distance_to_metric(end, units);
    let anchors_m: Vec<f64> = anchors
        .iter()
        .map(|&a| UnitConverter::distance_to_metric(a, units))
        .collect();

    // MBA-1478: the SHARED card headroom, `card_sample_max_range_m`, the same one the other
    // four surfaces sample with. It replaces a private `end_m * 1.02`, which left this
    // command with the identical fractional-`--end` hole MBA-1476 closed everywhere else and
    // then some: the hold curve's grid is anchored at zero with a fixed
    // `HoldCurve::SAMPLE_INTERVAL_M` spacing, so a 2% span leaves less than one whole cell of
    // headroom for every `--end` under ~50 yd, the last grid point lands short of the domain
    // end, and an ordinary request was refused outright as "past the solved trajectory's last
    // reachable point" through no fault of the load.
    let max_solve_range_m = if end_m.is_finite() && end_m > 0.0 {
        card_sample_max_range_m(end_m)
    } else {
        end_m
    };
    // Named explicitly rather than let `?` surface HoldCurve::solve's own message bare: that
    // message says nothing about which CLI flag supplied the bad value (e.g. `--end inf`),
    // the same "name the flag" gap N-3 fixed for the budget flags.
    let curve = HoldCurve::solve(&load, max_solve_range_m).map_err(|e| -> Box<dyn Error> {
        let dist_unit = match units {
            UnitSystem::Imperial => "yd",
            UnitSystem::Metric => "m",
        };
        format!("--end {end:.3} {dist_unit}: {e}").into()
    })?;

    // MBA-1478: truncate like every other card surface instead of refusing the whole card.
    //
    // `adaptive_card` still returns `DomainOutsideCurve` for a domain running past the
    // curve — it is a library entry point and a caller that hands it an unreachable domain
    // has asked for rows there is no ground truth for. What was wrong was the CLI passing
    // the request straight through: a `.22 LR --end 1200` exited 1 with no rows at all,
    // where `come-ups` on the same load prints its eighteen reachable ones and says what it
    // left out. The card now ends at the furthest range the curve supplies, and anchors past
    // that end go with the rows past it — the notice below is what says so.
    let reachable_end_m = curve.max_sampled_range_m();
    let truncation = if end_m.is_finite() && end_m > reachable_end_m {
        if start_m > reachable_end_m {
            // No row at all is reachable, so there is no card to truncate — the same
            // refusal, in the same words, the other four surfaces give that case.
            return Err(card_no_rows_error(start, curve.reach_m(), units));
        }
        Some(card_truncation(
            end,
            UnitConverter::distance_from_metric(reachable_end_m, units),
            curve.reach_m(),
            units,
        ))
    } else {
        None
    };
    // Only a TRUNCATED card drops anchors, and only the ones past its new end. On an
    // untruncated card an anchor outside the domain is still `AnchorOutsideDomain`, because
    // there the flight can reach it and the request is simply self-contradictory.
    let (end_m, anchors_m) = match truncation {
        Some(_) => (
            reachable_end_m,
            anchors_m
                .into_iter()
                .filter(|&a| a <= reachable_end_m)
                .collect(),
        ),
        None => (end_m, anchors_m),
    };

    let click = optic
        .as_ref()
        .map(|o| (&o.elevation_click, &o.windage_click));
    let req = AdaptiveRequest {
        domain_m: (start_m, end_m),
        anchors_m,
        budget: AdaptiveBudget {
            elevation: elevation_budget_printed,
            windage: windage_budget_printed,
        },
        max_rows,
        click,
        elevation_cf,
        windage_cf,
        // No --zero-set on this command's interface (MBA-1360 zero sets are out of scope
        // for Task 12's brief); a card is always relative to the plain, unbiased zero.
        bias_mil: 0.0,
    };

    let report =
        adaptive_card(&curve, &req, unit).map_err(|e| adaptive_card_error_message(e, units))?;

    let (dist_unit, drop_unit, vel_unit, energy_unit) = match units {
        UnitSystem::Imperial => ("yd", "in", "fps", "ft-lb"),
        UnitSystem::Metric => ("m", "mm", "m/s", "J"),
    };
    let display_rows: Vec<CardRow> = report
        .rows
        .iter()
        .map(|r| adaptive_card_display_row(r, units))
        .collect();

    match output {
        OutputFormat::Json => {
            // Verbatim: AdaptiveCardReportV1's own Serialize impl IS the wire format here,
            // unlike the four Task 9 surfaces' hand-built json! objects -- no footer, since
            // every fact the footer states is already a field on this struct.
            //
            // MBA-1478: except the truncation, which is not a fact about the card the engine
            // produced but about the card the CALLER asked for and did not get. It is spelled
            // `truncated`, with the identical block the other four surfaces emit, so one
            // reader handles all five.
            //
            // Flattened onto the report and serialized STRAIGHT TO TEXT rather than through
            // `serde_json::to_value`: a `Value`'s object is a sorted map, so routing this
            // report through one would silently re-alphabetize every key of an output that
            // has always been in the struct's own field order. The report's keys stay where
            // they were, `truncated` joins them at the end, and a card that ran to its
            // requested end serializes byte-identically to before.
            #[derive(serde::Serialize)]
            struct AdaptiveCardJson<'a> {
                #[serde(flatten)]
                report: &'a AdaptiveCardReportV1,
                #[serde(skip_serializing_if = "Option::is_none")]
                truncated: Option<serde_json::Value>,
            }
            println!(
                "{}",
                serde_json::to_string_pretty(&AdaptiveCardJson {
                    report: &report,
                    truncated: truncation.as_ref().map(|t| card_truncation_json(t, units)),
                })?
            );
        }
        OutputFormat::Csv => {
            let unit_lower = unit_label.to_lowercase();
            println!(
                "range_{dist_unit},drop_{drop_unit},drop_{unit_lower},wind_{drop_unit},wind_{unit_lower},velocity_{vel_unit},energy_{energy_unit},tof_s"
            );
            for r in &display_rows {
                println!(
                    "{},{:.1},{:.3},{:.1},{:.2},{:.0},{:.0},{:.2}",
                    format_adaptive_card_range(r.range),
                    r.drop_linear.unwrap(),
                    r.drop_adj.unwrap(),
                    r.wind_linear.unwrap(),
                    r.wind_adj.unwrap(),
                    r.velocity.unwrap(),
                    r.energy.unwrap(),
                    r.time.unwrap()
                );
            }
            eprint!(
                "{}",
                adaptive_card_footer(&report, units, unit_label, max_rows)
            );
        }
        OutputFormat::Table => {
            println!();
            println!(
                "Adaptive Range Card (zero: {:.0} {dist_unit}) -- method: {}",
                UnitConverter::distance_from_metric(load.zero_distance_m, units),
                report.method
            );
            println!(
                "┌───────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬───────┐"
            );
            println!(
                "│Range  │Drop     │Drop     │Wind     │Wind     │Vel      │Energy   │ToF    │"
            );
            println!(
                "│({:>2})   │({:>2})     │({:>3})    │({:>2})     │({:>3})    │({:>3})    │({:>4})   │(s)    │",
                dist_unit, drop_unit, unit_label, drop_unit, unit_label, vel_unit, energy_unit
            );
            println!(
                "├───────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼───────┤"
            );
            for r in &display_rows {
                println!("{}", adaptive_card_row_line(r));
            }
            println!(
                "└───────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴───────┘"
            );
            print!(
                "{}",
                adaptive_card_footer(&report, units, unit_label, max_rows)
            );
        }
        #[cfg(feature = "pdf")]
        OutputFormat::Pdf => {
            let output_path = output_file
                .as_ref()
                .ok_or("PDF output requires --output-file")?;
            let range_unit = match units {
                UnitSystem::Imperial => RangeUnit::Yards,
                UnitSystem::Metric => RangeUnit::Meters,
            };
            // The dope-card PDF header is always imperial, matching `trajectory -o pdf`'s
            // own PdfMetadata convention -- HoldCurveLoad is already metric-normalized
            // regardless of --units, so this converts unconditionally rather than
            // branching on the run's own unit system.
            let velocity_fps =
                UnitConverter::velocity_from_metric(load.velocity_mps, UnitSystem::Imperial);
            let temperature_f =
                UnitConverter::temperature_from_metric(load.temperature_c, UnitSystem::Imperial);
            let pressure_inhg =
                UnitConverter::pressure_from_metric(load.pressure_hpa, UnitSystem::Imperial);
            let altitude_ft =
                UnitConverter::altitude_from_metric(load.altitude_m, UnitSystem::Imperial);
            let wind_speed_mph =
                UnitConverter::wind_from_metric(load.wind_speed_mps, UnitSystem::Imperial);
            let weight_gr = UnitConverter::mass_from_metric(load.mass_kg, UnitSystem::Imperial);
            let da_ft = calculate_density_altitude(altitude_ft, pressure_inhg, temperature_f);

            let rifle_name = profile_data
                .as_ref()
                .map(|p| p.name.clone())
                .unwrap_or_else(|| "Adaptive Card".to_string());
            let bullet = profile_data
                .as_ref()
                .and_then(|p| p.bullet_name.clone())
                .unwrap_or_default();

            let pdf_config = DopeCardConfig {
                rifle_name,
                location: String::new(),
                density_altitude_ft: da_ft,
                pressure_inhg,
                pressure_hpa: load.pressure_hpa,
                temperature_f,
                altitude_ft,
                wind_speed_mph,
                target_speed_mph: 0.0,
                solver_mode: if cfg!(feature = "online") {
                    "online".to_string()
                } else {
                    "offline".to_string()
                },
                powder: String::new(),
                bullet,
                weight_gr,
                bc: load.bc,
                drag_model: load.drag_model.to_string(),
                velocity_fps,
                font_scale: 1.0,
                bold_data: false,
                elevation_unit_label: unit_label.to_string(),
                windage_unit_label: unit_label.to_string(),
                engine_version: env!("CARGO_PKG_VERSION").to_string(),
                table_version: String::new(),
                // MBA-1477/MBA-1478: a printed card that stops short says so on the paper.
                // A dope card is the one card surface that leaves the machine it was made
                // on, so a stderr warning it cannot carry is no notice at all.
                truncation_note: truncation
                    .as_ref()
                    .map(|t| t.printed_note(card_distance_unit(units)))
                    .unwrap_or_default(),
            };

            let pdf_bytes = ballistics_engine::pdf_dope_card::generate_dope_card_pdf(
                &pdf_config,
                &display_rows,
                range_unit,
            )?;
            std::fs::write(output_path, &pdf_bytes)?;
            eprintln!(
                "Adaptive range card PDF written to: {}",
                output_path.display()
            );
            eprint!(
                "{}",
                adaptive_card_footer(&report, units, unit_label, max_rows)
            );
        }
        #[cfg(not(feature = "pdf"))]
        OutputFormat::Pdf => {
            return Err(
                "PDF output requires building with the 'pdf' feature (e.g. cargo build --features pdf)"
                    .into(),
            );
        }
    }

    // MBA-1478: on stderr for every format, exactly as the other four surfaces do it — the
    // csv/json arms keep stdout machine-clean and carry the same facts structurally.
    if let Some(truncation) = &truncation {
        warn_card_truncated(truncation, units);
    }

    Ok(())
}

/// Review fix I-1 (review of `4e69435`): `format_adaptive_card_range`/`adaptive_card_row_line`
/// pin the near-integer-then-one-decimal range rule and prove it does not disturb the seven
/// other columns.
#[cfg(test)]
mod adaptive_card_row_tests {
    use super::*;

    /// Mirrors `pdf_dope_card::format_range`'s own pinned examples (`src/pdf_dope_card.rs`)
    /// exactly -- this is a separate copy of that identical rule (see this fn's doc comment
    /// for why it can't be a shared call), so matching its already-reviewed fixtures keeps
    /// the two provably in sync rather than merely similar by construction.
    #[test]
    fn format_adaptive_card_range_matches_the_pdf_dope_cards_pinned_examples() {
        assert_eq!(format_adaptive_card_range(400.0), "400");
        assert_eq!(format_adaptive_card_range(417.3), "417.3");
        assert_eq!(format_adaptive_card_range(400.02), "400");
        assert_eq!(format_adaptive_card_range(399.98), "400");
        assert_eq!(format_adaptive_card_range(100.0 + 1e-9), "100");
        assert_eq!(format_adaptive_card_range(100.5), "100.5");
        assert_eq!(format_adaptive_card_range(400.08), "400.1");
    }

    /// I-1's exact reproduction: a real `--anchor`/interior-row value must print its one
    /// decimal, not a silently rounded integer that disagrees with `-o json`/`-o pdf`.
    #[test]
    fn format_adaptive_card_range_does_not_silently_round_a_real_anchor() {
        assert_eq!(format_adaptive_card_range(412.5), "412.5");
        assert_eq!(format_adaptive_card_range(307.2384), "307.2");
    }

    fn sentinel_row(range: f64) -> CardRow {
        CardRow {
            range,
            drop_linear: Some(222.1),
            drop_adj: Some(333.2),
            come_up: None,
            wind_linear: Some(555.4),
            wind_adj: Some(666.5),
            velocity: Some(777.6),
            energy: Some(888.7),
            time: Some(9.123),
            lead_adj: None,
            wind_columns: Vec::new(),
        }
    }

    /// Same anti-transposition technique as
    /// `card_row_sentinel_tests::range_table_row_line_places_each_sentinel_in_its_own_column`
    /// (Task 9): `expected` is a literal, independently hand-typed string, not produced by
    /// calling the function under test. Two cases -- an integer range (the common case,
    /// previously-correct and must stay so) and a fractional one (the I-1 fix) -- so fixing
    /// the Range column is proven not to disturb the seven columns it must leave alone.
    #[test]
    fn adaptive_card_row_line_places_each_sentinel_in_its_own_column() {
        let integer_row = sentinel_row(111.0);
        let line = adaptive_card_row_line(&integer_row);
        let expected =
            "│   111 │   222.1 │ 333.200 │   555.4 │  666.50 │     778 │     889 │  9.12 │";
        assert_eq!(line, expected);

        let fractional_row = sentinel_row(111.4);
        let line = adaptive_card_row_line(&fractional_row);
        let expected =
            "│ 111.4 │   222.1 │ 333.200 │   555.4 │  666.50 │     778 │     889 │  9.12 │";
        assert_eq!(line, expected);
    }
}