ballistics_engine/

solve_v1.rs

//! Transport-free implementation of the solve-json v1 trajectory service.
//!
//! This module owns the semantic boundary between the stable, explicit-SI v1 data-transfer
//! objects and the engine's legacy internal input types.  It deliberately performs no JSON I/O,
//! filesystem access, network access, profile lookup, or terminal output.

use crate::solve_json::{
    AtmosphereV1, DragModelV1, DragTableKindV1, DragTableV1, EffectsV1, PressureReferenceV1,
    ProjectileV1, ResolvedAtmosphereV1, ResolvedConstantWindV1, ResolvedEffectsV1,
    ResolvedProjectileV1, ResolvedRifleV1, ResolvedSamplingV1, ResolvedSegmentedWindV1,
    ResolvedShotV1, ResolvedSolveRequestV1, ResolvedSolverV1, ResolvedWindSegmentV1,
    ResolvedWindV1, RifleV1, SampleFlagV1, SamplingV1, SchemaVersionV1, ShotV1, SolveErrorCodeV1,
    SolveErrorEnvelopeV1, SolveErrorV1, SolveNoticeV1, SolveRequestV1, SolveSuccessV1,
    SolveSummaryV1, SolverMethodV1, SolverV1, SuccessStatusV1, TerminationReasonV1,
    TrajectorySampleV1, TwistDirectionV1, WindReferenceV1, WindShearModelV1, WindV1,
    MAX_SOLVE_JSON_SAMPLES_V1,
};
use crate::trajectory_observation::{
    bracket_param, Bracket, TrajectoryObservation, TrajectoryObservationError,
    TrajectoryObservationFlag, TrajectoryTermination,
};
use crate::wind::WindSegment;
use crate::{
    AtmosphericConditions, BallisticInputs, BallisticsError, DragModel, TrajectorySolver,
    WindConditions,
};

const DEFAULT_SIGHT_HEIGHT_M: f64 = 0.05;
const DEFAULT_MUZZLE_HEIGHT_M: f64 = 0.0;
const DEFAULT_TWIST_RATE_M_PER_TURN: f64 = 0.3048;
const DEFAULT_ALTITUDE_M: f64 = 0.0;
const DEFAULT_RELATIVE_HUMIDITY: f64 = 0.5;
const DEFAULT_TIME_STEP_S: f64 = 0.001;
const DEFAULT_SAMPLE_INTERVAL_M: f64 = 10.0;
const DEFAULT_GROUND_THRESHOLD_M: f64 = -100.0;

const MIN_ICAO_ALTITUDE_M: f64 = -5_000.0;
const MAX_ICAO_ALTITUDE_M: f64 = 84_000.0;
const METERS_PER_INCH: f64 = 0.0254;
const KILOMETRES_PER_METRE: f64 = 0.001;
const SECONDS_PER_HOUR: f64 = 3_600.0;
pub(crate) const PASCALS_PER_HECTOPASCAL: f64 = 100.0;
pub(crate) const KELVIN_OFFSET_C: f64 = 273.15;
const KG_PER_GRAIN: f64 = 0.000_064_798_91;

/// Stable assumption code emitted for a literal protocol default.
pub const ASSUMPTION_DEFAULT_APPLIED: &str = "default_applied";
/// Stable assumption code emitted when station temperature is resolved from ICAO atmosphere.
pub const ASSUMPTION_ICAO_STANDARD_TEMPERATURE: &str = "icao_standard_temperature";
/// Stable assumption code emitted when station pressure is resolved from ICAO atmosphere.
pub const ASSUMPTION_ICAO_STANDARD_PRESSURE: &str = "icao_standard_pressure";
/// Stable assumption code emitted when an explicit `pressure_reference: "qnh"` pressure is
/// reduced to station pressure (MBA-1397).
pub const ASSUMPTION_QNH_REDUCED_TO_STATION_PRESSURE: &str = "qnh_reduced_to_station_pressure";
/// Stable assumption code emitted when projectile length is inferred from mass and diameter.
pub const ASSUMPTION_ESTIMATED_PROJECTILE_LENGTH: &str = "estimated_projectile_length";

/// Stable warning code for segmented wind that becomes calm before the requested maximum range.
pub const WARNING_PARTIAL_WIND_COVERAGE: &str = "partial_wind_coverage";
/// Stable warning code emitted for each opt-in experimental physical effect.
pub const WARNING_EXPERIMENTAL_EFFECT: &str = "experimental_effect";
/// Stable warning code for an explicitly supplied fixed step that adaptive RK45 ignores.
pub const WARNING_RK45_TIME_STEP_IGNORED: &str = "rk45_time_step_ignored";
/// Stable warning code for a request that supplies both `zero_distance_m` and
/// `muzzle_angle_rad` (0.33.0 decision-support Task 2): the explicit angle is used directly
/// and the elevation search does not run. `zero_distance_m` is retained in `resolved_request`
/// and is not otherwise inert -- see the warning message for what it still affects.
pub const WARNING_ZERO_DISTANCE_ELEVATION_NOT_RESOLVED: &str =
    "zero_distance_elevation_not_resolved";
/// Stable warning code emitted when a `corrections.bc5d_table_path` request names a drag
/// model outside the table's G1/G7 planes and the lookup is typed as G1 (the same coercion
/// the CLI's `--bc-table-dir` path performs, surfaced instead of silent).
pub const WARNING_BC5D_DRAG_MODEL_COERCED: &str = "bc5d_drag_model_coerced";
/// Stable warning code emitted when an accepted `effects.wind_shear_model` has no profile on
/// this solve path and therefore leaves the wind unchanged (0.36.0). Only `"ekman_spiral"`
/// reaches it today: the boundary-layer evaluator behind `TrajectorySolver` implements the
/// logarithmic and power-law profiles, and returns the operative wind for anything else. The
/// model is still echoed in `resolved_request`, so this warning is what distinguishes "applied
/// and it moved the numbers" from "applied and it could not".
pub const WARNING_WIND_SHEAR_MODEL_NOT_MODELED: &str = "wind_shear_model_not_modeled";

/// `effects.aerodynamic_jump` was enabled while the request left the geometry the estimator
/// reads to a default (MBA-959).
///
/// The jump scales with gyroscopic stability and bullet length, so it reads
/// `rifle.twist_rate_m_per_turn` and `projectile.length_m`. Omitting either does NOT disable
/// the correction and does not zero it — the solve proceeds against the assumed 1:12 barrel
/// and the mass/diameter length estimate, and produces a confident number computed for a
/// rifle the caller does not own. Measured on a .308 175 gr at 800 m in a 10 mph full-value
/// crosswind, an omitted twist moves the jump from 10.79 cm to 9.08 cm — a 16% error that is
/// invisible in the response, because the jump is folded into every drop rather than reported
/// as its own column.
///
/// The two assumption notices for the defaults themselves are still emitted; this one exists
/// because those say "a default was applied" without saying that anything now depends on it.
///
/// Aerodynamic jump is not the only effect that reads the barrel: `effects.magnus` and
/// `effects.enhanced_spin_drift` do too, under the separate
/// [`WARNING_SPIN_EFFECT_ASSUMED_TWIST_RATE`], and `summary.stability_factor` on every solve,
/// under [`WARNING_STABILITY_FACTOR_ASSUMED_TWIST_RATE`]. The codes are distinct so that each
/// one names the model it belongs to — they are NOT mutually exclusive, and a single omitted
/// `rifle.twist_rate_m_per_turn` routinely raises several of them at once. A request enabling
/// both `aerodynamic_jump` and `magnus` without a stated twist gets all three: one per
/// consumer, each at its own path. Callers must match on the code they care about rather than
/// assume at most one assumed-barrel warning is present.
pub const WARNING_AERODYNAMIC_JUMP_ASSUMED_GEOMETRY: &str = "aerodynamic_jump_assumed_geometry";

/// A spin-driven effect (`effects.magnus` or `effects.enhanced_spin_drift`) was enabled while
/// the request left `rifle.twist_rate_m_per_turn` to its default (MBA-1484).
///
/// Both models are functions of the spin the rifling imparts, so both read the twist rate —
/// enhanced spin drift through the muzzle gyroscopic stability factor that scales the Litz
/// drift, Magnus through the spin rate that sets its side force and yaw of repose. Omitting
/// the field does NOT disable either one and does not zero it: `resolve_rifle` substitutes
/// `DEFAULT_TWIST_RATE_M_PER_TURN` (0.3048 m, exactly 1:12 inches) and the solve runs against
/// that barrel, producing a confident number for a rifle the caller does not own. The early
/// return in `TrajectorySolver::apply_spin_drift` for a non-positive twist is real but is
/// unreachable from here, because the default is applied long before the solver sees the
/// field.
///
/// Measured on a .308 175 gr at 800 m: `enhanced_spin_drift` reports
/// `summary.spin_drift_m` = 0.1832 m with the twist omitted and the identical 0.1832 m with
/// 1:12 stated — the omission is not a distinguishable request — while a stated 1:8 gives
/// 0.3163 m, 73% more. Magnus's contribution is far smaller in absolute terms (it moved the
/// 800 m drop by 0.19 mm at the assumed 1:12) but is no less twist-bound: at a stated 1:6 the
/// same contribution is 0.75 mm, four times as large. In neither case is the dependence
/// visible in the response, because both models are folded into the trajectory columns rather
/// than reported separately — `summary.spin_drift_m` is the one exception, and it reports the
/// number, not the barrel it came from.
///
/// The assumption notice for the default itself is still emitted; this one exists because it
/// says "a default was applied" without saying that anything now depends on it.
///
/// This code covers the two opt-in models only. The twist is read on EVERY solve by
/// `summary.stability_factor`, which has its own
/// [`WARNING_STABILITY_FACTOR_ASSUMED_TWIST_RATE`]; both fire together when a spin effect is
/// enabled without a stated twist.
pub const WARNING_SPIN_EFFECT_ASSUMED_TWIST_RATE: &str = "spin_effect_assumed_twist_rate";

/// `summary.stability_factor` was computed from the default twist because the request left
/// `rifle.twist_rate_m_per_turn` out (MBA-1484).
///
/// Unlike every other assumed-barrel warning this module emits, this one is not gated on an
/// opt-in flag, because Sg is not opt-in: `effective_sg_from_inputs` runs on every solve and
/// the muzzle gyroscopic stability factor is a direct function of the twist. An omitted field
/// therefore does not leave Sg alone — it reports the Sg of a 1:12 barrel, under a field name
/// that says nothing about which barrel it describes.
///
/// Measured on a .308 175 gr with NO effects enabled at all: `summary.stability_factor` is
/// 1.6650154161603787 with the twist omitted, bit-identically 1.6650154161603787 with 1:12
/// stated, and 3.7462846863608514 with 1:8 stated — 2.25x, across the marginal/comfortable
/// line a shooter reads Sg to decide. `drop_m` and `windage_m` are bit-identical in all three,
/// so the trajectory really is twist-independent when no spin effect is enabled; the summary
/// is not, and that distinction is the whole reason this code exists separately from
/// [`WARNING_SPIN_EFFECT_ASSUMED_TWIST_RATE`].
///
/// Emitted at `$.rifle.twist_rate_m_per_turn` — the omitted field itself — because there is no
/// flag to hang it on, and only when Sg is actually reported: when
/// `summary.stability_factor` is absent nothing misleading was published and there is nothing
/// to warn about. It fires on any request that omits the twist and gets an Sg, which is most
/// of them; that breadth is the finding, not a reason to suppress it. The `default_applied`
/// assumption at the same path stays, and says a default was applied without saying that a
/// reported number now depends on it.
pub const WARNING_STABILITY_FACTOR_ASSUMED_TWIST_RATE: &str = "stability_factor_assumed_twist_rate";

/// Whether the raw request supplied the geometry fields the twist-reading effects need, as
/// opposed to letting `resolve_rifle`/`resolve_projectile` substitute a default.
///
/// `twist_rate` is read by aerodynamic jump, Magnus and enhanced spin drift;
/// `projectile_length` by aerodynamic jump. Carried rather than re-derived because
/// `resolve_effects` only sees `EffectsV1`, and the distinction is about the RAW request: by
/// the time the rifle and projectile are resolved, an assumed 1:12 twist is
/// indistinguishable from a stated one.
#[derive(Debug, Clone, Copy)]
struct SuppliedGeometry {
    twist_rate: bool,
    projectile_length: bool,
}

#[derive(Debug)]
pub(crate) struct PreparedSolveV1 {
    pub(crate) resolved_request: ResolvedSolveRequestV1,
    assumptions: Vec<SolveNoticeV1>,
    warnings: Vec<SolveNoticeV1>,
    pub(crate) inputs: BallisticInputs,
    pub(crate) wind: WindConditions,
    pub(crate) wind_segments: Vec<WindSegment>,
    pub(crate) atmosphere: AtmosphericConditions,
}

/// Execute one semantically validated solve-json v1 request.
///
/// The function is transport-free: callers are responsible for decoding and encoding the DTOs.
/// All dimensional request values are SI.  Valid requests produce a fully resolved success DTO;
/// invalid requests and engine failures produce the stable v1 error envelope.
pub fn solve_v1(request: SolveRequestV1) -> Result<SolveSuccessV1, SolveErrorEnvelopeV1> {
    let mut prepared = prepare_request(&request)?;
    let max_range_m = prepared.resolved_request.shot.max_range_m;
    let time_step_s = prepared.resolved_request.solver.time_step_s;
    let sample_interval_m = prepared.resolved_request.sampling.interval_m;
    let zero_distance_m = prepared.resolved_request.shot.zero_distance_m;
    let target_height_m = prepared.resolved_request.shot.target_height_m;
    let enhanced_spin_drift = prepared.resolved_request.effects.enhanced_spin_drift;

    // Retain the exact mapped inputs for summary diagnostics. TrajectorySolver owns its copy and
    // may update the private effective muzzle angle during zeroing.
    let summary_inputs = prepared.inputs.clone();
    let station_temperature_c = prepared.atmosphere.temperature;
    let station_pressure_hpa = prepared.atmosphere.pressure;

    let (solver, effective_angle) = build_zeroed_solver(
        prepared.inputs,
        prepared.wind,
        prepared.atmosphere,
        prepared.wind_segments,
        max_range_m,
        time_step_s,
        zero_distance_m,
        target_height_m,
        request.shot.muzzle_angle_rad,
    )?;
    // 0.33.0 decision-support Task 2: an explicitly supplied muzzle_angle_rad always wins over
    // zero_distance_m for ELEVATION (resolve_shot's match already resolved it that way; see
    // build_zeroed_solver's doc comment for the full zero-handling rationale, including the
    // windage-zero bias). Persist the searched angle -- bit-identical, not just numerically
    // re-converged, on a later round-trip -- only when the elevation search actually ran.
    if let Some(angle) = effective_angle {
        prepared.resolved_request.shot.muzzle_angle_rad = angle;
    }

    let result = solver.solve().map_err(solve_failed)?;
    let observations = result
        .sample_observations(sample_interval_m, MAX_SOLVE_JSON_SAMPLES_V1)
        .map_err(map_observation_error)?;

    // MBA-1403 target-plane drops reference: this solve path samples drop via
    // TrajectoryResult::sample_observations (LOS-perpendicular by construction), so the
    // 1/cos(shooting_angle) reference transform is applied exactly once here, at the wire
    // boundary. `"los"`/omitted divides by cos(0) == 1.0 exactly — byte-identical.
    // validate_for_solve has already rejected target mode at |shooting_angle| >= 90 deg.
    let drops_scale_denominator = match request.shot.drops_reference.unwrap_or_default() {
        crate::solve_json::DropsReferenceV1::Los => 1.0,
        crate::solve_json::DropsReferenceV1::Target => {
            prepared.resolved_request.shot.shooting_angle_rad.cos()
        }
    };
    let samples = observations
        .iter()
        .cloned()
        .map(|mut observation| {
            observation.drop_m /= drops_scale_denominator;
            observation_to_wire(observation)
        })
        .collect::<Vec<_>>();
    let terminal = observations.last().ok_or_else(|| {
        internal_error("trajectory observation sampling returned no terminal observation")
    })?;

    let maximum_height_m =
        maximum_world_height_m(&result, prepared.resolved_request.shot.shooting_angle_rad)?;

    let stability = crate::spin_drift::effective_sg_from_inputs(
        &summary_inputs,
        station_temperature_c,
        station_pressure_hpa,
    );
    let stability_factor = if stability.is_finite() && stability >= 0.0 {
        Some(stability)
    } else {
        None
    };

    // MBA-1484. Sg is a direct function of the twist and is computed on every solve, so an
    // omitted `rifle.twist_rate_m_per_turn` does not leave it alone: it publishes the Sg of the
    // assumed 1:12 barrel (1.665 on the .308 175 gr fixture, against 3.746 at a stated 1:8)
    // under a field name that says nothing about which barrel it describes. Warned here rather
    // than in `resolve_effects` because this is the one assumed-barrel consumer that is not
    // gated on a flag -- there is nothing in `EffectsV1` to key off, and the gate is whether Sg
    // was reported at all, which is not known until it has been computed.
    //
    // This does fire on nearly every twist-omitting request, including ones written before the
    // warning existed. That breadth is the finding rather than an argument against it: those
    // requests were always being handed a barrel-dependent Sg they never described. Warning on
    // Magnus, whose whole contribution is 0.19 mm of drop at 800 m, while staying silent about
    // a 2.25x swing in a reported stability number is not a line that can be defended.
    if request.rifle.twist_rate_m_per_turn.is_none() && stability_factor.is_some() {
        prepared.warnings.push(notice(
            WARNING_STABILITY_FACTOR_ASSUMED_TWIST_RATE,
            "summary.stability_factor is computed from the twist on every solve, but \
             rifle.twist_rate_m_per_turn was not supplied. The reported Sg is the Sg of the \
             assumed 1:12 barrel, not of a barrel this request specified. The trajectory \
             itself is unaffected unless a spin-driven effect is also enabled.",
            "$.rifle.twist_rate_m_per_turn",
        ));
    }
    let spin_drift_m = if enhanced_spin_drift {
        stability_factor
            .map(|sg| {
                crate::spin_drift::litz_drift_meters(
                    sg,
                    terminal.time_s,
                    summary_inputs.is_twist_right,
                )
            })
            .filter(|drift| drift.is_finite())
    } else {
        None
    };

    if enhanced_spin_drift && stability_factor.is_some() && spin_drift_m.is_none() {
        return Err(internal_error(
            "enhanced spin-drift summary calculation produced a non-finite value",
        ));
    }

    // MBA-1395: equivalent horizontal range (BDC shoot-to) — computed only for an
    // inclined shot fired against a solved zero; None (field absent) otherwise, keeping
    // every flat/pre-existing response byte-identical. The solver still holds the
    // inclined, zeroed state here, so the angular-match inversion runs against the same
    // zero the response describes.
    let equivalent_horizontal_range_m = match (
        zero_distance_m,
        prepared.resolved_request.shot.shooting_angle_rad != 0.0,
    ) {
        (Some(zero_m), true) => solver.equivalent_horizontal_range(terminal.distance_m, zero_m),
        _ => None,
    };

    // MBA-959: the jump the solver actually applied, read off its own components rather than
    // recomputed here -- a second spelling of the Litz regression is a second answer. `None`
    // when the flag is off or the solver declined the effect; `Some(0.0)` when it ran against
    // no muzzle crosswind, which is a different fact and worth being able to tell apart.
    let aerodynamic_jump_moa = result
        .aerodynamic_jump
        .as_ref()
        .map(|components| components.vertical_jump_moa)
        .filter(|moa| moa.is_finite());

    let summary = SolveSummaryV1 {
        actual_range_m: terminal.distance_m,
        maximum_height_m,
        time_of_flight_s: terminal.time_s,
        terminal_speed_mps: terminal.speed_mps,
        terminal_energy_j: terminal.energy_j,
        stability_factor,
        spin_drift_m,
        equivalent_horizontal_range_m,
        aerodynamic_jump_moa,
        termination: termination_to_wire(result.termination),
    };

    // MBA-1361: a pure post-processing read of the samples above — it cannot change the
    // trajectory, and `None` (no `reticle` block) keeps the response byte-identical.
    let reticle_hold = match request.reticle.as_ref() {
        Some(reticle) => Some(resolve_reticle_hold(reticle, &samples)?),
        None => None,
    };

    let success = SolveSuccessV1 {
        schema_version: SchemaVersionV1,
        engine_version: env!("CARGO_PKG_VERSION").to_owned(),
        status: SuccessStatusV1::Ok,
        resolved_request: prepared.resolved_request,
        assumptions: prepared.assumptions,
        warnings: prepared.warnings,
        summary,
        samples,
        reticle_hold,
    };
    success.validate_for_serialization()?;
    Ok(success)
}

/// Build a `TrajectorySolver` from prepared inputs, configure it, and apply `solve_v1`'s own
/// zero handling -- shared by `solve_v1` above and by the perturbation kernel's `evaluate`
/// (`src/perturbation/mod.rs`, 0.33.0 decision-support Task 6, I3 review fix), which reads
/// observations directly off the resulting solver's `TrajectoryResult` without going through
/// the wire success DTO, and without a second, independent implementation of this zero handling
/// that could silently drift from this one.
///
/// Returns the configured solver (not yet solved -- callers run `TrajectorySolver::solve`
/// themselves, since `solve_v1` needs the solver alive afterward too, for
/// `equivalent_horizontal_range`) alongside the elevation search's effective angle when it ran
/// (`Some`), so a caller that wants to persist it -- as `solve_v1` does, onto
/// `resolved_request.shot.muzzle_angle_rad` -- can; `None` when it did not run at all (no
/// `zero_distance_m`), or ran only for windage (`zero_distance_m` present alongside an explicit
/// `explicit_angle`, which needs no persisting since it was already supplied).
///
/// `explicit_angle` is the ORIGINAL (unresolved) request's `shot.muzzle_angle_rad`: an
/// explicitly supplied angle always wins over `zero_distance_m` for ELEVATION (`resolve_shot`'s
/// match already resolved it that way). `calculate_and_set_zero_angle` also applies a SEPARATE
/// windage-zero convergence bias (offset-mounted sights / MBA-1396, deliberate horizontal POI /
/// MBA-1359) to azimuth, gated only on `zero_distance_m` -- not on whether the elevation was
/// searched for or supplied directly -- so when both fields are present, this still applies just
/// the windage term on its own rather than skipping the whole call. That bias is deliberately
/// never returned/persisted (unlike the elevation): `zero_distance_m` being present no longer
/// implies "the search ran", so folding the bias into a persisted, echoed field would
/// double-apply it on a second-generation round-trip (the same trap avoided for
/// `atmosphere.pressure_reference` / `wind.wind_reference` in `request_roundtrip.rs`).
#[allow(clippy::too_many_arguments)]
pub(crate) fn build_zeroed_solver(
    prepared_inputs: BallisticInputs,
    wind: WindConditions,
    atmosphere: AtmosphericConditions,
    wind_segments: Vec<WindSegment>,
    max_range_m: f64,
    time_step_s: f64,
    zero_distance_m: Option<f64>,
    target_height_m: f64,
    explicit_angle: Option<f64>,
) -> Result<(TrajectorySolver, Option<f64>), SolveErrorEnvelopeV1> {
    let mut solver =
        TrajectorySolver::new_with_resolved_station_atmosphere(prepared_inputs, wind, atmosphere);
    solver.set_max_range(max_range_m);
    solver.set_time_step(time_step_s);
    if !wind_segments.is_empty() {
        solver.set_wind_segments(wind_segments);
    }

    let mut effective_angle = None;
    match (zero_distance_m, explicit_angle) {
        (Some(distance_m), None) => {
            let angle = solver
                .calculate_and_set_zero_angle(
                    distance_m,
                    target_height_m,
                    crate::cli_api::ZeroTargetFrame::WorldVertical,
                )
                .map_err(solve_failed)?;
            if !angle.is_finite() {
                return Err(solve_failed_message(
                    "zero-angle calculation returned a non-finite effective muzzle angle",
                ));
            }
            effective_angle = Some(angle);
        }
        (Some(distance_m), Some(_)) => solver.apply_windage_zero_bias(distance_m),
        (None, _) => {}
    }

    Ok((solver, effective_angle))
}

// `pub(crate)` (0.33.0 decision-support Task 6): the perturbation kernel's `evaluate` needs the
// same request resolution `solve_v1` above starts from, to read observations off the raw
// `TrajectoryResult` without going through the wire success DTO. Zero handling itself is shared
// via `build_zeroed_solver` above (I3 review fix: an earlier revision hand-duplicated that match
// in `perturbation/mod.rs` instead, verified consistent only by an outboard cross-check test --
// a structural share removes that ongoing "keep two copies in sync" risk instead of relying on a
// test to keep catching it).
pub(crate) fn prepare_request(
    request: &SolveRequestV1,
) -> Result<PreparedSolveV1, SolveErrorEnvelopeV1> {
    let mut assumptions = Vec::new();
    let mut warnings = Vec::new();

    let (projectile, bullet_length_m) = resolve_projectile(&request.projectile, &mut assumptions)?;
    let rifle = resolve_rifle(&request.rifle, &mut assumptions)?;
    let shot = resolve_shot(&request.shot, &rifle, &mut assumptions, &mut warnings)?;
    let atmosphere = resolve_atmosphere(&request.atmosphere, &mut assumptions)?;
    let wind_coverage_distance_m = shot.zero_distance_m.unwrap_or(0.0).max(shot.max_range_m);
    let (resolved_wind, wind, wind_segments) = resolve_wind(
        &request.wind,
        wind_coverage_distance_m,
        // MBA-1368: the RAW request option, not the resolved default — compass mode
        // must reject an omitted shot azimuth, never silently re-reference against
        // the 0.0 default.
        request.shot.shot_azimuth_rad,
        &mut assumptions,
        &mut warnings,
    )?;
    let solver = resolve_solver(&request.solver, &mut assumptions, &mut warnings)?;
    let effects = resolve_effects(
        &request.effects,
        atmosphere.latitude_rad,
        SuppliedGeometry {
            twist_rate: request.rifle.twist_rate_m_per_turn.is_some(),
            projectile_length: request.projectile.length_m.is_some(),
        },
        &mut assumptions,
        &mut warnings,
    )?;
    let sampling = resolve_sampling(&request.sampling, &mut assumptions)?;

    // Downrange segments and altitude shear are not a defined combination, and the solver does
    // not treat them as one: `TrajectorySolver::calculate_acceleration` takes the segmented
    // wind sock in preference to the shear branch, so a request asking for both would get its
    // shear dropped on the floor while `resolved_request` still claimed a model was applied.
    // The CLI (`--wind-segment` + `--enable-wind-shear`) and the WASM front end already refuse
    // this pairing; refuse it here too rather than inventing the third front end that solves it
    // silently.
    if matches!(resolved_wind, ResolvedWindV1::Segmented(_))
        && effects
            .wind_shear_model
            .is_some_and(WindShearModelV1::is_enabled)
    {
        return Err(conflicting_fields(
            "$.effects.wind_shear_model",
            "wind.segments cannot be combined with effects.wind_shear_model (downrange \
             segments plus altitude shear is not yet a defined model)",
        ));
    }

    // A BC5D table corrects a G1/G7 ballistic coefficient along the flight; a drag table
    // replaces the G-curve that BC is measured against, so the pair has no meaning. Refused
    // before the table path is ever opened.
    if projectile.drag_table.is_some()
        && request
            .corrections
            .as_ref()
            .is_some_and(|corrections| corrections.bc5d_table_path.is_some())
    {
        return Err(conflicting_fields(
            "$.corrections.bc5d_table_path",
            "corrections.bc5d_table_path cannot be combined with projectile.drag_table (BC5D \
             corrects a G1/G7 ballistic coefficient; a drag table replaces the G-curve)",
        ));
    }

    // MBA-1598: a BC ladder's band BCs are measured against a reference curve: drag_model's,
    // or a `reference`-kind drag table's, which replaces it and is flown as Cd_ref / BC with
    // the band BC exactly as a built-in model is (install_drag_table). A `projectile`-kind
    // table is the projectile's own Cd, divided by sectional density, so it has no BC for the
    // bands to change, and that pair is refused. The correction table builds its own ladder
    // from ballistic_coefficient, so a caller ladder beside it is two answers to one question.
    // Both refusals happen here, before the correction table path is ever opened.
    if projectile.bc_segments.is_some()
        && projectile
            .drag_table
            .as_ref()
            .is_some_and(|table| table.kind == DragTableKindV1::Projectile)
    {
        return Err(conflicting_fields(
            "$.projectile.bc_segments",
            "projectile.bc_segments cannot be combined with a projectile.drag_table of kind \
             \"projectile\": that curve is the projectile's own Cd and has no BC for the bands \
             to change",
        ));
    }
    if projectile.bc_segments.is_some()
        && request
            .corrections
            .as_ref()
            .is_some_and(|corrections| corrections.bc5d_table_path.is_some())
    {
        return Err(conflicting_fields(
            "$.projectile.bc_segments",
            "projectile.bc_segments cannot be combined with corrections.bc5d_table_path: the \
             correction table builds its own BC ladder from ballistic_coefficient",
        ));
    }

    let resolved_request = ResolvedSolveRequestV1 {
        schema_version: SchemaVersionV1,
        projectile,
        rifle,
        shot,
        atmosphere,
        wind: resolved_wind,
        solver,
        effects,
        sampling,
        // MBA-1361: pure pass-through echo (Task 1 of the 0.33.0 decision-support train) — no
        // defaulting, no unit conversion. The reticle hold itself is computed later in
        // solve_v1 straight from `request.reticle`, unaffected by this echo.
        reticle: request.reticle.clone(),
        // Pure pass-through echo, same contract as `reticle` above: segments are always
        // regenerated from the PUBLISHED ballistic_coefficient, so re-solving a resolved
        // request re-applies the same correction rather than compounding it.
        corrections: request.corrections.clone(),
    };

    let temperature_c = checked_conversion(
        resolved_request.atmosphere.temperature_k - KELVIN_OFFSET_C,
        "$.atmosphere.temperature_k",
        "temperature conversion to Celsius overflowed",
    )?;
    let pressure_hpa = checked_conversion(
        resolved_request.atmosphere.pressure_pa / PASCALS_PER_HECTOPASCAL,
        "$.atmosphere.pressure_pa",
        "pressure conversion to hectopascals overflowed",
    )?;
    let humidity_percent = checked_conversion(
        resolved_request.atmosphere.relative_humidity * 100.0,
        "$.atmosphere.relative_humidity",
        "relative-humidity conversion to percent overflowed",
    )?;
    let twist_rate_inches = checked_conversion(
        resolved_request.rifle.twist_rate_m_per_turn / METERS_PER_INCH,
        "$.rifle.twist_rate_m_per_turn",
        "twist-rate conversion to inches per turn overflowed",
    )?;
    let caliber_inches = checked_conversion(
        resolved_request.projectile.diameter_m / METERS_PER_INCH,
        "$.projectile.diameter_m",
        "diameter conversion to inches overflowed",
    )?;
    let weight_grains = checked_conversion(
        resolved_request.projectile.mass_kg / KG_PER_GRAIN,
        "$.projectile.mass_kg",
        "mass conversion to grains overflowed",
    )?;
    let latitude_degrees = resolved_request
        .atmosphere
        .latitude_rad
        .map(f64::to_degrees)
        .map(|value| {
            checked_conversion(
                value,
                "$.atmosphere.latitude_rad",
                "latitude conversion to degrees overflowed",
            )
        })
        .transpose()?;

    let (wind_speed, wind_direction) = match &resolved_request.wind {
        ResolvedWindV1::Constant(constant) => (constant.speed_mps, constant.direction_from_rad),
        ResolvedWindV1::Segmented(_) => (0.0, 0.0),
    };

    let mut inputs = BallisticInputs {
        bc_value: resolved_request.projectile.ballistic_coefficient,
        bc_type: drag_model_to_engine(resolved_request.projectile.drag_model),
        // solve-json v1 (docs/SOLVE_JSON_V1.md) has no BC-reference-standard field yet;
        // every published BC in that contract is treated as ICAO-referenced (MBA-1365
        // is a CLI/WASM/FFI/profile feature, not a v1 JSON schema change).
        bc_reference_standard: crate::cli_api::BcReferenceStandard::Icao,
        bullet_mass: resolved_request.projectile.mass_kg,
        muzzle_velocity: resolved_request.rifle.muzzle_velocity_mps,
        bullet_diameter: resolved_request.projectile.diameter_m,
        bullet_length: bullet_length_m,
        muzzle_angle: resolved_request.shot.muzzle_angle_rad,
        target_distance: resolved_request.shot.max_range_m,
        azimuth_angle: resolved_request.shot.aim_azimuth_rad,
        shot_azimuth: resolved_request.shot.shot_azimuth_rad,
        shooting_angle: resolved_request.shot.shooting_angle_rad,
        cant_angle: resolved_request.shot.cant_angle_rad,
        sight_height: resolved_request.rifle.sight_height_m,
        // MBA-1396: consumed straight from the request (validated in resolve_rifle) for the
        // engine inputs here. Separately echoed at ResolvedRifleV1::sight_offset_lateral_m
        // when supplied (0.33.0 decision-support Task 1) — same contract as the zero-POI
        // fields below.
        sight_offset_lateral_m: request.rifle.sight_offset_lateral_m.unwrap_or(0.0),
        muzzle_height: resolved_request.rifle.muzzle_height_m,
        target_height: resolved_request.shot.target_height_m,
        // MBA-1359: consumed straight from the request (validated in resolve_shot) for the
        // engine inputs here. Separately echoed at ResolvedShotV1::zero_poi_up_m /
        // zero_poi_right_m when supplied (0.33.0 decision-support Task 1) — see
        // resolve_shot's comment. The zero solve in solve_v1 runs on THIS solver, so both
        // the vertical and azimuth biases apply there.
        zero_poi_vertical_m: request.shot.zero_poi_up_m.unwrap_or(0.0),
        zero_poi_horizontal_m: request.shot.zero_poi_right_m.unwrap_or(0.0),
        ground_threshold: resolved_request.shot.ground_threshold_m,
        altitude: resolved_request.atmosphere.altitude_m,
        temperature: temperature_c,
        pressure: pressure_hpa,
        humidity: resolved_request.atmosphere.relative_humidity,
        latitude: latitude_degrees,
        wind_speed,
        wind_angle: wind_direction,
        twist_rate: twist_rate_inches,
        is_twist_right: resolved_request.rifle.twist_direction == TwistDirectionV1::Right,
        caliber_inches,
        weight_grains,
        manufacturer: None,
        bullet_model: None,
        bullet_id: None,
        bullet_cluster: None,
        use_rk4: resolved_request.solver.method != SolverMethodV1::Euler,
        use_adaptive_rk45: resolved_request.solver.method == SolverMethodV1::Rk45,
        enable_advanced_effects: resolved_request.effects.magnus
            || resolved_request.effects.coriolis,
        enable_magnus: resolved_request.effects.magnus,
        enable_coriolis: resolved_request.effects.coriolis,
        use_powder_sensitivity: false,
        powder_temp_sensitivity: 0.0,
        powder_temp: temperature_c,
        powder_temp_curve: None,
        powder_curve_temp_c: None,
        tipoff_yaw: 0.0,
        cd_delta2: 7.5,
        tipoff_decay_distance: 50.0,
        use_bc_segments: false,
        bc_segments: None,
        bc_segments_data: None,
        use_enhanced_spin_drift: resolved_request.effects.enhanced_spin_drift,
        use_form_factor: false,
        // Altitude-dependent wind shear (0.36.0). `enable_wind_shear` is derived from the
        // model rather than carried as its own request flag: `cli_api`'s shear branch maps
        // any name it does not recognize -- `"none"` included -- to the power law, so an
        // "enabled, model none" pair would silently run power-law shear. One field cannot
        // express that state.
        //
        // No shooter altitude is passed, and none exists to pass: this solve path runs on
        // `TrajectorySolver`, whose `get_wind_at_altitude` keys the boundary-layer profile off
        // height above the MUZZLE (McCoy Y plus an assumed 1.5 m muzzle height), and
        // `wind_shear::get_wind_at_position` -- the fast-integrate path's evaluator, which does
        // take a `shooter_altitude_m` -- discards it for the same reason. Shear is relative to
        // the local ground; `atmosphere.altitude_m` is height above SEA LEVEL, so feeding it in
        // would treat a shooter standing at 1500 m MSL as a bullet flying 1500 m above the
        // ground and inflate the ratio by an order of magnitude. `atmosphere.altitude_m`
        // continues to reach the solve exactly where it belongs, through `inputs.altitude`
        // above, as air density.
        enable_wind_shear: resolved_request
            .effects
            .wind_shear_model
            .is_some_and(WindShearModelV1::is_enabled),
        wind_shear_model: resolved_request
            .effects
            .wind_shear_model
            .unwrap_or_default()
            .as_engine_str()
            .to_owned(),
        enable_trajectory_sampling: false,
        sample_interval: resolved_request.sampling.interval_m,
        // MBA-1403: consumed straight from the request for the engine inputs here.
        // Separately echoed at ResolvedShotV1::drops_reference when supplied (0.33.0
        // decision-support Task 1), matching the zero-POI fields above. The engine-side
        // field is set for validation (target mode
        // rejects |shooting_angle| >= 90 deg inside validate_for_solve); the actual wire
        // transform is applied where observations map to samples in solve_v1, because this
        // solve path samples via TrajectoryResult::sample_observations, not the
        // trajectory-sampling module.
        drops_reference: match request.shot.drops_reference.unwrap_or_default() {
            crate::solve_json::DropsReferenceV1::Los => crate::cli_api::DropsReference::Los,
            crate::solve_json::DropsReferenceV1::Target => crate::cli_api::DropsReference::Target,
        },
        enable_pitch_damping: false,
        enable_precession_nutation: false,
        // MBA-959 / Alfredo Mendiola Loyola's change request: the JSON bridge's own switch,
        // where this used to be hardcoded false with no way for a caller to reach it.
        enable_aerodynamic_jump: resolved_request.effects.aerodynamic_jump.unwrap_or(false),
        use_cluster_bc: false,
        // MBA-1597: `projectile.drag_table` is installed just below, once these inputs exist —
        // the reference kind's scale reads their own sectional density, and a reference table
        // flown beside a BC ladder sets `custom_drag_reference` there instead.
        custom_drag_table: None,
        cd_scale: 1.0,
        custom_drag_reference: false,
        bc_type_str: None,
    };

    if let Some(drag_table) = &resolved_request.projectile.drag_table {
        install_drag_table(
            drag_table,
            resolved_request.projectile.ballistic_coefficient,
            resolved_request.projectile.bc_segments.is_some(),
            &mut inputs,
        )?;
    }

    apply_bc5d_correction(request, &resolved_request, &mut inputs, &mut warnings)?;
    apply_bc_segments(&resolved_request, &mut inputs)?;

    let atmosphere = AtmosphericConditions {
        temperature: temperature_c,
        pressure: pressure_hpa,
        humidity: humidity_percent,
        altitude: resolved_request.atmosphere.altitude_m,
    };

    Ok(PreparedSolveV1 {
        resolved_request,
        assumptions,
        warnings,
        inputs,
        wind,
        wind_segments,
        atmosphere,
    })
}

/// Install `projectile.drag_table` on the prepared engine inputs (MBA-1597).
///
/// The engine flies a custom table as the projectile's OWN drag coefficient divided by its
/// sectional density ([`BallisticInputs::custom_drag_denominator`]): the `projectile` kind, BC
/// unused, exactly as the CLI's `--drag-table`. A `reference` curve is instead a standard the
/// BC was measured against, which a built-in model flies as `Cd_ref / BC`. It is installed in
/// one of two ways, which fly that same quotient:
///
/// * Without a BC ladder, as the own-curve path with `cd_scale = SD / BC`. Since BC = SD / i,
///   `Cd_ref * SD / BC` is the projectile's own Cd, and the SD it is divided by is the very one
///   the scale was built from — no second retardation formula. This is the original MBA-1597
///   installation, kept unchanged so a request without a ladder solves byte-identically.
/// * With a BC ladder (`has_bc_ladder`), with [`BallisticInputs::custom_drag_reference`] set
///   and `cd_scale = 1.0`. The drag sites then divide the curve by the BC they resolve at each
///   speed, so the band BCs, the scalar in an interior gap and the smoothstep blending at the
///   band edges reach the table exactly as they reach a built-in model. One whole-curve scale
///   cannot carry a BC that changes from band to band.
///
/// Either installation is rebuilt from the request's BC on every prepare, so a kernel that
/// perturbs `ballistic_coefficient` and re-solves moves a reference-kind trajectory as it
/// moves a built-in one.
fn install_drag_table(
    drag_table: &DragTableV1,
    ballistic_coefficient: f64,
    has_bc_ladder: bool,
    inputs: &mut BallisticInputs,
) -> Result<(), SolveErrorEnvelopeV1> {
    let (mach, cd): (Vec<f64>, Vec<f64>) = drag_table
        .points
        .iter()
        .map(|point| (point.mach, point.cd))
        .unzip();
    // `resolve_projectile` has already applied the same rules with exact paths; this is the
    // engine's own gate, kept so a rule added there can never be skipped here.
    let table = crate::drag::DragTable::try_new(mach, cd)
        .map_err(|message| invalid_value("$.projectile.drag_table.points", message))?;
    inputs.cd_scale = match drag_table.kind {
        DragTableKindV1::Projectile => 1.0,
        // A ladder's band BC must reach the denominator at every speed, which the whole-curve
        // SD / BC scale below cannot carry, so the curve is flown as a built-in model is:
        // unscaled, over the BC each drag site resolves. Without a ladder the SD / BC arm
        // below is kept exactly as it was, so those solves stay byte-identical.
        DragTableKindV1::Reference if has_bc_ladder => {
            inputs.custom_drag_reference = true;
            1.0
        }
        DragTableKindV1::Reference => {
            let sectional_density = inputs.sectional_density_lb_in2().ok_or_else(|| {
                internal_error("projectile mass and diameter gave no sectional density")
            })?;
            sectional_density / ballistic_coefficient
        }
    };
    inputs.custom_drag_table = Some(table);
    Ok(())
}

/// Apply an optional BC5D offline correction (`$.corrections.bc5d_table_path`) to the
/// prepared engine inputs, mirroring the CLI's `--bc-table-dir` semantics exactly:
/// CRC-verified load, the same velocity-keyed segment ladder
/// ([`crate::bc_table_5d::Bc5dTable::generate_segments`], grains + fps axes), the
/// table's muzzle correction folded into the scalar `bc_value` as the interior-gap
/// fallback, and a G1 coercion warning for drag models outside the table's G1/G7
/// planes. Because `prepare_request` feeds both [`solve_v1`]'s zero search and the
/// trajectory (and the perturbation kernel), the zero is always solved with the SAME
/// schedule the flight uses — the 0.22.11 auto-zero lesson.
///
/// On wasm32 there is no filesystem: supplying the field is a structured
/// `invalid_value` error, never a silent no-op (WASM callers load table BYTES via
/// `loadBc5dTable` instead).
fn apply_bc5d_correction(
    request: &SolveRequestV1,
    resolved_request: &ResolvedSolveRequestV1,
    inputs: &mut BallisticInputs,
    warnings: &mut Vec<SolveNoticeV1>,
) -> Result<(), SolveErrorEnvelopeV1> {
    let Some(table_path) = request
        .corrections
        .as_ref()
        .and_then(|corrections| corrections.bc5d_table_path.as_deref())
    else {
        return Ok(());
    };

    #[cfg(target_arch = "wasm32")]
    {
        let _ = (table_path, resolved_request, inputs, warnings);
        Err(invalid_value(
            "$.corrections.bc5d_table_path",
            "bc5d_table_path is not supported on this build (no filesystem access); \
             load table bytes through the WASM loadBc5dTable API instead",
        ))
    }

    #[cfg(not(target_arch = "wasm32"))]
    {
        use crate::bc_table_5d::{path_cache, Bc5dError};

        // Identity, not just integrity: the table's header caliber must be this shot's
        // caliber. A wrong-caliber table is worse than no table, because every lookup
        // still succeeds (edge-bin clamping) and silently biases every row — so it is
        // refused as an invalid_value at the field that named it, never applied and
        // never downgraded to a silent uncorrected solve. See
        // `Bc5dTable::ensure_caliber_matches`.
        let shot_caliber_in = resolved_request.projectile.diameter_m / 0.0254;
        let table = path_cache::load_verified_for_caliber(
            std::path::Path::new(table_path),
            shot_caliber_in,
        )
        .map_err(|error| {
            let code = match error {
                Bc5dError::IoError(_) => SolveErrorCodeV1::IoError,
                _ => SolveErrorCodeV1::InvalidValue,
            };
            SolveErrorEnvelopeV1::new(
                SolveErrorV1::new(code, format!("bc5d_table_path: {error}"))
                    .at_path("$.corrections.bc5d_table_path"),
            )
        })?;

        // The v2 BC5D tables carry only G1/G7 planes; every other reference model is
        // typed as G1, with the same warning surface as the CLI/WASM aux paths.
        let drag_type = match resolved_request.projectile.drag_model {
            DragModelV1::G7 => "G7",
            DragModelV1::G1 => "G1",
            other => {
                warnings.push(SolveNoticeV1 {
                    code: WARNING_BC5D_DRAG_MODEL_COERCED.to_owned(),
                    message: format!(
                        "BC5D correction tables support G1/G7 only; treating drag model \
                         {other:?} as G1 for the table lookup"
                    ),
                    path: Some("$.corrections.bc5d_table_path".to_owned()),
                });
                "G1"
            }
        };

        // Table axes are grains and fps; the prepared inputs already carry both
        // conversions (the same checked ones the summary diagnostics use).
        let base_bc = resolved_request.projectile.ballistic_coefficient;
        let weight_grains = inputs.weight_grains;
        let muzzle_fps = resolved_request.rifle.muzzle_velocity_mps / 0.3048;

        if let Some(segments) =
            table.generate_segments(base_bc, drag_type, weight_grains, Some(muzzle_fps))
        {
            // CLI parity (main.rs `--bc-table-dir`): the scalar BC becomes the
            // muzzle-corrected fallback for interior coverage gaps.
            inputs.bc_value =
                table.get_effective_bc(weight_grains, base_bc, muzzle_fps, muzzle_fps, drag_type);
            inputs.use_bc_segments = true;
            inputs.bc_segments_data = Some(segments);
        }
        // A neutral table (no meaningful correction for this load) leaves the
        // published constant BC in place, exactly like the CLI.
        Ok(())
    }
}

/// Install a `projectile.bc_segments` ladder (MBA-1598) on the prepared inputs, converting its
/// m/s band edges to the fps the engine's `BCSegmentData` is keyed in. Without a ladder this
/// is a no-op.
///
/// The scalar `bc_value` is left untouched, exactly as the CLI's `--bc-segment` and `card.*`
/// leave it; the correction path above, by contrast, rewrites `bc_value`. The engine flies the
/// scalar only in an interior gap between two bands, and blended into the bands within up to
/// 25 fps either side of a gap edge. Below the lowest band, or at or above the highest, the
/// nearest edge band applies, so under a gapless ladder the scalar never flies.
/// Band BCs are referenced to `drag_model`'s curve, or to the drag table's curve when the table
/// is `reference`-kind, bands are selected by airspeed (speed relative to the air mass), and
/// every interior band edge and gap edge is smoothstep-blended (`velocity_segment_bc` in
/// `src/bc_estimation.rs`). The lookup does not depend on the array
/// order; the fastest-first order is only a validation rule.
fn apply_bc_segments(
    resolved_request: &ResolvedSolveRequestV1,
    inputs: &mut BallisticInputs,
) -> Result<(), SolveErrorEnvelopeV1> {
    let Some(bc_segments) = &resolved_request.projectile.bc_segments else {
        return Ok(());
    };

    let segments: Vec<crate::BCSegmentData> = bc_segments
        .iter()
        .map(|seg| crate::BCSegmentData {
            velocity_min: seg.velocity_min_mps / 0.3048,
            velocity_max: seg.velocity_max_mps / 0.3048,
            bc_value: seg.ballistic_coefficient,
        })
        .collect();

    inputs.use_bc_segments = true;
    inputs.bc_segments_data = Some(segments);
    Ok(())
}

fn resolve_projectile(
    projectile: &ProjectileV1,
    assumptions: &mut Vec<SolveNoticeV1>,
) -> Result<(ResolvedProjectileV1, f64), SolveErrorEnvelopeV1> {
    require_positive("$.projectile.mass_kg", projectile.mass_kg)?;
    require_positive("$.projectile.diameter_m", projectile.diameter_m)?;
    require_positive(
        "$.projectile.ballistic_coefficient",
        projectile.ballistic_coefficient,
    )?;
    if let Some(length_m) = projectile.length_m {
        require_positive("$.projectile.length_m", length_m)?;
    }
    if let Some(drag_table) = &projectile.drag_table {
        crate::solve_json::validate_drag_table_v1(drag_table)?;
    }
    if let Some(bc_segments) = &projectile.bc_segments {
        crate::solve_json::validate_bc_segments_v1(bc_segments, projectile.ballistic_coefficient)?;
    }

    let bullet_length_m = match projectile.length_m {
        Some(length_m) => length_m,
        None => {
            let estimated = crate::stability::estimate_bullet_length_m(
                projectile.diameter_m,
                projectile.mass_kg,
            );
            if !estimated.is_finite() || estimated <= 0.0 {
                return Err(invalid_value(
                    "$.projectile",
                    "projectile mass and diameter could not produce a finite positive length estimate",
                ));
            }
            assumptions.push(notice(
                ASSUMPTION_ESTIMATED_PROJECTILE_LENGTH,
                format!(
                    "Projectile length was omitted; the engine estimated {estimated:.12} m from mass and diameter."
                ),
                "$.projectile.length_m",
            ));
            estimated
        }
    };

    Ok((
        ResolvedProjectileV1 {
            mass_kg: projectile.mass_kg,
            diameter_m: projectile.diameter_m,
            length_m: projectile.length_m,
            drag_model: projectile.drag_model,
            ballistic_coefficient: projectile.ballistic_coefficient,
            drag_table: projectile.drag_table.clone(),
            bc_segments: projectile.bc_segments.clone(),
        },
        bullet_length_m,
    ))
}

fn resolve_rifle(
    rifle: &RifleV1,
    assumptions: &mut Vec<SolveNoticeV1>,
) -> Result<ResolvedRifleV1, SolveErrorEnvelopeV1> {
    require_positive("$.rifle.muzzle_velocity_mps", rifle.muzzle_velocity_mps)?;
    if let Some(value) = rifle.sight_height_m {
        require_non_negative("$.rifle.sight_height_m", value)?;
    }
    if let Some(value) = rifle.muzzle_height_m {
        require_finite("$.rifle.muzzle_height_m", value)?;
    }
    if let Some(value) = rifle.twist_rate_m_per_turn {
        require_positive("$.rifle.twist_rate_m_per_turn", value)?;
    }
    // MBA-1396: validated here but NOT resolved through `literal_default` — an absence
    // notice would change the response bytes of every request that predates the field.
    // Consumed directly into the engine inputs, and separately echoed on the resolved
    // DTO at ResolvedRifleV1::sight_offset_lateral_m when supplied (0.33.0
    // decision-support Task 1); omitting it still stays byte-identical to requests that
    // predate the field.
    if let Some(value) = rifle.sight_offset_lateral_m {
        require_finite("$.rifle.sight_offset_lateral_m", value)?;
        if value.abs() >= 0.5 {
            return Err(invalid_value(
                "$.rifle.sight_offset_lateral_m",
                "lateral sight offset must be smaller than 0.5 m in magnitude (the \
                 sight-to-bore mount offset, in meters)",
            ));
        }
    }

    let sight_height_m = literal_default(
        rifle.sight_height_m,
        DEFAULT_SIGHT_HEIGHT_M,
        "$.rifle.sight_height_m",
        "Sight height defaulted to 0.05 m.",
        assumptions,
    );
    let muzzle_height_m = literal_default(
        rifle.muzzle_height_m,
        DEFAULT_MUZZLE_HEIGHT_M,
        "$.rifle.muzzle_height_m",
        "Muzzle height defaulted to 0 m.",
        assumptions,
    );
    let twist_rate_m_per_turn = literal_default(
        rifle.twist_rate_m_per_turn,
        DEFAULT_TWIST_RATE_M_PER_TURN,
        "$.rifle.twist_rate_m_per_turn",
        "Twist rate defaulted to 0.3048 m per turn.",
        assumptions,
    );
    let twist_direction = match rifle.twist_direction {
        Some(direction) => direction,
        None => {
            assumptions.push(notice(
                ASSUMPTION_DEFAULT_APPLIED,
                "Twist direction defaulted to right-hand.",
                "$.rifle.twist_direction",
            ));
            TwistDirectionV1::Right
        }
    };

    Ok(ResolvedRifleV1 {
        muzzle_velocity_mps: rifle.muzzle_velocity_mps,
        sight_height_m,
        muzzle_height_m,
        twist_rate_m_per_turn,
        twist_direction,
        // MBA-1396: pure pass-through echo (Task 1 of the 0.33.0 decision-support train) — no
        // defaulting, no unit conversion. Validated above.
        sight_offset_lateral_m: rifle.sight_offset_lateral_m,
    })
}

fn resolve_shot(
    shot: &ShotV1,
    rifle: &ResolvedRifleV1,
    assumptions: &mut Vec<SolveNoticeV1>,
    warnings: &mut Vec<SolveNoticeV1>,
) -> Result<ResolvedShotV1, SolveErrorEnvelopeV1> {
    let muzzle_height_m = rifle.muzzle_height_m;
    require_positive("$.shot.max_range_m", shot.max_range_m)?;
    if let Some(value) = shot.zero_distance_m {
        require_positive("$.shot.zero_distance_m", value)?;
        if !(value * 2.0).is_finite() {
            return Err(invalid_value(
                "$.shot.zero_distance_m",
                "zero distance is too large to construct a finite trial trajectory range",
            ));
        }
    }
    if let Some(value) = shot.muzzle_angle_rad {
        require_finite("$.shot.muzzle_angle_rad", value)?;
    }
    // 0.33.0 decision-support Task 2: both fields may be supplied together. This used to be
    // a conflicting_fields error, but `From<&ResolvedSolveRequestV1> for SolveRequestV1`
    // (request_roundtrip.rs) always carries both when the original request solved a zero --
    // zero_distance_m as caller intent, muzzle_angle_rad as the effective angle already
    // found -- so a rebuilt request can reuse that exact angle without re-running the
    // elevation search. The match below already gives muzzle_angle_rad priority whenever it
    // is present, with or without zero_distance_m alongside it; solve_v1 mirrors that
    // priority by skipping the elevation search whenever an explicit angle was supplied.
    // zero_distance_m no longer re-derives the elevation in that case, but it is not
    // otherwise inert: solve_v1 still applies the separate windage-zero convergence bias
    // (sight_offset_lateral_m / zero_poi_right_m) gated on it, it still widens the required
    // wind coverage below, it is still validated above, and it still feeds
    // summary.equivalent_horizontal_range_m. A warning names this explicitly (below).

    for (path, value) in [
        ("$.shot.aim_azimuth_rad", shot.aim_azimuth_rad),
        ("$.shot.shot_azimuth_rad", shot.shot_azimuth_rad),
        ("$.shot.shooting_angle_rad", shot.shooting_angle_rad),
        ("$.shot.cant_angle_rad", shot.cant_angle_rad),
        ("$.shot.target_height_m", shot.target_height_m),
        ("$.shot.ground_threshold_m", shot.ground_threshold_m),
    ] {
        if let Some(value) = value {
            require_finite(path, value)?;
        }
    }

    // MBA-1359: deliberate POI offset at the zero range (Kestrel ZH/ZO). Validated here but
    // NOT resolved through `literal_default`: emitting an absence notice would change the
    // response bytes of every request that predates these fields. They are consumed
    // directly into the engine inputs, and separately echoed on the resolved DTO at
    // ResolvedShotV1::zero_poi_up_m / zero_poi_right_m when supplied (0.33.0
    // decision-support Task 1); omitting them still stays byte-identical to requests that
    // predate these fields.
    for (path, value) in [
        ("$.shot.zero_poi_up_m", shot.zero_poi_up_m),
        ("$.shot.zero_poi_right_m", shot.zero_poi_right_m),
    ] {
        if let Some(value) = value {
            require_finite(path, value)?;
            if value.abs() >= 1.0 {
                return Err(invalid_value(
                    path,
                    "zero POI offset must be smaller than 1.0 m in magnitude (a linear \
                     point-of-impact offset at the zero range, in meters)",
                ));
            }
        }
    }

    // MBA-1537: exactly the condition under which `build_zeroed_solver` runs the elevation
    // search, named once so the zero-frame default below cannot drift out of step with the
    // match that decides it.
    let elevation_search_runs = shot.zero_distance_m.is_some() && shot.muzzle_angle_rad.is_none();

    let muzzle_angle_rad = match (shot.zero_distance_m, shot.muzzle_angle_rad) {
        // An explicit angle always wins over zero_distance_m for elevation (0.33.0
        // decision-support Task 2). When both are supplied, note that the elevation search
        // did not run -- zero_distance_m is still retained and still has other effects (see
        // the warning message), but a caller relying on a stale muzzle_angle_rad while
        // setting a new zero_distance_m should not mistake the echo for confirmation that a
        // zero was actually solved.
        (Some(_), Some(angle)) => {
            warnings.push(notice(
                WARNING_ZERO_DISTANCE_ELEVATION_NOT_RESOLVED,
                "muzzle_angle_rad was supplied together with zero_distance_m: the elevation \
                 was used directly and the elevation search did not run. zero_distance_m is \
                 retained in resolved_request and still affects the windage-convergence bias \
                 (sight_offset_lateral_m / zero_poi_right_m), summary.equivalent_horizontal_range_m, \
                 and downrange wind-coverage validation.",
                "$.shot.zero_distance_m",
            ));
            angle
        }
        (None, Some(angle)) => angle,
        (Some(_), None) => 0.0, // Replaced with the calculated effective angle before solving.
        (None, None) => {
            assumptions.push(notice(
                ASSUMPTION_DEFAULT_APPLIED,
                "Muzzle angle defaulted to 0 rad.",
                "$.shot.muzzle_angle_rad",
            ));
            0.0
        }
    };
    let aim_azimuth_rad = literal_default(
        shot.aim_azimuth_rad,
        0.0,
        "$.shot.aim_azimuth_rad",
        "Aim azimuth defaulted to 0 rad.",
        assumptions,
    );
    let shot_azimuth_rad = literal_default(
        shot.shot_azimuth_rad,
        0.0,
        "$.shot.shot_azimuth_rad",
        "Shot azimuth defaulted to 0 rad (north).",
        assumptions,
    );
    let shooting_angle_rad = literal_default(
        shot.shooting_angle_rad,
        0.0,
        "$.shot.shooting_angle_rad",
        "Shooting angle defaulted to 0 rad.",
        assumptions,
    );
    let cant_angle_rad = literal_default(
        shot.cant_angle_rad,
        0.0,
        "$.shot.cant_angle_rad",
        "Cant angle defaulted to 0 rad.",
        assumptions,
    );
    // MBA-1537: when the elevation search runs and no target height was supplied, the height
    // the search converges on is the LINE OF SIGHT, not the ground datum.
    //
    // `target_height_m` is a world-vertical height above the local ground datum, and the line
    // of sight of a level rifle sits `muzzle_height_m + sight_height_m` above that datum -- the
    // same sum `TrajectoryResult::line_of_sight_height_m` reports and the same sum the sampler
    // uses as its LOS datum. Defaulting to a flat `0` aimed the search at the ground instead,
    // which put the bullet a full line-of-sight height LOW at the caller's stated zero: it
    // never crossed the line of sight at all. It also made `sight_height_m` inert -- the solved
    // angle was identical for every sight height -- and made the answer a function of
    // `muzzle_height_m`, which it physically is not: heights above the ground cancel once the
    // target tracks the line of sight. A raised muzzle stopped converging altogether once it
    // cleared the bullet's own drop over the zero distance (measured for a .308 at 100 yd:
    // 0.07 m still converges, 0.08 m does not; the drop over 91.44 m is 0.0661 m),
    // because the ground datum it was aiming at then sits below the muzzle.
    //
    // This is the height the `ZeroTargetFrame::SightLine` surfaces already use. `cli_api`'s
    // `calculate_zero_angle_with_conditions` solves against whatever target height its caller
    // hands it; the CLI hands it bore + sight (main.rs:8263), which is this sum. `ffi.rs`'s
    // `ballistics_calculate_zero_angle`
    // both solve against the sight height (the same sum, for their `muzzle_height` of 0).
    // Moving the default here is what makes them agree.
    //
    // Gated on the search actually running rather than on `zero_distance_m` alone: a request
    // that supplies `muzzle_angle_rad` uses that angle directly, so there is no zero to frame,
    // and such a request stays byte-identical -- assumption text, resolved echo and all.
    // Without a zero search `target_height_m` feeds only the `drops_reference: "target"`
    // sampler datum, which has its own distance reference (the target sits at `max_range_m`,
    // not at `zero_distance_m`); keeping the historical `0` there leaves that mode untouched.
    //
    // This is the LEVEL line of sight, and deliberately not projected by `shooting_angle_rad`
    // into the inclined sight line. Two reasons: the same field is the target-drops sampler's
    // LOS datum, where it is referenced to `max_range_m` rather than to `zero_distance_m`, so a
    // default computed at the zero distance would silently slope that datum over the wrong
    // span; and at `shooting_angle_rad == 0` the level form equals `sight_position_m` bit for
    // bit, which is what keeps that mode untouched here. An inclined zero therefore still has
    // to state its own target height -- `docs/SOLVE_JSON_V1.md` gives the projection, and
    // `tests/zero_sight_line_default.rs` pins both halves of that.
    let target_height_m = if elevation_search_runs {
        match shot.target_height_m {
            Some(value) => value,
            None => {
                let line_of_sight_m = muzzle_height_m + rifle.sight_height_m;
                assumptions.push(notice(
                    ASSUMPTION_DEFAULT_APPLIED,
                    format!(
                        "Target height defaulted to the line of sight, {line_of_sight_m} m above \
                         the local ground datum (muzzle_height_m + sight_height_m), so the solved \
                         elevation crosses the line of sight at zero_distance_m. Supply \
                         target_height_m explicitly -- 0 included -- to zero against the ground \
                         datum instead."
                    ),
                    "$.shot.target_height_m",
                ));
                line_of_sight_m
            }
        }
    } else {
        literal_default(
            shot.target_height_m,
            0.0,
            "$.shot.target_height_m",
            "Target height defaulted to 0 m above the local ground datum.",
            assumptions,
        )
    };
    let ground_threshold_m = literal_default(
        shot.ground_threshold_m,
        DEFAULT_GROUND_THRESHOLD_M,
        "$.shot.ground_threshold_m",
        "Ground threshold defaulted to -100 m.",
        assumptions,
    );
    if ground_threshold_m >= muzzle_height_m {
        return Err(invalid_value(
            "$.shot.ground_threshold_m",
            "ground threshold must be below the resolved muzzle height",
        ));
    }

    Ok(ResolvedShotV1 {
        max_range_m: shot.max_range_m,
        zero_distance_m: shot.zero_distance_m,
        muzzle_angle_rad,
        aim_azimuth_rad,
        shot_azimuth_rad,
        shooting_angle_rad,
        cant_angle_rad,
        target_height_m,
        ground_threshold_m,
        // MBA-1359/MBA-1403: pure pass-through echoes (Task 1 of the 0.33.0 decision-support
        // train) — no defaulting, no unit conversion. Validated above.
        zero_poi_up_m: shot.zero_poi_up_m,
        zero_poi_right_m: shot.zero_poi_right_m,
        drops_reference: shot.drops_reference,
    })
}

/// Resolve a solve-json v1 atmosphere exactly as a solve does: validate with `$.atmosphere.*`
/// paths, default what was omitted (announcing each default in `assumptions`), and reduce a
/// QNH to station pressure. Shared with `atmosphere.density_altitude` so that command
/// describes precisely the air a solve with the same `atmosphere` object would fly through.
pub(crate) fn resolve_atmosphere(
    atmosphere: &AtmosphereV1,
    assumptions: &mut Vec<SolveNoticeV1>,
) -> Result<ResolvedAtmosphereV1, SolveErrorEnvelopeV1> {
    if let Some(value) = atmosphere.altitude_m {
        require_range(
            "$.atmosphere.altitude_m",
            value,
            MIN_ICAO_ALTITUDE_M,
            MAX_ICAO_ALTITUDE_M,
        )?;
    }
    if let Some(value) = atmosphere.temperature_k {
        require_positive("$.atmosphere.temperature_k", value)?;
    }
    if let Some(value) = atmosphere.pressure_pa {
        require_positive("$.atmosphere.pressure_pa", value)?;
    }
    if let Some(value) = atmosphere.relative_humidity {
        require_range("$.atmosphere.relative_humidity", value, 0.0, 1.0)?;
    }
    if let Some(value) = atmosphere.latitude_rad {
        require_range(
            "$.atmosphere.latitude_rad",
            value,
            -std::f64::consts::FRAC_PI_2,
            std::f64::consts::FRAC_PI_2,
        )?;
    }

    let altitude_m = match atmosphere.altitude_m {
        Some(value) => value,
        None => {
            assumptions.push(notice(
                ASSUMPTION_DEFAULT_APPLIED,
                "Station altitude defaulted to 0 m.",
                "$.atmosphere.altitude_m",
            ));
            DEFAULT_ALTITUDE_M
        }
    };
    let (standard_temperature_k, standard_pressure_pa) =
        crate::atmosphere::calculate_icao_standard_atmosphere(altitude_m);
    let temperature_k = match atmosphere.temperature_k {
        Some(value) => value,
        None => {
            assumptions.push(notice(
                ASSUMPTION_ICAO_STANDARD_TEMPERATURE,
                format!(
                    "Station temperature was omitted; ICAO standard temperature at {altitude_m:.6} m is {standard_temperature_k:.12} K."
                ),
                "$.atmosphere.temperature_k",
            ));
            standard_temperature_k
        }
    };
    let pressure_pa = match atmosphere.pressure_pa {
        // MBA-1397: an explicit pressure declared as a QNH (sea-level-corrected altimeter
        // setting) is reduced to station pressure at `altitude_m` before use. `Absolute`
        // (including the omitted-field default) is a pure passthrough -- byte-identical to
        // pre-MBA-1397 behavior for every request that never sets `pressure_reference`.
        Some(value) if atmosphere.pressure_reference == Some(PressureReferenceV1::Qnh) => {
            let qnh_hpa = value / PASCALS_PER_HECTOPASCAL;
            let station_hpa =
                crate::atmosphere::reduce_qnh_to_station_pressure(qnh_hpa, altitude_m);
            let station_pa = station_hpa * PASCALS_PER_HECTOPASCAL;
            assumptions.push(notice(
                ASSUMPTION_QNH_REDUCED_TO_STATION_PRESSURE,
                format!(
                    "Station pressure was declared as a QNH (sea-level-corrected altimeter \
                     setting) of {value:.6} Pa; reduced to station pressure {station_pa:.12} Pa \
                     at {altitude_m:.6} m via the ICAO inverse-barometric formula."
                ),
                "$.atmosphere.pressure_pa",
            ));
            station_pa
        }
        Some(value) => value,
        None => {
            assumptions.push(notice(
                ASSUMPTION_ICAO_STANDARD_PRESSURE,
                format!(
                    "Station pressure was omitted; ICAO standard pressure at {altitude_m:.6} m is {standard_pressure_pa:.12} Pa."
                ),
                "$.atmosphere.pressure_pa",
            ));
            standard_pressure_pa
        }
    };
    let relative_humidity = literal_default(
        atmosphere.relative_humidity,
        DEFAULT_RELATIVE_HUMIDITY,
        "$.atmosphere.relative_humidity",
        "Relative humidity defaulted to 0.5.",
        assumptions,
    );

    Ok(ResolvedAtmosphereV1 {
        altitude_m,
        temperature_k,
        pressure_pa,
        relative_humidity,
        latitude_rad: atmosphere.latitude_rad,
        // MBA-1397: pure pass-through echo (Task 1 of the 0.33.0 decision-support train) — the
        // mode itself is not resolved to a literal default; only its effect on `pressure_pa`
        // above is (see the QNH-reduction branch).
        pressure_reference: atmosphere.pressure_reference,
    })
}

fn resolve_wind(
    wind: &WindV1,
    coverage_distance_m: f64,
    request_shot_azimuth_rad: Option<f64>,
    assumptions: &mut Vec<SolveNoticeV1>,
    warnings: &mut Vec<SolveNoticeV1>,
) -> Result<(ResolvedWindV1, WindConditions, Vec<WindSegment>), SolveErrorEnvelopeV1> {
    // MBA-1368: resolve the entry frame ONCE, before any direction is consumed.
    // Omitted == shooter, byte-identical with no assumption notice (the Batch A
    // additive-field precedent: a notice would change every pre-existing response).
    // In compass mode every direction below passes through `to_relative` BEFORE the
    // resolved echo and the engine structures are built, so downstream physics (and
    // the response) only ever see shooter-relative wind-FROM radians — the QNH
    // fold-into-the-resolved-value precedent.
    let compass_azimuth_rad = match wind.wind_reference.unwrap_or_default() {
        WindReferenceV1::Shooter => None,
        WindReferenceV1::Compass => match request_shot_azimuth_rad {
            Some(azimuth) => Some(azimuth),
            None => {
                return Err(conflicting_fields(
                    "$.wind.wind_reference",
                    "wind_reference \"compass\" requires shot.shot_azimuth_rad (earth-fixed \
                     bearings are re-referenced against the shot azimuth; omitting it would \
                     silently treat bearings as shooter-relative)",
                ))
            }
        },
    };
    let to_relative = |bearing_rad: f64| -> f64 {
        match compass_azimuth_rad {
            Some(azimuth) => {
                crate::wind::compass_bearing_to_shooter_relative_rad(bearing_rad, azimuth)
            }
            None => bearing_rad,
        }
    };

    if let Some(segments) = &wind.segments {
        if wind.speed_mps.is_some()
            || wind.direction_from_rad.is_some()
            || wind.vertical_speed_mps.is_some()
        {
            return Err(conflicting_fields(
                "$.wind",
                "segments cannot be combined with constant-wind fields",
            ));
        }
        if segments.is_empty() {
            return Err(invalid_value(
                "$.wind.segments",
                "segmented wind must contain at least one segment",
            ));
        }

        let mut resolved_segments = Vec::with_capacity(segments.len());
        let mut engine_segments = Vec::with_capacity(segments.len());
        let mut previous_until_m = 0.0;
        for (index, segment) in segments.iter().enumerate() {
            let base = format!("$.wind.segments[{index}]");
            require_positive(
                &format!("{base}.until_distance_m"),
                segment.until_distance_m,
            )?;
            require_non_negative(&format!("{base}.speed_mps"), segment.speed_mps)?;
            require_finite(
                &format!("{base}.direction_from_rad"),
                segment.direction_from_rad,
            )?;
            if let Some(value) = segment.vertical_speed_mps {
                require_finite(&format!("{base}.vertical_speed_mps"), value)?;
            }
            if index > 0 && segment.until_distance_m <= previous_until_m {
                return Err(invalid_value(
                    format!("{base}.until_distance_m"),
                    "wind-segment boundaries must be strictly increasing",
                ));
            }
            previous_until_m = segment.until_distance_m;

            let vertical_speed_mps = match segment.vertical_speed_mps {
                Some(value) => value,
                None => {
                    assumptions.push(notice(
                        ASSUMPTION_DEFAULT_APPLIED,
                        "Segment vertical wind speed defaulted to 0 m/s.",
                        format!("{base}.vertical_speed_mps"),
                    ));
                    0.0
                }
            };
            let speed_kmh = checked_conversion(
                segment.speed_mps * SECONDS_PER_HOUR * KILOMETRES_PER_METRE,
                &format!("{base}.speed_mps"),
                "wind speed conversion to kilometres per hour overflowed",
            )?;
            // MBA-1368: compass bearings become shooter-relative HERE, so both the
            // resolved echo and the engine segment carry the converted direction.
            let direction_from_rad = to_relative(segment.direction_from_rad);
            let angle_deg = checked_conversion(
                direction_from_rad.to_degrees(),
                &format!("{base}.direction_from_rad"),
                "wind direction conversion to degrees overflowed",
            )?;

            resolved_segments.push(ResolvedWindSegmentV1 {
                until_distance_m: segment.until_distance_m,
                speed_mps: segment.speed_mps,
                direction_from_rad,
                vertical_speed_mps,
            });
            engine_segments.push(WindSegment {
                speed_kmh,
                angle_deg,
                until_m: segment.until_distance_m,
                vertical_mps: vertical_speed_mps,
            });
        }

        let final_until_m = resolved_segments
            .last()
            .expect("non-empty segmented wind was checked")
            .until_distance_m;
        if final_until_m < coverage_distance_m {
            warnings.push(notice(
                WARNING_PARTIAL_WIND_COVERAGE,
                format!(
                    "Segmented wind ends at {final_until_m:.12} m; wind is calm from that boundary through the required {coverage_distance_m:.12} m solve/zero range."
                ),
                "$.wind.segments",
            ));
        }

        Ok((
            ResolvedWindV1::Segmented(ResolvedSegmentedWindV1 {
                segments: resolved_segments,
                // MBA-1368: pure pass-through echo (Task 1 of the 0.33.0 decision-support
                // train) — the mode itself is not resolved to a literal default; only its
                // effect on each segment's `direction_from_rad` above is (see `to_relative`).
                wind_reference: wind.wind_reference,
            }),
            WindConditions::default(),
            engine_segments,
        ))
    } else {
        match (wind.speed_mps, wind.direction_from_rad) {
            (Some(_), None) | (None, Some(_)) => {
                return Err(conflicting_fields(
                    "$.wind",
                    "speed_mps and direction_from_rad must be supplied together",
                ));
            }
            (None, None) if wind.vertical_speed_mps.is_some() => {
                return Err(conflicting_fields(
                    "$.wind",
                    "vertical_speed_mps requires speed_mps and direction_from_rad",
                ));
            }
            _ => {}
        }

        if let Some(value) = wind.speed_mps {
            require_non_negative("$.wind.speed_mps", value)?;
        }
        if let Some(value) = wind.direction_from_rad {
            require_finite("$.wind.direction_from_rad", value)?;
        }
        if let Some(value) = wind.vertical_speed_mps {
            require_finite("$.wind.vertical_speed_mps", value)?;
        }

        let (speed_mps, direction_from_rad, vertical_speed_mps) =
            if let (Some(speed), Some(direction)) = (wind.speed_mps, wind.direction_from_rad) {
                let vertical = match wind.vertical_speed_mps {
                    Some(value) => value,
                    None => {
                        assumptions.push(notice(
                            ASSUMPTION_DEFAULT_APPLIED,
                            "Constant vertical wind speed defaulted to 0 m/s.",
                            "$.wind.vertical_speed_mps",
                        ));
                        0.0
                    }
                };
                (speed, to_relative(direction), vertical)
            } else {
                assumptions.push(notice(
                    ASSUMPTION_DEFAULT_APPLIED,
                    "Wind defaulted to still air.",
                    "$.wind",
                ));
                (0.0, 0.0, 0.0)
            };

        Ok((
            ResolvedWindV1::Constant(ResolvedConstantWindV1 {
                speed_mps,
                direction_from_rad,
                vertical_speed_mps,
                // MBA-1368: pure pass-through echo (Task 1 of the 0.33.0 decision-support
                // train) — the mode itself is not resolved to a literal default; only its
                // effect on `direction_from_rad` above is (see `to_relative`).
                wind_reference: wind.wind_reference,
            }),
            WindConditions {
                speed: speed_mps,
                direction: direction_from_rad,
                vertical_speed: vertical_speed_mps,
            },
            Vec::new(),
        ))
    }
}

fn resolve_solver(
    solver: &SolverV1,
    assumptions: &mut Vec<SolveNoticeV1>,
    warnings: &mut Vec<SolveNoticeV1>,
) -> Result<ResolvedSolverV1, SolveErrorEnvelopeV1> {
    if let Some(value) = solver.time_step_s {
        require_positive("$.solver.time_step_s", value)?;
    }
    let method = match solver.method {
        Some(method) => method,
        None => {
            assumptions.push(notice(
                ASSUMPTION_DEFAULT_APPLIED,
                "Solver method defaulted to adaptive RK45.",
                "$.solver.method",
            ));
            SolverMethodV1::Rk45
        }
    };
    let time_step_s = literal_default(
        solver.time_step_s,
        DEFAULT_TIME_STEP_S,
        "$.solver.time_step_s",
        "Solver time step defaulted to 0.001 s.",
        assumptions,
    );
    if method == SolverMethodV1::Rk45 && solver.time_step_s.is_some() {
        warnings.push(notice(
            WARNING_RK45_TIME_STEP_IGNORED,
            "Adaptive RK45 owns its time step; the explicitly supplied fixed time step is retained in resolved_request but ignored by integration.",
            "$.solver.time_step_s",
        ));
    }

    Ok(ResolvedSolverV1 {
        method,
        time_step_s,
    })
}

fn resolve_effects(
    effects: &EffectsV1,
    latitude_rad: Option<f64>,
    geometry: SuppliedGeometry,
    assumptions: &mut Vec<SolveNoticeV1>,
    warnings: &mut Vec<SolveNoticeV1>,
) -> Result<ResolvedEffectsV1, SolveErrorEnvelopeV1> {
    let magnus = bool_default(
        effects.magnus,
        "$.effects.magnus",
        "Magnus effect defaulted to disabled.",
        assumptions,
    );
    let coriolis = bool_default(
        effects.coriolis,
        "$.effects.coriolis",
        "Coriolis effect defaulted to disabled.",
        assumptions,
    );
    let enhanced_spin_drift = bool_default(
        effects.enhanced_spin_drift,
        "$.effects.enhanced_spin_drift",
        "Enhanced spin drift defaulted to disabled.",
        assumptions,
    );

    if magnus && enhanced_spin_drift {
        return Err(conflicting_fields(
            "$.effects",
            "magnus and enhanced_spin_drift cannot both be enabled",
        ));
    }
    if coriolis && latitude_rad.is_none() {
        return Err(invalid_value(
            "$.atmosphere.latitude_rad",
            "latitude_rad is required when the Coriolis effect is enabled",
        ));
    }

    // Aerodynamic jump (MBA-959). Like `wind_shear_model` and unlike the three booleans
    // above, this is NOT run through `bool_default`: an omitted field pushes no assumption
    // notice and leaves the echo absent, so every request written before the field existed
    // still serializes byte-identically. `enabled_aerodynamic_jump` is what the solver acts
    // on; `aerodynamic_jump` is what the echo carries, and they differ precisely when the
    // caller said `false` out loud.
    let aerodynamic_jump = effects.aerodynamic_jump;
    let enabled_aerodynamic_jump = aerodynamic_jump.unwrap_or(false);

    for (enabled, path, name) in [
        (magnus, "$.effects.magnus", "Magnus"),
        (
            enhanced_spin_drift,
            "$.effects.enhanced_spin_drift",
            "enhanced spin drift",
        ),
        (
            enabled_aerodynamic_jump,
            "$.effects.aerodynamic_jump",
            "aerodynamic jump",
        ),
    ] {
        if enabled {
            warnings.push(notice(
                WARNING_EXPERIMENTAL_EFFECT,
                format!("The {name} effect is an opt-in experimental v1 model."),
                path,
            ));
        }
    }

    // MBA-1484. Magnus and enhanced spin drift are both functions of the spin the rifling
    // imparts, so an omitted twist does not leave either of them alone -- it solves them
    // against the assumed 1:12 barrel with the same confidence as a stated one. Emitted at the
    // flag that made the twist load-bearing, the way the aerodynamic-jump warning below is.
    //
    // The two flags are mutually exclusive here (the `conflicting_fields` check above returns
    // before this point), so the loop pushes at most one notice; it is written as a loop
    // anyway so that a future third spin-driven flag cannot quietly go unwarned.
    //
    // `summary.stability_factor` also reads the twist, on every solve rather than on a flag,
    // so it cannot be covered from here -- it is warned separately in `solve_v1` under
    // WARNING_STABILITY_FACTOR_ASSUMED_TWIST_RATE, gated on Sg having actually been reported.
    // The two codes both fire when a spin effect is enabled without a stated twist; they are
    // distinct so each names its own consumer, not because they are mutually exclusive.
    for (enabled, path, name) in [
        (magnus, "$.effects.magnus", "Magnus"),
        (
            enhanced_spin_drift,
            "$.effects.enhanced_spin_drift",
            "Enhanced spin drift",
        ),
    ] {
        if enabled && !geometry.twist_rate {
            warnings.push(notice(
                WARNING_SPIN_EFFECT_ASSUMED_TWIST_RATE,
                format!(
                    "{name} is computed from the spin the rifling imparts, but \
                     rifle.twist_rate_m_per_turn was not supplied. The effect is still \
                     applied, computed from the assumed 1:12 twist rather than disabled, so \
                     the result is for a barrel this request did not specify."
                ),
                path,
            ));
        }
    }

    // Wind shear (0.36.0). Deliberately NOT run through `bool_default`/`literal_default`: an
    // omitted field pushes no assumption notice and leaves the echo absent, so every request
    // written before this field existed still serializes byte-identically -- the same
    // additive-echo contract as `atmosphere.pressure_reference` and `wind.wind_reference`.
    //
    // The name reaching the engine is always the canonical one, so an `"ekman"` request and
    // an `"ekman_spiral"` request resolve to a single spelling in the echo. Unknown names
    // never arrive here: `decode_solve_request_v1` refuses them at
    // `$.effects.wind_shear_model`, and the typed enum makes them unrepresentable for a
    // caller that builds the DTO in Rust.
    let wind_shear_model = effects.wind_shear_model;
    if wind_shear_model == Some(WindShearModelV1::EkmanSpiral) {
        // Not silence: `cli_api`'s boundary-layer evaluator scales the operative wind by a
        // height ratio, and it has no near-ground closed form for the Ekman spiral, so the
        // ratio is 1.0 and the solve matches an unsheared one. Say so in the response
        // instead of letting a caller read "ekman_spiral applied" off the echo and believe
        // the numbers moved.
        warnings.push(notice(
            WARNING_WIND_SHEAR_MODEL_NOT_MODELED,
            "The ekman_spiral wind shear model has no near-ground profile on this solve path; \
             the wind is left at the operative value, so the result matches an unsheared solve.",
            "$.effects.wind_shear_model",
        ));
    }

    // The jump is a function of stability and bullet length, so a defaulted barrel does not
    // leave it alone -- it computes a different answer with the same confidence. Say so at the
    // flag that made the geometry load-bearing, naming whichever field is missing.
    if enabled_aerodynamic_jump && !(geometry.twist_rate && geometry.projectile_length) {
        let missing = match (geometry.twist_rate, geometry.projectile_length) {
            (false, false) => "rifle.twist_rate_m_per_turn and projectile.length_m were",
            (false, true) => "rifle.twist_rate_m_per_turn was",
            (true, false) => "projectile.length_m was",
            (true, true) => unreachable!("guarded by the condition above"),
        };
        warnings.push(notice(
            WARNING_AERODYNAMIC_JUMP_ASSUMED_GEOMETRY,
            format!(
                "Aerodynamic jump scales with gyroscopic stability and bullet length, but \
                 {missing} not supplied. The correction is still applied, computed from the \
                 assumed geometry rather than disabled, so the jump reported in \
                 summary.aerodynamic_jump_moa is for a barrel this request did not specify."
            ),
            "$.effects.aerodynamic_jump",
        ));
    }

    Ok(ResolvedEffectsV1 {
        magnus,
        coriolis,
        enhanced_spin_drift,
        wind_shear_model,
        aerodynamic_jump,
    })
}

fn resolve_sampling(
    sampling: &SamplingV1,
    assumptions: &mut Vec<SolveNoticeV1>,
) -> Result<ResolvedSamplingV1, SolveErrorEnvelopeV1> {
    if let Some(value) = sampling.interval_m {
        require_positive("$.sampling.interval_m", value)?;
    }
    let interval_m = literal_default(
        sampling.interval_m,
        DEFAULT_SAMPLE_INTERVAL_M,
        "$.sampling.interval_m",
        "Sampling interval defaulted to 10 m.",
        assumptions,
    );
    Ok(ResolvedSamplingV1 { interval_m })
}

fn maximum_world_height_m(
    result: &crate::TrajectoryResult,
    shooting_angle_rad: f64,
) -> Result<f64, SolveErrorEnvelopeV1> {
    let mut maximum = f64::NEG_INFINITY;
    for point in &result.points {
        let height = crate::atmosphere::shot_frame_altitude(
            0.0,
            point.position.x,
            point.position.y,
            shooting_angle_rad,
        );
        if !height.is_finite() {
            return Err(internal_error(
                "world-vertical maximum-height projection produced a non-finite value",
            ));
        }
        maximum = maximum.max(height);
    }
    if maximum.is_finite() {
        Ok(maximum)
    } else {
        Err(internal_error(
            "trajectory contained no finite points for maximum-height calculation",
        ))
    }
}

fn observation_to_wire(observation: TrajectoryObservation) -> TrajectorySampleV1 {
    TrajectorySampleV1 {
        distance_m: observation.distance_m,
        time_s: observation.time_s,
        speed_mps: observation.speed_mps,
        energy_j: observation.energy_j,
        drop_m: observation.drop_m,
        windage_m: observation.windage_m,
        mach: observation.mach,
        flags: observation
            .flags
            .into_iter()
            .map(observation_flag_to_wire)
            .collect(),
    }
}

fn observation_flag_to_wire(flag: TrajectoryObservationFlag) -> SampleFlagV1 {
    match flag {
        TrajectoryObservationFlag::Transonic => SampleFlagV1::Transonic,
        TrajectoryObservationFlag::Subsonic => SampleFlagV1::Subsonic,
        TrajectoryObservationFlag::Terminal => SampleFlagV1::Terminal,
        TrajectoryObservationFlag::GroundThreshold => SampleFlagV1::GroundThreshold,
    }
}

fn termination_to_wire(termination: TrajectoryTermination) -> TerminationReasonV1 {
    match termination {
        TrajectoryTermination::MaxRange => TerminationReasonV1::MaxRange,
        TrajectoryTermination::GroundThreshold => TerminationReasonV1::GroundThreshold,
        TrajectoryTermination::TimeLimit => TerminationReasonV1::TimeLimit,
        TrajectoryTermination::VelocityFloor => TerminationReasonV1::VelocityFloor,
    }
}

fn drag_model_to_engine(model: DragModelV1) -> DragModel {
    match model {
        DragModelV1::G1 => DragModel::G1,
        DragModelV1::G2 => DragModel::G2,
        DragModelV1::G5 => DragModel::G5,
        DragModelV1::G6 => DragModel::G6,
        DragModelV1::G7 => DragModel::G7,
        DragModelV1::G8 => DragModel::G8,
        DragModelV1::GI => DragModel::GI,
        DragModelV1::GS => DragModel::GS,
        DragModelV1::RA4 => DragModel::RA4,
    }
}

fn map_observation_error(error: TrajectoryObservationError) -> SolveErrorEnvelopeV1 {
    let message = error.to_string();
    match error {
        TrajectoryObservationError::SampleLimitExceeded { .. }
        | TrajectoryObservationError::AllocationFailed { .. } => error_at(
            SolveErrorCodeV1::ResourceLimit,
            message,
            "$.sampling.interval_m",
        ),
        TrajectoryObservationError::InvalidInterval { .. }
        | TrajectoryObservationError::UnrepresentableGrid { .. } => error_at(
            SolveErrorCodeV1::InvalidValue,
            message,
            "$.sampling.interval_m",
        ),
        // MBA-1599: a trajectory that really moves back toward the muzzle (a headwind carrying a
        // stalled projectile back, a launch past vertical, or an explicit-Euler/RK4 step too
        // coarse for the drag) cannot be reported against downrange distance. That is a failed
        // solve, the code the engine already returns when such a reversal lasts until
        // termination. Equal distances stay internal_error below: the engine collapses a
        // downrange stall, so a repeated distance would be a broken engine invariant.
        TrajectoryObservationError::NonMonotonicTrajectory {
            previous_distance_m,
            distance_m,
            ..
        } if distance_m < previous_distance_m => solve_failed_message(format!(
            "the projectile moved back toward the muzzle ({previous_distance_m} m then \
             {distance_m} m downrange) before reaching a termination boundary, so the \
             trajectory cannot be reported against downrange distance"
        )),
        TrajectoryObservationError::EmptyTrajectory
        | TrajectoryObservationError::NonFiniteQuery { .. }
        | TrajectoryObservationError::OutOfRange { .. }
        | TrajectoryObservationError::NonMonotonicTrajectory { .. }
        | TrajectoryObservationError::NonFiniteState { .. }
        | TrajectoryObservationError::InvalidState { .. }
        | TrajectoryObservationError::InvalidMetadata { .. }
        | TrajectoryObservationError::NonFiniteObservation { .. } => internal_error(message),
    }
}

/// Evaluate a request's reticle hold against the already-sampled trajectory (MBA-1361).
///
/// The angular drop/windage come from the SAME samples the response reports, linearly
/// interpolated at `range_m`, so the hold and the sample rows can never describe different
/// trajectories. Angles use the milliradian small-angle definition (1 mil subtends 1/1000
/// of the range) — the same conversion every other surface uses.
///
/// A range outside the sampled span is a structured [`SolveErrorCodeV1::InvalidValue`], not
/// a clamp or an extrapolation: a hold read off a trajectory that never got there is a
/// fabricated number.
fn resolve_reticle_hold(
    request: &crate::solve_json::ReticleRequestV1,
    samples: &[TrajectorySampleV1],
) -> Result<crate::solve_json::ReticleHoldV1, SolveErrorEnvelopeV1> {
    use crate::reticle::hold_point_in_reticle;

    let path = "$.reticle.range_m";
    let range_m = request.range_m;
    if !range_m.is_finite() || range_m <= 0.0 {
        return Err(invalid_value(
            path,
            "reticle.range_m must be finite and greater than zero",
        ));
    }

    let (lo, t) = match bracket_param(samples.len(), |i| samples[i].distance_m, range_m) {
        Bracket::Inside { lo, t } => (lo, t),
        Bracket::Degenerate => {
            return Err(internal_error(
                "trajectory sampling produced no points to read a reticle hold from",
            ));
        }
        Bracket::Below | Bracket::Above => {
            // `Degenerate` (len < 2) was already handled above, so at least two samples exist.
            let first = &samples[0];
            let last = &samples[samples.len() - 1];
            return Err(invalid_value(
                path,
                format!(
                    "reticle.range_m {range_m} is outside the sampled trajectory ({} to {} m)",
                    first.distance_m, last.distance_m
                ),
            ));
        }
    };
    let hi = lo + 1;
    let lerp = |a: f64, b: f64| a + (b - a) * t;
    let drop_mil = lerp(samples[lo].drop_m, samples[hi].drop_m) / range_m * 1000.0;
    let wind_mil = lerp(samples[lo].windage_m, samples[hi].windage_m) / range_m * 1000.0;

    let hold = hold_point_in_reticle(
        drop_mil,
        wind_mil,
        request.magnification,
        &request.description,
    )
    .map_err(|e| invalid_value("$.reticle", e.to_string()))?;

    let nearest = hold
        .nearest_mark
        .and_then(|index| request.description.marks.get(index));
    Ok(crate::solve_json::ReticleHoldV1 {
        range_m,
        magnification: request.magnification,
        down_mil: hold.down_mil,
        right_mil: hold.right_mil,
        mark_scale: hold.mark_scale,
        nearest_mark_index: hold.nearest_mark,
        nearest_mark_label: nearest.and_then(|mark| mark.label.clone()),
        nearest_mark_distance_mil: hold.nearest_mark_distance_mil,
        off_reticle: hold.off_reticle,
    })
}

// `pub(crate)` (0.33.0 decision-support Task 6, I3 review fix): the perturbation kernel's
// `evaluate` calls `TrajectorySolver::solve` itself (see `build_zeroed_solver` above) and needs
// the identical `BallisticsError` -> `SolveErrorEnvelopeV1` conversion `solve_v1` uses for the
// same call, so both report a solve failure in the same shape.
pub(crate) fn solve_failed(error: BallisticsError) -> SolveErrorEnvelopeV1 {
    solve_failed_message(error.to_string())
}

fn solve_failed_message(message: impl Into<String>) -> SolveErrorEnvelopeV1 {
    SolveErrorEnvelopeV1::new(SolveErrorV1::new(SolveErrorCodeV1::SolveFailed, message))
}

fn internal_error(message: impl Into<String>) -> SolveErrorEnvelopeV1 {
    SolveErrorEnvelopeV1::new(SolveErrorV1::new(SolveErrorCodeV1::InternalError, message))
}

fn invalid_value(path: impl Into<String>, message: impl Into<String>) -> SolveErrorEnvelopeV1 {
    error_at(SolveErrorCodeV1::InvalidValue, message, path)
}

fn conflicting_fields(path: impl Into<String>, message: impl Into<String>) -> SolveErrorEnvelopeV1 {
    error_at(SolveErrorCodeV1::ConflictingFields, message, path)
}

fn error_at(
    code: SolveErrorCodeV1,
    message: impl Into<String>,
    path: impl Into<String>,
) -> SolveErrorEnvelopeV1 {
    SolveErrorEnvelopeV1::new(SolveErrorV1::new(code, message).at_path(path))
}

fn notice(
    code: impl Into<String>,
    message: impl Into<String>,
    path: impl Into<String>,
) -> SolveNoticeV1 {
    SolveNoticeV1 {
        code: code.into(),
        message: message.into(),
        path: Some(path.into()),
    }
}

fn literal_default(
    value: Option<f64>,
    default: f64,
    path: &'static str,
    message: &'static str,
    assumptions: &mut Vec<SolveNoticeV1>,
) -> f64 {
    match value {
        Some(value) => value,
        None => {
            assumptions.push(notice(ASSUMPTION_DEFAULT_APPLIED, message, path));
            default
        }
    }
}

fn bool_default(
    value: Option<bool>,
    path: &'static str,
    message: &'static str,
    assumptions: &mut Vec<SolveNoticeV1>,
) -> bool {
    match value {
        Some(value) => value,
        None => {
            assumptions.push(notice(ASSUMPTION_DEFAULT_APPLIED, message, path));
            false
        }
    }
}

fn checked_conversion(value: f64, path: &str, message: &str) -> Result<f64, SolveErrorEnvelopeV1> {
    if value.is_finite() {
        Ok(value)
    } else {
        Err(invalid_value(path, message))
    }
}

fn require_finite(path: &str, value: f64) -> Result<(), SolveErrorEnvelopeV1> {
    if value.is_finite() {
        Ok(())
    } else {
        Err(invalid_value(path, "value must be finite"))
    }
}

fn require_positive(path: &str, value: f64) -> Result<(), SolveErrorEnvelopeV1> {
    if value.is_finite() && value > 0.0 {
        Ok(())
    } else {
        Err(invalid_value(
            path,
            "value must be finite and greater than zero",
        ))
    }
}

fn require_non_negative(path: &str, value: f64) -> Result<(), SolveErrorEnvelopeV1> {
    if value.is_finite() && value >= 0.0 {
        Ok(())
    } else {
        Err(invalid_value(path, "value must be finite and non-negative"))
    }
}

fn require_range(
    path: &str,
    value: f64,
    minimum: f64,
    maximum: f64,
) -> Result<(), SolveErrorEnvelopeV1> {
    if value.is_finite() && (minimum..=maximum).contains(&value) {
        Ok(())
    } else {
        Err(invalid_value(
            path,
            format!("value must be finite and in the inclusive range [{minimum}, {maximum}]"),
        ))
    }
}

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

    fn minimal_request() -> SolveRequestV1 {
        SolveRequestV1 {
            schema_version: SchemaVersionV1,
            projectile: ProjectileV1 {
                mass_kg: 0.01134,
                diameter_m: 0.00782,
                length_m: None,
                drag_model: DragModelV1::G7,
                ballistic_coefficient: 0.243,
                drag_table: None,
                bc_segments: None,
            },
            rifle: RifleV1 {
                muzzle_velocity_mps: 823.0,
                sight_height_m: None,
                muzzle_height_m: None,
                twist_rate_m_per_turn: None,
                twist_direction: None,
                sight_offset_lateral_m: None,
            },
            shot: ShotV1 {
                max_range_m: 1_000.0,
                zero_distance_m: None,
                muzzle_angle_rad: None,
                aim_azimuth_rad: None,
                shot_azimuth_rad: None,
                shooting_angle_rad: None,
                cant_angle_rad: None,
                target_height_m: None,
                ground_threshold_m: None,
                zero_poi_up_m: None,
                zero_poi_right_m: None,
                drops_reference: None,
            },
            atmosphere: AtmosphereV1::default(),
            wind: WindV1::default(),
            solver: SolverV1::default(),
            effects: EffectsV1::default(),
            sampling: SamplingV1::default(),
            reticle: None,
            corrections: None,
        }
    }

    #[test]
    fn defaults_are_resolved_in_deterministic_request_field_order() {
        let request = minimal_request();
        let prepared = prepare_request(&request).expect("valid request");
        let code_paths = prepared
            .assumptions
            .iter()
            .map(|notice| (notice.code.as_str(), notice.path.as_deref().unwrap()))
            .collect::<Vec<_>>();

        assert_eq!(
            code_paths,
            vec![
                (
                    ASSUMPTION_ESTIMATED_PROJECTILE_LENGTH,
                    "$.projectile.length_m"
                ),
                (ASSUMPTION_DEFAULT_APPLIED, "$.rifle.sight_height_m"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.rifle.muzzle_height_m"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.rifle.twist_rate_m_per_turn"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.rifle.twist_direction"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.shot.muzzle_angle_rad"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.shot.aim_azimuth_rad"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.shot.shot_azimuth_rad"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.shot.shooting_angle_rad"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.shot.cant_angle_rad"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.shot.target_height_m"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.shot.ground_threshold_m"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.atmosphere.altitude_m"),
                (
                    ASSUMPTION_ICAO_STANDARD_TEMPERATURE,
                    "$.atmosphere.temperature_k"
                ),
                (
                    ASSUMPTION_ICAO_STANDARD_PRESSURE,
                    "$.atmosphere.pressure_pa"
                ),
                (ASSUMPTION_DEFAULT_APPLIED, "$.atmosphere.relative_humidity"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.wind"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.solver.method"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.solver.time_step_s"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.effects.magnus"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.effects.coriolis"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.effects.enhanced_spin_drift"),
                (ASSUMPTION_DEFAULT_APPLIED, "$.sampling.interval_m"),
            ]
        );
        assert_eq!(
            prepared.resolved_request.rifle.twist_rate_m_per_turn,
            0.3048
        );
        assert!((prepared.inputs.twist_rate - 12.0).abs() < 1.0e-12);
        assert_eq!(prepared.atmosphere.humidity, 50.0);
        assert_eq!(prepared.inputs.humidity, 0.5);
    }

    #[test]
    fn explicit_standard_station_values_at_altitude_remain_authoritative() {
        let mut request = minimal_request();
        request.atmosphere.altitude_m = Some(1_500.0);
        request.atmosphere.temperature_k = Some(288.15);
        request.atmosphere.pressure_pa = Some(101_325.0);

        let prepared = prepare_request(&request).expect("valid explicit station conditions");
        assert_eq!(prepared.atmosphere.temperature, 15.0);
        assert_eq!(prepared.atmosphere.pressure, 1013.25);
        assert_eq!(prepared.resolved_request.atmosphere.temperature_k, 288.15);
        assert_eq!(prepared.resolved_request.atmosphere.pressure_pa, 101_325.0);
        assert!(!prepared
            .assumptions
            .iter()
            .any(|notice| notice.code == ASSUMPTION_ICAO_STANDARD_TEMPERATURE
                || notice.code == ASSUMPTION_ICAO_STANDARD_PRESSURE));
    }

    /// MBA-1397: `pressure_reference: "qnh"` reduces an explicit pressure to station pressure
    /// and records the reduction as an assumption instead of treating it as authoritative
    /// as-is.
    #[test]
    fn qnh_pressure_reference_reduces_to_station_pressure_and_is_noted() {
        let mut request = minimal_request();
        request.atmosphere.altitude_m = Some(1_500.0);
        request.atmosphere.pressure_pa = Some(103_000.0); // 1030.0 hPa QNH
        request.atmosphere.pressure_reference = Some(PressureReferenceV1::Qnh);

        let prepared = prepare_request(&request).expect("valid QNH request");
        let expected_station_hpa =
            crate::atmosphere::reduce_qnh_to_station_pressure(1030.0, 1_500.0);
        assert!((prepared.atmosphere.pressure - expected_station_hpa).abs() < 1e-9);
        assert!(
            (prepared.resolved_request.atmosphere.pressure_pa - expected_station_hpa * 100.0).abs()
                < 1e-6
        );
        // Strictly lower than the raw QNH -- proves the reduction actually happened.
        assert!(prepared.resolved_request.atmosphere.pressure_pa < 103_000.0);

        assert!(prepared.assumptions.iter().any(|notice| notice.code
            == ASSUMPTION_QNH_REDUCED_TO_STATION_PRESSURE
            && notice.path.as_deref() == Some("$.atmosphere.pressure_pa")));
        // Must NOT also emit the omitted-pressure notice: this is a present, explicit value.
        assert!(!prepared
            .assumptions
            .iter()
            .any(|notice| notice.code == ASSUMPTION_ICAO_STANDARD_PRESSURE));
    }

    /// `pressure_reference: "qnh"` with `pressure_pa` OMITTED must be byte-identical to the
    /// absolute default: an omitted pressure always resolves to the ICAO standard station
    /// pressure regardless of the declared reference (mathematically the same result as
    /// reducing a QNH of exactly the ICAO sea-level standard).
    #[test]
    fn qnh_pressure_reference_with_omitted_pressure_matches_absolute_default() {
        let mut request = minimal_request();
        request.atmosphere.altitude_m = Some(1_500.0);
        request.atmosphere.pressure_reference = Some(PressureReferenceV1::Qnh);

        let prepared = prepare_request(&request).expect("valid request");

        let mut absolute_request = minimal_request();
        absolute_request.atmosphere.altitude_m = Some(1_500.0);
        let absolute_prepared = prepare_request(&absolute_request).expect("valid request");

        assert_eq!(
            prepared.resolved_request.atmosphere.pressure_pa,
            absolute_prepared.resolved_request.atmosphere.pressure_pa
        );
        assert!(prepared
            .assumptions
            .iter()
            .any(|notice| notice.code == ASSUMPTION_ICAO_STANDARD_PRESSURE));
        assert!(!prepared
            .assumptions
            .iter()
            .any(|notice| notice.code == ASSUMPTION_QNH_REDUCED_TO_STATION_PRESSURE));
    }

    /// `pressure_reference` absent entirely (every request before MBA-1397) must be
    /// byte-identical to `Some(Absolute)` -- the default variant is a pure passthrough.
    #[test]
    fn absent_pressure_reference_matches_explicit_absolute() {
        let mut request = minimal_request();
        request.atmosphere.altitude_m = Some(1_500.0);
        request.atmosphere.pressure_pa = Some(90_000.0);

        let mut explicit_absolute = request.clone();
        explicit_absolute.atmosphere.pressure_reference = Some(PressureReferenceV1::Absolute);

        let prepared = prepare_request(&request).expect("valid request");
        let prepared_explicit = prepare_request(&explicit_absolute).expect("valid request");
        assert_eq!(
            prepared.resolved_request.atmosphere.pressure_pa,
            prepared_explicit.resolved_request.atmosphere.pressure_pa
        );
        assert_eq!(prepared.resolved_request.atmosphere.pressure_pa, 90_000.0);
    }

    #[test]
    fn partial_segmented_wind_maps_units_and_warns_without_extending_coverage() {
        let mut request = minimal_request();
        request.wind.segments = Some(vec![crate::solve_json::WindSegmentV1 {
            until_distance_m: 300.0,
            speed_mps: 5.0,
            direction_from_rad: std::f64::consts::FRAC_PI_2,
            vertical_speed_mps: None,
        }]);

        let prepared = prepare_request(&request).expect("partial wind is valid");
        assert_eq!(prepared.wind_segments.len(), 1);
        assert_eq!(prepared.wind_segments[0].speed_kmh, 18.0);
        assert_eq!(prepared.wind_segments[0].angle_deg, 90.0);
        assert_eq!(prepared.wind_segments[0].until_m, 300.0);
        assert_eq!(prepared.wind_segments[0].vertical_mps, 0.0);
        assert!(prepared.warnings.iter().any(|notice| {
            notice.code == WARNING_PARTIAL_WIND_COVERAGE
                && notice.path.as_deref() == Some("$.wind.segments")
        }));
        assert!(matches!(
            prepared.resolved_request.wind,
            ResolvedWindV1::Segmented(_)
        ));
    }

    #[test]
    fn partial_wind_coverage_includes_a_zero_beyond_the_output_range() {
        let mut request = minimal_request();
        request.shot.max_range_m = 200.0;
        request.shot.zero_distance_m = Some(500.0);
        request.wind.segments = Some(vec![crate::solve_json::WindSegmentV1 {
            until_distance_m: 300.0,
            speed_mps: 5.0,
            direction_from_rad: 0.0,
            vertical_speed_mps: Some(0.0),
        }]);

        let prepared = prepare_request(&request).expect("partial zero wind is valid");
        assert!(prepared.warnings.iter().any(|notice| {
            notice.code == WARNING_PARTIAL_WIND_COVERAGE
                && notice.path.as_deref() == Some("$.wind.segments")
                && notice.message.contains("500.000000000000 m")
        }));
    }

    /// 0.33.0 decision-support Task 2: supplying both no longer conflicts. An explicit
    /// muzzle_angle_rad always wins (no zero search runs to derive it), while
    /// zero_distance_m is retained purely as the caller's original zeroing intent. This is
    /// exactly what `From<&ResolvedSolveRequestV1> for SolveRequestV1`
    /// (request_roundtrip.rs) produces for a zeroed solve, so a request rebuilt from a
    /// resolved request can reuse the exact original angle instead of silently re-zeroing.
    #[test]
    fn explicit_muzzle_angle_wins_over_zero_distance_when_both_are_supplied() {
        let mut request = minimal_request();
        request.shot.zero_distance_m = Some(100.0);
        request.shot.muzzle_angle_rad = Some(0.01);
        let prepared =
            prepare_request(&request).expect("both fields together are no longer a conflict");
        assert_eq!(prepared.resolved_request.shot.muzzle_angle_rad, 0.01);
        assert_eq!(prepared.resolved_request.shot.zero_distance_m, Some(100.0));
        // S5 (0.33.0 final-review fix wave): the elevation search did not run -- a caller must
        // be told so, not left to assume the echoed zero_distance_m confirms a zero was
        // actually solved for it.
        assert!(
            prepared.warnings.iter().any(|notice| {
                notice.code == WARNING_ZERO_DISTANCE_ELEVATION_NOT_RESOLVED
                    && notice.path.as_deref() == Some("$.shot.zero_distance_m")
            }),
            "expected a {WARNING_ZERO_DISTANCE_ELEVATION_NOT_RESOLVED} warning naming \
             $.shot.zero_distance_m; got {:?}",
            prepared.warnings
        );
    }

    #[test]
    fn semantic_conflicts_and_invalid_values_keep_exact_paths() {
        let mut request = minimal_request();
        request.atmosphere.relative_humidity = Some(1.01);
        let error = prepare_request(&request).expect_err("humidity above one");
        assert_eq!(error.error.code, SolveErrorCodeV1::InvalidValue);
        assert_eq!(error.error.path(), Some("$.atmosphere.relative_humidity"));

        let mut request = minimal_request();
        request.effects.coriolis = Some(true);
        let error = prepare_request(&request).expect_err("Coriolis needs latitude");
        assert_eq!(error.error.code, SolveErrorCodeV1::InvalidValue);
        assert_eq!(error.error.path(), Some("$.atmosphere.latitude_rad"));

        let mut request = minimal_request();
        request.shot.zero_distance_m = Some(f64::MAX);
        let error = prepare_request(&request).expect_err("zero trial range must remain finite");
        assert_eq!(error.error.code, SolveErrorCodeV1::InvalidValue);
        assert_eq!(error.error.path(), Some("$.shot.zero_distance_m"));
    }

    /// Zero and fly a prepared request as `solve_v1` does when no explicit muzzle angle was
    /// supplied, returning its samples.
    fn fly(prepared: PreparedSolveV1) -> Vec<TrajectoryObservation> {
        let max_range_m = prepared.resolved_request.shot.max_range_m;
        let time_step_s = prepared.resolved_request.solver.time_step_s;
        let zero_distance_m = prepared.resolved_request.shot.zero_distance_m;
        let target_height_m = prepared.resolved_request.shot.target_height_m;
        let (solver, _) = build_zeroed_solver(
            prepared.inputs,
            prepared.wind,
            prepared.atmosphere,
            prepared.wind_segments,
            max_range_m,
            time_step_s,
            zero_distance_m,
            target_height_m,
            None,
        )
        .expect("zeroed solver");
        solver
            .solve()
            .expect("solve")
            .sample_observations(25.0, MAX_SOLVE_JSON_SAMPLES_V1)
            .expect("samples")
    }

    /// `minimal_request` zeroed at 100 m, with a ladder written straight into the engine inputs.
    fn fly_with_engine_ladder(segments: Vec<crate::BCSegmentData>) -> Vec<TrajectoryObservation> {
        let mut request = minimal_request();
        request.shot.zero_distance_m = Some(100.0);
        let mut prepared = prepare_request(&request).expect("valid request");
        prepared.inputs.use_bc_segments = true;
        prepared.inputs.bc_segments_data = Some(segments);
        fly(prepared)
    }

    /// MBA-1598: a wire ladder's m/s band edges reach the engine as the fps `BCSegmentData`
    /// the CLI's `--bc-segment` builds. The ladder arrives as JSON text through
    /// `decode_solve_request_v1`, so the wire spelling is covered too, and is pinned against a
    /// solve whose ladder is written directly in fps, with every edge on a round fps number.
    /// The .308 slows from 2700 fps through a band, an interior gap, a touching edge and a
    /// third band, so a missing or wrong conversion would key every edge off the wrong speed.
    #[test]
    fn bc_segment_edges_reach_the_engine_in_fps() {
        use crate::solve_json::{decode_solve_request_v1, BcSegmentV1};
        use crate::BCSegmentData;

        // fps: 2200-3000 at 0.250, a 2000-2200 gap flying the scalar 0.243, then 1500-2000 at
        // 0.235 touching 0-1500 at 0.225.
        let fps_ladder = [
            (2_200.0, 3_000.0, 0.250),
            (1_500.0, 2_000.0, 0.235),
            (0.0, 1_500.0, 0.225),
        ];
        let mut base = minimal_request();
        base.shot.zero_distance_m = Some(100.0);
        let mut wire = serde_json::to_value(&base).expect("serialize the base request");
        wire["projectile"]["bc_segments"] = serde_json::json!([
            {"velocity_min_mps": 670.56, "velocity_max_mps": 914.4, "ballistic_coefficient": 0.250},
            {"velocity_min_mps": 457.2, "velocity_max_mps": 609.6, "ballistic_coefficient": 0.235},
            {"velocity_min_mps": 0.0, "velocity_max_mps": 457.2, "ballistic_coefficient": 0.225}
        ]);
        let request = decode_solve_request_v1(&wire.to_string()).expect("decodable ladder");
        assert_eq!(
            request.projectile.bc_segments.as_deref(),
            Some(
                &[
                    (670.56, 914.4, 0.250),
                    (457.2, 609.6, 0.235),
                    (0.0, 457.2, 0.225),
                ]
                .map(|(min, max, bc)| BcSegmentV1 {
                    velocity_min_mps: min,
                    velocity_max_mps: max,
                    ballistic_coefficient: bc,
                })[..]
            ),
            "the wire names decode onto the struct fields"
        );
        assert_eq!(
            SolveRequestV1 {
                projectile: ProjectileV1 {
                    bc_segments: None,
                    ..request.projectile.clone()
                },
                ..request.clone()
            },
            base,
            "only the ladder differs from the base request"
        );

        let prepared = prepare_request(&request).expect("valid ladder");
        assert!(prepared.inputs.use_bc_segments);
        assert_eq!(
            prepared.inputs.bc_value, 0.243,
            "the scalar BC is left alone"
        );
        let installed = prepared
            .inputs
            .bc_segments_data
            .clone()
            .expect("ladder installed");
        assert_eq!(installed.len(), fps_ladder.len());
        for (band, (min_fps, max_fps, bc)) in installed.iter().zip(fps_ladder) {
            assert!((band.velocity_min - min_fps).abs() < 1e-9, "{band:?}");
            assert!((band.velocity_max - max_fps).abs() < 1e-9, "{band:?}");
            assert_eq!(band.bc_value, bc);
        }

        let from_wire = fly(prepared);
        let engine_ladder = |scale: f64| {
            fps_ladder
                .iter()
                .map(|&(min, max, bc)| BCSegmentData {
                    velocity_min: min * scale,
                    velocity_max: max * scale,
                    bc_value: bc,
                })
                .collect::<Vec<_>>()
        };
        let direct = fly_with_engine_ladder(engine_ladder(1.0));
        assert_eq!(from_wire.len(), direct.len());
        for (wire, engine) in from_wire.iter().zip(&direct) {
            assert!((wire.distance_m - engine.distance_m).abs() < 1e-9);
            assert!(
                (wire.drop_m - engine.drop_m).abs() < 1e-9,
                "{wire:?} vs {engine:?}"
            );
            assert!(
                (wire.speed_mps - engine.speed_mps).abs() < 1e-9,
                "{wire:?} vs {engine:?}"
            );
            assert!(
                (wire.time_s - engine.time_s).abs() < 1e-12,
                "{wire:?} vs {engine:?}"
            );
        }

        // The pin is not vacuous: edges left in m/s, or the scalar alone, fly differently.
        let terminal_drop = |samples: &[TrajectoryObservation]| samples.last().unwrap().drop_m;
        let unconverted = fly_with_engine_ladder(engine_ladder(0.3048));
        let mut scalar_only = minimal_request();
        scalar_only.shot.zero_distance_m = Some(100.0);
        let scalar_only = fly(prepare_request(&scalar_only).unwrap());
        for other in [&unconverted, &scalar_only] {
            assert!(
                (terminal_drop(&from_wire) - terminal_drop(other)).abs() > 1e-3,
                "{} vs {}",
                terminal_drop(&from_wire),
                terminal_drop(other)
            );
        }
    }

    /// How `install_drag_table` installs each kind, with and without a BC ladder. Only a
    /// reference table beside a ladder takes the reference-curve path (`custom_drag_reference`
    /// set, `cd_scale` 1.0). A reference table alone keeps the original `cd_scale = SD / BC`
    /// installation, so every request accepted before ladders could sit beside a reference
    /// table solves byte-identically, and a projectile table beside a ladder is refused.
    #[test]
    fn install_drag_table_takes_the_reference_curve_path_only_beside_a_ladder() {
        let prepare = |kind: DragTableKindV1, with_ladder: bool| {
            let mut request = minimal_request();
            request.projectile.drag_table = Some(DragTableV1 {
                kind,
                name: None,
                points: vec![
                    crate::solve_json::DragPointV1 { mach: 0.0, cd: 0.2 },
                    crate::solve_json::DragPointV1 { mach: 2.0, cd: 0.3 },
                ],
            });
            if with_ladder {
                request.projectile.bc_segments = Some(vec![
                    crate::solve_json::BcSegmentV1 {
                        velocity_min_mps: 600.0,
                        velocity_max_mps: 999.0,
                        ballistic_coefficient: 0.260,
                    },
                    crate::solve_json::BcSegmentV1 {
                        velocity_min_mps: 0.0,
                        velocity_max_mps: 600.0,
                        ballistic_coefficient: 0.220,
                    },
                ]);
            }
            prepare_request(&request)
        };

        let alone = prepare(DragTableKindV1::Reference, false).unwrap().inputs;
        let sd = alone.sectional_density_lb_in2().expect("SD");
        assert!(!alone.custom_drag_reference);
        assert_eq!(alone.cd_scale, sd / 0.243);

        let laddered = prepare(DragTableKindV1::Reference, true).unwrap().inputs;
        assert!(laddered.custom_drag_reference);
        assert_eq!(laddered.cd_scale, 1.0);
        assert!(laddered.custom_drag_table.is_some());
        assert!(laddered.use_bc_segments && laddered.bc_segments_data.is_some());
        assert_eq!(laddered.bc_value, 0.243, "the scalar still flies in a gap");

        let own = prepare(DragTableKindV1::Projectile, false).unwrap().inputs;
        assert!(!own.custom_drag_reference);
        assert_eq!(own.cd_scale, 1.0);

        let refused = prepare(DragTableKindV1::Projectile, true)
            .expect_err("a ladder beside a projectile table is refused");
        assert_eq!(refused.error.code, SolveErrorCodeV1::ConflictingFields);
        assert_eq!(refused.error.path(), Some("$.projectile.bc_segments"));
    }

    #[test]
    fn enum_mappers_cover_every_engine_metadata_variant() {
        assert_eq!(drag_model_to_engine(DragModelV1::G1), DragModel::G1);
        assert_eq!(drag_model_to_engine(DragModelV1::G2), DragModel::G2);
        assert_eq!(drag_model_to_engine(DragModelV1::G5), DragModel::G5);
        assert_eq!(drag_model_to_engine(DragModelV1::G6), DragModel::G6);
        assert_eq!(drag_model_to_engine(DragModelV1::G7), DragModel::G7);
        assert_eq!(drag_model_to_engine(DragModelV1::G8), DragModel::G8);
        assert_eq!(drag_model_to_engine(DragModelV1::GI), DragModel::GI);
        assert_eq!(drag_model_to_engine(DragModelV1::GS), DragModel::GS);
        assert_eq!(drag_model_to_engine(DragModelV1::RA4), DragModel::RA4);

        for (engine, wire) in [
            (
                TrajectoryTermination::MaxRange,
                TerminationReasonV1::MaxRange,
            ),
            (
                TrajectoryTermination::GroundThreshold,
                TerminationReasonV1::GroundThreshold,
            ),
            (
                TrajectoryTermination::TimeLimit,
                TerminationReasonV1::TimeLimit,
            ),
            (
                TrajectoryTermination::VelocityFloor,
                TerminationReasonV1::VelocityFloor,
            ),
        ] {
            assert_eq!(termination_to_wire(engine), wire);
        }
    }
}