ballistics_engine/

ffi.rs

//! FFI bindings for iOS/Swift integration

use crate::{
    calculate_zero_angle_with_conditions, run_monte_carlo_with_direction_std_dev,
    AtmosphericConditions, BallisticInputs, DragModel, MonteCarloParams, TrajectorySolver,
    WindConditions,
};
use std::os::raw::{c_char, c_double, c_int};
use std::ptr;

/// Minimum C-ABI trajectory `step_size`, in milliseconds (0.1 ms = 0.0001 s).
///
/// Smaller steps are rejected before integration because fixed-step solves retain one public
/// trajectory point per step. All in-repository FFI examples use values in `[0.1, 1.0]` ms.
pub const MIN_FFI_STEP_SIZE_MS: c_double = 0.1;

/// Maximum C-ABI custom drag-table row count.
///
/// `drag_table_from_raw` copies both caller arrays before validation; an unbounded
/// `len` lets a single call request two multi-gigabyte allocations and abort the
/// process (MBA-1407). Real Cd decks are two to three orders of magnitude smaller
/// (the embedded G1/G7 references are under 100 rows; doppler exports run a few
/// hundred), so 4096 is far above any legitimate deck.
pub const MAX_FFI_DRAG_TABLE_LEN: c_int = 4096;

// FFI-safe structures with C-compatible layouts

#[repr(C)]
pub struct FFIBallisticInputs {
    pub muzzle_velocity: c_double,         // m/s
    pub muzzle_angle: c_double,            // radians (launch angle)
    pub bc_value: c_double,                // ballistic coefficient
    pub bullet_mass: c_double,             // kg
    pub bullet_diameter: c_double,         // meters
    pub bc_type: c_int,                    // 0=G1, 1=G7, 2=G2, 3=G5, 4=G6, 5=G8, 6=GI, 7=GS, 8=RA4 (MBA-1386; unrecognized -> G1)
    pub sight_height: c_double,            // meters
    pub target_distance: c_double,         // meters
    pub temperature: c_double,             // Celsius
    pub twist_rate: c_double,              // inches per turn
    pub is_twist_right: c_int,             // 0=false, 1=true
    pub shooting_angle: c_double,          // uphill/downhill angle in radians
    pub altitude: c_double,                // meters
    pub latitude: c_double,                // degrees (use NAN if not provided)
    pub azimuth_angle: c_double,           // horizontal aiming angle in radians
    pub use_rk4: c_int,                    // 0=Euler, 1=RK4
    pub use_adaptive_rk45: c_int,          // 0=false, 1=true (adaptive RK45)
    pub enable_wind_shear: c_int,          // 0=false, 1=true
    pub enable_trajectory_sampling: c_int, // 0=false, 1=true
    pub sample_interval: c_double,         // meters
    pub enable_pitch_damping: c_int,       // 0=false, 1=true
    pub enable_precession_nutation: c_int, // 0=false, 1=true
    pub enable_spin_drift: c_int,          // 0=false, 1=true
    pub enable_magnus: c_int,              // 0=false, 1=true
    pub enable_coriolis: c_int,            // 0=false, 1=true
    // Appended (keeps existing field offsets): compass bearing the shot is fired
    // along, radians, 0=North, PI/2=East. Drives the Coriolis Eötvös/drift azimuth.
    // Distinct from azimuth_angle (the small aiming offset). 0.0 if unset.
    pub shot_azimuth: c_double,
    // Appended (keeps existing field offsets): rifle cant angle in RADIANS about the line
    // of sight, positive = clockwise from the shooter. Rotates the sight-frame aim offsets
    // and bore geometry ("zeroed level, fired canted" -> POI right and low). 0.0 if unset.
    pub cant_angle: c_double,
}

#[repr(C)]
pub struct FFIWindConditions {
    pub speed: c_double, // m/s
    // radians, wind-FROM convention: 0 = headwind, PI/2 = from the right,
    // PI = tailwind, 3*PI/2 = from the left (matches WindConditions / WindSock).
    pub direction: c_double,
    // Appended (keeps existing field offsets): vertical wind m/s, positive = updraft;
    // 0.0 if unset.
    pub vertical_speed: c_double,
}

#[repr(C)]
pub struct FFIAtmosphericConditions {
    pub temperature: c_double, // Celsius
    pub pressure: c_double,    // hPa
    pub humidity: c_double,    // percentage (0-100)
    pub altitude: c_double,    // meters
}

#[repr(C)]
pub struct FFITrajectorySample {
    pub distance: c_double,       // meters
    pub time: c_double,           // seconds
    pub velocity_mps: c_double,   // meters per second
    pub energy_joules: c_double,  // joules
    pub drop_meters: c_double,    // meters
    pub windage_meters: c_double, // meters
    pub mach: c_double,           // Mach number
    pub spin_rate_rps: c_double,  // revolutions per second
}

#[repr(C)]
pub struct FFITrajectoryPoint {
    pub time: c_double,
    pub position_x: c_double,
    pub position_y: c_double,
    pub position_z: c_double,
    pub velocity_magnitude: c_double,
    pub kinetic_energy: c_double,
}

#[repr(C)]
pub struct FFITrajectoryResult {
    pub max_range: c_double,
    pub max_height: c_double,
    pub time_of_flight: c_double,
    pub impact_velocity: c_double,
    pub impact_energy: c_double,
    pub points: *mut FFITrajectoryPoint,
    pub point_count: c_int,
    pub sampled_points: *mut FFITrajectorySample,
    pub sampled_point_count: c_int,
    pub min_pitch_damping: c_double,    // NAN if not calculated
    pub transonic_mach: c_double,       // NAN if not reached
    pub final_pitch_angle: c_double,    // NAN if not calculated
    pub final_yaw_angle: c_double,      // NAN if not calculated
    pub max_yaw_angle: c_double,        // NAN if not calculated
    pub max_precession_angle: c_double, // NAN if not calculated
}

// Monte Carlo simulation parameters
#[repr(C)]
pub struct FFIMonteCarloParams {
    pub num_simulations: c_int,
    pub velocity_std_dev: c_double,
    pub angle_std_dev: c_double,
    pub bc_std_dev: c_double,
    pub wind_speed_std_dev: c_double,
    pub target_distance: c_double,     // Use NAN if not specified
    pub base_wind_speed: c_double,     // Base wind speed in m/s
    pub base_wind_direction: c_double, // Base wind direction in radians
    pub azimuth_std_dev: c_double,     // Horizontal aiming variation in radians
}

// Monte Carlo simulation results
#[repr(C)]
pub struct FFIMonteCarloResults {
    pub ranges: *mut c_double,
    pub impact_velocities: *mut c_double,
    pub impact_positions_x: *mut c_double,
    /// `-1.0e9` marks a sample that did not reach the target plane; exclude it from dispersion
    /// statistics but retain it as a miss for probability calculations.
    pub impact_positions_y: *mut c_double,
    pub impact_positions_z: *mut c_double,
    pub num_results: c_int,
    pub mean_range: c_double,
    pub std_dev_range: c_double,
    pub mean_impact_velocity: c_double,
    pub std_dev_impact_velocity: c_double,
    pub hit_probability: c_double, // If target_distance was specified
}

// Helper function to convert FFI inputs to internal types
#[allow(clippy::field_reassign_with_default)] // Keep the C-to-Rust field mapping sequential/auditable.
fn convert_inputs(inputs: &FFIBallisticInputs) -> BallisticInputs {
    let mut ballistic_inputs = BallisticInputs::default();

    ballistic_inputs.muzzle_velocity = inputs.muzzle_velocity;
    ballistic_inputs.muzzle_angle = inputs.muzzle_angle;
    ballistic_inputs.azimuth_angle = inputs.azimuth_angle;
    ballistic_inputs.shot_azimuth = inputs.shot_azimuth;
    ballistic_inputs.cant_angle = inputs.cant_angle;
    ballistic_inputs.use_rk4 = inputs.use_rk4 != 0;
    ballistic_inputs.use_adaptive_rk45 = inputs.use_adaptive_rk45 != 0;
    ballistic_inputs.bc_value = inputs.bc_value;
    ballistic_inputs.bullet_mass = inputs.bullet_mass;
    ballistic_inputs.bullet_diameter = inputs.bullet_diameter;
    ballistic_inputs.bc_type = match inputs.bc_type {
        1 => DragModel::G7,
        2 => DragModel::G2,
        3 => DragModel::G5,
        4 => DragModel::G6,
        5 => DragModel::G8,
        6 => DragModel::GI,
        7 => DragModel::GS,
        // MBA-1386: additive slot for the new RA4 family. Existing callers passing
        // 0-7 are unaffected; any other/unrecognized value still falls back to G1.
        8 => DragModel::RA4,
        _ => DragModel::G1,
    };
    ballistic_inputs.sight_height = inputs.sight_height;
    ballistic_inputs.target_distance = inputs.target_distance;
    ballistic_inputs.temperature = inputs.temperature;
    ballistic_inputs.twist_rate = inputs.twist_rate;
    ballistic_inputs.is_twist_right = inputs.is_twist_right != 0;
    ballistic_inputs.shooting_angle = inputs.shooting_angle;
    ballistic_inputs.altitude = inputs.altitude;

    if !inputs.latitude.is_nan() {
        ballistic_inputs.latitude = Some(inputs.latitude);
    }

    // Set derived values
    ballistic_inputs.caliber_inches = inputs.bullet_diameter / 0.0254;
    ballistic_inputs.weight_grains = inputs.bullet_mass / crate::constants::GRAINS_TO_KG;
    // MBA-1135: mass-based length estimate (was a mass-blind 4.5-caliber default). The C ABI does
    // not carry a bullet length, so derive it from diameter + mass; fall back to 4.5-cal if mass<=0.
    ballistic_inputs.bullet_length = {
        let est = crate::stability::estimate_bullet_length_m(
            ballistic_inputs.bullet_diameter,
            ballistic_inputs.bullet_mass,
        );
        if est > 0.0 {
            est
        } else {
            ballistic_inputs.bullet_diameter * 4.5
        }
    };

    // New advanced physics flags
    ballistic_inputs.enable_wind_shear = inputs.enable_wind_shear != 0;
    ballistic_inputs.enable_trajectory_sampling = inputs.enable_trajectory_sampling != 0;
    ballistic_inputs.sample_interval = inputs.sample_interval;
    ballistic_inputs.enable_pitch_damping = inputs.enable_pitch_damping != 0;
    ballistic_inputs.enable_precession_nutation = inputs.enable_precession_nutation != 0;
    ballistic_inputs.use_enhanced_spin_drift = inputs.enable_spin_drift != 0;
    ballistic_inputs.enable_advanced_effects =
        inputs.enable_magnus != 0 || inputs.enable_coriolis != 0;
    // Gate Magnus and Coriolis independently so enabling one does not enable the other.
    ballistic_inputs.enable_magnus = inputs.enable_magnus != 0;
    ballistic_inputs.enable_coriolis = inputs.enable_coriolis != 0;

    ballistic_inputs
}

/// Build a validated [`crate::drag::DragTable`] from borrowed C arrays.
///
/// Both arrays must contain `len` elements, with `len` in `[2, MAX_FFI_DRAG_TABLE_LEN]`.
/// The data is copied; the caller retains ownership. Returns `Err(())` for null
/// pointers, `len` outside that range, or any deck that fails
/// [`crate::drag::DragTable::try_new`] validation (non-ascending Mach, non-positive
/// or non-finite Cd). No error detail crosses the ABI, matching the null/NAN
/// error convention of this module.
///
/// # Safety
///
/// When non-null, `mach` and `cd` must each point to `len` readable `f64` values
/// that remain valid and unmutated for the duration of the call.
unsafe fn drag_table_from_raw(
    mach: *const c_double,
    cd: *const c_double,
    len: c_int,
) -> Result<crate::drag::DragTable, ()> {
    if mach.is_null() || cd.is_null() || !(2..=MAX_FFI_DRAG_TABLE_LEN).contains(&len) {
        return Err(());
    }
    let len = len as usize;
    let mach = unsafe { std::slice::from_raw_parts(mach, len) }.to_vec();
    let cd = unsafe { std::slice::from_raw_parts(cd, len) }.to_vec();
    crate::drag::DragTable::try_new(mach, cd).map_err(|_| ())
}

/// Shared implementation for the trajectory exports. `custom_drag_table`, when
/// present, replaces the G-model + BC drag (the deck's Cd is divided by sectional
/// density — see `BallisticInputs::custom_drag_denominator`). `cd_scale` multiplies the
/// deck's interpolated Cd (MBA-1356); callers that don't expose a scale pass `1.0`
/// (neutral, byte-identical to no scale). It is inert when `custom_drag_table` is `None`.
unsafe fn calculate_trajectory_impl(
    inputs: *const FFIBallisticInputs,
    wind: *const FFIWindConditions,
    atmosphere: *const FFIAtmosphericConditions,
    max_range: c_double,
    step_size: c_double,
    custom_drag_table: Option<crate::drag::DragTable>,
    cd_scale: c_double,
) -> *mut FFITrajectoryResult {
    if inputs.is_null() {
        return ptr::null_mut();
    }
    if !step_size.is_finite() || step_size < MIN_FFI_STEP_SIZE_MS {
        return ptr::null_mut();
    }

    let inputs = unsafe { &*inputs };
    let mut ballistic_inputs = convert_inputs(inputs);
    ballistic_inputs.custom_drag_table = custom_drag_table;
    ballistic_inputs.cd_scale = cd_scale;
    let twist_rate_in = ballistic_inputs.twist_rate;

    let wind_conditions = if wind.is_null() {
        WindConditions::default()
    } else {
        let wind = unsafe { &*wind };
        WindConditions {
            speed: wind.speed,
            direction: wind.direction,
            vertical_speed: wind.vertical_speed,
        }
    };

    let atmospheric_conditions = if atmosphere.is_null() {
        AtmosphericConditions::default()
    } else {
        let atmo = unsafe { &*atmosphere };
        AtmosphericConditions {
            temperature: atmo.temperature,
            pressure: atmo.pressure,
            humidity: atmo.humidity,
            altitude: atmo.altitude,
        }
    };

    // Create solver and calculate trajectory
    let (sample_temp_c, sample_pressure_hpa) = crate::atmosphere::resolve_station_conditions(
        atmospheric_conditions.temperature,
        atmospheric_conditions.pressure,
        atmospheric_conditions.altitude,
    );
    let (_, sample_speed_of_sound) = crate::atmosphere::calculate_atmosphere(
        atmospheric_conditions.altitude,
        Some(sample_temp_c),
        Some(sample_pressure_hpa),
        atmospheric_conditions.humidity,
    );

    let mut solver =
        TrajectorySolver::new(ballistic_inputs, wind_conditions, atmospheric_conditions);

    // Set max range and time step
    solver.set_max_range(max_range);
    solver.set_time_step(step_size / 1000.0); // milliseconds -> seconds

    match solver.solve() {
        Ok(result) => {
            // Convert trajectory points to FFI format
            let point_count = result.points.len();
            let points = if point_count > 0 {
                let mut ffi_points = Vec::with_capacity(point_count);
                for point in result.points.iter() {
                    ffi_points.push(FFITrajectoryPoint {
                        time: point.time,
                        position_x: point.position[0],
                        position_y: point.position[1],
                        position_z: point.position[2],
                        velocity_magnitude: point.velocity_magnitude,
                        kinetic_energy: point.kinetic_energy,
                    });
                }
                let points_ptr = ffi_points.as_mut_ptr();
                std::mem::forget(ffi_points); // Prevent deallocation
                points_ptr
            } else {
                ptr::null_mut()
            };

            // Convert sampled points if available
            let (sampled_points, sampled_point_count) =
                if let Some(ref samples) = result.sampled_points {
                    let mut ffi_samples = Vec::with_capacity(samples.len());
                    for sample in samples {
                        ffi_samples.push(FFITrajectorySample {
                            distance: sample.distance_m,
                            time: sample.time_s,
                            velocity_mps: sample.velocity_mps,
                            energy_joules: sample.energy_j,
                            drop_meters: sample.drop_m,
                            windage_meters: sample.wind_drift_m,
                            mach: if sample_speed_of_sound > 0.0 {
                                sample.velocity_mps / sample_speed_of_sound
                            } else {
                                0.0
                            },
                            spin_rate_rps: if twist_rate_in > 0.0 {
                                sample.velocity_mps / (twist_rate_in * 0.0254)
                            } else {
                                0.0
                            },
                        });
                    }
                    let count = ffi_samples.len() as c_int;
                    let samples_ptr = ffi_samples.as_mut_ptr();
                    std::mem::forget(ffi_samples);
                    (samples_ptr, count)
                } else {
                    (ptr::null_mut(), 0)
                };

            // Extract angular state values if available
            let (final_pitch, final_yaw, max_yaw, max_prec) =
                if let Some(ref angular) = result.angular_state {
                    (
                        angular.pitch_angle,
                        angular.yaw_angle,
                        result.max_yaw_angle.unwrap_or(f64::NAN),
                        result.max_precession_angle.unwrap_or(f64::NAN),
                    )
                } else {
                    (f64::NAN, f64::NAN, f64::NAN, f64::NAN)
                };

            // Create result on heap
            let ffi_result = Box::new(FFITrajectoryResult {
                max_range: result.max_range,
                max_height: result.max_height,
                time_of_flight: result.time_of_flight,
                impact_velocity: result.impact_velocity,
                impact_energy: result.impact_energy,
                points,
                point_count: point_count as c_int,
                sampled_points,
                sampled_point_count,
                min_pitch_damping: result.min_pitch_damping.unwrap_or(f64::NAN),
                transonic_mach: result.transonic_mach.unwrap_or(f64::NAN),
                final_pitch_angle: final_pitch,
                final_yaw_angle: final_yaw,
                max_yaw_angle: max_yaw,
                max_precession_angle: max_prec,
            });

            Box::into_raw(ffi_result)
        }
        Err(_) => ptr::null_mut(),
    }
}

/// Calculate a trajectory through the C ABI.
///
/// `step_size` is expressed in milliseconds and must be finite and at least
/// [`MIN_FFI_STEP_SIZE_MS`]. This boundary contract is validated for every solver mode, although
/// adaptive RK45 chooses its integration steps internally. Invalid values return null without
/// starting a solve. A solve that would exceed [`crate::MAX_TRAJECTORY_POINTS`] also returns null;
/// an enabled sampling grid above [`crate::MAX_TRAJECTORY_SAMPLES`] does likewise. Callers can
/// increase `step_size`, reduce `max_range`, or select adaptive RK45.
///
/// # Safety
///
/// `inputs` may be null, in which case this function returns null. When non-null,
/// it must point to a valid, properly aligned [`FFIBallisticInputs`] that remains
/// readable and is not mutated for the duration of this call. `wind` and
/// `atmosphere` may also be null; each non-null pointer has the same requirements
/// for its corresponding type.
/// The returned pointer, when non-null, must be released exactly once with
/// [`ballistics_free_trajectory_result`].
#[no_mangle]
pub unsafe extern "C" fn ballistics_calculate_trajectory(
    inputs: *const FFIBallisticInputs,
    wind: *const FFIWindConditions,
    atmosphere: *const FFIAtmosphericConditions,
    max_range: c_double,
    step_size: c_double,
) -> *mut FFITrajectoryResult {
    unsafe { calculate_trajectory_impl(inputs, wind, atmosphere, max_range, step_size, None, 1.0) }
}

/// [`ballistics_calculate_trajectory`] with a caller-supplied custom drag deck
/// (Cd vs Mach, e.g. Hornady CDM / Doppler-radar data). The deck REPLACES the
/// G-model + BC for drag: `bc_type`/`bc_value` are ignored, and the retardation
/// denominator becomes the projectile's sectional density (mass and diameter in
/// `inputs` must therefore be positive). Mach values must be strictly ascending
/// with `drag_table_len` in `[2, MAX_FFI_DRAG_TABLE_LEN]` and finite positive Cd;
/// outside the deck's Mach domain the nearest endpoint Cd is held.
///
/// Returns null for an invalid deck (null arrays, `drag_table_len` outside
/// `[2, MAX_FFI_DRAG_TABLE_LEN]`, or failed validation), in addition to every
/// failure mode of the base function.
///
/// # Safety
///
/// Same contract as [`ballistics_calculate_trajectory`] for `inputs`, `wind`, and
/// `atmosphere`. Additionally, when non-null, `drag_mach` and `drag_cd` must each
/// point to `drag_table_len` readable `f64` values, borrowed only for the duration
/// of this call (the deck is copied; the caller retains ownership — no new free
/// function is required). The returned pointer, when non-null, must be released
/// exactly once with [`ballistics_free_trajectory_result`].
#[no_mangle]
pub unsafe extern "C" fn ballistics_calculate_trajectory_with_drag_table(
    inputs: *const FFIBallisticInputs,
    wind: *const FFIWindConditions,
    atmosphere: *const FFIAtmosphericConditions,
    max_range: c_double,
    step_size: c_double,
    drag_mach: *const c_double,
    drag_cd: *const c_double,
    drag_table_len: c_int,
) -> *mut FFITrajectoryResult {
    let table = match unsafe { drag_table_from_raw(drag_mach, drag_cd, drag_table_len) } {
        Ok(t) => t,
        Err(()) => return ptr::null_mut(),
    };
    unsafe {
        calculate_trajectory_impl(
            inputs, wind, atmosphere, max_range, step_size, Some(table), 1.0,
        )
    }
}

/// [`ballistics_calculate_trajectory_with_drag_table`] with an additional whole-curve
/// drag scale (MBA-1356): the deck's interpolated Cd is multiplied by `cd_scale` at the
/// same site the base export uses, i.e. `Cd_used = table.interpolate(mach) * cd_scale`.
/// `cd_scale = 1.0` is neutral and produces byte-identical output to
/// [`ballistics_calculate_trajectory_with_drag_table`] on the same deck. Typical truing
/// values are in `[0.90, 1.10]`; values outside that band are accepted here (the engine
/// only rejects non-finite or non-positive) — an "unusually large" warning is a CLI-only
/// concern (Task 2), not part of this frozen C ABI.
///
/// Returns null when `cd_scale` is not finite or not `> 0`, in addition to every failure
/// mode of [`ballistics_calculate_trajectory_with_drag_table`] (matching that export's
/// null sentinel for an invalid deck).
///
/// # Safety
///
/// Same contract as [`ballistics_calculate_trajectory_with_drag_table`].
#[no_mangle]
pub unsafe extern "C" fn ballistics_calculate_trajectory_with_drag_table_scaled(
    inputs: *const FFIBallisticInputs,
    wind: *const FFIWindConditions,
    atmosphere: *const FFIAtmosphericConditions,
    max_range: c_double,
    step_size: c_double,
    drag_mach: *const c_double,
    drag_cd: *const c_double,
    drag_table_len: c_int,
    cd_scale: c_double,
) -> *mut FFITrajectoryResult {
    if !cd_scale.is_finite() || cd_scale <= 0.0 {
        return ptr::null_mut();
    }
    let table = match unsafe { drag_table_from_raw(drag_mach, drag_cd, drag_table_len) } {
        Ok(t) => t,
        Err(()) => return ptr::null_mut(),
    };
    unsafe {
        calculate_trajectory_impl(
            inputs, wind, atmosphere, max_range, step_size, Some(table), cd_scale,
        )
    }
}

/// Release a trajectory result allocated by [`ballistics_calculate_trajectory`].
///
/// # Safety
///
/// `result` must be null or a pointer returned by
/// [`ballistics_calculate_trajectory`] that has not already been freed. Its
/// embedded pointers and counts must be unchanged from the returned values.
/// After this call, the result and its point arrays must not be accessed again.
#[no_mangle]
pub unsafe extern "C" fn ballistics_free_trajectory_result(result: *mut FFITrajectoryResult) {
    if !result.is_null() {
        unsafe {
            let result = Box::from_raw(result);
            if !result.points.is_null() && result.point_count > 0 {
                let points = Vec::from_raw_parts(
                    result.points,
                    result.point_count as usize,
                    result.point_count as usize,
                );
                drop(points);
            }
            if !result.sampled_points.is_null() && result.sampled_point_count > 0 {
                let samples = Vec::from_raw_parts(
                    result.sampled_points,
                    result.sampled_point_count as usize,
                    result.sampled_point_count as usize,
                );
                drop(samples);
            }
            drop(result);
        }
    }
}

/// Shared implementation for the zero-angle exports. `custom_drag_table`, when
/// present, replaces the G-model + BC drag (the deck's Cd is divided by sectional
/// density — see `BallisticInputs::custom_drag_denominator`), matching the deck
/// semantics of [`calculate_trajectory_impl`] so a zero solved with a deck and a
/// trajectory flown with the same deck agree. `cd_scale` multiplies the deck's
/// interpolated Cd (MBA-1356); callers that don't expose a scale pass `1.0` (neutral).
unsafe fn calculate_zero_angle_impl(
    inputs: *const FFIBallisticInputs,
    wind: *const FFIWindConditions,
    atmosphere: *const FFIAtmosphericConditions,
    zero_distance: c_double,
    custom_drag_table: Option<crate::drag::DragTable>,
    cd_scale: c_double,
) -> c_double {
    if inputs.is_null() {
        return f64::NAN;
    }

    let inputs = unsafe { &*inputs };
    let mut ballistic_inputs = convert_inputs(inputs);
    ballistic_inputs.custom_drag_table = custom_drag_table;
    ballistic_inputs.cd_scale = cd_scale;

    let wind_conditions = if wind.is_null() {
        WindConditions::default()
    } else {
        let wind = unsafe { &*wind };
        WindConditions {
            speed: wind.speed,
            direction: wind.direction,
            vertical_speed: wind.vertical_speed,
        }
    };

    let atmospheric_conditions = if atmosphere.is_null() {
        AtmosphericConditions::default()
    } else {
        let atmo = unsafe { &*atmosphere };
        AtmosphericConditions {
            temperature: atmo.temperature,
            pressure: atmo.pressure,
            humidity: atmo.humidity,
            altitude: atmo.altitude,
        }
    };

    // For zero angle, we want the bullet to hit at sight height at the zero distance
    // This means the bullet crosses the line of sight at the zero distance
    let target_height = ballistic_inputs.sight_height;

    calculate_zero_angle_with_conditions(
        ballistic_inputs,
        zero_distance,
        target_height,
        wind_conditions,
        atmospheric_conditions,
    )
    .unwrap_or(f64::NAN)
}

/// Calculate the zero angle for a target distance through the C ABI.
///
/// # Safety
///
/// `inputs` may be null, in which case this function returns NaN. When non-null,
/// it must point to a valid, properly aligned [`FFIBallisticInputs`] that remains
/// readable and is not mutated for the duration of this call. `wind` and
/// `atmosphere` may also be null; each non-null pointer has the same requirements
/// for its corresponding type.
#[no_mangle]
pub unsafe extern "C" fn ballistics_calculate_zero_angle(
    inputs: *const FFIBallisticInputs,
    wind: *const FFIWindConditions,
    atmosphere: *const FFIAtmosphericConditions,
    zero_distance: c_double,
) -> c_double {
    unsafe { calculate_zero_angle_impl(inputs, wind, atmosphere, zero_distance, None, 1.0) }
}

/// [`ballistics_calculate_zero_angle`] with a caller-supplied custom drag deck
/// (Cd vs Mach, e.g. Hornady CDM / Doppler-radar data). The deck REPLACES the
/// G-model + BC for drag: `bc_type`/`bc_value` are ignored, and the retardation
/// denominator becomes the projectile's sectional density (mass and diameter in
/// `inputs` must therefore be positive). Mach values must be strictly ascending
/// with `drag_table_len` in `[2, MAX_FFI_DRAG_TABLE_LEN]` and finite positive Cd;
/// outside the deck's Mach domain the nearest endpoint Cd is held. Pair this with
/// [`ballistics_calculate_trajectory_with_drag_table`] using the same deck to fly
/// the solved angle — the two exports share identical deck semantics.
///
/// Returns NaN for an invalid deck (null arrays, `drag_table_len` outside
/// `[2, MAX_FFI_DRAG_TABLE_LEN]`, or failed validation), in addition to every
/// failure mode of the base function.
///
/// # Safety
///
/// Same contract as [`ballistics_calculate_zero_angle`] for `inputs`, `wind`, and
/// `atmosphere`. Additionally, when non-null, `drag_mach` and `drag_cd` must each
/// point to `drag_table_len` readable `f64` values, borrowed only for the duration
/// of this call (the deck is copied; the caller retains ownership — no new free
/// function is required).
#[no_mangle]
pub unsafe extern "C" fn ballistics_calculate_zero_angle_with_drag_table(
    inputs: *const FFIBallisticInputs,
    wind: *const FFIWindConditions,
    atmosphere: *const FFIAtmosphericConditions,
    zero_distance: c_double,
    drag_mach: *const c_double,
    drag_cd: *const c_double,
    drag_table_len: c_int,
) -> c_double {
    let table = match unsafe { drag_table_from_raw(drag_mach, drag_cd, drag_table_len) } {
        Ok(t) => t,
        Err(()) => return f64::NAN,
    };
    unsafe {
        calculate_zero_angle_impl(inputs, wind, atmosphere, zero_distance, Some(table), 1.0)
    }
}

/// [`ballistics_calculate_zero_angle_with_drag_table`] with an additional whole-curve
/// drag scale (MBA-1356): the deck's interpolated Cd is multiplied by `cd_scale` at the
/// same site the base export uses, i.e. `Cd_used = table.interpolate(mach) * cd_scale`.
/// `cd_scale = 1.0` is neutral and produces byte-identical output to
/// [`ballistics_calculate_zero_angle_with_drag_table`] on the same deck. Pair this with
/// [`ballistics_calculate_trajectory_with_drag_table_scaled`] using the same deck AND the
/// same `cd_scale` to fly the solved angle. Typical truing values are in `[0.90, 1.10]`;
/// values outside that band are accepted here (the engine only rejects non-finite or
/// non-positive) — an "unusually large" warning is a CLI-only concern (Task 2).
///
/// Returns NaN when `cd_scale` is not finite or not `> 0`, in addition to every failure
/// mode of [`ballistics_calculate_zero_angle_with_drag_table`] (matching that export's
/// NaN sentinel for an invalid deck).
///
/// # Safety
///
/// Same contract as [`ballistics_calculate_zero_angle_with_drag_table`].
#[no_mangle]
pub unsafe extern "C" fn ballistics_calculate_zero_angle_with_drag_table_scaled(
    inputs: *const FFIBallisticInputs,
    wind: *const FFIWindConditions,
    atmosphere: *const FFIAtmosphericConditions,
    zero_distance: c_double,
    drag_mach: *const c_double,
    drag_cd: *const c_double,
    drag_table_len: c_int,
    cd_scale: c_double,
) -> c_double {
    if !cd_scale.is_finite() || cd_scale <= 0.0 {
        return f64::NAN;
    }
    let table = match unsafe { drag_table_from_raw(drag_mach, drag_cd, drag_table_len) } {
        Ok(t) => t,
        Err(()) => return f64::NAN,
    };
    unsafe {
        calculate_zero_angle_impl(
            inputs,
            wind,
            atmosphere,
            zero_distance,
            Some(table),
            cd_scale,
        )
    }
}

// Simple trajectory calculation for quick results
#[no_mangle]
#[allow(clippy::field_reassign_with_default)] // Preserve the staged zero-angle workflow below.
pub extern "C" fn ballistics_quick_trajectory(
    muzzle_velocity: c_double,
    bc: c_double,
    sight_height: c_double,
    zero_distance: c_double,
    target_distance: c_double,
) -> c_double {
    // This provides a simple drop calculation at target distance
    // Using simplified ballistic calculations

    let mut inputs = BallisticInputs::default();
    inputs.muzzle_velocity = muzzle_velocity;
    inputs.bc_value = bc;
    inputs.sight_height = sight_height;
    inputs.target_distance = target_distance;

    let wind = WindConditions::default();
    let atmo = AtmosphericConditions::default();

    // First calculate zero angle
    let zero_angle = match calculate_zero_angle_with_conditions(
        inputs.clone(),
        zero_distance,
        sight_height,
        wind.clone(),
        atmo.clone(),
    ) {
        Ok(angle) => angle,
        Err(_) => return f64::NAN,
    };

    // Now calculate trajectory with that zero angle
    inputs.muzzle_angle = zero_angle;

    let mut solver = TrajectorySolver::new(inputs, wind, atmo);
    solver.set_max_range(target_distance * 1.1);

    match solver.solve() {
        Ok(result) => {
            // Find the drop at target distance
            for point in result.points {
                if point.position[0] >= target_distance {
                    return sight_height - point.position[1];
                }
            }
            f64::NAN
        }
        Err(_) => f64::NAN,
    }
}

/// Run a Monte Carlo simulation through the C ABI.
///
/// # Safety
///
/// `inputs` and `params` may be null, in which case this function returns null.
/// Each non-null pointer must point to a valid, properly aligned value of its
/// corresponding FFI type that remains readable and is not mutated for the
/// duration of this call. `atmosphere` may be null; a non-null pointer has the
/// same requirements for [`FFIAtmosphericConditions`]. The returned pointer,
/// when non-null, must be released exactly once with
/// [`ballistics_free_monte_carlo_results`].
#[no_mangle]
pub unsafe extern "C" fn ballistics_monte_carlo(
    inputs: *const FFIBallisticInputs,
    atmosphere: *const FFIAtmosphericConditions,
    params: *const FFIMonteCarloParams,
) -> *mut FFIMonteCarloResults {
    unsafe { ballistics_monte_carlo_impl(inputs, atmosphere, params, 0.0) }
}

/// Run a Monte Carlo simulation with independent wind-direction uncertainty through the C ABI.
///
/// `wind_direction_std_dev` is in radians. This additive entry point keeps
/// [`FFIMonteCarloParams`] and [`ballistics_monte_carlo`] binary-compatible; the older function
/// delegates with zero wind-direction uncertainty.
///
/// # Safety
///
/// The pointer and ownership requirements are identical to [`ballistics_monte_carlo`].
#[no_mangle]
pub unsafe extern "C" fn ballistics_monte_carlo_with_direction_std_dev(
    inputs: *const FFIBallisticInputs,
    atmosphere: *const FFIAtmosphericConditions,
    params: *const FFIMonteCarloParams,
    wind_direction_std_dev: c_double,
) -> *mut FFIMonteCarloResults {
    unsafe { ballistics_monte_carlo_impl(inputs, atmosphere, params, wind_direction_std_dev) }
}

unsafe fn ballistics_monte_carlo_impl(
    inputs: *const FFIBallisticInputs,
    atmosphere: *const FFIAtmosphericConditions,
    params: *const FFIMonteCarloParams,
    wind_direction_std_dev: f64,
) -> *mut FFIMonteCarloResults {
    if inputs.is_null() || params.is_null() {
        return ptr::null_mut();
    }

    let inputs = unsafe { &*inputs };
    let params = unsafe { &*params };

    // Reject an out-of-range simulation count. num_simulations is a c_int (i32) cast straight to
    // usize: a negative value would wrap to a near-max usize, and even a large positive value (up
    // to i32::MAX ~ 2.1e9) would drive billions of iterations with the result arrays scaling to
    // match — an unbounded-loop / OOM DoS from a single FFI call. Bound it to a sane maximum.
    // (n == 0 also yields NaN stats and a zero-size allocation.)
    const MAX_SIMULATIONS: c_int = 1_000_000;
    if params.num_simulations <= 0 || params.num_simulations > MAX_SIMULATIONS {
        return ptr::null_mut();
    }

    // Convert FFI inputs to internal types
    let mut ballistic_inputs = convert_inputs(inputs);
    ballistic_inputs.muzzle_height = 1.5;
    ballistic_inputs.ground_threshold = 0.0;
    if !atmosphere.is_null() {
        let atmo = unsafe { &*atmosphere };
        ballistic_inputs.temperature = atmo.temperature;
        ballistic_inputs.pressure = atmo.pressure;
        ballistic_inputs.humidity = (atmo.humidity / 100.0).clamp(0.0, 1.0);
        ballistic_inputs.altitude = atmo.altitude;
    }

    // Create Monte Carlo parameters
    let mc_params = MonteCarloParams {
        num_simulations: params.num_simulations as usize,
        velocity_std_dev: params.velocity_std_dev,
        angle_std_dev: params.angle_std_dev,
        bc_std_dev: params.bc_std_dev,
        wind_speed_std_dev: params.wind_speed_std_dev,
        target_distance: if params.target_distance.is_nan() {
            None
        } else {
            Some(params.target_distance)
        },
        base_wind_speed: params.base_wind_speed,
        base_wind_direction: params.base_wind_direction,
        azimuth_std_dev: params.azimuth_std_dev,
    };

    // Run Monte Carlo simulation
    match run_monte_carlo_with_direction_std_dev(
        ballistic_inputs,
        mc_params,
        wind_direction_std_dev,
    ) {
        Ok(results) => {
            let num_results = results.ranges.len() as c_int;

            // Calculate statistics
            let mean_range: f64 = results.ranges.iter().sum::<f64>() / num_results as f64;
            let variance_range: f64 = results
                .ranges
                .iter()
                .map(|r| (r - mean_range).powi(2))
                .sum::<f64>()
                / num_results as f64;
            let std_dev_range = variance_range.sqrt();

            let mean_velocity: f64 =
                results.impact_velocities.iter().sum::<f64>() / num_results as f64;
            let variance_velocity: f64 = results
                .impact_velocities
                .iter()
                .map(|v| (v - mean_velocity).powi(2))
                .sum::<f64>()
                / num_results as f64;
            let std_dev_velocity = variance_velocity.sqrt();

            // Calculate hit probability if target distance was specified. MBA-971: use the shared
            // position-based criterion (fraction within DEFAULT_HIT_RADIUS_M of the point of aim
            // at the target plane). The old inline version had a redundant `distance < target`
            // clause comparing a ~meter deviation to the ~hundreds-of-meters target distance
            // (effectively always true), and the CLI used a different range-based notion entirely.
            let hit_probability = if params.target_distance.is_nan() {
                0.0
            } else {
                results.hit_probability(crate::DEFAULT_HIT_RADIUS_M)
            };

            // Allocate memory for arrays
            let ranges_ptr = unsafe {
                let ptr = std::alloc::alloc(
                    std::alloc::Layout::array::<c_double>(num_results as usize).unwrap(),
                ) as *mut c_double;
                for (i, &range) in results.ranges.iter().enumerate() {
                    *ptr.add(i) = range;
                }
                ptr
            };

            let velocities_ptr = unsafe {
                let ptr = std::alloc::alloc(
                    std::alloc::Layout::array::<c_double>(num_results as usize).unwrap(),
                ) as *mut c_double;
                for (i, &vel) in results.impact_velocities.iter().enumerate() {
                    *ptr.add(i) = vel;
                }
                ptr
            };

            let pos_x_ptr = unsafe {
                let ptr = std::alloc::alloc(
                    std::alloc::Layout::array::<c_double>(num_results as usize).unwrap(),
                ) as *mut c_double;
                for (i, pos) in results.impact_positions.iter().enumerate() {
                    *ptr.add(i) = pos.x;
                }
                ptr
            };

            let pos_y_ptr = unsafe {
                let ptr = std::alloc::alloc(
                    std::alloc::Layout::array::<c_double>(num_results as usize).unwrap(),
                ) as *mut c_double;
                for (i, pos) in results.impact_positions.iter().enumerate() {
                    *ptr.add(i) = pos.y;
                }
                ptr
            };

            let pos_z_ptr = unsafe {
                let ptr = std::alloc::alloc(
                    std::alloc::Layout::array::<c_double>(num_results as usize).unwrap(),
                ) as *mut c_double;
                for (i, pos) in results.impact_positions.iter().enumerate() {
                    *ptr.add(i) = pos.z;
                }
                ptr
            };

            // Create result structure
            let result = Box::new(FFIMonteCarloResults {
                ranges: ranges_ptr,
                impact_velocities: velocities_ptr,
                impact_positions_x: pos_x_ptr,
                impact_positions_y: pos_y_ptr,
                impact_positions_z: pos_z_ptr,
                num_results,
                mean_range,
                std_dev_range,
                mean_impact_velocity: mean_velocity,
                std_dev_impact_velocity: std_dev_velocity,
                hit_probability,
            });

            Box::into_raw(result)
        }
        Err(_) => ptr::null_mut(),
    }
}

/// Release Monte Carlo results allocated by either Monte Carlo C entry point.
///
/// # Safety
///
/// `results` must be null or a pointer returned by [`ballistics_monte_carlo`] or
/// [`ballistics_monte_carlo_with_direction_std_dev`] that has not already been freed. Its
/// embedded pointers and result count must be unchanged from the returned values. After this
/// call, the result and all of its arrays must not be accessed again.
#[no_mangle]
pub unsafe extern "C" fn ballistics_free_monte_carlo_results(results: *mut FFIMonteCarloResults) {
    if results.is_null() {
        return;
    }

    unsafe {
        let results = Box::from_raw(results);
        let num = results.num_results as usize;

        // Free arrays
        if !results.ranges.is_null() {
            std::alloc::dealloc(
                results.ranges as *mut u8,
                std::alloc::Layout::array::<c_double>(num).unwrap(),
            );
        }

        if !results.impact_velocities.is_null() {
            std::alloc::dealloc(
                results.impact_velocities as *mut u8,
                std::alloc::Layout::array::<c_double>(num).unwrap(),
            );
        }

        if !results.impact_positions_x.is_null() {
            std::alloc::dealloc(
                results.impact_positions_x as *mut u8,
                std::alloc::Layout::array::<c_double>(num).unwrap(),
            );
        }

        if !results.impact_positions_y.is_null() {
            std::alloc::dealloc(
                results.impact_positions_y as *mut u8,
                std::alloc::Layout::array::<c_double>(num).unwrap(),
            );
        }

        if !results.impact_positions_z.is_null() {
            std::alloc::dealloc(
                results.impact_positions_z as *mut u8,
                std::alloc::Layout::array::<c_double>(num).unwrap(),
            );
        }

        // Box automatically deallocates the result structure
    }
}

// Get library version
#[no_mangle]
pub extern "C" fn ballistics_get_version() -> *const c_char {
    // Return a pointer to a static NUL-terminated string (the caller must NOT free it).
    // Previously this leaked a freshly-allocated CString on every call and reported a
    // stale hardcoded "0.3.0"; use the real crate version with no allocation.
    concat!(env!("CARGO_PKG_VERSION"), "\0").as_ptr() as *const c_char
}

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

    fn valid_trajectory_inputs() -> FFIBallisticInputs {
        FFIBallisticInputs {
            muzzle_velocity: 800.0,
            muzzle_angle: 0.0,
            bc_value: 0.5,
            bullet_mass: 0.01,
            bullet_diameter: 0.00762,
            bc_type: 0,
            sight_height: 0.05,
            target_distance: 1.0,
            temperature: 15.0,
            twist_rate: 12.0,
            is_twist_right: 1,
            shooting_angle: 0.0,
            altitude: 0.0,
            latitude: f64::NAN,
            azimuth_angle: 0.0,
            use_rk4: 1,
            use_adaptive_rk45: 0,
            enable_wind_shear: 0,
            enable_trajectory_sampling: 0,
            sample_interval: 10.0,
            enable_pitch_damping: 0,
            enable_precession_nutation: 0,
            enable_spin_drift: 0,
            enable_magnus: 0,
            enable_coriolis: 0,
            shot_azimuth: 0.0,
            cant_angle: 0.0,
        }
    }

    #[allow(dead_code)]
    #[repr(C)]
    struct LegacyFFIMonteCarloParams {
        num_simulations: c_int,
        velocity_std_dev: c_double,
        angle_std_dev: c_double,
        bc_std_dev: c_double,
        wind_speed_std_dev: c_double,
        target_distance: c_double,
        base_wind_speed: c_double,
        base_wind_direction: c_double,
        azimuth_std_dev: c_double,
    }

    #[test]
    fn monte_carlo_params_legacy_abi_size_is_unchanged() {
        assert_eq!(
            std::mem::size_of::<FFIMonteCarloParams>(),
            std::mem::size_of::<LegacyFFIMonteCarloParams>()
        );
        assert_eq!(
            std::mem::align_of::<FFIMonteCarloParams>(),
            std::mem::align_of::<LegacyFFIMonteCarloParams>()
        );
    }

    /// MBA-1386 scope addition: `bc_type` gains an additive numeric slot (8) for the
    /// new RA4 family, appended after the existing 0-7 mapping (G1, G7, G2, G5, G6,
    /// G8, GI, GS). No existing caller's value changes meaning; `8` is simply new,
    /// and anything still outside 0-8 keeps falling back to G1.
    #[test]
    fn bc_type_8_maps_to_ra4() {
        let mut inputs = valid_trajectory_inputs();
        inputs.bc_type = 8;
        assert_eq!(convert_inputs(&inputs).bc_type, DragModel::RA4);

        // Every pre-existing code is unaffected by the addition.
        let expected = [
            (0, DragModel::G1),
            (1, DragModel::G7),
            (2, DragModel::G2),
            (3, DragModel::G5),
            (4, DragModel::G6),
            (5, DragModel::G8),
            (6, DragModel::GI),
            (7, DragModel::GS),
        ];
        for (code, model) in expected {
            let mut inputs = valid_trajectory_inputs();
            inputs.bc_type = code;
            assert_eq!(convert_inputs(&inputs).bc_type, model, "code {code}");
        }

        // Unrecognized codes (including ones above the new 8) still fall back to G1.
        for code in [9, 42, -1] {
            let mut inputs = valid_trajectory_inputs();
            inputs.bc_type = code;
            assert_eq!(convert_inputs(&inputs).bc_type, DragModel::G1, "code {code}");
        }
    }

    #[test]
    fn null_pointer_contracts_return_sentinels_and_free_safely() {
        unsafe {
            assert!(ballistics_calculate_trajectory(
                std::ptr::null(),
                std::ptr::null(),
                std::ptr::null(),
                1_000.0,
                1.0,
            )
            .is_null());
            assert!(ballistics_calculate_zero_angle(
                std::ptr::null(),
                std::ptr::null(),
                std::ptr::null(),
                100.0,
            )
            .is_nan());
            assert!(ballistics_calculate_trajectory_with_drag_table(
                std::ptr::null(),
                std::ptr::null(),
                std::ptr::null(),
                1_000.0,
                1.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
            )
            .is_null());
            assert!(ballistics_calculate_zero_angle_with_drag_table(
                std::ptr::null(),
                std::ptr::null(),
                std::ptr::null(),
                100.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
            )
            .is_nan());
            assert!(
                ballistics_monte_carlo(std::ptr::null(), std::ptr::null(), std::ptr::null(),)
                    .is_null()
            );
            assert!(ballistics_monte_carlo_with_direction_std_dev(
                std::ptr::null(),
                std::ptr::null(),
                std::ptr::null(),
                0.1,
            )
            .is_null());

            ballistics_free_trajectory_result(std::ptr::null_mut());
            ballistics_free_monte_carlo_results(std::ptr::null_mut());
        }
    }

    #[test]
    fn mba1283_ffi_enforces_step_floor_for_every_solver_mode() {
        for (mode, use_rk4, use_adaptive_rk45) in [("Euler", 0, 0), ("RK4", 1, 0), ("RK45", 1, 1)] {
            for step_size in [
                f64::NAN,
                f64::INFINITY,
                f64::NEG_INFINITY,
                -1.0,
                -0.0,
                0.0,
                0.001,
                MIN_FFI_STEP_SIZE_MS - 0.001,
            ] {
                let mut inputs = valid_trajectory_inputs();
                inputs.use_rk4 = use_rk4;
                inputs.use_adaptive_rk45 = use_adaptive_rk45;
                let result = unsafe {
                    ballistics_calculate_trajectory(
                        &inputs,
                        std::ptr::null(),
                        std::ptr::null(),
                        0.01,
                        step_size,
                    )
                };
                assert!(
                    result.is_null(),
                    "{mode} step_size={step_size:?} bypassed the FFI floor"
                );
            }

            let mut inputs = valid_trajectory_inputs();
            inputs.use_rk4 = use_rk4;
            inputs.use_adaptive_rk45 = use_adaptive_rk45;
            let result = unsafe {
                ballistics_calculate_trajectory(
                    &inputs,
                    std::ptr::null(),
                    std::ptr::null(),
                    0.01,
                    MIN_FFI_STEP_SIZE_MS,
                )
            };
            assert!(
                !result.is_null(),
                "the documented minimum step must remain usable in {mode}"
            );
            unsafe {
                assert!((*result).point_count >= 0);
                assert!((*result).point_count as usize <= crate::MAX_TRAJECTORY_POINTS);
                ballistics_free_trajectory_result(result);
            }
        }
    }

    /// A tiny valid deck: strictly ascending Mach, positive Cd.
    const DECK_MACH: [f64; 4] = [0.5, 1.0, 2.0, 3.0];
    /// Deliberately LOW drag so the deck measurably increases impact velocity vs G1.
    const DECK_CD_LOW: [f64; 4] = [0.05, 0.08, 0.06, 0.05];

    #[test]
    fn trajectory_with_drag_table_applies_the_deck() {
        let inputs = valid_trajectory_inputs();
        unsafe {
            let plain = ballistics_calculate_trajectory(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
            );
            let decked = ballistics_calculate_trajectory_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
            );
            assert!(!plain.is_null() && !decked.is_null());
            // The low-drag deck must retain materially more velocity than the G-model.
            assert!(
                (*decked).impact_velocity > (*plain).impact_velocity + 1.0,
                "deck did not change the solve: plain={} decked={}",
                (*plain).impact_velocity,
                (*decked).impact_velocity
            );
            ballistics_free_trajectory_result(plain);
            ballistics_free_trajectory_result(decked);
        }
    }

    #[test]
    fn trajectory_with_drag_table_rejects_invalid_decks() {
        let inputs = valid_trajectory_inputs();
        let descending = [3.0, 2.0, 1.0, 0.5];
        let negative_cd = [0.05, -0.08, 0.06, 0.05];
        unsafe {
            // null arrays
            assert!(ballistics_calculate_trajectory_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                std::ptr::null(),
                DECK_CD_LOW.as_ptr(),
                4,
            )
            .is_null());
            assert!(ballistics_calculate_trajectory_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                DECK_MACH.as_ptr(),
                std::ptr::null(),
                4,
            )
            .is_null());
            // too few points
            assert!(ballistics_calculate_trajectory_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                1,
            )
            .is_null());
            // non-ascending Mach
            assert!(ballistics_calculate_trajectory_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                descending.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                4,
            )
            .is_null());
            // non-positive Cd
            assert!(ballistics_calculate_trajectory_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                DECK_MACH.as_ptr(),
                negative_cd.as_ptr(),
                4,
            )
            .is_null());
            // null inputs still rejected
            assert!(ballistics_calculate_trajectory_with_drag_table(
                std::ptr::null(),
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                4,
            )
            .is_null());
        }
    }

    #[test]
    fn zero_angle_with_drag_table_applies_the_deck() {
        // A realistic zeroing setup: 100 m zero.
        let inputs = valid_trajectory_inputs();
        unsafe {
            let plain =
                ballistics_calculate_zero_angle(&inputs, std::ptr::null(), std::ptr::null(), 100.0);
            let decked = ballistics_calculate_zero_angle_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                100.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
            );
            assert!(plain.is_finite() && decked.is_finite());
            // A much lower-drag deck needs a flatter (smaller) zero angle; at minimum it
            // must differ measurably from the G-model zero.
            assert!(
                (plain - decked).abs() > 1e-6,
                "deck did not change the zero: plain={plain} decked={decked}"
            );
        }
    }

    #[test]
    fn zero_angle_with_drag_table_rejects_invalid_decks() {
        let inputs = valid_trajectory_inputs();
        let descending = [3.0, 2.0, 1.0, 0.5];
        unsafe {
            assert!(ballistics_calculate_zero_angle_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                100.0,
                std::ptr::null(),
                DECK_CD_LOW.as_ptr(),
                4,
            )
            .is_nan());
            assert!(ballistics_calculate_zero_angle_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                100.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                0,
            )
            .is_nan());
            assert!(ballistics_calculate_zero_angle_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                100.0,
                descending.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                4,
            )
            .is_nan());
            // null inputs still rejected
            assert!(ballistics_calculate_zero_angle_with_drag_table(
                std::ptr::null(),
                std::ptr::null(),
                std::ptr::null(),
                100.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                4,
            )
            .is_nan());
        }
    }

    #[test]
    fn zero_then_fly_with_same_deck_is_consistent() {
        // The pair-use case the two exports exist for: zero with the deck, fly with the
        // deck at the solved angle; the trajectory must cross near sight height at the
        // zero distance (i.e. the two functions share identical deck semantics).
        let mut inputs = valid_trajectory_inputs();
        unsafe {
            let angle = ballistics_calculate_zero_angle_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                100.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
            );
            assert!(angle.is_finite());
            inputs.muzzle_angle = angle;
            let result = ballistics_calculate_trajectory_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                150.0,
                1.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
            );
            assert!(!result.is_null());
            // Interpolate y at exactly the zero distance (100 m) rather than snapping to the
            // nearest raw trajectory sample, so the residual reflects only zero-solver
            // convergence, not the sampling grid's x-offset from 100 m.
            let zero_distance = 100.0;
            let pts = std::slice::from_raw_parts((*result).points, (*result).point_count as usize);
            let bracket = pts
                .windows(2)
                .find(|w| w[0].position_x <= zero_distance && w[1].position_x >= zero_distance)
                .expect("trajectory brackets the zero distance");
            let (lo, hi) = (&bracket[0], &bracket[1]);
            let y_at_zero = if hi.position_x > lo.position_x {
                let t = (zero_distance - lo.position_x) / (hi.position_x - lo.position_x);
                lo.position_y + t * (hi.position_y - lo.position_y)
            } else {
                lo.position_y
            };
            assert!(
                (y_at_zero - inputs.sight_height).abs() < 0.002,
                "zeroed flight missed the line of sight at 100 m: y={} (sight_height={})",
                y_at_zero,
                inputs.sight_height
            );
            ballistics_free_trajectory_result(result);
        }
    }

    #[test]
    fn drag_table_len_above_cap_is_rejected() {
        // A valid, monotonically increasing deck that is simply too long: the cap
        // must reject it BEFORE the to_vec() copies, returning the null sentinel.
        let n = (MAX_FFI_DRAG_TABLE_LEN + 1) as usize;
        let mach: Vec<f64> = (0..n).map(|i| 0.01 + i as f64 * 0.001).collect();
        let cd: Vec<f64> = vec![0.3; n];
        let inputs = valid_trajectory_inputs();
        unsafe {
            let r = ballistics_calculate_trajectory_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                mach.as_ptr(),
                cd.as_ptr(),
                n as c_int,
            );
            assert!(r.is_null(), "len {n} must be rejected by the cap");
        }
    }

    #[test]
    fn drag_table_len_at_cap_is_accepted() {
        let n = MAX_FFI_DRAG_TABLE_LEN as usize;
        let mach: Vec<f64> = (0..n).map(|i| 0.01 + i as f64 * 0.001).collect();
        let cd: Vec<f64> = vec![0.3; n];
        let inputs = valid_trajectory_inputs();
        unsafe {
            let r = ballistics_calculate_trajectory_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                mach.as_ptr(),
                cd.as_ptr(),
                n as c_int,
            );
            assert!(!r.is_null(), "len == cap must be accepted");
            ballistics_free_trajectory_result(r);
        }
    }

    #[test]
    fn ffi_cant_angle_deflects_laterally() {
        let mut level = valid_trajectory_inputs();
        level.muzzle_angle = 0.003;
        let mut canted = valid_trajectory_inputs();
        canted.muzzle_angle = 0.003;
        canted.cant_angle = 10f64.to_radians();
        unsafe {
            let a = ballistics_calculate_trajectory(&level, std::ptr::null(), std::ptr::null(), 400.0, 1.0);
            let b = ballistics_calculate_trajectory(&canted, std::ptr::null(), std::ptr::null(), 400.0, 1.0);
            assert!(!a.is_null() && !b.is_null());
            let za = std::slice::from_raw_parts((*a).points, (*a).point_count as usize).last().unwrap().position_z;
            let zb = std::slice::from_raw_parts((*b).points, (*b).point_count as usize).last().unwrap().position_z;
            assert!(zb > za + 0.005, "FFI cant must deflect right: level={za} canted={zb}");
            ballistics_free_trajectory_result(a);
            ballistics_free_trajectory_result(b);
        }
    }

    #[test]
    fn ffi_vertical_wind_raises_trajectory() {
        let inputs = valid_trajectory_inputs();
        let no_wind = FFIWindConditions {
            speed: 0.0,
            direction: 0.0,
            vertical_speed: 0.0,
        };
        let updraft = FFIWindConditions {
            speed: 0.0,
            direction: 0.0,
            vertical_speed: 5.0,
        };
        unsafe {
            let a = ballistics_calculate_trajectory(&inputs, &no_wind, std::ptr::null(), 400.0, 1.0);
            let b = ballistics_calculate_trajectory(&inputs, &updraft, std::ptr::null(), 400.0, 1.0);
            assert!(!a.is_null() && !b.is_null());
            let ya = std::slice::from_raw_parts((*a).points, (*a).point_count as usize).last().unwrap().position_y;
            let yb = std::slice::from_raw_parts((*b).points, (*b).point_count as usize).last().unwrap().position_y;
            assert!(yb > ya + 0.01, "FFI updraft must raise the trajectory: no_wind={ya} updraft={yb}");
            ballistics_free_trajectory_result(a);
            ballistics_free_trajectory_result(b);
        }
    }

    // --- MBA-1356: cd_scale `_scaled` FFI variants ---

    #[test]
    fn trajectory_scaled_at_one_matches_unscaled_export() {
        let inputs = valid_trajectory_inputs();
        unsafe {
            let unscaled = ballistics_calculate_trajectory_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
            );
            let scaled = ballistics_calculate_trajectory_with_drag_table_scaled(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
                1.0,
            );
            assert!(!unscaled.is_null() && !scaled.is_null());
            assert_eq!(
                (*unscaled).impact_velocity.to_bits(),
                (*scaled).impact_velocity.to_bits(),
                "cd_scale=1.0 must be byte-identical to the unscaled export: unscaled={} scaled={}",
                (*unscaled).impact_velocity,
                (*scaled).impact_velocity
            );
            ballistics_free_trajectory_result(unscaled);
            ballistics_free_trajectory_result(scaled);
        }
    }

    #[test]
    fn trajectory_scaled_at_1_10_lowers_impact_velocity() {
        let inputs = valid_trajectory_inputs();
        unsafe {
            let baseline = ballistics_calculate_trajectory_with_drag_table_scaled(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
                1.0,
            );
            let scaled_up = ballistics_calculate_trajectory_with_drag_table_scaled(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
                1.10,
            );
            assert!(!baseline.is_null() && !scaled_up.is_null());
            assert!(
                (*scaled_up).impact_velocity < (*baseline).impact_velocity,
                "cd_scale=1.10 must increase drag -> lower impact velocity: base={} scaled={}",
                (*baseline).impact_velocity,
                (*scaled_up).impact_velocity
            );
            ballistics_free_trajectory_result(baseline);
            ballistics_free_trajectory_result(scaled_up);
        }
    }

    #[test]
    fn trajectory_scaled_rejects_invalid_cd_scale() {
        let inputs = valid_trajectory_inputs();
        unsafe {
            for bad in [0.0, -1.0, f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
                let r = ballistics_calculate_trajectory_with_drag_table_scaled(
                    &inputs,
                    std::ptr::null(),
                    std::ptr::null(),
                    300.0,
                    1.0,
                    DECK_MACH.as_ptr(),
                    DECK_CD_LOW.as_ptr(),
                    DECK_MACH.len() as c_int,
                    bad,
                );
                assert!(r.is_null(), "cd_scale={bad} must be rejected (null sentinel)");
            }
        }
    }

    #[test]
    fn zero_angle_scaled_at_one_matches_unscaled_export() {
        let inputs = valid_trajectory_inputs();
        unsafe {
            let unscaled = ballistics_calculate_zero_angle_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                100.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
            );
            let scaled = ballistics_calculate_zero_angle_with_drag_table_scaled(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                100.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
                1.0,
            );
            assert!(unscaled.is_finite() && scaled.is_finite());
            assert_eq!(
                unscaled.to_bits(),
                scaled.to_bits(),
                "cd_scale=1.0 must be byte-identical to the unscaled export: unscaled={unscaled} scaled={scaled}"
            );
        }
    }

    #[test]
    fn zero_angle_scaled_at_1_10_differs_from_baseline() {
        let inputs = valid_trajectory_inputs();
        unsafe {
            let baseline = ballistics_calculate_zero_angle_with_drag_table_scaled(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                100.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
                1.0,
            );
            let scaled_up = ballistics_calculate_zero_angle_with_drag_table_scaled(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                100.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
                1.10,
            );
            assert!(baseline.is_finite() && scaled_up.is_finite());
            // More drag needs a steeper (larger) zero angle to still reach 100 m.
            assert!(
                scaled_up > baseline,
                "cd_scale=1.10 must need a larger zero angle: base={baseline} scaled={scaled_up}"
            );
        }
    }

    #[test]
    fn zero_angle_scaled_rejects_invalid_cd_scale() {
        let inputs = valid_trajectory_inputs();
        unsafe {
            for bad in [0.0, -1.0, f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
                let angle = ballistics_calculate_zero_angle_with_drag_table_scaled(
                    &inputs,
                    std::ptr::null(),
                    std::ptr::null(),
                    100.0,
                    DECK_MACH.as_ptr(),
                    DECK_CD_LOW.as_ptr(),
                    DECK_MACH.len() as c_int,
                    bad,
                );
                assert!(angle.is_nan(), "cd_scale={bad} must be rejected (NaN sentinel)");
            }
        }
    }

    /// Legacy exports must remain byte-identical: the same deck through the unscaled
    /// export must be unaffected by the new cd_scale plumbing (a regression guard
    /// alongside the pre-existing, untouched drag-table tests above).
    #[test]
    fn legacy_drag_table_exports_unaffected_by_cd_scale_plumbing() {
        let inputs = valid_trajectory_inputs();
        unsafe {
            let a = ballistics_calculate_trajectory_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
            );
            let b = ballistics_calculate_trajectory_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                300.0,
                1.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
            );
            assert!(!a.is_null() && !b.is_null());
            assert_eq!((*a).impact_velocity.to_bits(), (*b).impact_velocity.to_bits());
            ballistics_free_trajectory_result(a);
            ballistics_free_trajectory_result(b);

            let za = ballistics_calculate_zero_angle_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                100.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
            );
            let zb = ballistics_calculate_zero_angle_with_drag_table(
                &inputs,
                std::ptr::null(),
                std::ptr::null(),
                100.0,
                DECK_MACH.as_ptr(),
                DECK_CD_LOW.as_ptr(),
                DECK_MACH.len() as c_int,
            );
            assert!(za.is_finite() && zb.is_finite());
            assert_eq!(za.to_bits(), zb.to_bits());
        }
    }
}