nereids_pipeline/

pipeline.rs

//! Single-spectrum analysis pipeline.
//!
//! Orchestrates the full analysis chain for a single transmission spectrum:
//! ENDF loading → cross-section calculation → broadening → fitting.
//!
//! This is the building block for the spatial mapping pipeline.
//!
//! Uses `UnifiedFitConfig` with `SolverConfig` and typed `InputData` variants.

use std::fmt;
use std::sync::Arc;

use nereids_core::constants::{EV_TO_JOULES, NEUTRON_MASS_KG, PIVOT_FLOOR, tof_to_energy};
use nereids_endf::resonance::ResonanceData;
use nereids_fitting::exact_count_model::ExactTwoArmRatioModel;
use nereids_fitting::joint_poisson::{self, JointPoissonFitConfig, JointPoissonObjective};
use nereids_fitting::lm::{self, FitModel, LmConfig, LmResult};
use nereids_fitting::parameters::{FitParameter, ParameterSet};
use nereids_fitting::poisson::{self, PoissonConfig};
use nereids_fitting::transmission_model::{
    EnergyScaleTransmissionModel, MultiplicativeBaselineModel, NormalizedTransmissionModel,
    PrecomputedTransmissionModel, TransmissionFitModel,
};
use nereids_physics::counts_response::DetectorBinResponseMatrix;
use nereids_physics::resolution::ResolutionFunction;
use nereids_physics::transmission::{InstrumentParams, WorkingGridLayout, WorkingGridXs};

use crate::error::PipelineError;

#[derive(Debug, Clone)]
pub struct PrecomputedXs {
    pub sigma: Arc<Vec<Vec<f64>>>,
    pub layout: Arc<WorkingGridLayout>,
}

impl From<WorkingGridXs> for PrecomputedXs {
    fn from(working: WorkingGridXs) -> Self {
        Self {
            sigma: Arc::new(working.sigma),
            layout: Arc::new(working.layout),
        }
    }
}

/// SAMMY-style normalization and background configuration.
///
/// When enabled, the transmission model becomes:
///   T_out(E) = Anorm × T_inner(E) + BackA + BackB / √E + BackC × √E
///            + BackD × exp(−BackF / √E)
///
/// The first 4 background parameters (Anorm, BackA, BackB, BackC) are always
/// available.  The exponential tail (BackD, BackF) is optional and disabled
/// by default (`fit_back_d = false`, `fit_back_f = false`).
///
/// ## SAMMY Reference
/// SAMMY manual Sec III.E.2 — NORMAlization and BACKGround cards.
/// SAMMY fits up to 6 background terms; we implement all 6.
#[derive(Debug, Clone)]
pub struct BackgroundConfig {
    /// Initial value for the normalization factor (default 1.0).
    pub anorm_init: f64,
    /// Initial value for the constant background (default 0.0).
    pub back_a_init: f64,
    /// Initial value for the 1/√E background term (default 0.0).
    pub back_b_init: f64,
    /// Initial value for the √E background term (default 0.0).
    pub back_c_init: f64,
    /// Initial value for the exponential amplitude (default 0.01).
    ///
    /// Must be > 0 when `fit_back_f` is true, otherwise the Jacobian
    /// column for BackF is identically zero and BackF cannot be learned.
    pub back_d_init: f64,
    /// Initial value for the exponential decay constant (default 1.0).
    ///
    /// Units: √eV.  Must be > 0 when `fit_back_d` is true, otherwise
    /// BackD is indistinguishable from BackA (both become constants).
    pub back_f_init: f64,
    /// Whether Anorm is free (true) or fixed (false).
    pub fit_anorm: bool,
    /// Whether BackA is free (true) or fixed (false).
    pub fit_back_a: bool,
    /// Whether BackB is free (true) or fixed (false).
    pub fit_back_b: bool,
    /// Whether BackC is free (true) or fixed (false).
    pub fit_back_c: bool,
    /// Whether BackD (exponential amplitude) is free (true) or fixed (false).
    pub fit_back_d: bool,
    /// Whether BackF (exponential decay constant) is free (true) or fixed (false).
    pub fit_back_f: bool,
}

impl Default for BackgroundConfig {
    fn default() -> Self {
        Self {
            anorm_init: 1.0,
            back_a_init: 0.0,
            back_b_init: 0.0,
            back_c_init: 0.0,
            back_d_init: 0.01,
            back_f_init: 1.0,
            fit_anorm: true,
            fit_back_a: true,
            fit_back_b: true,
            fit_back_c: true,
            fit_back_d: false,
            fit_back_f: false,
        }
    }
}

/// Indices of SAMMY background parameters in the full parameter vector.
///
/// Replaces the previous 4-tuple representation and supports the optional
/// exponential tail terms (BackD, BackF).
#[derive(Debug, Clone, Copy)]
struct BackgroundIndices {
    anorm: usize,
    back_a: usize,
    back_b: usize,
    back_c: usize,
    back_d: Option<usize>,
    back_f: Option<usize>,
}

/// Bounded multiplicative polynomial baseline (issue #635):
/// `y(E) = (b0 + b1·z + b2·z²) · T_model(E)` with `z = ln(E/E_ref)` and
/// `E_ref = √(E_min·E_max)` of the fit grid.
///
/// A NEREIDS extension (see `MultiplicativeBaselineModel` for the SAMMY
/// departure record): real VENUS sample/open-beam ratios sit a few % from
/// unity with smooth energy dependence, and freeing the SAMMY `Anorm`
/// together with temperature and density is degenerate on such data
/// (IPTS-37432 finding A3: T → 4471 K with no warning).  The bounded
/// multiplicative form fitted jointly with temperature at fixed density is
/// the production recipe (χ²/ν ≈ 2–8 across the 20-run campaign).
///
/// `b0` is exactly degenerate with `Anorm`, so a free `Anorm` alongside ANY
/// configured baseline — even a fully frozen one — is rejected
/// (`validate_multiplicative_baseline`).  A frozen-`b0` + free-`Anorm`
/// combination would be well-posed, but supporting it buys nothing (`Anorm`
/// would just play `b0`'s role at a rescaled value); the sanctioned
/// combination is the additive ABC(+DF) background with `fit_anorm = false`.
///
/// What prevents the A3-style runaway is SMOOTHNESS, not amplitude: a
/// single global quadratic in ln E cannot produce a narrow local feature at
/// a resonance whatever its coefficients, so the dips stay attributed to
/// the physics model.  The (configurable) coefficient boxes bound the
/// baseline's overall tilt/curvature PER ln-E UNIT, not the evaluated
/// `B(E)` itself: the worst-case excursion from `b0` grows with the grid's
/// log-width, `|B − b0| ≤ |b1|·|z|_max + |b2|·z²_max` (≈ ±0.23 beyond
/// `b0`'s own ±0.1 box on a 1–30 eV grid at the default ±0.05 boxes; more
/// on wider grids, where only the runtime `B(E) > 0` guard applies).
/// "A few % off unity" describes the typical FITTED values on campaign
/// data and the hard `b0` box at mid-grid — not a hard envelope on `B(E)`
/// across the grid.
#[derive(Debug, Clone)]
pub struct MultiplicativeBaselineConfig {
    /// Initial mid-grid baseline value `b0` (default 1.0).
    pub b0_init: f64,
    /// Initial slope per ln-E unit `b1` (default 0.0).
    pub b1_init: f64,
    /// Initial curvature per ln-E² unit `b2` (default 0.0).
    pub b2_init: f64,
    /// Whether `b0` is free (default true).  All-false = frozen baseline
    /// (the #633 fixed-parameter pattern; used by the spatial global mode).
    pub fit_b0: bool,
    /// Whether `b1` is free (default true).
    pub fit_b1: bool,
    /// Whether `b2` is free (default true).
    pub fit_b2: bool,
    /// `spatial_map_typed` only: fit ONE baseline on the aggregated mean
    /// spectrum, then freeze it for every pixel (default true — per-pixel
    /// baselines on <500 counts/bin biased fitted temperatures by up to
    /// +150 K on IPTS-37432; the global mode removed 80 % of that).
    /// Ignored by the single-spectrum fitters.
    pub spatial_global: bool,
    /// Optimizer box for `b0` (default `(0.9, 1.1)` — "a few % off unity").
    pub b0_bounds: (f64, f64),
    /// Optimizer box for `b1` (default `(-0.05, 0.05)`).
    pub b1_bounds: (f64, f64),
    /// Optimizer box for `b2` (default `(-0.05, 0.05)`).
    pub b2_bounds: (f64, f64),
}

impl Default for MultiplicativeBaselineConfig {
    fn default() -> Self {
        Self {
            b0_init: 1.0,
            b1_init: 0.0,
            b2_init: 0.0,
            fit_b0: true,
            fit_b1: true,
            fit_b2: true,
            spatial_global: true,
            b0_bounds: (0.9, 1.1),
            b1_bounds: (-0.05, 0.05),
            b2_bounds: (-0.05, 0.05),
        }
    }
}

/// Indices of the multiplicative-baseline parameters in the full parameter
/// vector (issue #635).
#[derive(Debug, Clone, Copy)]
struct BaselineIndices {
    b0: usize,
    b1: usize,
    b2: usize,
}

// ── New typed pipeline API (Phase 0) ─────────────────────────────────────

/// Typed input data — makes the data format explicit at the API boundary.
///
/// The two variants carry genuinely different data:
/// - **Counts**: raw detector counts + open beam → Poisson statistics native
/// - **Transmission**: normalized T = sample/open_beam + uncertainty → Gaussian statistics
///
/// `spatial_map_typed` dispatches to the correct fitting engine based on
/// which variant is provided.  This eliminates the overloaded positional
/// arguments that caused silent misinterpretation in the old API.
#[derive(Debug, Clone)]
pub enum InputData {
    /// Pre-normalized transmission with Gaussian uncertainties.
    ///
    /// Use with LM; a Poisson/KL count objective is rejected for ratios.
    Transmission {
        /// Measured transmission T(E), values typically in [0, 2].
        transmission: Vec<f64>,
        /// Per-bin uncertainty σ_T(E).
        uncertainty: Vec<f64>,
    },
    /// Raw detector counts with open beam reference.
    ///
    /// Always uses Poisson KL (statistically optimal for count data).
    /// The fitting engine works directly on counts — no information-losing
    /// normalization to transmission.
    Counts {
        /// Sample counts per energy bin.
        sample_counts: Vec<f64>,
        /// Open-beam counts per energy bin (normalization reference).
        open_beam_counts: Vec<f64>,
    },
    /// Counts with pre-estimated nuisance parameters (power users).
    ///
    /// Use when you want to inspect or override the flux estimate before fitting.
    CountsWithNuisance {
        /// Sample counts per energy bin.
        sample_counts: Vec<f64>,
        /// Estimated flux spectrum (from open beam spatial average).
        flux: Vec<f64>,
        /// Estimated detector background spectrum.
        background: Vec<f64>,
    },
}

impl InputData {
    /// Number of energy bins.
    pub fn n_energies(&self) -> usize {
        match self {
            Self::Transmission { transmission, .. } => transmission.len(),
            Self::Counts { sample_counts, .. } => sample_counts.len(),
            Self::CountsWithNuisance { sample_counts, .. } => sample_counts.len(),
        }
    }

    /// Whether this is count data (Poisson-native).
    pub fn is_counts(&self) -> bool {
        matches!(self, Self::Counts { .. } | Self::CountsWithNuisance { .. })
    }
}

/// Solver-specific configuration.
///
/// Carries the full solver config inside each variant, making invalid
/// combinations unrepresentable.
#[derive(Debug, Clone, Default)]
pub enum SolverConfig {
    /// Levenberg-Marquardt chi-squared minimizer (transmission path).
    LevenbergMarquardt(LmConfig),
    /// Poisson-KL counts-domain fitter.
    ///
    /// For **counts** inputs this dispatches to the joint-Poisson profile-
    /// binomial-deviance path (`joint_poisson_fit`), validated against
    /// synthetic counts benchmarks and locked by a real-VENUS counts
    /// regression test on the committed aggregated-Hf fixture.  Uses an explicit
    /// `c = Q_s/Q_ob` from `CountsBackgroundConfig::c` and reports
    /// `D/(n − k)` as the primary
    /// GOF.  Stage-1 damped Fisher + optional Nelder-Mead polish (see
    /// [`nereids_fitting::joint_poisson::JointPoissonFitConfig`]).
    ///
    /// **Transmission inputs are rejected.** A Poisson objective requires the
    /// separate open and sample counts; applying it to a fractional
    /// transmission silently ignores the supplied uncertainty.
    PoissonKL(PoissonConfig),
    /// Automatic: Counts → PoissonKL (counts-domain joint-Poisson),
    /// Transmission → LM.
    #[default]
    Auto,
}

/// Background model for the counts fitting engine.
///
/// In the counts domain, the forward model is:
///   Y(E) = α₁ · [Φ(E) · exp(-Σ nᵢσᵢ(E))] + α₂ · B(E)
///
/// where Φ(E) is the incident flux and B(E) is detector/gamma background.
/// The reference Φ(E) / B(E) spectra are supplied by the caller or by
/// spatial pre-processing; this config only controls the fitted scale factors.
///
/// Important distinction:
/// - This is a detector-space counts background model `B(E)`.
/// - It is NOT the same as the transmission-lift background used by
///   `BackgroundConfig`, which models additive uplift of the apparent
///   transmission curve (for example gamma-tail structure that pushes
///   transmission upward).
///
/// For VENUS MCP/TPX event detectors, the current working assumption is:
/// - raw/open-beam is the correct normalization baseline
/// - dark-current / CCD-style electronic offset is not modeled
/// - rare ghost counts may exist at the hardware level, but are currently
///   treated as negligible unless a detector-background reference spectrum
///   is explicitly provided
///
/// This is structurally different from the transmission background model
/// ([`BackgroundConfig`]) because:
/// - Φ and B are reference spectra, not fitted per pixel
/// - α₁ and α₂ are optional per-pixel scale corrections
/// - All terms are non-negative (required for valid Poisson NLL)
#[derive(Debug, Clone)]
pub struct CountsBackgroundConfig {
    /// **Research-only.** Initial α₁ flux-scale value used by
    /// [`crate::pipeline::evaluate_jacobian_and_fisher`] (Fisher-info
    /// research helper, Epic #394).  Not honoured by the production fit
    /// path; `SolverConfig::PoissonKL` profiles the flux via `λ̂` and
    /// rejects alpha fitting.
    pub alpha_1_init: f64,
    /// **Research-only.** Initial α₂ detector-bg-scale value, same
    /// provisions as `alpha_1_init`.
    pub alpha_2_init: f64,
    /// **Research-only.** Fit α₁ flag — only consumed by
    /// `evaluate_jacobian_and_fisher`.  Passing `true` through
    /// `SolverConfig::PoissonKL` on counts input yields an error.
    pub fit_alpha_1: bool,
    /// **Research-only.** Fit α₂ flag — see `fit_alpha_1`.
    pub fit_alpha_2: bool,
    /// Proton-charge ratio `c = Q_s / Q_ob` for the counts-KL solver.
    ///
    /// Default `1.0`, correct only when the caller has already PC-
    /// normalized the open-beam counts so that `flux = c · O`.  For the
    /// counts-KL dispatch (`SolverConfig::PoissonKL` on counts input),
    /// set this to the actual `Q_sample / Q_open_beam` ratio and pass
    /// raw open-beam counts — the joint-Poisson solver will profile
    /// `λ̂` itself.  Ignored by LM paths.
    pub c: f64,
}

impl Default for CountsBackgroundConfig {
    fn default() -> Self {
        Self {
            alpha_1_init: 1.0,
            alpha_2_init: 1.0,
            fit_alpha_1: false,
            fit_alpha_2: false,
            c: 1.0,
        }
    }
}

/// Source and detector-bin information required for exact resolved-count fits.
///
/// `UnifiedFitConfig::energies` supplies the true-energy quadrature points.
/// The observed open/sample count arrays must be in the same detector-time
/// order as consecutive intervals in `detector_time_edges_us`.
#[derive(Debug, Clone)]
pub struct ExactCountResponseConfig {
    /// Incident neutron fluence already integrated over each true-energy
    /// quadrature element, with detector efficiency folded in — the discrete
    /// `F_j = w_j ε(E_j) Φ(E_j)` of the pipeline-map contract (R5·7). The
    /// absolute scale cancels in the profiled count likelihood; the energy
    /// dependence does not.
    pub incident_fluence_weights: Vec<f64>,
    /// Actual detector-time bin edges in ascending microseconds.
    pub detector_time_edges_us: Vec<f64>,
    /// Fixed time offset applied by the detector response, in microseconds.
    pub timing_offset_us: f64,
}

// ── Phase 2: UnifiedFitConfig + fit_spectrum_typed ───────────────────────

/// Unified fit configuration for all data types and solvers.
///
/// Carries both transmission and counts background configs, and uses
/// [`SolverConfig`] (which embeds solver-specific tuning).
#[derive(Debug, Clone)]
pub struct UnifiedFitConfig {
    // ── Physics (shared by both engines) ──
    energies: Vec<f64>,
    resonance_data: Vec<ResonanceData>,
    isotope_names: Vec<String>,
    temperature_k: f64,
    resolution: Option<ResolutionFunction>,
    initial_densities: Vec<f64>,
    fit_temperature: bool,
    compute_covariance: bool,
    /// Inflate covariance-only uncertainties by `sqrt(χ²/dof)` at convergence
    /// (issue #638). Applies only to the raw-count joint-Poisson path; the LM
    /// transmission path is already χ²-scaled, so the flag is a no-op there.
    /// Off by default — reported σ stays the inverse-Fisher lower bound.
    scale_by_chi2: bool,

    // ── Solver ──
    solver: SolverConfig,

    // ── Background models (engine-specific) ──
    /// SAMMY-style background for the transmission engine.
    transmission_background: Option<BackgroundConfig>,
    /// Optional bounded multiplicative baseline (issue #635); `None` = off.
    multiplicative_baseline: Option<MultiplicativeBaselineConfig>,
    /// Counts-domain background for the counts engine.
    counts_background: Option<CountsBackgroundConfig>,
    /// Exact separate-arm response inputs for resolved counts.
    exact_count_response: Option<ExactCountResponseConfig>,

    // ── Joint-Poisson solver knobs (counts path only) ──
    /// When `Some(false)`, the counts-KL dispatch disables Nelder-Mead polish
    /// (stage-1 damped Fisher only).  When `Some(true)`, polish is forced on
    /// regardless of context.  When `None`, the dispatcher picks a default:
    /// polish on for single-spectrum fits, off for per-pixel spatial maps
    /// (17 min polish per pixel is untenable).
    counts_enable_polish: Option<bool>,

    // ── Precomputed caches (injected by spatial_map_typed) ──
    precomputed_cross_sections: Option<PrecomputedXs>,
    precomputed_base_xs: Option<Arc<Vec<Vec<f64>>>>,
    /// Resolution broadening plan built once for `(energies, resolution)`.
    ///
    /// Populated by [`spatial_map_typed`] when the data grid is shared
    /// across every pixel, so each per-pixel fit reuses a single
    /// hoisted TOF / kernel-interpolation / bracket table instead of
    /// rebuilding it every broadening call.  `None` ⇒ the fit-model
    /// layer falls back to the per-call broadening path with byte-
    /// identical output.
    precomputed_resolution_plan: Option<Arc<nereids_physics::resolution::ResolutionPlan>>,
    /// Sparse empirical cubature plan built once for `(energies,
    /// isotope_set, density_box)` — when present and the dispatch
    /// conditions hold (k ≥ 2, fixed calibration, fixed temperature),
    /// the fit model replaces `exp(-Σ n σ) + apply_resolution` with
    /// `cubature.forward_and_jacobian(n)` directly.  See epic #472.
    ///
    /// `None` ⇒ existing path.  The cubature is advisory — if its
    /// target grid doesn't match `energies` or if `k == 1` or
    /// temperature/energy-scale fitting is active, the fit model
    /// silently falls back to the exact path.
    precomputed_sparse_cubature_plan:
        Option<Arc<nereids_physics::surrogate::SparseEmpiricalCubaturePlan>>,
    /// Scalar (k = 1) surrogate plan for the grouped-Hf / single-
    /// isotope path.  Parallel to `precomputed_sparse_cubature_plan`
    /// but dispatches at `k == 1`.
    precomputed_sparse_scalar_plan: Option<Arc<nereids_physics::surrogate::ScalarSurrogatePlan>>,

    // ── Energy-scale calibration (SAMMY TZERO equivalent) ──
    /// When true, fit t₀ (μs) and L_scale (dimensionless) parameters.
    /// These adjust the energy axis during fitting:
    ///   E_corr = (TOF_FACTOR * L * L_scale / (t_nom - t₀))²
    fit_energy_scale: bool,
    /// Initial t₀ value in microseconds (default 0.0).
    t0_init_us: f64,
    /// Initial L_scale value (dimensionless, default 1.0).
    l_scale_init: f64,
    /// Flight path in meters for TOF↔energy conversion (default from resolution or 25.0).
    flight_path_m: f64,
    /// Method for the t0 / L_scale Jacobian columns. `None` defers to
    /// `EnergyScaleJacobianMethod::from_env`: it uses the
    /// `NEREIDS_TZERO_JACOBIAN` env var when set, and otherwise falls
    /// back to `PartialGal` (the default since issue #489).
    /// `Some(_)` bypasses both the env var and the default.
    tzero_jacobian_method: Option<nereids_fitting::transmission_model::EnergyScaleJacobianMethod>,
    /// Whether the resonance peak-match seed runs before an energy-scale fit
    /// (default `true`).  `calibrate_energy` disables it (issue #634): its
    /// global anchor stages already seed `(t0, L_scale)`, and the peak-match
    /// dip detector mislocates saturated flat-bottom dips (a strict
    /// local-minimum test on a ≈0 plateau), producing an in-bounds but wrong
    /// least-squares seed that OVERWRITES the caller's anchor — observed
    /// driving a fit from 0.12 µs off truth to a 7 µs-wrong pit.
    energy_scale_seed_enabled: bool,

    // ── Fit energy range restriction (SAMMY EMIN/EMAX equivalent) ──
    /// User-specified fit-energy-range restriction.  When `Some((min,
    /// max))`, the configured `energies` grid is expected to extend
    /// beyond `[min, max]` by a kernel-margin (~5×FWHM); the GUI / pre-
    /// processing layer slices the input data to that extended grid
    /// before constructing this config.  The solver cost functions
    /// (LM transmission and joint-Poisson PBD) mask residuals outside
    /// `[min, max]` to zero so resonance contributions just inside the
    /// boundaries are correctly broadened.
    ///
    /// `None` (default) = full grid, no masking.  Reduced χ² / dof
    /// counts are computed against the active bin count when masking
    /// is in effect.  SAMMY equivalent: the `EMIN` / `EMAX` analysis
    /// limits (INPut-file card set 2, manual Table VI A.1); the kernel
    /// margin follows the same endpoint-extension principle as SAMMY's
    /// auxiliary grid (general construction Sec. III.A.2(c); the
    /// quantitative `[Emin − Wmin, Emax + Wmax]` statement is in the
    /// Leal-Hwang procedure, Sec. III.B.2), with a deliberately
    /// conservative 5×FWHM margin.
    fit_energy_range: Option<(f64, f64)>,

    // ── Isotope group mapping (optional) ──
    /// Maps member isotope index → density parameter index.
    /// `None` = identity mapping (one param per isotope, backward compat).
    pub(crate) density_indices: Option<Vec<usize>>,
    /// Fractional ratio per member isotope.
    /// `None` = all 1.0 (backward compat).
    pub(crate) density_ratios: Option<Vec<f64>>,
    /// Number of density parameters (groups or isotopes).
    /// `None` = `resonance_data.len()` (backward compat).
    n_density_params: Option<usize>,

    /// Per-density-parameter free/fixed mask (issue #633).
    ///
    /// `None` = every density is free (default; preserves the historic
    /// behaviour bit-for-bit). `Some(mask)` with `mask[i] == false`
    /// freezes density parameter `i` at its initial value — the standard
    /// resonance-thermometry workflow, where the areal density is known
    /// from a calibration foil and only temperature (and/or the energy
    /// scale / baseline) is fitted. Length equals `n_density_params()`.
    ///
    /// A frozen density still occupies its slot in the FULL parameter
    /// vector (built as [`FitParameter::fixed`]), so *value* reads from
    /// `result.params[i]` are unchanged. Its *uncertainty*, however, is
    /// not: the solver's covariance/uncertainty vector is FREE-only
    /// (length `n_free`), so a frozen density has no entry there. Result
    /// extraction must map full-layout indices to free positions (see
    /// `free_uncertainty`) and report a frozen density's 1-σ as `NaN`.
    density_free: Option<Vec<bool>>,
}

impl UnifiedFitConfig {
    /// Construct a new config with validation.
    pub fn new(
        energies: Vec<f64>,
        resonance_data: Vec<ResonanceData>,
        isotope_names: Vec<String>,
        temperature_k: f64,
        resolution: Option<ResolutionFunction>,
        initial_densities: Vec<f64>,
    ) -> Result<Self, FitConfigError> {
        if energies.is_empty() {
            return Err(FitConfigError::EmptyEnergies);
        }
        if resonance_data.is_empty() {
            return Err(FitConfigError::EmptyResonanceData);
        }
        if initial_densities.len() != resonance_data.len() {
            return Err(FitConfigError::DensityCountMismatch {
                densities: initial_densities.len(),
                isotopes: resonance_data.len(),
            });
        }
        if isotope_names.len() != resonance_data.len() {
            return Err(FitConfigError::NameCountMismatch {
                names: isotope_names.len(),
                isotopes: resonance_data.len(),
            });
        }
        if !temperature_k.is_finite() {
            return Err(FitConfigError::NonFiniteTemperature(temperature_k));
        }
        if temperature_k < 0.0 {
            return Err(FitConfigError::NegativeTemperature(temperature_k));
        }
        Ok(Self {
            energies,
            resonance_data,
            isotope_names,
            temperature_k,
            resolution,
            initial_densities,
            fit_temperature: false,
            compute_covariance: true,
            scale_by_chi2: false,
            solver: SolverConfig::Auto,
            transmission_background: None,
            multiplicative_baseline: None,
            counts_background: None,
            exact_count_response: None,
            counts_enable_polish: None,
            precomputed_cross_sections: None,
            precomputed_base_xs: None,
            precomputed_resolution_plan: None,
            precomputed_sparse_cubature_plan: None,
            precomputed_sparse_scalar_plan: None,
            fit_energy_scale: false,
            t0_init_us: 0.0,
            l_scale_init: 1.0,
            flight_path_m: 25.0,
            density_indices: None,
            density_ratios: None,
            n_density_params: None,
            density_free: None,
            tzero_jacobian_method: None,
            energy_scale_seed_enabled: true,
            fit_energy_range: None,
        })
    }

    /// Override the method used for the t0 / L_scale Jacobian columns
    /// in `EnergyScaleTransmissionModel`. `None` (default) defers to
    /// the model's own default selection via
    /// `EnergyScaleJacobianMethod::from_env`: `PartialGal` since issue
    /// #489 unless overridden by `NEREIDS_TZERO_JACOBIAN`.
    #[must_use]
    pub fn with_tzero_jacobian_method(
        mut self,
        method: Option<nereids_fitting::transmission_model::EnergyScaleJacobianMethod>,
    ) -> Self {
        self.tzero_jacobian_method = method;
        self
    }

    /// Enable/disable the resonance peak-match `(t0, L_scale)` seed that
    /// normally runs before an energy-scale fit (default `true`).  Callers
    /// that supply their own, stronger alignment anchor — `calibrate_energy`
    /// (issue #634) — disable it: the seed's dip detector mislocates
    /// saturated flat-bottom dips and its in-bounds least-squares result
    /// would overwrite the anchor.
    #[must_use]
    pub fn with_energy_scale_seed(mut self, enabled: bool) -> Self {
        self.energy_scale_seed_enabled = enabled;
        self
    }

    // ── Builder methods ──

    #[must_use]
    pub fn with_solver(mut self, solver: SolverConfig) -> Self {
        self.solver = solver;
        self
    }

    #[must_use]
    pub fn with_fit_temperature(mut self, v: bool) -> Self {
        self.fit_temperature = v;
        self
    }

    #[must_use]
    pub fn with_compute_covariance(mut self, v: bool) -> Self {
        self.compute_covariance = v;
        self
    }

    /// Enable χ²-scaled uncertainties (issue #638).
    ///
    /// When `true`, inflate the reported covariance-only σ by `sqrt` of the
    /// goodness-of-fit-per-dof that the **same result reports**, turning the
    /// inverse-Fisher lower bound into a goodness-of-fit-scaled estimate.
    /// Self-consistent on every path:
    ///
    /// - **Transmission (LM)**: the LM path applies its chi-squared scaling
    ///   unconditionally (Numerical Recipes §15.6), so the flag is a **no-op**.
    /// - **Counts (joint-Poisson)**: `σ → σ·√(D/ν)` using the
    ///   conditional-binomial `deviance_per_dof` (a genuine count-statistics
    ///   GOF), on opt-in.
    ///
    /// It never scales by a Poisson deviance on transmission fractions (which
    /// would be a pseudo-Poisson statistic, not a valid reduced-χ²). Off by
    /// default, so existing results are unchanged.
    #[must_use]
    pub fn with_scale_by_chi2(mut self, v: bool) -> Self {
        self.scale_by_chi2 = v;
        self
    }

    /// Enable energy-scale fitting (SAMMY TZERO equivalent).
    ///
    /// Adds t₀ (μs) and L_scale (dimensionless) as fit parameters.
    /// These adjust the energy axis during fitting to correct for
    /// flight-path and timing-offset uncertainties.
    #[must_use]
    pub fn with_energy_scale(
        mut self,
        t0_init_us: f64,
        l_scale_init: f64,
        flight_path_m: f64,
    ) -> Self {
        self.fit_energy_scale = true;
        self.t0_init_us = t0_init_us;
        self.l_scale_init = l_scale_init;
        self.flight_path_m = flight_path_m;
        self
    }

    /// Restrict the fit cost function to bins inside `[min_eV, max_eV]`
    /// (SAMMY EMIN/EMAX equivalent).  The configured `energies` grid is
    /// expected to extend by ~5×FWHM beyond `[min, max]` on each side
    /// (the GUI / pre-processing layer handles this); the LM and
    /// joint-Poisson cost paths mask residuals outside `[min, max]` to
    /// zero so resonance broadening at the boundaries is correct.
    /// `None` (default) = full grid, no masking.
    ///
    /// Validates the range up-front so non-finite or reversed bounds
    /// (which would silently produce an empty active-bin mask and a
    /// deceptive fit) are rejected at config-build time rather than
    /// surfacing as a downstream solver error.
    pub fn with_fit_energy_range(
        mut self,
        range: Option<(f64, f64)>,
    ) -> Result<Self, FitConfigError> {
        if let Some((lo, hi)) = range {
            if !lo.is_finite() || !hi.is_finite() {
                return Err(FitConfigError::InvalidFitEnergyRange(
                    "fit_energy_range bounds must be finite",
                ));
            }
            if lo >= hi {
                return Err(FitConfigError::InvalidFitEnergyRange(
                    "fit_energy_range min must be strictly less than max",
                ));
            }
        }
        self.fit_energy_range = range;
        Ok(self)
    }

    #[must_use]
    pub fn with_transmission_background(mut self, bg: BackgroundConfig) -> Self {
        self.transmission_background = Some(bg);
        self
    }

    /// Enable the bounded multiplicative polynomial baseline (issue #635):
    /// `y(E) = (b0 + b1·z + b2·z²) · T_model(E)`, `z = ln(E/E_ref)`.
    /// See [`MultiplicativeBaselineConfig`].  Validated at fit dispatch by
    /// `validate_multiplicative_baseline` (inits within bounds, `B(E) > 0`
    /// at the initial point, and no free `Anorm` alongside — `b0` and
    /// `Anorm` are degenerate normalizations).
    #[must_use]
    pub fn with_multiplicative_baseline(mut self, bl: MultiplicativeBaselineConfig) -> Self {
        self.multiplicative_baseline = Some(bl);
        self
    }

    #[must_use]
    pub fn with_counts_background(mut self, bg: CountsBackgroundConfig) -> Self {
        self.counts_background = Some(bg);
        self
    }

    /// Enable the exact separate-arm detector response for raw counts.
    #[must_use]
    pub fn with_exact_count_response(mut self, response: ExactCountResponseConfig) -> Self {
        self.exact_count_response = Some(response);
        self
    }

    /// Override the Nelder-Mead polish flag for the counts-KL dispatch.
    /// `Some(true)` forces polish on, `Some(false)` forces it off, `None`
    /// (the default) lets the dispatcher pick (polish on for single-spectrum,
    /// off for spatial maps).
    #[must_use]
    pub fn with_counts_enable_polish(mut self, v: Option<bool>) -> Self {
        self.counts_enable_polish = v;
        self
    }

    #[must_use]
    pub fn with_precomputed_cross_sections(mut self, xs: PrecomputedXs) -> Self {
        self.precomputed_cross_sections = Some(xs);
        self.precomputed_sparse_cubature_plan = None;
        self.precomputed_sparse_scalar_plan = None;
        self
    }

    #[must_use]
    pub fn with_precomputed_base_xs(mut self, xs: Arc<Vec<Vec<f64>>>) -> Self {
        self.precomputed_base_xs = Some(xs);
        // Base XS swap implies σ will be re-Doppler-broadened, so
        // the cubature's σ stack becomes stale.  Invalidate for
        // the same reason as `with_precomputed_cross_sections`.
        self.precomputed_sparse_cubature_plan = None;
        self.precomputed_sparse_scalar_plan = None;
        self
    }

    /// Attach a prebuilt resolution plan for the config's energy grid.
    ///
    /// The caller (typically `spatial_map_typed`) must ensure that
    /// `plan.target_energies()` equals `self.energies()`, otherwise
    /// the fit-model layer will return either a length-mismatch
    /// error or `ResolutionError::PlanGridMismatch` (for a different
    /// same-length grid) on the first broadening call.
    #[must_use]
    pub fn with_precomputed_resolution_plan(
        mut self,
        plan: Arc<nereids_physics::resolution::ResolutionPlan>,
    ) -> Self {
        self.precomputed_resolution_plan = Some(plan);
        self
    }

    /// Attach a prebuilt sparse empirical cubature plan for the
    /// config's energy grid + isotope set (see epic #472).
    ///
    /// The plan is advisory — the fit model falls back to the exact
    /// `ResolutionPlan` path when any of these guards fire:
    ///
    /// * `plan.target_energies() != self.energies()` (grid mismatch).
    /// * `plan.k() != n_density_params` (isotope-set mismatch).
    /// * `self.fit_temperature == true` (σ changes → atoms stale).
    /// * `self.fit_energy_scale == true` (grid changes → plan stale).
    /// * `n_density_params == 1` (the scalar fast-path is handled
    ///   separately — see the `k == 1` dispatch).
    ///
    /// Callers (typically `spatial_map_typed`) are responsible for
    /// ensuring the plan was built against compatible `sigmas` /
    /// `training_densities` / `jacobian_anchor`; the fit model cannot
    /// re-check those at dispatch time.
    #[must_use]
    pub fn with_precomputed_sparse_cubature_plan(
        mut self,
        plan: Arc<nereids_physics::surrogate::SparseEmpiricalCubaturePlan>,
    ) -> Self {
        self.precomputed_sparse_cubature_plan = Some(plan);
        self
    }

    /// Attach a prebuilt scalar (k = 1) surrogate plan.  Same
    /// invalidation discipline as the cubature: the plan is cleared on
    /// `with_groups` / `with_precomputed_cross_sections` /
    /// `with_precomputed_base_xs`, so a stale σ cannot silently
    /// dispatch.
    #[must_use]
    pub fn with_precomputed_sparse_scalar_plan(
        mut self,
        plan: Arc<nereids_physics::surrogate::ScalarSurrogatePlan>,
    ) -> Self {
        self.precomputed_sparse_scalar_plan = Some(plan);
        self
    }

    /// Configure isotope groups with ratio constraints.
    ///
    /// Each group binds multiple isotopes to one fitted density parameter.
    /// `groups` is a slice of `(IsotopeGroup, member_resonance_data)` pairs.
    /// `initial_densities` must have one entry per group.
    ///
    /// Replaces the existing per-isotope configuration with the expanded
    /// group mapping (flattened resonance_data + density_indices + density_ratios).
    ///
    /// # Errors
    /// [`FitConfigError::DensityFreezeBeforeGroups`] if a density-freeze mask
    /// (issue #633) was already set — grouping redefines the density
    /// parameters, so the pre-group mask no longer applies. Configure the
    /// freeze *after* grouping. (Erroring rather than silently clearing the
    /// mask keeps a mis-ordered builder chain from producing an unexpectedly
    /// unfrozen fit.)
    pub fn with_groups(
        mut self,
        groups: &[(&nereids_core::types::IsotopeGroup, &[ResonanceData])],
        initial_densities: Vec<f64>,
    ) -> Result<Self, FitConfigError> {
        if self.density_free.is_some() {
            return Err(FitConfigError::DensityFreezeBeforeGroups);
        }
        if groups.is_empty() {
            return Err(FitConfigError::EmptyResonanceData);
        }
        if initial_densities.len() != groups.len() {
            return Err(FitConfigError::DensityCountMismatch {
                densities: initial_densities.len(),
                isotopes: groups.len(),
            });
        }
        let mut all_resonance_data = Vec::new();
        let mut all_indices = Vec::new();
        let mut all_ratios = Vec::new();
        let mut names = Vec::new();
        for (g_idx, (group, rd_list)) in groups.iter().enumerate() {
            if rd_list.len() != group.n_members() {
                return Err(FitConfigError::GroupMemberCountMismatch {
                    group_name: group.name().to_string(),
                    rd_count: rd_list.len(),
                    member_count: group.n_members(),
                });
            }
            names.push(group.name().to_string());
            for ((isotope, ratio), rd) in group.members().iter().zip(rd_list.iter()) {
                // Validate that the ResonanceData matches the expected member isotope.
                if rd.isotope != *isotope {
                    return Err(FitConfigError::GroupMemberIsotopeMismatch {
                        group_name: group.name().to_string(),
                        expected_z: isotope.z(),
                        expected_a: isotope.a(),
                        got_z: rd.isotope.z(),
                        got_a: rd.isotope.a(),
                    });
                }
                all_resonance_data.push(rd.clone());
                all_indices.push(g_idx);
                all_ratios.push(*ratio);
            }
        }
        self.resonance_data = all_resonance_data;
        self.isotope_names = names;
        self.initial_densities = initial_densities;
        self.n_density_params = Some(groups.len());
        self.density_indices = Some(all_indices);
        self.density_ratios = Some(all_ratios);
        // Note: a pre-existing density-freeze mask (issue #633) is rejected up
        // front (see the guard at the top of this method), so by here
        // `density_free` is always `None`. Freezing is configured after
        // grouping, against the new group density layout.
        // Clear stale caches — the isotope set changed.
        self.precomputed_cross_sections = None;
        self.precomputed_base_xs = None;
        // Clear the cubature plan too: atoms are σ-coordinates in
        // ℝ^k and `k` / σ-stack change when groups are reconfigured,
        // so a stale plan would silently produce wrong forward /
        // Jacobian values for the new isotope set even if
        // `cubature_eligible` accepts the same k + grid.
        self.precomputed_sparse_cubature_plan = None;
        self.precomputed_sparse_scalar_plan = None;
        Ok(self)
    }

    // ── Accessors ──

    /// Caller-attached sparse empirical cubature plan, if any.
    /// `spatial_map_typed` reads this so a pre-existing plan is
    /// preserved instead of being clobbered by the local rebuild
    /// pathway.
    pub fn precomputed_sparse_cubature_plan(
        &self,
    ) -> Option<&Arc<nereids_physics::surrogate::SparseEmpiricalCubaturePlan>> {
        self.precomputed_sparse_cubature_plan.as_ref()
    }

    /// Caller-attached scalar (k = 1) surrogate plan, if any.
    pub fn precomputed_sparse_scalar_plan(
        &self,
    ) -> Option<&Arc<nereids_physics::surrogate::ScalarSurrogatePlan>> {
        self.precomputed_sparse_scalar_plan.as_ref()
    }

    pub fn energies(&self) -> &[f64] {
        &self.energies
    }
    pub fn resonance_data(&self) -> &[ResonanceData] {
        &self.resonance_data
    }
    pub fn isotope_names(&self) -> &[String] {
        &self.isotope_names
    }
    pub fn temperature_k(&self) -> f64 {
        self.temperature_k
    }
    pub fn resolution(&self) -> Option<&ResolutionFunction> {
        self.resolution.as_ref()
    }
    pub fn initial_densities(&self) -> &[f64] {
        &self.initial_densities
    }
    pub fn solver(&self) -> &SolverConfig {
        &self.solver
    }
    pub fn fit_temperature(&self) -> bool {
        self.fit_temperature
    }
    pub fn transmission_background(&self) -> Option<&BackgroundConfig> {
        self.transmission_background.as_ref()
    }
    /// The configured multiplicative baseline (issue #635), if any.
    pub fn multiplicative_baseline(&self) -> Option<&MultiplicativeBaselineConfig> {
        self.multiplicative_baseline.as_ref()
    }
    pub fn counts_background(&self) -> Option<&CountsBackgroundConfig> {
        self.counts_background.as_ref()
    }
    pub fn exact_count_response(&self) -> Option<&ExactCountResponseConfig> {
        self.exact_count_response.as_ref()
    }
    /// Counts-KL polish override (see [`Self::with_counts_enable_polish`]).
    pub fn counts_enable_polish(&self) -> Option<bool> {
        self.counts_enable_polish
    }
    /// Whether SAMMY TZERO energy-scale calibration is enabled
    /// (see [`Self::with_energy_scale`]).
    pub fn fit_energy_scale(&self) -> bool {
        self.fit_energy_scale
    }
    /// Whether χ²-scaled uncertainties are enabled
    /// (see [`Self::with_scale_by_chi2`]).
    pub fn scale_by_chi2(&self) -> bool {
        self.scale_by_chi2
    }
    /// Nominal flight path (m) configured via [`Self::with_energy_scale`].
    pub fn flight_path_m(&self) -> f64 {
        self.flight_path_m
    }
    /// User-specified fit-energy-range restriction (SAMMY EMIN/EMAX
    /// equivalent), or `None` for full-grid fitting.
    /// See [`Self::with_fit_energy_range`].
    pub fn fit_energy_range(&self) -> Option<(f64, f64)> {
        self.fit_energy_range
    }
    /// Baseline log-basis reference energy over the ACTIVE fit window
    /// (issue #648).  Every baseline construction site must use this rather
    /// than `baseline_reference_energy(self.energies())`: with a
    /// `fit_energy_range` set, the full-grid midpoint sits thousands of eV
    /// away from the window and the baseline silently absorbs temperature
    /// broadening.  Folds the `fit_energy_range` mask in one place so no
    /// call site can reintroduce the full-grid bug.
    pub fn baseline_reference_energy(&self) -> f64 {
        let mask = nereids_fitting::active_mask::build_active_mask(
            self.energies(),
            self.fit_energy_range(),
        );
        nereids_fitting::transmission_model::baseline_reference_energy_active(
            self.energies(),
            mask.as_deref(),
        )
    }
    pub fn precomputed_cross_sections(&self) -> Option<&PrecomputedXs> {
        self.precomputed_cross_sections.as_ref()
    }
    /// Number of density parameters (one per group or per isotope).
    pub fn n_density_params(&self) -> usize {
        self.n_density_params.unwrap_or(self.resonance_data.len())
    }

    /// Freeze (or unfreeze) **all** density parameters at their initial
    /// values (issue #633). The standard resonance-thermometry recipe:
    /// the areal density is known from a calibration foil, so only
    /// temperature (and/or the energy scale / baseline) is fitted.
    ///
    /// `with_fix_densities(true)` sets an all-fixed mask;
    /// `with_fix_densities(false)` clears any mask back to all-free.
    /// Applies to every fitter and to `spatial_map_typed`.
    ///
    /// Call this **after** [`Self::with_groups`] — grouping redefines the
    /// density parameters, so [`Self::with_groups`] rejects a freeze mask set
    /// before it ([`FitConfigError::DensityFreezeBeforeGroups`]).
    #[must_use]
    pub fn with_fix_densities(mut self, fix: bool) -> Self {
        self.density_free = if fix {
            Some(vec![false; self.n_density_params()])
        } else {
            None
        };
        self
    }

    /// Per-density-parameter free/fixed mask (SAMMY-style selective
    /// freezing): `free[i] == false` freezes density parameter `i` at its
    /// initial value. Length must equal [`Self::n_density_params`] — one
    /// entry per isotope for ungrouped fits, one per group for grouped
    /// fits.
    ///
    /// Call this **after** [`Self::with_groups`] — grouping redefines the
    /// density parameters, so [`Self::with_groups`] rejects a freeze mask set
    /// before it ([`FitConfigError::DensityFreezeBeforeGroups`]).
    ///
    /// # Errors
    /// [`FitConfigError::DensityCountMismatch`] if `free.len()` differs
    /// from the density-parameter count.
    pub fn with_density_free(mut self, free: Vec<bool>) -> Result<Self, FitConfigError> {
        let n = self.n_density_params();
        if free.len() != n {
            return Err(FitConfigError::DensityCountMismatch {
                densities: free.len(),
                isotopes: n,
            });
        }
        // All-free is represented as `None` so the historic path stays
        // byte-identical (no behavioural change when nothing is frozen).
        self.density_free = if free.iter().all(|&f| f) {
            None
        } else {
            Some(free)
        };
        Ok(self)
    }

    /// Whether density parameter `i` is frozen. `false` (free) unless an
    /// explicit mask marks it fixed.
    fn density_is_fixed(&self, i: usize) -> bool {
        self.density_free
            .as_ref()
            .is_some_and(|mask| !mask.get(i).copied().unwrap_or(true))
    }

    /// Count of density parameters that are free (not frozen). Equals
    /// [`Self::n_density_params`] when no mask is set.
    fn n_free_density_params(&self) -> usize {
        (0..self.n_density_params())
            .filter(|&i| !self.density_is_fixed(i))
            .count()
    }

    /// Resolve `SolverConfig::Auto` into a concrete solver for the given input.
    pub(crate) fn effective_solver(&self, input: &InputData) -> SolverConfig {
        match &self.solver {
            SolverConfig::Auto => {
                if input.is_counts() {
                    SolverConfig::PoissonKL(PoissonConfig::default())
                } else {
                    SolverConfig::LevenbergMarquardt(LmConfig::default())
                }
            }
            other => other.clone(),
        }
    }
}

/// Validate the exact separate-arm contract for count-domain resolution.
///
/// The physical detector observes separately broadened arms `R[Phi]` and
/// `R[Phi*T]`; a post-hoc broadened ratio `R[T]` is not that response
/// (pipeline-map R5·7). Counts with an active instrument resolution therefore
/// require the exact-response inputs, and every shape/consistency rule of
/// those inputs is enforced here.
///
/// Kept as one shared boundary check so single-spectrum fitting, spatial
/// fitting, and the public Fisher helper cannot drift to different behavior.
pub(crate) fn validate_counts_resolution_route(
    is_counts: bool,
    observed_bin_count: usize,
    config: &UnifiedFitConfig,
) -> Result<(), PipelineError> {
    if !is_counts && config.exact_count_response().is_some() {
        return Err(PipelineError::InvalidParameter(
            "exact_count_response is a raw-count model and cannot be attached to \
             normalized transmission"
                .into(),
        ));
    }
    if is_counts && let Some(resolution) = config.resolution() {
        // A Gaussian energy-broadening model has no detector-time bin
        // probability law, so the exact-input remedy is impossible for it —
        // do not send the caller to build inputs that a later stage rejects.
        if matches!(resolution, ResolutionFunction::Gaussian(_)) {
            return Err(PipelineError::InvalidParameter(
                "counts input with instrument resolution requires the exact \
                 separate-arm model R[Phi] and R[Phi*T], and Gaussian energy \
                 broadening cannot provide it: resolved raw-count fitting needs \
                 a detector-time response (TabulatedResolution or \
                 IkedaCarpenter); the R[T] shortcut is not used"
                    .into(),
            ));
        }
        let exact = config.exact_count_response().ok_or_else(|| {
            PipelineError::InvalidParameter(
                "counts input with instrument resolution requires the exact \
                 separate-arm model R[Phi] and R[Phi*T]: provide incident fluence \
                 weights and detector-time bin edges through exact_count_response; \
                 the R[T] shortcut is not used"
                    .into(),
            )
        })?;
        if exact.incident_fluence_weights.len() != config.energies().len() {
            return Err(PipelineError::ShapeMismatch(format!(
                "exact_count_response incident_fluence_weights length {} must match \
                 the true-energy grid length {}",
                exact.incident_fluence_weights.len(),
                config.energies().len()
            )));
        }
        // Validate the fluence VALUES at the boundary, not deep inside
        // `ExactTwoArmRatioModel::new` after the parallel response-matrix
        // build: a caller error must surface as InvalidParameter (Python
        // ValueError) like its sibling exact-input errors, never as a
        // solver-class Fitting error (RuntimeError), and must not pay for
        // the matrix build first.
        for (index, &fluence) in exact.incident_fluence_weights.iter().enumerate() {
            if !fluence.is_finite() || fluence < 0.0 {
                return Err(PipelineError::InvalidParameter(format!(
                    "exact_count_response incident_fluence_weights[{index}] must be \
                     finite and >= 0, got {fluence}"
                )));
            }
        }
        if !exact.incident_fluence_weights.iter().any(|&f| f > 0.0) {
            return Err(PipelineError::InvalidParameter(
                "exact_count_response incident_fluence_weights must contain at least \
                 one positive value; an all-zero incident source cannot produce the \
                 observed counts"
                    .into(),
            ));
        }
        if exact.detector_time_edges_us.len() != observed_bin_count + 1 {
            return Err(PipelineError::ShapeMismatch(format!(
                "exact_count_response detector_time_edges_us length {} must be one \
                 greater than the observed count-bin length {}",
                exact.detector_time_edges_us.len(),
                observed_bin_count
            )));
        }
        if !exact.timing_offset_us.is_finite() {
            return Err(PipelineError::InvalidParameter(format!(
                "exact_count_response timing_offset_us must be finite, got {}",
                exact.timing_offset_us
            )));
        }
        if config.fit_energy_scale() {
            return Err(PipelineError::InvalidParameter(
                "energy-scale fitting is not yet connected to the exact two-arm \
                 detector response; fitting cross-section energy while holding the \
                 response clock fixed would be physically inconsistent"
                    .into(),
            ));
        }
        if config.fit_energy_range().is_some() {
            return Err(PipelineError::InvalidParameter(
                "fit_energy_range is not yet supported by exact detector-time count \
                 response because true-energy points and detector-time bins are \
                 different axes"
                    .into(),
            ));
        }
    } else if is_counts && config.exact_count_response().is_some() {
        return Err(PipelineError::InvalidParameter(
            "exact_count_response requires an instrument resolution model".into(),
        ));
    }
    Ok(())
}

/// Fit a single spectrum using the typed input data API.
///
/// Dispatches to the correct fitting engine based on the `InputData` variant
/// and solver configuration:
///
/// | Input | Solver | Path |
/// |-------|--------|------|
/// | Transmission | LM | LM chi-squared with optional SAMMY background |
/// | Transmission | KL | Rejected: fractional transmission is not Poisson count data |
/// | Counts | KL | Poisson NLL on raw counts (statistically optimal) |
/// | Counts | LM | Rejected: silent ratio conversion loses count information |
/// | CountsWithNuisance | KL | Compatibility-only; nonzero background rejected |
pub fn fit_spectrum_typed(
    input: &InputData,
    config: &UnifiedFitConfig,
) -> Result<SpectrumFitResult, PipelineError> {
    validate_precomputed_cross_sections(config)?;
    fit_spectrum_validated(input, config)
}

pub(crate) fn fit_spectrum_validated(
    input: &InputData,
    config: &UnifiedFitConfig,
) -> Result<SpectrumFitResult, PipelineError> {
    let n_e = config.energies().len();

    // Validate temperature when fitting is requested
    if config.fit_temperature && config.temperature_k < 1.0 {
        return Err(PipelineError::InvalidParameter(format!(
            "temperature must be >= 1.0 K when fit_temperature is true, got {}",
            config.temperature_k,
        )));
    }

    // Reject a fully-constrained fit up front (issue #633): freezing every
    // density with no other free parameter leaves nothing to vary, and the
    // solver cores' all-fixed fast path would otherwise report
    // `converged = true` from a no-op evaluate-once — a misleading success at
    // a public entry point. Surface it as a clear config error instead.
    if count_free_params(config) == 0 {
        return Err(PipelineError::InvalidParameter(
            "no free parameters to fit: all densities are frozen and no other \
             parameter is free — free at least one density (with_density_free) \
             or enable fit_temperature / energy-scale / background"
                .to_string(),
        ));
    }

    // Exact resolved counts have two distinct axes: the config grid is true
    // neutron energy, while the input arrays are measured detector-time bins.
    // All other routes still require one datum per configured energy.
    let exact_resolved_counts = input.is_counts() && config.exact_count_response().is_some();
    if input.n_energies() != n_e && !exact_resolved_counts {
        return Err(PipelineError::ShapeMismatch(format!(
            "input data has {} energy bins but config.energies has {}",
            input.n_energies(),
            n_e,
        )));
    }

    // Validate auxiliary array lengths match the primary data
    match input {
        InputData::Transmission {
            transmission,
            uncertainty,
        } => {
            if uncertainty.len() != transmission.len() {
                return Err(PipelineError::ShapeMismatch(format!(
                    "uncertainty length {} != transmission length {}",
                    uncertainty.len(),
                    transmission.len(),
                )));
            }
        }
        InputData::Counts {
            sample_counts,
            open_beam_counts,
        } => {
            if open_beam_counts.len() != sample_counts.len() {
                return Err(PipelineError::ShapeMismatch(format!(
                    "open_beam_counts length {} != sample_counts length {}",
                    open_beam_counts.len(),
                    sample_counts.len(),
                )));
            }
        }
        InputData::CountsWithNuisance {
            sample_counts,
            flux,
            background,
        } => {
            if flux.len() != sample_counts.len() {
                return Err(PipelineError::ShapeMismatch(format!(
                    "flux length {} != sample_counts length {}",
                    flux.len(),
                    sample_counts.len(),
                )));
            }
            if background.len() != sample_counts.len() {
                return Err(PipelineError::ShapeMismatch(format!(
                    "background length {} != sample_counts length {}",
                    background.len(),
                    sample_counts.len(),
                )));
            }
        }
    }

    if matches!(input, InputData::Transmission { .. }) && config.counts_background().is_some() {
        return Err(PipelineError::InvalidParameter(
            "counts background configuration cannot be used with transmission data; \
             use SAMMY transmission_background or multiplicative_baseline for a \
             transmission fit, or supply separate open/sample counts"
                .into(),
        ));
    }

    validate_counts_resolution_route(input.is_counts(), input.n_energies(), config)?;

    let effective_solver = config.effective_solver(input);

    match (input, &effective_solver) {
        // ── Transmission + LM: the well-tested path ──
        (
            InputData::Transmission {
                transmission,
                uncertainty,
            },
            SolverConfig::LevenbergMarquardt(lm_cfg),
        ) => fit_transmission_lm(transmission, uncertainty, config, lm_cfg),

        // ── Transmission + KL: statistically invalid cross-domain route ──
        (InputData::Transmission { .. }, SolverConfig::PoissonKL(_)) => {
            Err(PipelineError::InvalidParameter(
                "normalized transmission cannot use the Poisson/KL count objective: \
                 fractional transmission is not Poisson count data and the supplied \
                 uncertainty would be ignored; use the LM least-squares transmission \
                 engine, or supply separate open/sample counts"
                    .into(),
            ))
        }

        // ── Counts + KL: joint-Poisson profile-binomial-deviance path ──
        //
        // The counts-KL solver is now the joint-Poisson fitter, validated
        // against synthetic benchmarks and a real-VENUS regression gate.  Uses the
        // explicit `c = Q_s/Q_ob` from `CountsBackgroundConfig::c` and
        // reports `D/(n − k)` as the primary
        // GOF.  Detector-space counts background `B_det` is assumed zero
        // here; the `CountsWithNuisance` arm lets callers supply a
        // detector-bg spectrum.
        (
            InputData::Counts {
                sample_counts,
                open_beam_counts,
            },
            SolverConfig::PoissonKL(poisson_cfg),
        ) => {
            let bg = vec![0.0f64; sample_counts.len()];
            fit_counts_joint_poisson(
                sample_counts,
                open_beam_counts,
                &bg,
                config,
                &poisson_to_joint_poisson_config(poisson_cfg, config),
            )
        }

        // ── CountsWithNuisance + KL: user-supplied nuisance ──
        (
            InputData::CountsWithNuisance {
                sample_counts,
                flux,
                background,
            },
            SolverConfig::PoissonKL(poisson_cfg),
        ) => fit_counts_joint_poisson(
            sample_counts,
            flux,
            background,
            config,
            &poisson_to_joint_poisson_config(poisson_cfg, config),
        ),

        // ── Counts + LM: information-losing cross-domain route ──
        (InputData::Counts { .. }, SolverConfig::LevenbergMarquardt(_)) => {
            Err(PipelineError::InvalidParameter(
                "separate open/sample counts cannot use the LM least-squares \
                 transmission engine: silently dividing the arms loses open-beam \
                 uncertainty and count statistics; use the Poisson/KL count engine"
                    .into(),
            ))
        }

        // ── CountsWithNuisance + LM: not meaningful ──
        (InputData::CountsWithNuisance { .. }, SolverConfig::LevenbergMarquardt(_)) => {
            Err(PipelineError::InvalidParameter(
                "CountsWithNuisance requires a counts-domain solver (LM cannot use nuisance parameters)"
                    .into(),
            ))
        }

        // Auto should be resolved by effective_solver
        (_, SolverConfig::Auto) => unreachable!("Auto should be resolved before dispatch"),
    }
}

/// Translate the user-facing `PoissonConfig` (payload of `SolverConfig::PoissonKL`)
/// into the internal `JointPoissonFitConfig` required by `joint_poisson_fit`.
///
/// Copies `max_iter` (the only field both structures meaningfully share) and
/// applies any spatial-level polish override carried on the `UnifiedFitConfig`.
fn poisson_to_joint_poisson_config(
    poisson_cfg: &PoissonConfig,
    config: &UnifiedFitConfig,
) -> JointPoissonFitConfig {
    let mut jp_cfg = JointPoissonFitConfig {
        max_iter: poisson_cfg.max_iter,
        scale_by_chi2: config.scale_by_chi2,
        ..Default::default()
    };
    if let Some(override_val) = config.counts_enable_polish() {
        jp_cfg.enable_polish = override_val;
    }
    jp_cfg
}

/// Transmission + LM path.
fn fit_transmission_lm(
    measured_t: &[f64],
    sigma: &[f64],
    config: &UnifiedFitConfig,
    lm_config: &LmConfig,
) -> Result<SpectrumFitResult, PipelineError> {
    let n_density_params = config.n_density_params();

    // Build parameter vector
    let mut param_vec = build_density_params(config);

    let temperature_index = append_temperature_param(&mut param_vec, config);
    let energy_scale_indices = append_energy_scale_params(&mut param_vec, config);

    // Issue #608: seed (t0, L_scale) via resonance peak-matching so the
    // production cold start lands in the global-min basin of the sharply
    // non-convex calibration χ² (the true-σ model's basins are razor-thin).
    seed_energy_scale_in_params(&mut param_vec, energy_scale_indices, measured_t, config);

    // Background parameters (rejects partial BackD/BackF; see
    // validate_transmission_background docstring).
    if let Some(bg) = config.transmission_background.as_ref() {
        validate_transmission_background(bg)?;
    }
    let bg_indices = config
        .transmission_background
        .as_ref()
        .map(|bg| append_background_params(&mut param_vec, bg));

    // Multiplicative-baseline parameters (issue #635) — appended LAST
    // (density → temperature → energy-scale → background → baseline).
    validate_multiplicative_baseline(config)?;
    let bl_indices = config
        .multiplicative_baseline
        .as_ref()
        .map(|bl| append_multiplicative_baseline_params(&mut param_vec, bl));

    let mut params = ParameterSet::new(param_vec);
    let mut lm_cfg = lm_config.clone();
    lm_cfg.compute_covariance = config.compute_covariance;

    // Build model — use EnergyScaleTransmissionModel when energy-scale is enabled
    let model: Box<dyn FitModel> = if let Some((t0_idx, ls_idx)) = energy_scale_indices {
        build_energy_scale_transmission_model(config, t0_idx, ls_idx, temperature_index)?
    } else {
        build_transmission_model(config, n_density_params, temperature_index)?
    };

    // Build the per-bin active mask (SAMMY EMIN/EMAX-equivalent fit-energy
    // -range restriction).  `None` when no range is configured — the
    // LM core treats that as "all bins active".
    let active_mask = nereids_fitting::active_mask::build_active_mask(
        config.energies(),
        config.fit_energy_range(),
    );

    // When a fit-energy-range is configured, reject the call early if
    // the user's `[E_min, E_max]` selects fewer active bins than the
    // dispatch can solve.  The LM core's `n_active < n_free` check
    // would also catch the underdetermined case on the main path, but
    // a dispatcher-level rejection gives the user a clear "range too
    // narrow" error instead of a confusing non-converged result, and
    // adds the `n_active < 2` numerical-stability floor so that even
    // an `n_free == 1` fit gets at least one degree of freedom.  See
    // [`required_active_bins`] for the combined `max(2, n_free)`
    // requirement.
    if let Some((e_min, e_max)) = config.fit_energy_range() {
        let n_active = nereids_fitting::active_mask::active_count(
            active_mask.as_deref(),
            config.energies().len(),
        );
        let required = required_active_bins(config);
        if n_active < required {
            return Err(PipelineError::InvalidParameter(format!(
                "fit_energy_range [{e_min}, {e_max}] eV selects {n_active} active bin(s) \
                 on the configured energy grid; at least {required} active bin(s) are \
                 required for LM transmission fitting with {n_free} free parameter(s) \
                 (underdetermined when n_active < n_free)",
                n_free = count_free_params(config),
            )));
        }
    }

    // Dispatch with optional background / baseline wrapping.  Wrappers
    // Box-stack linearly (the `Box<M>` FitModel blanket impl in lm.rs):
    // inner physics → NormalizedTransmissionModel (additive SAMMY
    // background, if configured) → MultiplicativeBaselineModel (issue
    // #635, OUTERMOST, if configured).
    let mut stacked: Box<dyn FitModel> = model;
    if let Some(bi) = bg_indices {
        stacked = if let (Some(di), Some(fi)) = (bi.back_d, bi.back_f) {
            Box::new(NormalizedTransmissionModel::new_with_exponential(
                stacked,
                config.energies(),
                bi.anorm,
                bi.back_a,
                bi.back_b,
                bi.back_c,
                di,
                fi,
            ))
        } else {
            Box::new(NormalizedTransmissionModel::new(
                stacked,
                config.energies(),
                bi.anorm,
                bi.back_a,
                bi.back_b,
                bi.back_c,
            ))
        };
    }
    if let Some(bli) = bl_indices {
        stacked = Box::new(
            MultiplicativeBaselineModel::new(
                stacked,
                config.energies(),
                nereids_fitting::transmission_model::baseline_reference_energy_active(
                    config.energies(),
                    active_mask.as_deref(),
                ),
                bli.b0,
                bli.b1,
                bli.b2,
            )
            // Scope the runtime positivity guard to the fit window (#514).
            .with_active_mask(active_mask.as_deref()),
        );
    }
    let result = lm::levenberg_marquardt_with_mask(
        &*stacked,
        measured_t,
        sigma,
        &mut params,
        &lm_cfg,
        active_mask.as_deref(),
    )?;

    let free_indices = params.free_indices();
    let mut sr = extract_result(
        config,
        &result,
        n_density_params,
        &free_indices,
        bg_indices,
        bl_indices,
    )?;

    // Populate energy-scale results if fitted.
    if let Some((t0_idx, ls_idx)) = energy_scale_indices {
        sr.t0_us = Some(result.params[t0_idx]);
        sr.l_scale = Some(result.params[ls_idx]);
        sr.energy_scale_flight_path_m = Some(config.flight_path_m);
    }

    Ok(sr)
}

/// Joint-Poisson counts-path fitter.
///
/// Builds a pure transmission `FitModel` (density + optional temperature +
/// optional energy-scale) and feeds it to [`joint_poisson::joint_poisson_fit`]
/// together with explicit `(O, S, c)`.  Returns a [`SpectrumFitResult`] with
/// `deviance_per_dof = Some(...)` as the primary GOF.
/// `reduced_chi_squared` is set to the same value so GUI consumers that
/// still read the legacy field see a deviance-based metric.
///
/// `detector_background` is expected counts per bin, and it enters BOTH
/// arms with the same value: it is a detector-space term, present whether or
/// not the sample is in the beam. A background that DIFFERS between the arms
/// — the sample's own scatter and gammas — needs a second array this entry
/// point does not carry, though `JointPoissonObjective` takes the two arms
/// separately.
///
/// Current scope: `fit_alpha_1` and `fit_alpha_2` remain rejected (`λ̂`
/// absorbs the global flux scale, and fitting the background amplitudes is
/// not implemented — the background here is declared, not fitted).
/// `transmission_background` with `A_n` + `B_A` / `B_B` / `B_C` is
/// supported, subject to the operational rule that `B_A` must
/// be enabled if any of `B_A` / `B_B` / `B_C` is enabled (benchmarked:
/// A_n alone cannot absorb a constant offset — density
/// bias −23%).  Exponential-tail terms `BackD` / `BackF` are rejected
/// (support is deferred).
fn fit_counts_joint_poisson(
    sample_counts: &[f64],
    flux: &[f64],
    detector_background: &[f64],
    config: &UnifiedFitConfig,
    jp_cfg: &JointPoissonFitConfig,
) -> Result<SpectrumFitResult, PipelineError> {
    // ── Compatibility gates (deferred features are out of scope here) ──
    if let Some(bg) = config.counts_background()
        && (bg.fit_alpha_1 || bg.fit_alpha_2)
    {
        return Err(PipelineError::InvalidParameter(
            "joint-Poisson solver does not support fit_alpha_1/fit_alpha_2: \
             the profile lambda-hat absorbs the global flux scale (alpha_1 redundant); \
             alpha_2 / B_det wiring is not yet implemented."
                .into(),
        ));
    }
    if detector_background
        .iter()
        .any(|&v| !v.is_finite() || v < 0.0)
    {
        return Err(PipelineError::InvalidParameter(
            "detector_background must be finite and non-negative expected counts".into(),
        ));
    }

    // ── Operational rule: B_A required if any additive term enabled ──
    if let Some(bg) = config.transmission_background.as_ref() {
        if bg.fit_back_d || bg.fit_back_f {
            return Err(PipelineError::InvalidParameter(
                "joint-Poisson solver does not support the BackD/BackF exponential \
                 tail (support is deferred)."
                    .into(),
            ));
        }
        if (bg.fit_back_b || bg.fit_back_c) && !bg.fit_back_a {
            return Err(PipelineError::InvalidParameter(
                "joint-Poisson transmission_background: B_A (fit_back_a) must be \
                 enabled whenever any of B_B / B_C is enabled (A_n alone cannot \
                 absorb a constant offset — benchmarked at −23% density bias)."
                    .into(),
            ));
        }
    }

    let c = config.counts_background().map(|b| b.c).unwrap_or(1.0);
    if !(c.is_finite() && c > 0.0) {
        return Err(PipelineError::InvalidParameter(format!(
            "joint-Poisson solver requires finite c > 0 in CountsBackgroundConfig, got {c}",
        )));
    }

    // ── Build parameter vector (density → temperature → energy-scale →
    // transmission background), using the shared
    // append_temperature_param / append_energy_scale_params /
    // append_background_params helpers.
    let n_density_params = config.n_density_params();
    let mut param_vec = build_density_params(config);

    let temperature_index = append_temperature_param(&mut param_vec, config);
    let energy_scale_indices = append_energy_scale_params(&mut param_vec, config);

    // Issue #608: peak-match seed for (t0, L_scale).  The KL/counts path fits
    // the same sharply non-convex calibration landscape as the LM path, so it
    // needs the same seed; run it on a (sample − bg)/(flux − bg) transmission
    // proxy (the resonance-dip positions are all the seed needs).
    if energy_scale_indices.is_some() {
        let t_proxy: Vec<f64> = sample_counts
            .iter()
            .zip(flux.iter())
            .zip(detector_background.iter())
            .map(|((&s, &f), &b)| {
                let den = f - b;
                if den > 0.0 {
                    ((s - b).max(0.0) / den).min(2.0)
                } else {
                    1.0
                }
            })
            .collect();
        seed_energy_scale_in_params(&mut param_vec, energy_scale_indices, &t_proxy, config);
    }

    // ── Transmission background (A_n + B_A/B/C) parameters ──
    // Use the same SAMMY-style param block as the LM transmission path.
    // If BackD/BackF were enabled, we would have already errored out above.
    let bg_indices = config
        .transmission_background
        .as_ref()
        .map(|bg| append_background_params(&mut param_vec, bg));

    // ── Multiplicative-baseline parameters (issue #635), appended LAST ──
    // B(E) multiplies the model TRANSMISSION, so it flows through the
    // profile λ̂ = Σc(O+S)/Σ(1+cT) exactly like any other T-shape change —
    // no JP-specific wiring needed.
    validate_multiplicative_baseline(config)?;
    let bl_indices = config
        .multiplicative_baseline
        .as_ref()
        .map(|bl| append_multiplicative_baseline_params(&mut param_vec, bl));

    let mut params = ParameterSet::new(param_vec);

    // ── Build the true-energy transmission model ──
    // The exact count wrapper applies detector response after this model. Clear
    // the legacy transmission-broadening fields so R[T] cannot be evaluated
    // inside the inner model and then broadened a second time.
    let mut true_model_config = config.clone();
    if config.exact_count_response().is_some() {
        true_model_config.resolution = None;
        true_model_config.precomputed_resolution_plan = None;
        true_model_config.precomputed_sparse_cubature_plan = None;
        true_model_config.precomputed_sparse_scalar_plan = None;
    }
    let t_model: Box<dyn FitModel> = if let Some((t0_idx, ls_idx)) = energy_scale_indices {
        build_energy_scale_transmission_model(
            &true_model_config,
            t0_idx,
            ls_idx,
            temperature_index,
        )?
    } else {
        build_transmission_model(&true_model_config, n_density_params, temperature_index)?
    };

    // ── Wrap with NormalizedTransmissionModel if bg is active ──
    // The wrapper adds `T_out = A_n · T_inner + B_A + B_B/√E + B_C·√E`,
    // exactly matching the SAMMY form used by the LM transmission path.
    // Its analytical Jacobian chains through the inner model correctly,
    // so JointPoissonObjective picks up gradients for both density and
    // background parameters without further wiring.

    // Build the per-bin active mask (SAMMY EMIN/EMAX-equivalent fit-energy
    // -range restriction).  `None` when no range is configured — the
    // JP objective treats that as "all bins active".
    let mut active_mask = nereids_fitting::active_mask::build_active_mask(
        config.energies(),
        config.fit_energy_range(),
    );

    // Reject early when the configured range selects fewer active
    // bins than the joint-Poisson dispatch can solve.  `joint_poisson_fit`
    // already rejects the `n_active < n_free` case (and the
    // `n_active == 0` early-return), but a dispatcher-level rejection
    // gives users a clear "range too narrow" error instead of a
    // non-converged JP result, and adds the `n_active < 2` numerical-
    // stability floor so even an `n_free == 1` fit gets at least one
    // degree of freedom.  See [`required_active_bins`] for the
    // combined `max(2, n_free)` requirement.
    if let Some((e_min, e_max)) = config.fit_energy_range() {
        let n_active = nereids_fitting::active_mask::active_count(
            active_mask.as_deref(),
            config.energies().len(),
        );
        let required = required_active_bins(config);
        if n_active < required {
            return Err(PipelineError::InvalidParameter(format!(
                "fit_energy_range [{e_min}, {e_max}] eV selects {n_active} active bin(s) \
                 on the configured energy grid; at least {required} active bin(s) are \
                 required for joint-Poisson fitting with {n_free} free parameter(s) \
                 (underdetermined when n_active < n_free)",
                n_free = count_free_params(config),
            )));
        }
    }

    // Model placement is domain-specific. The multiplicative baseline changes
    // the true-energy sample arm before detector response. The SAMMY
    // normalization/ABC curve changes apparent transmission in the measured
    // bins, so on the exact route it is applied only after the separate-arm
    // detector ratio has been formed.
    let mut stacked: Box<dyn FitModel> = t_model;
    if let Some(exact) = config.exact_count_response() {
        if let Some(bli) = bl_indices {
            stacked = Box::new(MultiplicativeBaselineModel::new(
                stacked,
                config.energies(),
                nereids_fitting::transmission_model::baseline_reference_energy_active(
                    config.energies(),
                    None,
                ),
                bli.b0,
                bli.b1,
                bli.b2,
            ));
        }
        let response = config.resolution().expect(
            "validate_counts_resolution_route requires resolution with exact_count_response",
        );
        let matrix = DetectorBinResponseMatrix::new(
            config.energies(),
            &exact.detector_time_edges_us,
            exact.timing_offset_us,
            response,
        )
        .map_err(|error| {
            PipelineError::InvalidParameter(format!(
                "failed to build exact detector-bin response: {error}"
            ))
        })?;
        // Config-shaped failures here (fluence values/length) are already
        // rejected by `validate_counts_resolution_route`; map anything that
        // still escapes to InvalidParameter so the taxonomy matches the
        // adjacent matrix-build error rather than reporting a caller mistake
        // as a solver failure.
        let exact_model =
            ExactTwoArmRatioModel::new(stacked, matrix, &exact.incident_fluence_weights).map_err(
                |error| {
                    PipelineError::InvalidParameter(format!(
                        "failed to build the exact two-arm ratio model: {error}"
                    ))
                },
            )?;
        // An occupied bin with no neutron response means the supplied
        // source/response cannot explain the counts — UNLESS a background is
        // declared, in which case pure-background counts in a tail or
        // source-gap bin are exactly what is expected.
        //
        // Such a bin still cannot be fitted. `ExactTwoArmRatioModel` reports
        // T = 1 where there is no response, and the objective profiles a free
        // flux per bin, so leaving it active lets background fluctuations be
        // fitted as neutron flux. It carries no information about any fitted
        // parameter either: the background here is declared, not fitted. So
        // it is dropped from the active set rather than explained away.
        let mut dead_occupied = Vec::new();
        for (bin, ((&observed_open, &observed_sample), &predicted_open)) in flux
            .iter()
            .zip(sample_counts)
            .zip(exact_model.open_expectation())
            .enumerate()
        {
            if observed_open + observed_sample > 0.0 && predicted_open <= PIVOT_FLOOR {
                // Per BIN, not per run: a background somewhere else in the
                // spectrum explains nothing about THIS bin. Without one here,
                // its counts still have no source and the hard error stands.
                if detector_background[bin] <= 0.0 {
                    return Err(PipelineError::InvalidParameter(format!(
                        "exact incident source has zero detector response in occupied \
                         detector bin {bin}; the supplied source/response cannot explain \
                         the observed counts"
                    )));
                }
                dead_occupied.push(bin);
            }
        }
        if !dead_occupied.is_empty() {
            let mask = active_mask.get_or_insert_with(|| vec![true; flux.len()]);
            for &bin in &dead_occupied {
                mask[bin] = false;
            }
            let remaining = mask.iter().filter(|&&active| active).count();
            let required = required_active_bins(config);
            if remaining < required {
                return Err(PipelineError::InvalidParameter(format!(
                    "{} detector bin(s) hold only background and cannot be fitted, \
                     leaving {remaining} active bin(s); at least {required} are required",
                    dead_occupied.len()
                )));
            }
        }
        stacked = Box::new(exact_model);

        if let Some(bi) = bg_indices {
            // The SAMMY apparent-transmission background is evaluated per
            // MEASURED bin, so each detector-time bin needs a pseudo-energy:
            // bin center in time, fixed offset removed, then TOF -> energy.
            //
            // A real acquisition's time axis may start at the frame trigger,
            // BEFORE the calibrated offset, so leading bins have a
            // non-positive corrected TOF and no physical energy. Those bins
            // are unoccupied (an occupied one with no detector response was
            // already rejected by the pre-check above), and an unoccupied bin
            // contributes identically zero deviance for every parameter value
            // (its profiled rate is zero), so its background value cannot
            // affect the fit. Rejecting the whole fit for them would refuse a
            // mainstream acquisition that fits fine without background; only
            // an OCCUPIED bin without a physical energy is a real error.
            let flight_path_m = response.flight_path_m();
            let raw_energies: Vec<Option<f64>> = exact
                .detector_time_edges_us
                .windows(2)
                .map(|edges| {
                    let corrected_tof_us = 0.5 * (edges[0] + edges[1]) - exact.timing_offset_us;
                    let energy = tof_to_energy(corrected_tof_us, flight_path_m);
                    (energy.is_finite() && energy > 0.0).then_some(energy)
                })
                .collect();
            for (bin, energy) in raw_energies.iter().enumerate() {
                let occupied = flux[bin] + sample_counts[bin] > 0.0;
                if energy.is_none() && occupied {
                    return Err(PipelineError::InvalidParameter(format!(
                        "detector-time bin {bin} carries observed counts but has \
                         non-positive time after the fixed timing offset, so the \
                         SAMMY apparent-transmission background has no physical \
                         energy there; check timing_offset_us against the \
                         detector-time axis"
                    )));
                }
            }
            // Fill the non-contributing bins with their nearest valid
            // neighbour's energy: any finite positive value leaves the model
            // finite (no NaN into the Jacobian/Fisher rows) and the bin's
            // zero deviance weight makes the choice unobservable.
            let first_valid = raw_energies
                .iter()
                .flatten()
                .copied()
                .next()
                .ok_or_else(|| {
                    PipelineError::InvalidParameter(
                        "no detector-time bin has a positive time after the fixed timing \
                     offset; the entire acquisition window precedes timing_offset_us"
                            .to_string(),
                    )
                })?;
            let mut last_valid = first_valid;
            let detector_energies: Vec<f64> = raw_energies
                .into_iter()
                .map(|energy| {
                    if let Some(value) = energy {
                        last_valid = value;
                    }
                    last_valid
                })
                .collect();
            stacked = Box::new(NormalizedTransmissionModel::new(
                stacked,
                &detector_energies,
                bi.anorm,
                bi.back_a,
                bi.back_b,
                bi.back_c,
            ));
        }
    } else {
        // Box-stack the wrappers (same as the LM transmission path):
        // inner physics → NormalizedTransmissionModel (if bg) →
        // MultiplicativeBaselineModel (issue #635, OUTERMOST, if configured).
        if let Some(bi) = bg_indices {
            stacked = Box::new(NormalizedTransmissionModel::new(
                stacked,
                config.energies(),
                bi.anorm,
                bi.back_a,
                bi.back_b,
                bi.back_c,
            ));
        }
        if let Some(bli) = bl_indices {
            stacked = Box::new(
                MultiplicativeBaselineModel::new(
                    stacked,
                    config.energies(),
                    nereids_fitting::transmission_model::baseline_reference_energy_active(
                        config.energies(),
                        active_mask.as_deref(),
                    ),
                    bli.b0,
                    bli.b1,
                    bli.b2,
                )
                // Scope the runtime positivity guard to the fit window (#514).
                .with_active_mask(active_mask.as_deref()),
            );
        }
    }
    // `detector_background` is a detector-space term: it is present whether
    // or not the sample is in the beam, so it enters BOTH arms. That is the
    // convention the energy-scale seed already uses, which forms its
    // transmission proxy as `(S - b) / (O - b)`.
    //
    // A background that DIFFERS between the arms — the sample's own scatter
    // and gammas — is a second array this entry point does not yet carry.
    // `JointPoissonObjective` takes the two arms separately, so supplying it
    // is a plumbing change rather than a likelihood one.
    let background =
        (!detector_background.iter().all(|&v| v == 0.0)).then_some(detector_background);
    let objective = JointPoissonObjective {
        model: &*stacked,
        o: flux,
        s: sample_counts,
        c,
        active_mask: active_mask.as_deref(),
        open_background: background,
        sample_background: background,
    };
    let mut cfg = jp_cfg.clone();
    cfg.compute_covariance = config.compute_covariance;
    cfg.scale_by_chi2 = config.scale_by_chi2;
    // Solver / numeric failures map to PipelineError::Fitting — NOT
    // InvalidParameter (review R4): the binding taxonomy sends
    // InvalidParameter to Python ValueError (bad user input), and a
    // joint-Poisson failure at this point (config already validated
    // up-front) is a solver-class error that must stay RuntimeError,
    // matching the LM / KL-transmission paths' `?`-conversion of
    // FittingError.
    let result = joint_poisson::joint_poisson_fit(&objective, &mut params, &cfg)
        .map_err(PipelineError::Fitting)?;

    // ── Extract fitted quantities ──
    let densities: Vec<f64> = (0..n_density_params).map(|i| result.params[i]).collect();

    let (uncertainties, temperature_k_unc) = if let Some(ref unc_all) = result.uncertainties {
        // `unc_all` is FREE-only; map full-layout indices to free positions
        // so a frozen density (issue #633) reports NaN instead of stealing a
        // neighbouring free parameter's error bar. See `free_uncertainty`.
        let free_idx = params.free_indices();
        let dens_unc: Vec<f64> = (0..n_density_params)
            .map(|i| free_uncertainty(&free_idx, unc_all, i).unwrap_or(f64::NAN))
            .collect();
        let t_unc = temperature_index.and_then(|idx| free_uncertainty(&free_idx, unc_all, idx));
        (Some(dens_unc), t_unc)
    } else {
        (None, None)
    };
    let fitted_temp = temperature_index.map(|idx| result.params[idx]);

    // Convergence signal: the deviance value is the
    // acceptance criterion, but we expose a boolean to preserve the
    // existing SpectrumFitResult shape.  Report True when EITHER stage
    // self-flagged convergence (whichever accepts).
    let converged = result.gn_converged || result.polish_converged;

    // ── Background parameter readout ──
    // When bg is active, read A_n / B_A / B_B / B_C from the fitted
    // parameter vector at their registered indices.  When bg is absent,
    // use the convention A_n = 1 (subsumed into λ̂), bg = 0.
    let (anorm_out, bg_abc_out) = if let Some(bi) = bg_indices {
        (
            result.params[bi.anorm],
            [
                result.params[bi.back_a],
                result.params[bi.back_b],
                result.params[bi.back_c],
            ],
        )
    } else {
        (1.0, [0.0, 0.0, 0.0])
    };

    // Multiplicative-baseline readout (issue #635) — mirrors extract_result.
    let (baseline_out, baseline_e_ref_out) = if let Some(bli) = bl_indices {
        (
            Some([
                result.params[bli.b0],
                result.params[bli.b1],
                result.params[bli.b2],
            ]),
            Some(
                nereids_fitting::transmission_model::baseline_reference_energy_active(
                    config.energies(),
                    active_mask.as_deref(),
                ),
            ),
        )
    } else {
        (None, None)
    };

    Ok(SpectrumFitResult {
        densities,
        uncertainties,
        // Back-compat bridge: reduced_chi_squared carries D/(n−k) for the
        // joint-Poisson path.  The deviance is the primary GOF; Pearson
        // χ² is secondary.
        reduced_chi_squared: result.deviance_per_dof,
        converged,
        iterations: result.gn_iterations + result.polish_iterations,
        temperature_k: fitted_temp,
        temperature_k_unc,
        anorm: anorm_out,
        background: bg_abc_out,
        // Joint-Poisson never fits the exponential tail.  `None`
        // signals "tail not fit" to downstream consumers (GUI overlay
        // curve drops the exponential term; PyO3 conversion passes
        // through to Python as `None`).
        back_d: None,
        back_f: None,
        t0_us: energy_scale_indices.map(|(t0_idx, _)| result.params[t0_idx]),
        l_scale: energy_scale_indices.map(|(_, ls_idx)| result.params[ls_idx]),
        energy_scale_flight_path_m: energy_scale_indices.map(|_| config.flight_path_m),
        deviance_per_dof: Some(result.deviance_per_dof),
        baseline: baseline_out,
        baseline_e_ref_ev: baseline_e_ref_out,
        warnings: degenerate_normalization_warning(config)
            .into_iter()
            .collect(),
    })
}

// ── Shared helpers for fit_spectrum_typed ──

fn build_density_params(config: &UnifiedFitConfig) -> Vec<FitParameter> {
    config
        .initial_densities
        .iter()
        .enumerate()
        .map(|(i, &d)| {
            let name = config
                .isotope_names
                .get(i)
                .cloned()
                .unwrap_or_else(|| format!("isotope_{i}"));
            // Frozen densities (issue #633) still occupy their slot as a
            // `fixed` parameter — held at the initial value, no Jacobian
            // column — so downstream index-based result extraction is
            // unaffected.
            if config.density_is_fixed(i) {
                FitParameter::fixed(name, d)
            } else {
                FitParameter::non_negative(name, d)
            }
        })
        .collect()
}

/// Optimizer box for a fitted sample temperature (K).
///
/// The lower edge is above zero because a zero-temperature sample has no
/// Doppler broadening at all, which is not a sample any of these paths
/// describe; the upper edge is the range the resonance physics is validated
/// over. Every fit path that frees a temperature uses this box, so they
/// cannot disagree about what a temperature is allowed to be.
pub(crate) const TEMPERATURE_BOUNDS_K: (f64, f64) = (1.0, 5000.0);

/// Append a temperature parameter to the fit vector if
/// `config.fit_temperature` is `true`.  Returns the parameter index.
///
/// Temperature unit is Kelvin; the initial value is `config.temperature_k`.
fn append_temperature_param(
    param_vec: &mut Vec<FitParameter>,
    config: &UnifiedFitConfig,
) -> Option<usize> {
    if !config.fit_temperature {
        return None;
    }
    let idx = param_vec.len();
    param_vec.push(FitParameter {
        name: "temperature_k".into(),
        value: config.temperature_k,
        lower: TEMPERATURE_BOUNDS_K.0,
        upper: TEMPERATURE_BOUNDS_K.1,
        fixed: false,
    });
    Some(idx)
}

/// Detect significant transmission dips (resonance signatures) in a measured
/// spectrum: returns `(energy_eV, depth)` for each local minimum whose depth
/// below the no-absorption baseline is a meaningful fraction of the deepest
/// dip.  Light 3-point smoothing suppresses single-bin noise.  Used to seed the
/// energy-scale calibration (issue #608).
fn detect_transmission_dips(measured: &[f64], energies: &[f64]) -> Vec<(f64, f64)> {
    let n = measured.len();
    if n < 5 || energies.len() != n {
        return Vec::new();
    }
    let mut sm = measured.to_vec();
    for i in 1..n - 1 {
        sm[i] = (measured[i - 1] + measured[i] + measured[i + 1]) / 3.0;
    }
    // No-absorption baseline ≈ a high percentile of the (smoothed) signal.
    let mut sorted = sm.clone();
    sorted.sort_by(f64::total_cmp);
    let baseline = sorted[((0.9 * (n as f64 - 1.0)).round() as usize).min(n - 1)];
    let mut dips: Vec<(f64, f64)> = Vec::new();
    let mut max_depth = 0.0f64;
    for i in 1..n - 1 {
        if sm[i] < sm[i - 1] && sm[i] <= sm[i + 1] {
            let depth = baseline - sm[i];
            if depth > 0.0 {
                dips.push((energies[i], depth));
                max_depth = max_depth.max(depth);
            }
        }
    }
    // Keep dips that are a meaningful fraction of the deepest — filters noise
    // wiggles while retaining genuine (even weak) resonance dips.
    dips.retain(|&(_, d)| d >= 0.2 * max_depth);
    dips
}

/// Seed `(t0, L_scale)` for the energy-scale fit by resonance peak-matching.
///
/// A TOF calibration is linear: `tof_measured = t0 + L_scale · tof_nominal`.
/// We detect the transmission dips in the measured spectrum, match each to its
/// nearest known resonance energy (under the nominal calibration), and
/// least-squares-fit the matched `(tof_nominal, tof_measured)` pairs for
/// `(t0, L_scale)`.  This is landscape-independent — it seeds the LM into the
/// global-minimum basin of the sharply non-convex post-#608 calibration χ²,
/// which a cold start (t0=0, L_scale=1) or a grid scan cannot reliably find
/// (the physically-exact true-σ model's basins are razor-thin).  The physics is
/// unchanged; this only chooses the LM's starting point.
///
/// Returns `None` (→ caller keeps the configured cold start) when fewer than
/// two distinct resonances can be matched, so it is a safe enhancement: it
/// improves the seed when it can and never degrades the existing behaviour.
fn peak_match_energy_scale_seed(
    measured: &[f64],
    energies: &[f64],
    config: &UnifiedFitConfig,
    flight_path_m: f64,
    t0_bounds: (f64, f64),
    l_scale_bounds: (f64, f64),
) -> Option<(f64, f64)> {
    let n = energies.len();
    if n < 5 || measured.len() != n {
        return None;
    }
    // Resonance centers within the measured energy range (true frame).
    let refs: Vec<&ResonanceData> = config.resonance_data().iter().collect();
    let (e_lo, e_hi) = (
        energies[0].min(energies[n - 1]),
        energies[0].max(energies[n - 1]),
    );
    let res_e: Vec<f64> = nereids_physics::transmission::resonance_center_energies(&refs)
        .into_iter()
        .filter(|&e| e > e_lo && e < e_hi)
        .collect();
    if res_e.len() < 2 {
        return None;
    }
    let dips = detect_transmission_dips(measured, energies);
    if dips.len() < 2 {
        return None;
    }
    // Match each dip to its nearest resonance (nominal calibration ⇒
    // corrected ≈ measured), keeping the deepest dip per resonance.  Reject a
    // dip that does not sit UNAMBIGUOUSLY near a resonance — within half the
    // minimum inter-resonance spacing — so a spurious/mis-matched dip drops out
    // rather than poisoning the linear fit (issue #608).  `res_e` is sorted
    // and de-duplicated.
    //
    // Floor `match_tol` at the energy-grid resolution: a dip
    // is localized to ~one grid step, so a single closely-spaced resonance pair
    // must not collapse the GLOBAL tolerance toward 0 and reject dips at
    // well-separated resonances.  Dedup already stops exact duplicates from
    // zeroing it; the floor additionally guards distinct near-degenerate
    // energies.  Well-separated resonances keep `0.5·min_spacing ≫ grid_res`, so
    // the floor is inert in the common case.
    let min_spacing = res_e
        .windows(2)
        .map(|w| (w[1] - w[0]).abs())
        .fold(f64::INFINITY, f64::min);
    let mut grid_steps: Vec<f64> = energies.windows(2).map(|w| (w[1] - w[0]).abs()).collect();
    grid_steps.sort_by(f64::total_cmp);
    let grid_res = grid_steps.get(grid_steps.len() / 2).copied().unwrap_or(0.0);
    let match_tol = (0.5 * min_spacing).max(grid_res);
    let mut best: Vec<Option<(f64, f64)>> = vec![None; res_e.len()];
    for &(e_dip, depth) in &dips {
        let Some((k, &re)) = res_e
            .iter()
            .enumerate()
            .min_by(|(_, a), (_, b)| (*a - e_dip).abs().total_cmp(&(*b - e_dip).abs()))
        else {
            continue;
        };
        if (re - e_dip).abs() > match_tol {
            continue;
        }
        match best[k] {
            Some((_, d)) if d >= depth => {}
            _ => best[k] = Some((e_dip, depth)),
        }
    }
    // Matched (tof_nominal, tof_measured) pairs.  The common factor
    // `tof_factor · flight_path` must match `EnergyScaleTransmissionModel`'s
    // `corrected_energies` (it cancels in the slope but sets the intercept t0).
    let tof_factor = (0.5 * NEUTRON_MASS_KG / EV_TO_JOULES).sqrt() * 1.0e6;
    let c = tof_factor * flight_path_m;
    let pairs: Vec<(f64, f64)> = res_e
        .iter()
        .zip(best.iter())
        .filter_map(|(&re, b)| b.map(|(e_dip, _)| (c / re.sqrt(), c / e_dip.sqrt())))
        .collect();
    if pairs.len() < 2 {
        return None;
    }
    // Linear least squares: tof_meas = t0 + L_scale · tof_nom.
    let m = pairs.len() as f64;
    let mean_x = pairs.iter().map(|p| p.0).sum::<f64>() / m;
    let mean_y = pairs.iter().map(|p| p.1).sum::<f64>() / m;
    let mut sxx = 0.0f64;
    let mut sxy = 0.0f64;
    for &(x, y) in &pairs {
        sxx += (x - mean_x) * (x - mean_x);
        sxy += (x - mean_x) * (y - mean_y);
    }
    if sxx <= 0.0 {
        return None;
    }
    let l_scale = sxy / sxx;
    let t0 = mean_y - l_scale * mean_x;
    if !t0.is_finite() || !l_scale.is_finite() {
        return None;
    }
    // Reject (→ keep the configured cold start) when the fitted seed falls
    // outside the parameter bounds.  Clamping an out-of-range fit onto a bound
    // would seed the LM worse than its cold start — the opposite of this seed's
    // purpose (issue #608).  An in-range fit is the high-confidence case.
    if t0 < t0_bounds.0
        || t0 > t0_bounds.1
        || l_scale < l_scale_bounds.0
        || l_scale > l_scale_bounds.1
    {
        return None;
    }
    Some((t0, l_scale))
}

/// Apply the peak-matching seed to the `(t0, L_scale)` entries of `param_vec`
/// in place, when energy-scale fitting is enabled (issue #608).  No-op when the
/// seed cannot be computed (→ the configured cold start is kept).
fn seed_energy_scale_in_params(
    param_vec: &mut [FitParameter],
    energy_scale_indices: Option<(usize, usize)>,
    measured_transmission: &[f64],
    config: &UnifiedFitConfig,
) {
    // Issue #634: callers with their own alignment anchor (calibrate_energy)
    // disable the seed — see `with_energy_scale_seed`.
    if !config.energy_scale_seed_enabled {
        return;
    }
    let Some((t0_idx, ls_idx)) = energy_scale_indices else {
        return;
    };
    let t0_b = (param_vec[t0_idx].lower, param_vec[t0_idx].upper);
    let ls_b = (param_vec[ls_idx].lower, param_vec[ls_idx].upper);
    if let Some((t0_seed, ls_seed)) = peak_match_energy_scale_seed(
        measured_transmission,
        config.energies(),
        config,
        config.flight_path_m,
        t0_b,
        ls_b,
    ) {
        param_vec[t0_idx].value = t0_seed;
        param_vec[ls_idx].value = ls_seed;
    }
}

/// Optimizer box bound on the TZERO offset: `t_0 ∈ [−T0, +T0]` µs.
/// `calibrate_energy` (calibration.rs) composes multiple fits when an
/// offset exceeds one box (issue #634); each individual fit is bounded here.
const ENERGY_SCALE_T0_BOUND_US: f64 = 10.0;
/// Optimizer box bounds on the flight-path scale `L_scale` (dimensionless,
/// ±1 %).  `calibrate_energy` re-anchors across cycles to cover its wider
/// documented band (issue #634); each individual fit is bounded here.
const ENERGY_SCALE_L_SCALE_LO: f64 = 0.99;
/// Upper `L_scale` bound; see [`ENERGY_SCALE_L_SCALE_LO`].
const ENERGY_SCALE_L_SCALE_HI: f64 = 1.01;

/// Append SAMMY TZERO energy-scale parameters (t_0 and L_scale) when
/// `config.fit_energy_scale` is `true`.  Returns `(t0_idx, l_scale_idx)`.
///
/// Bounds: `t_0 ∈ [-10.0, 10.0] μs` and `L_scale ∈ [0.99, 1.01]`
/// (dimensionless).  Matches the LM / KL transmission paths.
fn append_energy_scale_params(
    param_vec: &mut Vec<FitParameter>,
    config: &UnifiedFitConfig,
) -> Option<(usize, usize)> {
    if !config.fit_energy_scale {
        return None;
    }
    let t0_idx = param_vec.len();
    param_vec.push(FitParameter {
        name: "t0_us".into(),
        value: config.t0_init_us,
        lower: -ENERGY_SCALE_T0_BOUND_US,
        upper: ENERGY_SCALE_T0_BOUND_US,
        fixed: false,
    });
    let ls_idx = param_vec.len();
    param_vec.push(FitParameter {
        name: "l_scale".into(),
        value: config.l_scale_init,
        lower: ENERGY_SCALE_L_SCALE_LO,
        upper: ENERGY_SCALE_L_SCALE_HI,
        fixed: false,
    });
    Some((t0_idx, ls_idx))
}

/// Validate that the SAMMY-style `BackgroundConfig` is internally
/// consistent for the purposes of the production fit dispatch.
///
/// **BackD / BackF must travel together.**  The
/// `NormalizedTransmissionModel` exponential-tail wrapper takes both
/// indices or neither (`new_with_exponential` requires both, `new` takes
/// neither).  Allowing only one of `fit_back_d` / `fit_back_f` would
/// leave the other parameter registered as "free" but absent from the
/// objective and Jacobian — silently fitting nothing while reporting a
/// misleading initial value back to the caller.  Reject the partial
/// configuration up-front with a clear error.
///
/// Idempotent on valid configs; intended to be called by every
/// production fit entry that takes a `transmission_background`.
pub(crate) fn validate_transmission_background(bg: &BackgroundConfig) -> Result<(), PipelineError> {
    if bg.fit_back_d != bg.fit_back_f {
        return Err(PipelineError::InvalidParameter(format!(
            "transmission_background: fit_back_d ({}) and fit_back_f ({}) \
             must both be true or both be false. The exponential tail \
             wrapper (BackD · exp(−BackF / √E)) requires both parameters \
             together; enabling only one leaves the other registered but \
             unused, silently producing the initial value as the fitted \
             result. Either enable both (to fit the exponential tail) or \
             disable both (4-term wrapper without exponential).",
            bg.fit_back_d, bg.fit_back_f,
        )));
    }
    Ok(())
}

/// Validate a [`MultiplicativeBaselineConfig`] against the fit grid
/// (issue #635).  Rejects:
/// - non-finite inits or bounds, reversed bounds, inits outside bounds
///   (silent clamping would move the caller's value — reject instead);
/// - an initial baseline `B_init(E) <= 0` anywhere on the grid (the model's
///   runtime positivity guard treats mid-iteration violations as rejected
///   trial steps, but the INITIAL point must be valid);
/// - a free SAMMY `Anorm` alongside (`b0` and `Anorm` are degenerate
///   normalizations — never free two of them; hold `Anorm` fixed via
///   `fit_anorm = false` to combine the additive ABC background with the
///   baseline).
///
/// All-`false` fit flags are allowed: that is the frozen-baseline form the
/// spatial global mode uses (the same fixed-parameter substrate as
/// `with_fix_densities`).
pub(crate) fn validate_multiplicative_baseline(
    config: &UnifiedFitConfig,
) -> Result<(), PipelineError> {
    let Some(bl) = config.multiplicative_baseline() else {
        return Ok(());
    };
    for (name, init, (lo, hi)) in [
        ("b0", bl.b0_init, bl.b0_bounds),
        ("b1", bl.b1_init, bl.b1_bounds),
        ("b2", bl.b2_init, bl.b2_bounds),
    ] {
        if !init.is_finite() {
            return Err(PipelineError::InvalidParameter(format!(
                "multiplicative baseline: {name}_init must be finite, got {init}"
            )));
        }
        if !lo.is_finite() || !hi.is_finite() || lo >= hi {
            return Err(PipelineError::InvalidParameter(format!(
                "multiplicative baseline: {name}_bounds must be finite with \
                 lower < upper, got ({lo}, {hi})"
            )));
        }
        if init < lo || init > hi {
            return Err(PipelineError::InvalidParameter(format!(
                "multiplicative baseline: {name}_init = {init} lies outside \
                 {name}_bounds ({lo}, {hi})"
            )));
        }
    }
    // Initial-point positivity over the ACTIVE bins (#514 semantics,
    // review R2): bins masked out by fit_energy_range contribute nothing
    // to any mask-honouring cost function, so an init that is positive
    // everywhere inside the fit window must not be rejected because of
    // out-of-window bins on a wide TOF grid.  E_ref is the ACTIVE-window
    // reference used by the fitter (#648): with fit_energy_range set it is
    // the geometric midpoint of the active bins, not the full grid, so
    // this validation evaluates the baseline basis exactly as the fit
    // does.  (Only positivity matters here — any E_ref > 0 spans the same
    // quadratic family — but using the fitter's value keeps validation and
    // fit consistent.  Reported b0/b1/b2 are therefore defined relative to
    // the active-window E_ref and are not comparable across window choices.)
    let e_ref = config.baseline_reference_energy();
    if !e_ref.is_finite() || e_ref <= 0.0 {
        return Err(PipelineError::InvalidParameter(format!(
            "multiplicative baseline: reference energy sqrt(E_min*E_max) is \
             invalid ({e_ref}) — check the energy grid"
        )));
    }
    let active_mask = nereids_fitting::active_mask::build_active_mask(
        config.energies(),
        config.fit_energy_range(),
    );
    for (i, &e) in config.energies().iter().enumerate() {
        if active_mask.as_ref().is_some_and(|m| !m[i]) {
            continue;
        }
        let z = (e / e_ref).ln();
        let b = bl.b0_init + bl.b1_init * z + bl.b2_init * z * z;
        let positive = b.is_finite() && b > 0.0;
        if !positive {
            return Err(PipelineError::InvalidParameter(format!(
                "multiplicative baseline: initial B(E) = {b} is not strictly \
                 positive at E = {e} eV (inside the fit window) — adjust the \
                 b0/b1/b2 inits"
            )));
        }
    }
    if config
        .transmission_background()
        .is_some_and(|bg| bg.fit_anorm)
    {
        return Err(PipelineError::InvalidParameter(
            "multiplicative baseline and a FREE SAMMY Anorm cannot be fitted \
             together: b0 and Anorm are degenerate normalizations. Set \
             BackgroundConfig::fit_anorm = false to combine the additive ABC \
             background with the baseline."
                .into(),
        ));
    }
    Ok(())
}

/// A free SAMMY `Anorm` together with a free temperature and at least one
/// free density is a degenerate normalization trio on real data (observed on
/// VENUS transmission: T ran to 4471 K with n +76 % and chi2/nu 932, with no
/// warning).  Returns a warning string rather than an error: the combination
/// is SAMMY-legal and can converge on synthetic data.
pub(crate) fn degenerate_normalization_warning(config: &UnifiedFitConfig) -> Option<String> {
    let anorm_free = config
        .transmission_background()
        .is_some_and(|bg| bg.fit_anorm);
    if anorm_free && config.fit_temperature && config.n_free_density_params() >= 1 {
        Some(
            "fit configuration frees Anorm, temperature, AND at least one \
             density together — a degenerate normalization trio on real data \
             (observed: T ran to 4471 K with chi2/nu 932 and no warning). \
             Consider with_multiplicative_baseline (bounded normalization) \
             and/or with_fix_densities (known areal density)."
                .to_string(),
        )
    } else {
        None
    }
}

pub(crate) fn validate_precomputed_cross_sections(
    config: &UnifiedFitConfig,
) -> Result<(), PipelineError> {
    let Some(xs) = config.precomputed_cross_sections() else {
        return Ok(());
    };
    if xs.sigma.is_empty() {
        return Err(PipelineError::ShapeMismatch(
            "precomputed_cross_sections must not be empty".into(),
        ));
    }
    let n_work = xs.layout.energies.len();
    for (i, row) in xs.sigma.iter().enumerate() {
        if row.len() != n_work {
            return Err(PipelineError::ShapeMismatch(format!(
                "precomputed_cross_sections row {i} has length {} but its grid has {n_work} \
                 energies",
                row.len(),
            )));
        }
        if let Some(j) = row.iter().position(|s| !s.is_finite()) {
            return Err(PipelineError::ShapeMismatch(format!(
                "precomputed_cross_sections row {i} has non-finite σ at energy index {j}: {}",
                row[j],
            )));
        }
    }

    let n_params = config.n_density_params();
    let member_rows = config.density_indices.as_ref().map(|di| di.len());
    let row_ok = xs.sigma.len() == n_params || member_rows == Some(xs.sigma.len());
    if !row_ok {
        let expected = match member_rows {
            Some(m) if m != n_params => format!("{n_params} (collapsed) or {m} (per-member)"),
            _ => format!("{n_params}"),
        };
        return Err(PipelineError::ShapeMismatch(format!(
            "precomputed_cross_sections has {} rows but expected {expected}",
            xs.sigma.len(),
        )));
    }

    let instrument = if config.exact_count_response().is_some() {
        None
    } else {
        config.resolution().map(|r| InstrumentParams {
            resolution: r.clone(),
        })
    };
    let rd_refs: Vec<&ResonanceData> = config.resonance_data().iter().collect();
    let expected = nereids_physics::transmission::resolution_working_grid(
        config.energies(),
        instrument.as_ref(),
        &rd_refs,
    )
    .map_err(PipelineError::Transmission)?;
    let same_energies = xs.layout.energies.len() == expected.energies.len()
        && xs
            .layout
            .energies
            .iter()
            .zip(&expected.energies)
            .all(|(a, b)| a.to_bits() == b.to_bits());
    if !same_energies || xs.layout.data_indices != expected.data_indices {
        return Err(PipelineError::ShapeMismatch(format!(
            "precomputed_cross_sections layout ({} energies, {} data points) is not the \
             working grid this fit broadens on ({} energies, {} data points)",
            xs.layout.energies.len(),
            xs.layout.data_indices.len(),
            expected.energies.len(),
            expected.data_indices.len(),
        )));
    }
    Ok(())
}

/// Count the number of free parameters the production LM transmission
/// or joint-Poisson (counts-KL) dispatch will register for `config`.
///
/// Mirrors the parameter-vector assembly performed by
/// [`fit_transmission_lm`], [`fit_counts_joint_poisson`] and the
/// shared `build_density_params` / `append_*_param` helpers below:
///
/// * `n_free_density_params` density slots — frozen densities (issue
///   #633, via `with_fix_densities` / `with_density_free`) hold a fixed
///   slot but get no Jacobian column, so they are excluded here.
/// * `+1` if [`UnifiedFitConfig::fit_temperature`] is set.
/// * `+2` if [`UnifiedFitConfig::fit_energy_scale`] is set
///   (t_0 and L_scale).
/// * For a transmission_background, the count of `true` flags on
///   `(fit_anorm, fit_back_a, fit_back_b, fit_back_c, fit_back_d,
///   fit_back_f)`.  The joint-Poisson dispatch rejects BackD/BackF
///   up-front, but this helper counts them as free when set so the
///   fail-fast diagnostic ordering (`underdetermined > BackD/BackF
///   reject`) does not flip across paths.
/// * For a multiplicative_baseline (issue #635), the count of `true`
///   flags on `(fit_b0, fit_b1, fit_b2)`.
///
/// Used both by [`validate_spatial_fit_preflight`] (whole-map
/// rejection) and by the per-pixel LM / JP dispatchers
/// (single-spectrum rejection) so the `n_active < required` bound
/// stays in lockstep across the spatial / single-spectrum boundary.
/// The research-only `fit_alpha_1` / `fit_alpha_2` flags on
/// `CountsBackgroundConfig` are *not* counted: the joint-Poisson
/// dispatch rejects them up-front and the LM path never wires them.
pub(crate) fn count_free_params(config: &UnifiedFitConfig) -> usize {
    // Frozen densities (issue #633) hold a fixed parameter slot but get
    // no Jacobian column, so they must not count toward the free-DoF
    // total the underdetermined-system guard checks against.
    let mut n_free = config.n_free_density_params();
    if config.fit_temperature {
        n_free += 1;
    }
    if config.fit_energy_scale {
        n_free += 2;
    }
    if let Some(bg) = config.transmission_background.as_ref() {
        n_free += usize::from(bg.fit_anorm);
        n_free += usize::from(bg.fit_back_a);
        n_free += usize::from(bg.fit_back_b);
        n_free += usize::from(bg.fit_back_c);
        n_free += usize::from(bg.fit_back_d);
        n_free += usize::from(bg.fit_back_f);
    }
    if let Some(bl) = config.multiplicative_baseline.as_ref() {
        n_free += usize::from(bl.fit_b0);
        n_free += usize::from(bl.fit_b1);
        n_free += usize::from(bl.fit_b2);
    }
    n_free
}

/// Minimum number of active bins the LM / joint-Poisson dispatch
/// requires for a fit on `config`.  Encodes two distinct constraints:
///
/// 1. **Underdetermined-system rejection**: a fit with `n_active <
///    n_free` cannot be solved (the Jacobian cannot be full rank).
///    Lifting this check out of the LM / joint-Poisson cores into
///    the dispatcher gives the user an actionable error instead of
///    silent NaN propagation through the spatial map.
/// 2. **Numerical-stability floor**: even with `n_free == 1`, a
///    one-active-bin fit (`n_active == 1`) is exactly determined
///    (`dof == 0`) and gives no curvature for the LM step / no
///    deviance signal for the joint-Poisson reduced GOF.  We keep
///    the previous `n_active < 2` minimum so callers that relied
///    on it (e.g. the spatial-preflight regression tests for
///    narrow `fit_energy_range` windows) continue to receive the
///    same actionable diagnostic.
///
/// The combined requirement is `max(2, count_free_params(config))`.
pub(crate) fn required_active_bins(config: &UnifiedFitConfig) -> usize {
    count_free_params(config).max(2)
}

fn append_background_params(
    param_vec: &mut Vec<FitParameter>,
    bg: &BackgroundConfig,
) -> BackgroundIndices {
    // Anorm bounded to [0.5, 2.0] — physically reasonable normalization range.
    // Previously unbounded [0, ∞), which allowed the fitter to absorb signal
    // into anorm (e.g., anorm=15.9 with density=0.03×true).
    // SAMMY also bounds normalization to a reasonable range.
    let anorm = param_vec.len();
    param_vec.push(if bg.fit_anorm {
        FitParameter {
            name: "anorm".into(),
            value: bg.anorm_init,
            lower: 0.5,
            upper: 2.0,
            fixed: false,
        }
    } else {
        FitParameter::fixed("anorm", bg.anorm_init)
    });
    // Background terms bounded to [-0.5, 0.5].
    // These are small corrections to the transmission baseline.
    // Unbounded background allows the fitter to absorb resonance signal
    // into the background polynomial, producing meaningless densities.
    // SAMMY also constrains background to reasonable ranges.
    let back_a = param_vec.len();
    param_vec.push(if bg.fit_back_a {
        FitParameter {
            name: "back_a".into(),
            value: bg.back_a_init,
            lower: -0.5,
            upper: 0.5,
            fixed: false,
        }
    } else {
        FitParameter::fixed("back_a", bg.back_a_init)
    });
    let back_b = param_vec.len();
    param_vec.push(if bg.fit_back_b {
        FitParameter {
            name: "back_b".into(),
            value: bg.back_b_init,
            lower: -0.5,
            upper: 0.5,
            fixed: false,
        }
    } else {
        FitParameter::fixed("back_b", bg.back_b_init)
    });
    let back_c = param_vec.len();
    param_vec.push(if bg.fit_back_c {
        FitParameter {
            name: "back_c".into(),
            value: bg.back_c_init,
            lower: -0.5,
            upper: 0.5,
            fixed: false,
        }
    } else {
        FitParameter::fixed("back_c", bg.back_c_init)
    });

    // Exponential tail: BackD × exp(−BackF / √E).
    // SAMMY manual Sec III.E.2 — terms 5-6.
    // BackD (amplitude): non-negative, bounded [0, 1].
    // BackF (decay constant in √eV units): non-negative, bounded [0, 100].
    // Note: if BackD_init = 0, the Jacobian column for BackF is identically
    // zero and the optimizer cannot learn BackF.  The default init (0.01)
    // avoids this.
    let back_d = if bg.fit_back_d {
        let idx = param_vec.len();
        param_vec.push(FitParameter {
            name: "back_d".into(),
            value: bg.back_d_init,
            lower: 0.0,
            upper: 1.0,
            fixed: false,
        });
        Some(idx)
    } else {
        None
    };
    let back_f = if bg.fit_back_f {
        let idx = param_vec.len();
        param_vec.push(FitParameter {
            name: "back_f".into(),
            value: bg.back_f_init,
            lower: 0.0,
            upper: 100.0,
            fixed: false,
        });
        Some(idx)
    } else {
        None
    };

    BackgroundIndices {
        anorm,
        back_a,
        back_b,
        back_c,
        back_d,
        back_f,
    }
}

/// Append the three multiplicative-baseline coefficients (issue #635) to the
/// parameter vector, mirroring [`append_background_params`].
///
/// Bounds come from the caller-visible [`MultiplicativeBaselineConfig`]
/// (validated finite / lo < hi / init-in-bounds by
/// [`validate_multiplicative_baseline`] before any fitter reaches this
/// helper).  A `fit_*` flag of `false` freezes the coefficient at its init
/// via [`FitParameter::fixed`] — the same substrate as frozen densities, so
/// `count_free_params` and the LM free-index mapping handle it without
/// special cases.  All three slots are ALWAYS pushed (fixed or free): the
/// wrapper model indexes them unconditionally.
fn append_multiplicative_baseline_params(
    param_vec: &mut Vec<FitParameter>,
    bl: &MultiplicativeBaselineConfig,
) -> BaselineIndices {
    let b0 = param_vec.len();
    param_vec.push(if bl.fit_b0 {
        FitParameter {
            name: "baseline_b0".into(),
            value: bl.b0_init,
            lower: bl.b0_bounds.0,
            upper: bl.b0_bounds.1,
            fixed: false,
        }
    } else {
        FitParameter::fixed("baseline_b0", bl.b0_init)
    });
    let b1 = param_vec.len();
    param_vec.push(if bl.fit_b1 {
        FitParameter {
            name: "baseline_b1".into(),
            value: bl.b1_init,
            lower: bl.b1_bounds.0,
            upper: bl.b1_bounds.1,
            fixed: false,
        }
    } else {
        FitParameter::fixed("baseline_b1", bl.b1_init)
    });
    let b2 = param_vec.len();
    param_vec.push(if bl.fit_b2 {
        FitParameter {
            name: "baseline_b2".into(),
            value: bl.b2_init,
            lower: bl.b2_bounds.0,
            upper: bl.b2_bounds.1,
            fixed: false,
        }
    } else {
        FitParameter::fixed("baseline_b2", bl.b2_init)
    });

    BaselineIndices { b0, b1, b2 }
}

/// Build an [`EnergyScaleTransmissionModel`] for the energy-scale fit branch
/// of `fit_transmission_lm` / `fit_counts_joint_poisson`.
///
/// Absorbs the 3 byte-identical construction blocks that used to live inline
/// in each fitter (see commit `1b4131f` for the pre-extraction pattern).
/// Stays private — internal pipeline construction detail, not part of the
/// crate's public surface.
///
/// Issue #608: the energy-scale model evaluates the TRUE cross-section at the
/// corrected energies from resonance data (matching `forward_model`) rather
/// than interpolating a precomputed σ grid, so it is constructed from the
/// per-isotope `config.resonance_data`, the density mapping
/// (`config.density_indices` / `config.density_ratios`, defaulting to the
/// identity mapping with ratio 1.0 when no groups are configured), and
/// `config.temperature_k` for Doppler broadening.  Resolution is NOT applied
/// here — the model applies it inside `evaluate()` on the working grid via the
/// wrapped [`InstrumentParams`].  The per-isotope density accumulation
/// (`params[density_indices[i]] * density_ratios[i]`) happens inside the model,
/// so no cross-section pre-collapse is done here.
///
/// `t0_idx` and `ls_idx` are the parameter indices for `t0` and `l_scale`,
/// produced by [`append_energy_scale_params`] at each fitter's setup.
fn build_energy_scale_transmission_model(
    config: &UnifiedFitConfig,
    t0_idx: usize,
    ls_idx: usize,
    temperature_index: Option<usize>,
) -> Result<Box<dyn FitModel>, PipelineError> {
    let instrument = config
        .resolution
        .clone()
        .map(|r| Arc::new(InstrumentParams { resolution: r }));
    // Issue #608: EnergyScale evaluates the TRUE σ at the corrected energies
    // from resonance data (matching forward_model) rather than interpolating a
    // precomputed σ grid, so it takes the per-isotope resonance data + density
    // mapping + temperature.  When no groups are configured, each isotope is its
    // own density parameter (identity mapping, ratio 1.0).
    let n_iso = config.resonance_data.len();
    let density_indices = config
        .density_indices
        .clone()
        .unwrap_or_else(|| (0..n_iso).collect());
    let density_ratios = config
        .density_ratios
        .clone()
        .unwrap_or_else(|| vec![1.0; n_iso]);
    let mut es_model = EnergyScaleTransmissionModel::new(
        Arc::new(config.resonance_data.clone()),
        Arc::new(density_indices),
        Arc::new(density_ratios),
        config.temperature_k,
        config.energies.clone(),
        config.flight_path_m,
        t0_idx,
        ls_idx,
        instrument,
    )
    // Issue #634: when temperature is also fit, wire its parameter index in
    // so the model rebuilds σ at the free temperature and emits a T Jacobian
    // column. `None` keeps temperature fixed (unchanged behavior).
    .with_temperature_index(temperature_index)
    .map_err(|e| PipelineError::InvalidParameter(format!("energy-scale model: {e}")))?;
    if let Some(method) = config.tzero_jacobian_method {
        es_model = es_model.with_jacobian_method(method);
    }
    Ok(Box::new(es_model))
}

/// Build the transmission forward model, selecting precomputed or full path.
fn build_transmission_model(
    config: &UnifiedFitConfig,
    n_density_params: usize,
    temperature_index: Option<usize>,
) -> Result<Box<dyn FitModel>, PipelineError> {
    let n_params = config.n_density_params();
    let instrument = config
        .resolution
        .clone()
        .map(|r| Arc::new(InstrumentParams { resolution: r }));

    if !config.fit_temperature {
        let xs = match &config.precomputed_cross_sections {
            Some(xs) => xs.clone(),
            None => PrecomputedXs::from(
                nereids_physics::transmission::broadened_cross_sections_on_working_grid(
                    config.energies(),
                    &config.resonance_data,
                    config.temperature_k,
                    instrument.as_deref(),
                    None,
                )
                .map_err(PipelineError::Transmission)?,
            ),
        };
        let cross_sections = match (&config.density_indices, &config.density_ratios) {
            (Some(di), Some(dr)) if xs.sigma.len() == di.len() && di.len() == dr.len() => {
                let mut eff = vec![vec![0.0f64; xs.sigma[0].len()]; n_params];
                for ((&idx, &ratio), member) in di.iter().zip(dr.iter()).zip(xs.sigma.iter()) {
                    for (j, &sigma) in member.iter().enumerate() {
                        eff[idx][j] += ratio * sigma;
                    }
                }
                Arc::new(eff)
            }
            _ => Arc::clone(&xs.sigma),
        };
        let (resolution_plan, sparse_cubature_plan, sparse_scalar_plan) = if instrument.is_some() {
            (
                config.precomputed_resolution_plan.clone(),
                config.precomputed_sparse_cubature_plan.clone(),
                config.precomputed_sparse_scalar_plan.clone(),
            )
        } else {
            (None, None, None)
        };
        return Ok(Box::new(PrecomputedTransmissionModel {
            cross_sections,
            density_indices: Arc::new((0..n_params).collect()),
            instrument,
            resolution_plan,
            sparse_cubature_plan,
            sparse_scalar_plan,
            layout: Arc::clone(&xs.layout),
        }));
    }

    let base_xs = config.precomputed_base_xs.clone();
    let density_ratios = config
        .density_ratios
        .clone()
        .unwrap_or_else(|| vec![1.0; n_density_params]);
    let density_indices = config
        .density_indices
        .clone()
        .unwrap_or_else(|| (0..n_density_params).collect());
    let resolution_plan = if instrument.is_some() {
        config.precomputed_resolution_plan.clone()
    } else {
        None
    };
    let sparse_cubature_plan = if instrument.is_some() {
        config.precomputed_sparse_cubature_plan.clone()
    } else {
        None
    };
    let sparse_scalar_plan = if instrument.is_some() {
        config.precomputed_sparse_scalar_plan.clone()
    } else {
        None
    };
    Ok(Box::new(
        TransmissionFitModel::new(
            config.energies.clone(),
            config.resonance_data.clone(),
            config.temperature_k,
            instrument,
            (density_indices, density_ratios),
            temperature_index,
            base_xs,
        )?
        .with_resolution_plan(resolution_plan)
        .with_sparse_cubature_plan(sparse_cubature_plan)
        .with_sparse_scalar_plan(sparse_scalar_plan),
    ))
}

/// Uncertainty of the full-layout parameter `full_index`, read from the
/// solver's FREE-only `uncertainties` vector.
///
/// The solver returns `params` in the FULL layout (fixed parameters included
/// at their slots) but `uncertainties` in FREE order (length `n_free`, one
/// entry per free parameter, ordered by ascending full index — matching
/// [`ParameterSet::free_indices`](nereids_fitting::parameters::ParameterSet::free_indices)).
/// A fixed parameter — e.g. a density frozen via
/// [`UnifiedFitConfig::with_fix_densities`] /
/// [`with_density_free`](UnifiedFitConfig::with_density_free) — has no entry,
/// so this returns `None` for it (callers report that as `NaN`).
fn free_uncertainty(free_indices: &[usize], unc_all: &[f64], full_index: usize) -> Option<f64> {
    free_indices
        .iter()
        .position(|&fi| fi == full_index)
        .and_then(|pos| unc_all.get(pos).copied())
}

/// Extract SpectrumFitResult from solver output.
fn extract_result(
    config: &UnifiedFitConfig,
    result: &LmResult,
    n_density_params: usize,
    free_indices: &[usize],
    bg_indices: Option<BackgroundIndices>,
    bl_indices: Option<BaselineIndices>,
) -> Result<SpectrumFitResult, PipelineError> {
    let densities: Vec<f64> = (0..n_density_params).map(|i| result.params[i]).collect();

    // Multiplicative baseline readout (issue #635): report the coefficients
    // the model actually used (fixed or free) plus the E_ref the ln-basis
    // was centered on, so consumers reconstruct B(E) exactly.
    let (baseline, baseline_e_ref_ev) = if let Some(bli) = bl_indices {
        (
            Some([
                result.params[bli.b0],
                result.params[bli.b1],
                result.params[bli.b2],
            ]),
            Some(config.baseline_reference_energy()),
        )
    } else {
        (None, None)
    };

    let (anorm, background, back_d, back_f): (f64, [f64; 3], Option<f64>, Option<f64>) =
        if let Some(bi) = bg_indices {
            // `Option<f64>` distinguishes "exponential tail not fit"
            // (`None`) from "fit produced zero" (`Some(0.0)`).
            let bd = bi.back_d.map(|i| result.params[i]);
            let bf = bi.back_f.map(|i| result.params[i]);
            (
                result.params[bi.anorm],
                [
                    result.params[bi.back_a],
                    result.params[bi.back_b],
                    result.params[bi.back_c],
                ],
                bd,
                bf,
            )
        } else {
            (1.0, [0.0, 0.0, 0.0], None, None)
        };

    let (uncertainties, temperature_k, temperature_k_unc) = if result.converged {
        match &result.uncertainties {
            Some(unc_all) => {
                // `result.params` is the FULL layout, but `unc_all` is
                // FREE-only (length n_free): a density frozen via #633 holds
                // a full-layout slot yet has NO uncertainty entry. Map each
                // full-layout index to its free position through
                // `free_indices`; a frozen density has no free slot → NaN.
                // (Before #633 all densities were free, so full-index ==
                // free-index and the old naive `unc_all[i]` happened to line
                // up — it silently misassigned once freezing was possible.)
                let (temp_k, temp_unc) = if config.fit_temperature {
                    (
                        Some(result.params[n_density_params]),
                        Some(
                            free_uncertainty(free_indices, unc_all, n_density_params)
                                .unwrap_or(f64::NAN),
                        ),
                    )
                } else {
                    (None, None)
                };
                let unc: Vec<f64> = (0..n_density_params)
                    .map(|i| free_uncertainty(free_indices, unc_all, i).unwrap_or(f64::NAN))
                    .collect();
                (Some(unc), temp_k, temp_unc)
            }
            None => {
                let temp_k = if config.fit_temperature {
                    Some(result.params[n_density_params])
                } else {
                    None
                };
                (None, temp_k, None)
            }
        }
    } else {
        let temp_k = if config.fit_temperature {
            Some(result.params[n_density_params])
        } else {
            None
        };
        (None, temp_k, None)
    };

    Ok(SpectrumFitResult {
        densities,
        uncertainties,
        reduced_chi_squared: result.reduced_chi_squared,
        converged: result.converged,
        iterations: result.iterations,
        temperature_k,
        temperature_k_unc,
        anorm,
        background,
        back_d,
        back_f,
        t0_us: None,
        l_scale: None,
        energy_scale_flight_path_m: None,
        deviance_per_dof: None,
        baseline,
        baseline_e_ref_ev,
        warnings: degenerate_normalization_warning(config)
            .into_iter()
            .collect(),
    })
}

// ── Research: exact Jacobian/Fisher at arbitrary parameters ──────────────

/// Result of Jacobian/Fisher evaluation at given parameters.
///
/// Produced by [`evaluate_jacobian_and_fisher`], which builds the same model
/// chain as the production fitting pipeline but evaluates at the caller's
/// parameter values instead of optimising.
pub struct ModelJacobianResult {
    /// Analytical Jacobian J (n_data × n_free), row-major.
    pub jacobian: lm::FlatMatrix,
    /// Expected Poisson Fisher F = Jᵀ diag(1/μ) J (n_free × n_free).
    pub fisher: lm::FlatMatrix,
    /// Model prediction μ(E) at the evaluation point.
    pub model_prediction: Vec<f64>,
    /// Names of free parameters, in Jacobian column order.
    pub param_names: Vec<String>,
}

pub fn evaluate_jacobian_and_fisher(
    config: &UnifiedFitConfig,
    flux: &[f64],
    background: &[f64],
) -> Result<ModelJacobianResult, PipelineError> {
    // This helper builds a counts-space Jacobian/Fisher from the legacy
    // transmission-first chain and does not implement the exact two-arm
    // detector operator at all — intercept BOTH resolved-count shapes
    // (resolution attached, exact inputs attached, or either alone) before
    // the shared validator, whose "provide exact_count_response" remedy
    // would send this entry point's callers to a config the next line
    // rejects. Resolved counts belong to fit_counts_spectrum_typed.
    if config.exact_count_response().is_some() || config.resolution().is_some() {
        return Err(PipelineError::InvalidParameter(
            "evaluate_jacobian_and_fisher does not implement the exact two-arm \
             detector operator required for resolved counts (the separate-arm \
             model R[Phi] and R[Phi*T]); use fit_counts_spectrum_typed with \
             exact_count_response for resolved counts, or drop the instrument \
             resolution for this research helper"
                .into(),
        ));
    }
    // Shared boundary check kept for the remaining (unresolved-counts)
    // invariants so this helper cannot drift from the fit routes.
    validate_counts_resolution_route(true, flux.len(), config)?;

    // Reject a malformed caller-supplied precomputed cross-section stack here,
    // before it reaches `build_transmission_model`.  Without this, an empty
    // stack is caught only deep in `PrecomputedTransmissionModel` (as an
    // `InvalidConfig`, not a `ShapeMismatch`) and a wrong-shaped / non-finite
    // stack indexes `xs[0]` / `neg_opt[j]` directly.  This is the third public
    // entry point that consumes `config.precomputed_cross_sections`; it must
    // guard the same way as `fit_spectrum_typed` / `spatial_map_typed` so all
    // three surface the same typed `ShapeMismatch` at the boundary.
    validate_precomputed_cross_sections(config)?;

    // The multiplicative baseline (issue #635) is NOT wired into this
    // research helper: its parameter layout below is frozen for Epic #394
    // research-script compatibility (kl_b0/kl_b1 stand in for the
    // transmission background; the production anorm/ABC block is likewise
    // absent).  Silently ignoring a configured baseline would report a
    // Jacobian/Fisher for a DIFFERENT model than the caller asked for —
    // reject explicitly instead.
    if config.multiplicative_baseline.is_some() {
        return Err(PipelineError::InvalidParameter(
            "evaluate_jacobian_and_fisher does not support a multiplicative \
             baseline: its parameter layout is frozen for research-script \
             compatibility (kl_b0/kl_b1 background stand-ins). Remove \
             with_multiplicative_baseline from the config for this helper."
                .into(),
        ));
    }

    let n_density_params = config.n_density_params();

    // ── Build parameter vector — preserves the pre-collapse fixed-flux
    // layout (density → temperature → transmission_background → α₁/α₂)
    // that the research Fisher helper has historically used.  NOT
    // equivalent to the production counts-KL dispatch's parameter
    // layout; kept unchanged for Epic #394 research-script compatibility.
    //     ─────────────────────────────────────────────────────────
    let mut param_vec = build_density_params(config);

    let temperature_index = if config.fit_temperature {
        let idx = param_vec.len();
        param_vec.push(FitParameter {
            name: "temperature_k".into(),
            value: config.temperature_k,
            lower: TEMPERATURE_BOUNDS_K.0,
            upper: TEMPERATURE_BOUNDS_K.1,
            fixed: false,
        });
        Some(idx)
    } else {
        None
    };

    let kl_bg = if config.transmission_background.is_some() {
        let base = param_vec.len();
        param_vec.push(FitParameter {
            name: "kl_b0".into(),
            value: 0.0,
            lower: 0.0,
            upper: 0.5,
            fixed: false,
        });
        param_vec.push(FitParameter {
            name: "kl_b1".into(),
            value: 0.0,
            lower: 0.0,
            upper: 0.5,
            fixed: false,
        });
        Some((base, base + 1))
    } else {
        None
    };

    let counts_bg = if let Some(bg) = config.counts_background() {
        let alpha1_idx = param_vec.len();
        param_vec.push(if bg.fit_alpha_1 {
            FitParameter {
                name: "alpha_1".into(),
                value: bg.alpha_1_init,
                lower: 0.0,
                upper: 10.0,
                fixed: false,
            }
        } else {
            FitParameter::fixed("alpha_1", bg.alpha_1_init)
        });
        let alpha2_idx = param_vec.len();
        param_vec.push(if bg.fit_alpha_2 {
            FitParameter {
                name: "alpha_2".into(),
                value: bg.alpha_2_init,
                lower: 0.0,
                upper: 10.0,
                fixed: false,
            }
        } else {
            FitParameter::fixed("alpha_2", bg.alpha_2_init)
        });
        Some((alpha1_idx, alpha2_idx))
    } else {
        None
    };

    let params = ParameterSet::new(param_vec);
    let all_vals = params.all_values();
    let free_idx = params.free_indices();
    let n_free = free_idx.len();

    // Collect free parameter names.
    let param_names: Vec<String> = free_idx
        .iter()
        .map(|&i| params.params[i].name.to_string())
        .collect();

    let t_model = build_transmission_model(config, n_density_params, temperature_index)?;

    // ── Build counts model chain and evaluate ───────────────────────
    // Use a closure that evaluates and computes Jacobian for any FitModel.
    let evaluate_and_jacobian =
        |model: &dyn FitModel| -> Result<(Vec<f64>, lm::FlatMatrix), PipelineError> {
            let y_model = model.evaluate(&all_vals)?;
            let jac = model
                .analytical_jacobian(&all_vals, &free_idx, &y_model)
                .ok_or_else(|| {
                    PipelineError::InvalidParameter(
                        "analytical Jacobian not available for this model configuration".into(),
                    )
                })?;
            Ok((y_model, jac))
        };

    let (y_model, jac) = if let Some((b0_idx, b1_idx)) = kl_bg {
        let inv_sqrt_e: Vec<f64> = config
            .energies()
            .iter()
            .map(|&e| 1.0 / e.max(1e-10).sqrt())
            .collect();
        let wrapped = poisson::TransmissionKLBackgroundModel {
            inner: &*t_model,
            inv_sqrt_energies: inv_sqrt_e,
            b0_index: b0_idx,
            b1_index: b1_idx,
            n_params: params.params.len(),
        };
        if let Some((a1, a2)) = counts_bg {
            let cm = poisson::CountsBackgroundScaleModel {
                transmission_model: &wrapped,
                flux,
                background,
                alpha1_index: a1,
                alpha2_index: a2,
                n_params: params.params.len(),
            };
            evaluate_and_jacobian(&cm)?
        } else {
            let cm = poisson::CountsModel {
                transmission_model: &wrapped,
                flux,
                background,
                n_params: params.params.len(),
            };
            evaluate_and_jacobian(&cm)?
        }
    } else if let Some((a1, a2)) = counts_bg {
        let cm = poisson::CountsBackgroundScaleModel {
            transmission_model: &*t_model,
            flux,
            background,
            alpha1_index: a1,
            alpha2_index: a2,
            n_params: params.params.len(),
        };
        evaluate_and_jacobian(&cm)?
    } else {
        let cm = poisson::CountsModel {
            transmission_model: &*t_model,
            flux,
            background,
            n_params: params.params.len(),
        };
        evaluate_and_jacobian(&cm)?
    };

    // ── Assemble expected Poisson Fisher: F = Jᵀ diag(1/μ) J ───────
    let mut fisher = lm::FlatMatrix::zeros(n_free, n_free);
    for (i, &mu_i) in y_model.iter().enumerate() {
        let mu_inv = 1.0 / mu_i.max(1e-30);
        for a in 0..n_free {
            let ja = jac.get(i, a);
            for b in 0..=a {
                let jb = jac.get(i, b);
                *fisher.get_mut(a, b) += ja * jb * mu_inv;
                if a != b {
                    *fisher.get_mut(b, a) += ja * jb * mu_inv;
                }
            }
        }
    }

    Ok(ModelJacobianResult {
        jacobian: jac,
        fisher,
        model_prediction: y_model,
        param_names,
    })
}

// ── End Phase 2 ──────────────────────────────────────────────────────────

/// Errors from `FitConfig` construction.
#[derive(Debug, PartialEq)]
pub enum FitConfigError {
    /// Energy grid must be non-empty.
    EmptyEnergies,
    /// Resonance data must be non-empty.
    EmptyResonanceData,
    /// initial_densities length must match resonance_data length.
    DensityCountMismatch { densities: usize, isotopes: usize },
    /// isotope_names length must match resonance_data length.
    NameCountMismatch { names: usize, isotopes: usize },
    /// resonance_data count must match group member count.
    GroupMemberCountMismatch {
        group_name: String,
        rd_count: usize,
        member_count: usize,
    },
    /// ResonanceData isotope doesn't match expected group member.
    GroupMemberIsotopeMismatch {
        group_name: String,
        expected_z: u32,
        expected_a: u32,
        got_z: u32,
        got_a: u32,
    },
    /// Temperature must be finite.
    NonFiniteTemperature(f64),
    /// Temperature must be non-negative.
    NegativeTemperature(f64),
    /// `fit_energy_range` bounds were non-finite or reversed/empty.
    InvalidFitEnergyRange(&'static str),
    /// A density-freeze mask (`with_fix_densities` / `with_density_free`,
    /// issue #633) was set before [`UnifiedFitConfig::with_groups`].
    /// Grouping redefines the density parameters, so the pre-group mask no
    /// longer applies; configure the freeze *after* grouping.
    DensityFreezeBeforeGroups,
}

impl fmt::Display for FitConfigError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::EmptyEnergies => write!(f, "energy grid must be non-empty"),
            Self::EmptyResonanceData => write!(f, "resonance_data must be non-empty"),
            Self::DensityCountMismatch {
                densities,
                isotopes,
            } => write!(
                f,
                "initial_densities length ({densities}) must match number of density parameters ({isotopes})"
            ),
            Self::NameCountMismatch { names, isotopes } => write!(
                f,
                "isotope_names length ({names}) must match resonance_data length ({isotopes})"
            ),
            Self::GroupMemberCountMismatch {
                group_name,
                rd_count,
                member_count,
            } => write!(
                f,
                "group '{group_name}': provided {rd_count} ResonanceData but group has {member_count} members"
            ),
            Self::GroupMemberIsotopeMismatch {
                group_name,
                expected_z,
                expected_a,
                got_z,
                got_a,
            } => write!(
                f,
                "group '{group_name}': expected Z={expected_z} A={expected_a} but got Z={got_z} A={got_a}"
            ),
            Self::NonFiniteTemperature(v) => {
                write!(f, "temperature must be finite, got {v}")
            }
            Self::NegativeTemperature(v) => {
                write!(f, "temperature must be non-negative, got {v}")
            }
            Self::InvalidFitEnergyRange(msg) => {
                write!(f, "invalid fit_energy_range: {msg}")
            }
            Self::DensityFreezeBeforeGroups => write!(
                f,
                "density freeze (with_fix_densities / with_density_free) must be configured \
                 after with_groups: grouping redefines the density parameters"
            ),
        }
    }
}

impl std::error::Error for FitConfigError {}

/// Result of fitting a single spectrum.
#[derive(Debug, Clone)]
pub struct SpectrumFitResult {
    /// Fitted areal densities (atoms/barn), one per isotope.
    pub densities: Vec<f64>,
    /// Uncertainty on each density.
    ///
    /// `None` when covariance computation was skipped.
    pub uncertainties: Option<Vec<f64>>,
    /// Reduced chi-squared of the fit.
    pub reduced_chi_squared: f64,
    /// Whether the fit converged.
    pub converged: bool,
    /// Number of iterations.
    pub iterations: usize,
    /// Fitted temperature in Kelvin (only when `fit_temperature` is true).
    pub temperature_k: Option<f64>,
    /// 1-sigma uncertainty on the fitted temperature (from covariance matrix).
    ///
    /// **Covariance-only lower bound** for the raw-count joint-Poisson path:
    /// this is `sqrt` of the temperature diagonal
    /// of the inverse curvature (Fisher) matrix at convergence. It reflects only
    /// statistical curvature — baseline/model noise is not in the covariance —
    /// so on real data it can **underestimate the observed per-superpixel scatter
    /// by ~3–4×**. Set `UnifiedFitConfig::scale_by_chi2` to inflate it by `sqrt`
    /// of the `deviance_per_dof` this result reports, for a
    /// goodness-of-fit-scaled estimate. The LM transmission path is
    /// already χ²-scaled (Numerical Recipes §15.6), so the flag is a no-op there.
    pub temperature_k_unc: Option<f64>,
    /// Fitted normalization scale (SAMMY `Anorm`).  When background
    /// fitting is disabled, the pipeline emits `1.0` (`λ̂` absorbs
    /// the scale).
    pub anorm: f64,
    /// Fitted background polynomial coefficients `[BackA, BackB, BackC]`
    /// for the SAMMY-style 6-term background:
    ///
    /// ```text
    /// bg(E) = BackA + BackB / √E + BackC · √E + BackD · exp(-BackF / √E)
    /// ```
    ///
    /// Both LM-transmission and counts-KL solver paths use the same
    /// SAMMY semantics here — the legacy alpha-fitting `[b0, b1,
    /// alpha_2]` layout was removed when `fit_counts_poisson` was
    /// retired.  When background fitting is disabled, the
    /// pipeline emits `[0.0, 0.0, 0.0]`.
    pub background: [f64; 3],
    /// Fitted exponential background amplitude (SAMMY BackD).
    /// `None` when the exponential tail is not fitted; `Some(value)`
    /// when the LM transmission background was active with
    /// `fit_back_d=true`.  Mirrors [`Self::t0_us`] /
    /// [`Self::l_scale`] semantics so the GUI overlay can
    /// distinguish "unfit" from "fitted to zero" without an ambiguous
    /// `0.0` sentinel.
    pub back_d: Option<f64>,
    /// Fitted exponential background decay constant (SAMMY BackF).
    /// `None` when the exponential tail is not fitted; `Some(value)`
    /// when the LM transmission background was active with
    /// `fit_back_f=true`.  Paired with [`Self::back_d`] — SAMMY
    /// requires both flags toggled together (see
    /// `validate_transmission_background`).
    pub back_f: Option<f64>,
    /// Fitted TOF offset in microseconds (SAMMY TZERO t₀).
    /// `None` when energy-scale fitting is not enabled.
    pub t0_us: Option<f64>,
    /// Fitted flight-path scale factor (SAMMY TZERO L₀, dimensionless).
    /// `None` when energy-scale fitting is not enabled.
    pub l_scale: Option<f64>,
    /// The nominal flight path (m) the energy-scale fit was configured
    /// with — stored so [`Self::corrected_energies`] reproduces the
    /// transform with the SAME flight path the fit used, closing the
    /// caller-resupplied-mismatch channel (issue #634 review: a wrong but
    /// positive flight path silently changes the t₀ term).  `None` when
    /// energy-scale fitting is not enabled.
    pub energy_scale_flight_path_m: Option<f64>,
    /// Conditional binomial deviance divided by `(n − k)`
    /// (primary GOF for the counts-KL dispatch, i.e.
    /// `SolverConfig::PoissonKL` on `InputData::Counts` or
    /// `InputData::CountsWithNuisance`).
    ///
    /// `Some(D/dof)` when the counts-KL (joint-Poisson) path was used;
    /// `None` for the LM transmission path (which populates
    /// `reduced_chi_squared` with Pearson χ² / (n−k) instead).
    pub deviance_per_dof: Option<f64>,
    /// Fitted multiplicative-baseline coefficients `[b0, b1, b2]` (issue
    /// #635) for
    ///
    /// ```text
    /// B(E) = b0 + b1·ln(E/E_ref) + b2·ln²(E/E_ref)
    /// ```
    ///
    /// On the transmission routes the baseline is applied OUTERMOST:
    /// `y(E) = B(E)·[Anorm·T + additive background]`. On the exact
    /// resolved-count route the composition is domain-specific: `B(E)`
    /// multiplies the true-energy sample arm BEFORE detector response,
    /// and the Anorm/ABC normalization applies to the measured detector
    /// bins after the separate-arm ratio (see `fit_counts_joint_poisson`).
    /// `None` when no multiplicative baseline was configured (values that
    /// were configured but frozen via `fit_b0/b1/b2 = false` still report
    /// `Some` — they are part of the model that produced the fit).
    pub baseline: Option<[f64; 3]>,
    /// Reference energy `E_ref` (eV) the baseline's `ln(E/E_ref)` basis was
    /// centered on — the geometric midpoint `√(E_min·E_max)` of the fit
    /// grid, stored so consumers reconstruct `B(E)` with the EXACT
    /// reference the fit used (the same resupply-mismatch channel
    /// [`Self::energy_scale_flight_path_m`] closes for the energy scale).
    /// `None` when no multiplicative baseline was configured.
    pub baseline_e_ref_ev: Option<f64>,
    /// Structured fit-configuration warnings (issue #635).  Non-fatal
    /// conditions the caller should surface to the user — currently the
    /// degenerate normalization trio (free `Anorm` + free temperature +
    /// ≥1 free density), which on real VENUS data converged to T = 4471 K
    /// with χ²/ν = 932 and no diagnostic.  Empty when nothing is flagged.
    /// A `Vec<String>` rather than tracing: nereids-pipeline has no
    /// tracing dependency, and structured warnings survive across the
    /// PyO3 / GUI boundaries.
    pub warnings: Vec<String>,
}

impl SpectrumFitResult {
    /// Map a nominal energy grid through the fitted SAMMY energy scale
    /// `(t0_us, l_scale)` to the corrected (calibrated) energies the fit
    /// evaluated the physics on (issue #634).
    ///
    /// This exposes the transform the fitter used so downstream code never
    /// has to re-derive it — replicating it by hand with a `+t0` sign
    /// (instead of the correct `−t0`) caused a silent +400 K temperature bias
    /// in the field. It reuses the canonical
    /// [`corrected_energy_grid`](nereids_fitting::resolution_calib::corrected_energy_grid)
    /// (SAMMY `dat/mdat0.f90:189`, −t0 convention) with the SAME flight path
    /// the fit was configured with (stored on the result), so a mismatched
    /// caller-supplied flight path cannot silently skew the t₀ term.
    ///
    /// One divergence from the fit's internal evaluation: at a DEGENERATE
    /// `t0` at/past the grid's shortest flight time, the model clamps `t0`
    /// just below the limit and keeps evaluating, while this accessor
    /// returns `Some(Err(_))` — a degenerate calibration should be
    /// re-examined, not silently reproduced.
    ///
    /// Returns `None` when energy-scale fitting was not enabled — the
    /// corrected grid would equal the input, but `None` distinguishes
    /// "not fitted" from "fitted to the identity".
    pub fn corrected_energies(
        &self,
        nominal_energies: &[f64],
    ) -> Option<Result<Vec<f64>, PipelineError>> {
        match (self.t0_us, self.l_scale, self.energy_scale_flight_path_m) {
            (Some(t0), Some(l_scale), Some(flight_path_m)) => Some(
                nereids_fitting::resolution_calib::corrected_energy_grid(
                    nominal_energies,
                    t0,
                    l_scale,
                    flight_path_m,
                )
                .map_err(|e| PipelineError::InvalidParameter(e.to_string())),
            ),
            _ => None,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use nereids_endf::resonance::test_support::{
        hf178_mlbw_two_resonances, synthetic_single_resonance, u238_single_resonance,
        u238_three_resonances,
    };
    use nereids_fitting::lm::FitModel;
    use nereids_fitting::transmission_model::{
        EnergyScaleJacobianMethod, EnergyScaleTransmissionModel,
    };
    use nereids_physics::transmission as phys_transmission;

    /// Gauss–Jordan inverse of a small dense matrix (test-only; the crate's
    /// `invert_matrix` is `pub(crate)` in nereids-fitting and unreachable here).
    /// Returns `None` on a singular pivot.
    fn invert_dense(a: &[Vec<f64>]) -> Option<Vec<Vec<f64>>> {
        let n = a.len();
        let mut m: Vec<Vec<f64>> = a.to_vec();
        let mut inv: Vec<Vec<f64>> = (0..n)
            .map(|i| (0..n).map(|j| if i == j { 1.0 } else { 0.0 }).collect())
            .collect();
        for col in 0..n {
            // Partial pivot.
            let mut piv = col;
            for r in (col + 1)..n {
                if m[r][col].abs() > m[piv][col].abs() {
                    piv = r;
                }
            }
            if m[piv][col].abs() < 1e-300 {
                return None;
            }
            m.swap(col, piv);
            inv.swap(col, piv);
            let d = m[col][col];
            for j in 0..n {
                m[col][j] /= d;
                inv[col][j] /= d;
            }
            for r in 0..n {
                if r == col {
                    continue;
                }
                let f = m[r][col];
                for j in 0..n {
                    m[r][j] -= f * m[col][j];
                    inv[r][j] -= f * inv[col][j];
                }
            }
        }
        Some(inv)
    }

    /// Issue #608: the dip detector finds the resonance signatures (local
    /// transmission minima) the energy-scale peak-match seed needs.
    #[test]
    fn detect_transmission_dips_finds_clear_dips() {
        let energies: Vec<f64> = (0..120).map(|i| 1.0 + (i as f64) * 0.5).collect();
        let mut t = vec![1.0_f64; 120];
        // Two clear, multi-bin dips so 3-point smoothing keeps them as minima.
        for v in t.iter_mut().take(33).skip(28) {
            *v = 0.4;
        }
        for v in t.iter_mut().take(83).skip(78) {
            *v = 0.6;
        }
        let dips = detect_transmission_dips(&t, &energies);
        assert_eq!(dips.len(), 2, "expected 2 dips, got {dips:?}");
        let mut de: Vec<f64> = dips.iter().map(|&(e, _)| e).collect();
        de.sort_by(f64::total_cmp);
        // Centres near energies[30] (16.0 eV) and energies[80] (41.0 eV).
        assert!(
            (de[0] - energies[30]).abs() <= 1.0,
            "first dip at {} eV",
            de[0]
        );
        assert!(
            (de[1] - energies[80]).abs() <= 1.0,
            "second dip at {} eV",
            de[1]
        );
    }

    /// Issue #648: `UnifiedFitConfig::baseline_reference_energy()` must fold
    /// the `fit_energy_range` mask, so a full grid that runs into the keV/MeV
    /// tail yields the ACTIVE-window midpoint, not the full-grid midpoint that
    /// silently let the baseline absorb Doppler broadening (T runaway,
    /// warnings=[]).  Mirrors the real VENUS Ta grid.
    #[test]
    fn baseline_reference_energy_honours_fit_energy_range() {
        let data = hf178_mlbw_two_resonances();
        // 8–45 eV resonance region plus a keV-scale tail bin, like the VENUS grid.
        let mut energies: Vec<f64> = (0..400).map(|i| 8.0 + (i as f64) * 0.0925).collect();
        energies.push(3211.0 * 3211.0 / 8.0); // pushes full-grid midpoint far away
        let config = UnifiedFitConfig::new(
            energies.clone(),
            vec![data],
            vec!["Hf-178".into()],
            293.6,
            None,
            vec![0.1],
        )
        .unwrap();
        let full = nereids_fitting::transmission_model::baseline_reference_energy(&energies);
        // No range → full grid (unchanged behaviour).
        assert!((config.baseline_reference_energy() - full).abs() < 1e-6);
        // With fit_energy_range 8–45 eV → active-window midpoint ≈ 19 eV.
        let windowed = config.with_fit_energy_range(Some((8.0, 45.0))).unwrap();
        let e_ref = windowed.baseline_reference_energy();
        assert!(
            e_ref > 8.0 && e_ref < 45.0,
            "windowed E_ref = {e_ref} eV must lie inside the 8–45 eV fit window"
        );
        assert!(
            (e_ref - full).abs() > 100.0,
            "windowed E_ref must differ from the buggy full-grid value {full}"
        );
    }

    /// Issue #608: the energy-scale peak-match seed recovers the identity
    /// calibration (t0≈0, L_scale≈1) when the transmission dips sit at the known
    /// resonance energies — exercising the full seed path (dip detection,
    /// nearest-resonance matching, linear TOF fit).
    #[test]
    fn peak_match_energy_scale_seed_identity() {
        let data = hf178_mlbw_two_resonances(); // s-waves at 7.8 and 16.9 eV
        let energies: Vec<f64> = (0..400).map(|i| 4.0 + (i as f64) * 0.05).collect();
        let (t_obs, _sigma) = synthetic_transmission(&data, 0.1, &energies);
        let config = UnifiedFitConfig::new(
            energies.clone(),
            vec![data],
            vec!["Hf-178".into()],
            293.6,
            None,
            vec![0.1],
        )
        .unwrap()
        .with_energy_scale(0.0, 1.0, 25.0);
        let (t0, l_scale) = peak_match_energy_scale_seed(
            &t_obs,
            config.energies(),
            &config,
            25.0,
            (-10.0, 10.0),
            (0.99, 1.01),
        )
        .expect("seed should be Some with 2 resonances and detectable dips");
        // Dips at the un-shifted resonance energies ⇒ identity calibration.
        assert!(
            t0.abs() < 0.5,
            "t0 should be ≈0 for un-shifted data, got {t0}"
        );
        assert!(
            (l_scale - 1.0).abs() < 5e-3,
            "L_scale should be ≈1 for un-shifted data, got {l_scale}"
        );
    }

    /// Issue #608: the peak-match seed must recover a NON-identity
    /// calibration, not just confirm identity.  Generate measured data with a
    /// known injected `(t0, L_scale)` via the `EnergyScaleTransmissionModel`
    /// (which shifts the resonance positions), then assert the seed recovers it.
    #[test]
    fn peak_match_energy_scale_seed_recovers_nonidentity() {
        let data = hf178_mlbw_two_resonances(); // s-waves at 7.8 and 16.9 eV
        // Finer grid than the identity test so the discrete dip positions pin
        // the slope (L_scale) tightly enough to distinguish it from 1.0.
        let energies: Vec<f64> = (0..900).map(|i| 4.0 + (i as f64) * 0.02).collect();
        let density = 0.1_f64;
        let flight_path = 25.0_f64;
        let (t0_true, l_scale_true) = (2.0_f64, 1.006_f64);
        // EnergyScale model (no resolution: dip POSITIONS, not shapes, drive the
        // seed) evaluated at the injected calibration ⇒ shifted measured data.
        let model = EnergyScaleTransmissionModel::new(
            Arc::new(vec![data.clone()]),
            Arc::new(vec![0]),
            Arc::new(vec![1.0]),
            293.6,
            energies.clone(),
            flight_path,
            1, // t0 index
            2, // l_scale index
            None,
        );
        let t_obs = model.evaluate(&[density, t0_true, l_scale_true]).unwrap();
        let config = UnifiedFitConfig::new(
            energies.clone(),
            vec![data],
            vec!["Hf-178".into()],
            293.6,
            None,
            vec![density],
        )
        .unwrap()
        .with_energy_scale(0.0, 1.0, flight_path);
        let (t0, l_scale) = peak_match_energy_scale_seed(
            &t_obs,
            config.energies(),
            &config,
            flight_path,
            (-10.0, 10.0),
            (0.99, 1.01),
        )
        .expect("seed should be Some for a clean shifted two-resonance spectrum");
        // The seed is a coarse peak-match (dip energies quantized to the grid),
        // so tolerances are looser than a converged LM — it just needs to land
        // in the global-min basin, clearly distinct from the cold start (0, 1).
        assert!(
            (t0 - t0_true).abs() < 0.6,
            "seed should recover t0 ≈ {t0_true}, got {t0}"
        );
        assert!(
            (l_scale - l_scale_true).abs() < 4e-3,
            "seed should recover L_scale ≈ {l_scale_true}, got {l_scale}"
        );
        // Sanity: the recovered seed is strictly closer to truth than cold start.
        assert!(
            (t0 - t0_true).abs() < (0.0 - t0_true).abs()
                && (l_scale - l_scale_true).abs() < (1.0 - l_scale_true).abs(),
            "seed must improve on the cold start"
        );
    }

    /// Issue #608: a heavily-absorbing but FEATURELESS spectrum (no
    /// resonance dips) yields fewer than two detectable dips, so the seed must
    /// return `None` and the caller keeps the cold start rather than fitting a
    /// spurious calibration.
    #[test]
    fn peak_match_energy_scale_seed_none_on_featureless_spectrum() {
        let data = hf178_mlbw_two_resonances(); // 2 resonances in range (gate passes)
        let energies: Vec<f64> = (0..400).map(|i| 4.0 + (i as f64) * 0.05).collect();
        // Strong smooth 1/√E absorption, monotonic ⇒ NO local minima ⇒ < 2 dips.
        let t_obs: Vec<f64> = energies.iter().map(|&e| (-5.0 / e.sqrt()).exp()).collect();
        let config = UnifiedFitConfig::new(
            energies.clone(),
            vec![data],
            vec!["Hf-178".into()],
            293.6,
            None,
            vec![0.1],
        )
        .unwrap()
        .with_energy_scale(0.0, 1.0, 25.0);
        assert!(
            peak_match_energy_scale_seed(
                &t_obs,
                config.energies(),
                &config,
                25.0,
                (-10.0, 10.0),
                (0.99, 1.01),
            )
            .is_none(),
            "a featureless heavily-absorbing spectrum has no resonance dips ⇒ \
             seed must return None (cold-start fallback)"
        );
    }

    /// Issue #608: duplicate resonance center energies — two
    /// isotopes with a resonance at the SAME energy in a grouped fit — must not
    /// collapse the seed's `match_tol` to 0.  Pre-fix `resonance_center_energies`
    /// returned `[7.8, 7.8, 16.9]` ⇒ minimum spacing 0 ⇒ `match_tol` 0 ⇒ every
    /// dip rejected ⇒ seed silently `None` (cold start).  With the dedup + grid
    /// floor the seed recovers the (identity) calibration.
    #[test]
    fn peak_match_energy_scale_seed_handles_duplicate_resonance_energies() {
        use nereids_physics::transmission::{SampleParams, forward_model};

        // Two isotopes share an EXACT resonance energy (7.8); a third is distinct.
        let iso_a = synthetic_single_resonance(72, 178, 176.0, 7.8);
        let iso_b = synthetic_single_resonance(74, 184, 182.0, 7.8); // duplicate energy
        let iso_c = synthetic_single_resonance(40, 90, 89.0, 16.9); // distinct
        let energies: Vec<f64> = (0..900).map(|i| 4.0 + (i as f64) * 0.02).collect();
        let density = 0.05_f64;
        let sample = SampleParams::new(
            293.6,
            vec![
                (iso_a.clone(), density),
                (iso_b.clone(), density),
                (iso_c.clone(), density),
            ],
        )
        .unwrap();
        let t_obs = forward_model(&energies, &sample, None).unwrap();
        let config = UnifiedFitConfig::new(
            energies.clone(),
            vec![iso_a, iso_b, iso_c],
            vec!["A".into(), "B".into(), "C".into()],
            293.6,
            None,
            vec![density, density, density],
        )
        .unwrap()
        .with_energy_scale(0.0, 1.0, 25.0);
        let (t0, l_scale) = peak_match_energy_scale_seed(
            &t_obs,
            config.energies(),
            &config,
            25.0,
            (-10.0, 10.0),
            (0.99, 1.01),
        )
        .expect(
            "duplicate resonance energies must not collapse match_tol to 0 — \
             seed should be Some (was silently None pre-fix)",
        );
        assert!(t0.abs() < 0.5, "identity calibration: t0 ≈ 0, got {t0}");
        assert!(
            (l_scale - 1.0).abs() < 5e-3,
            "identity calibration: L_scale ≈ 1, got {l_scale}"
        );
    }

    // ── Phase 0: InputData + SolverConfig + CountsBackgroundConfig tests ──

    #[test]
    fn test_input_data_transmission_n_energies() {
        let data = InputData::Transmission {
            transmission: vec![0.9, 0.8, 0.7],
            uncertainty: vec![0.01, 0.01, 0.01],
        };
        assert_eq!(data.n_energies(), 3);
        assert!(!data.is_counts());
    }

    #[test]
    fn test_input_data_counts_n_energies() {
        let data = InputData::Counts {
            sample_counts: vec![10.0, 20.0, 30.0, 40.0],
            open_beam_counts: vec![100.0, 100.0, 100.0, 100.0],
        };
        assert_eq!(data.n_energies(), 4);
        assert!(data.is_counts());
    }

    #[test]
    fn test_input_data_counts_with_nuisance() {
        let data = InputData::CountsWithNuisance {
            sample_counts: vec![5.0, 6.0],
            flux: vec![100.0, 100.0],
            background: vec![0.5, 0.5],
        };
        assert_eq!(data.n_energies(), 2);
        assert!(data.is_counts());
    }

    #[test]
    fn test_solver_config_default_is_auto() {
        let cfg = SolverConfig::default();
        assert!(matches!(cfg, SolverConfig::Auto));
    }

    #[test]
    fn test_counts_background_config_default() {
        let cfg = CountsBackgroundConfig::default();
        assert!((cfg.alpha_1_init - 1.0).abs() < f64::EPSILON);
        assert!((cfg.alpha_2_init - 1.0).abs() < f64::EPSILON);
        assert!(!cfg.fit_alpha_1);
        assert!(!cfg.fit_alpha_2);
    }

    // ── Phase 2: fit_spectrum_typed tests ──

    /// Helper: build synthetic transmission data from known density.
    fn synthetic_transmission(
        data: &ResonanceData,
        true_density: f64,
        energies: &[f64],
    ) -> (Vec<f64>, Vec<f64>) {
        let model = PrecomputedTransmissionModel {
            cross_sections: Arc::new(vec![
                phys_transmission::broadened_cross_sections(
                    energies,
                    std::slice::from_ref(data),
                    0.0,
                    None,
                    None,
                )
                .unwrap()
                .into_iter()
                .next()
                .unwrap(),
            ]),
            density_indices: Arc::new(vec![0]),
            instrument: None,
            resolution_plan: None,
            sparse_cubature_plan: None,
            sparse_scalar_plan: None,
            layout: Arc::new(WorkingGridLayout::identity(energies)),
        };
        let t = model.evaluate(&[true_density]).unwrap();
        let sigma: Vec<f64> = t.iter().map(|&v| 0.01 * v.max(0.01)).collect();
        (t, sigma)
    }

    /// Helper: build synthetic counts from known density.
    fn synthetic_counts(
        data: &ResonanceData,
        true_density: f64,
        energies: &[f64],
        i0: f64,
    ) -> (Vec<f64>, Vec<f64>) {
        let (t, _) = synthetic_transmission(data, true_density, energies);
        let open_beam: Vec<f64> = vec![i0; energies.len()];
        let sample: Vec<f64> = t.iter().map(|&v| (v * i0).round().max(0.0)).collect();
        (sample, open_beam)
    }

    #[test]
    fn test_typed_transmission_lm_recovers_density() {
        let data = u238_single_resonance();
        let true_density = 0.002;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, sigma) = synthetic_transmission(&data, true_density, &energies);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()));

        let input = InputData::Transmission {
            transmission: t,
            uncertainty: sigma,
        };

        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(result.converged, "LM should converge");
        let fitted = result.densities[0];
        assert!(
            (fitted - true_density).abs() / true_density < 0.05,
            "density: fitted={fitted}, true={true_density}"
        );
    }

    fn table_on_data_grid(config: &UnifiedFitConfig, sigma: Vec<Vec<f64>>) -> PrecomputedXs {
        PrecomputedXs {
            sigma: Arc::new(sigma),
            layout: Arc::new(WorkingGridLayout::identity(config.energies())),
        }
    }

    /// Helper: a valid single-isotope transmission config + input on a short
    /// grid, for precomputed-cross-section shape-validation tests.
    fn precomputed_xs_fixture() -> (UnifiedFitConfig, InputData) {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..11).map(|i| 1.0 + (i as f64) * 0.1).collect();
        let (t, sigma) = synthetic_transmission(&data, 0.001, &energies);
        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()));
        let input = InputData::Transmission {
            transmission: t,
            uncertainty: sigma,
        };
        (config, input)
    }

    #[test]
    fn test_fit_rejects_empty_precomputed_cross_sections() {
        // An empty XS stack used to panic on `xs[0].len()` deep in the
        // forward-model builder; it must now be a typed up-front error.
        let (config, input) = precomputed_xs_fixture();
        let config = config
            .clone()
            .with_precomputed_cross_sections(table_on_data_grid(&config, Vec::new()));
        let err = fit_spectrum_typed(&input, &config).unwrap_err();
        assert!(
            matches!(err, PipelineError::ShapeMismatch(_)),
            "expected ShapeMismatch, got {err:?}"
        );
        assert!(err.to_string().contains("must not be empty"));
    }

    #[test]
    fn test_fit_rejects_wrong_row_count_precomputed_cross_sections() {
        // 1 isotope → exactly 1 σ row expected; supply 2.
        let (config, input) = precomputed_xs_fixture();
        let n_e = config.energies().len();
        let bad = vec![vec![1.0; n_e], vec![1.0; n_e]];
        let config = config
            .clone()
            .with_precomputed_cross_sections(table_on_data_grid(&config, bad));
        let err = fit_spectrum_typed(&input, &config).unwrap_err();
        assert!(
            matches!(err, PipelineError::ShapeMismatch(_)),
            "expected ShapeMismatch, got {err:?}"
        );
        assert!(err.to_string().contains("rows"));
    }

    #[test]
    fn test_fit_rejects_wrong_energy_length_precomputed_cross_sections() {
        // Correct row count (1) but the row is the wrong length.
        let (config, input) = precomputed_xs_fixture();
        let n_e = config.energies().len();
        let bad = vec![vec![1.0; n_e + 3]];
        let config = config
            .clone()
            .with_precomputed_cross_sections(table_on_data_grid(&config, bad));
        let err = fit_spectrum_typed(&input, &config).unwrap_err();
        assert!(
            matches!(err, PipelineError::ShapeMismatch(_)),
            "expected ShapeMismatch, got {err:?}"
        );
        assert!(err.to_string().contains("its grid has"));
    }

    #[test]
    fn test_fit_accepts_correct_precomputed_cross_sections() {
        // A correctly-shaped precomputed stack must still fit (no false
        // rejection): 1 row of length n_e.
        let (config, input) = precomputed_xs_fixture();
        let n_e = config.energies().len();
        let xs = phys_transmission::broadened_cross_sections(
            config.energies(),
            config.resonance_data(),
            0.0,
            None,
            None,
        )
        .unwrap();
        assert_eq!(xs.len(), 1);
        assert_eq!(xs[0].len(), n_e);
        let config = config
            .clone()
            .with_precomputed_cross_sections(table_on_data_grid(&config, xs));
        // Must not error on shape; the fit itself may or may not converge,
        // but the call must reach the solver rather than fail validation.
        let result = fit_spectrum_typed(&input, &config);
        assert!(
            result.is_ok(),
            "correctly-shaped precomputed XS must pass validation, got {result:?}"
        );
    }

    #[test]
    fn test_fit_rejects_non_finite_precomputed_cross_sections() {
        // A correctly-shaped row whose σ values are NaN passes the shape
        // checks but poisons the forward model (NaN residual swallowed as a
        // failed pixel).  It must be rejected at the boundary.  `NaN < x` is
        // `false`, so a bare order comparison would let it through — the
        // `is_finite()` half of the guard is what catches it.
        let (config, input) = precomputed_xs_fixture();
        let n_e = config.energies().len();
        let bad = vec![vec![f64::NAN; n_e]];
        let config = config
            .clone()
            .with_precomputed_cross_sections(table_on_data_grid(&config, bad));
        let err = fit_spectrum_typed(&input, &config).unwrap_err();
        assert!(
            matches!(err, PipelineError::ShapeMismatch(_)),
            "expected ShapeMismatch, got {err:?}"
        );
        assert!(
            err.to_string().contains("non-finite"),
            "error should mention non-finite σ, got: {err}"
        );

        // ±∞ is equally rejected.
        let (config, input) = precomputed_xs_fixture();
        let mut row = vec![1.0; n_e];
        row[n_e / 2] = f64::INFINITY;
        let config = config
            .clone()
            .with_precomputed_cross_sections(table_on_data_grid(&config, vec![row]));
        let err = fit_spectrum_typed(&input, &config).unwrap_err();
        assert!(
            matches!(err, PipelineError::ShapeMismatch(_)),
            "expected ShapeMismatch for +inf σ, got {err:?}"
        );
    }

    #[test]
    fn test_evaluate_jacobian_rejects_malformed_precomputed_cross_sections() {
        // `evaluate_jacobian_and_fisher` is a third public entry point that
        // consumes `config.precomputed_cross_sections`.  An empty stack used
        // to reach `build_transmission_model` and panic on `xs[0].len()`; it
        // must now fail the shared up-front validator instead.
        let (config, _input) = precomputed_xs_fixture();
        let n_e = config.energies().len();
        let flux = vec![1.0; n_e];
        let background = vec![0.0; n_e];

        // `ModelJacobianResult` (the Ok type) is not `Debug`, so match on the
        // result rather than calling `unwrap_err()`.
        let empty = config
            .clone()
            .with_precomputed_cross_sections(table_on_data_grid(&config, Vec::new()));
        match evaluate_jacobian_and_fisher(&empty, &flux, &background) {
            Err(PipelineError::ShapeMismatch(msg)) => {
                assert!(msg.contains("must not be empty"), "got: {msg}");
            }
            Err(other) => panic!("expected ShapeMismatch for empty XS, got {other:?}"),
            Ok(_) => panic!("empty precomputed XS must be rejected"),
        }

        // Non-finite σ is rejected on this path too.
        let nan = config
            .clone()
            .with_precomputed_cross_sections(table_on_data_grid(
                &config,
                vec![vec![f64::NAN; n_e]],
            ));
        match evaluate_jacobian_and_fisher(&nan, &flux, &background) {
            Err(PipelineError::ShapeMismatch(msg)) => {
                assert!(msg.contains("non-finite"), "got: {msg}");
            }
            Err(other) => panic!("expected ShapeMismatch for NaN σ, got {other:?}"),
            Ok(_) => panic!("non-finite precomputed σ must be rejected"),
        }
    }

    #[test]
    fn test_extract_result_drops_uncertainties_when_unconverged() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..21).map(|i| 1.0 + (i as f64) * 0.1).collect();
        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            293.6,
            None,
            vec![0.001],
        )
        .unwrap();

        let result = LmResult {
            chi_squared: 1.0,
            reduced_chi_squared: 1.0,
            iterations: 5,
            converged: false,
            params: vec![0.001],
            covariance: Some(lm::FlatMatrix::zeros(1, 1)),
            uncertainties: Some(vec![0.123]),
        };

        // Single free density → its full-layout index 0 is also free-index 0.
        let extracted = extract_result(&config, &result, 1, &[0], None, None).unwrap();
        assert!(!extracted.converged);
        assert!(
            extracted.uncertainties.is_none(),
            "pipeline must not surface uncertainties from an unconverged fit"
        );
        assert!(extracted.temperature_k_unc.is_none());
    }

    #[test]
    fn test_typed_counts_kl_recovers_density() {
        let data = u238_single_resonance();
        let true_density = 0.002;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (sample, open_beam) = synthetic_counts(&data, true_density, &energies, 1000.0);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()));

        let input = InputData::Counts {
            sample_counts: sample,
            open_beam_counts: open_beam,
        };

        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(result.converged, "KL on counts should converge");
        let fitted = result.densities[0];
        assert!(
            (fitted - true_density).abs() / true_density < 0.10,
            "density: fitted={fitted}, true={true_density}"
        );
    }

    #[test]
    fn test_typed_counts_kl_low_counts_recovers_density() {
        // I0=10 counts per bin — the regime where KL excels and LM fails
        let data = u238_single_resonance();
        let true_density = 0.0005;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (sample, open_beam) = synthetic_counts(&data, true_density, &energies, 10.0);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()));

        let input = InputData::Counts {
            sample_counts: sample,
            open_beam_counts: open_beam,
        };

        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(result.converged, "KL on low counts should converge");
        let fitted = result.densities[0];
        // Wider tolerance for low counts
        assert!(
            (fitted - true_density).abs() / true_density < 0.30,
            "density: fitted={fitted}, true={true_density}"
        );
    }

    #[test]
    fn test_typed_transmission_kl_is_rejected() {
        let data = u238_single_resonance();
        let true_density = 0.0005;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, sigma) = synthetic_transmission(&data, true_density, &energies);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()));

        let input = InputData::Transmission {
            transmission: t,
            uncertainty: sigma,
        };

        let error = fit_spectrum_typed(&input, &config)
            .expect_err("fractional transmission must not use a Poisson count objective");
        let message = error.to_string();
        assert!(
            message.contains("transmission")
                && message.contains("Poisson")
                && message.contains("least-squares"),
            "rejection must explain the valid transmission engine, got: {message}"
        );
    }

    #[test]
    fn test_typed_counts_lm_is_rejected() {
        // Counts + LM used to silently divide the arms into transmission;
        // the lossy conversion is rejected at the dispatch boundary now.
        let data = u238_single_resonance();
        let true_density = 0.0005;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (sample, open_beam) = synthetic_counts(&data, true_density, &energies, 1000.0);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()));

        let input = InputData::Counts {
            sample_counts: sample,
            open_beam_counts: open_beam,
        };

        let error = fit_spectrum_typed(&input, &config)
            .expect_err("raw counts must not be silently converted to transmission");
        let message = error.to_string();
        assert!(
            message.contains("counts")
                && message.contains("least-squares")
                && message.contains("Poisson"),
            "rejection must explain the valid counts engine, got: {message}"
        );
    }

    #[test]
    fn transmission_rejects_counts_background_config() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (transmission, uncertainty) = synthetic_transmission(&data, 0.0005, &energies);
        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()))
        .with_counts_background(CountsBackgroundConfig::default());
        let input = InputData::Transmission {
            transmission,
            uncertainty,
        };

        let error = fit_spectrum_typed(&input, &config)
            .expect_err("a counts-background request must not be ignored on transmission");
        let message = error.to_string();
        assert!(
            message.contains("counts background") && message.contains("transmission"),
            "rejection must name the domain mismatch, got: {message}"
        );
    }

    #[test]
    fn test_typed_auto_solver_selects_kl_for_counts() {
        let data = u238_single_resonance();
        let true_density = 0.0005;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (sample, open_beam) = synthetic_counts(&data, true_density, &energies, 1000.0);

        // Auto solver (default)
        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap(); // SolverConfig::Auto by default

        let input = InputData::Counts {
            sample_counts: sample,
            open_beam_counts: open_beam,
        };

        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(
            result.converged,
            "Auto solver on counts should use KL and converge"
        );
    }

    #[test]
    fn test_typed_transmission_with_background_lm() {
        let data = u238_single_resonance();
        let true_density = 0.0005;
        let true_anorm = 0.95;
        let true_back_a = 0.02;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();

        // Generate synthetic data with background
        let (t_pure, _) = synthetic_transmission(&data, true_density, &energies);
        let t_bg: Vec<f64> = t_pure
            .iter()
            .map(|&v| true_anorm * v + true_back_a)
            .collect();
        let sigma: Vec<f64> = t_bg.iter().map(|&v| 0.01 * v.max(0.01)).collect();

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig {
            max_iter: 500,
            ..LmConfig::default()
        }))
        .with_transmission_background(BackgroundConfig::default());

        let input = InputData::Transmission {
            transmission: t_bg,
            uncertainty: sigma,
        };

        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(
            result.converged,
            "LM+BG should converge on noiseless synthetic data (chi2r={}, iter={})",
            result.reduced_chi_squared, result.iterations
        );
        assert!(
            (result.densities[0] - true_density).abs() / true_density < 0.05,
            "density: fitted={}, true={true_density}",
            result.densities[0]
        );
        assert!(
            (result.anorm - true_anorm).abs() / true_anorm < 0.05,
            "anorm: fitted={}, true={true_anorm}",
            result.anorm
        );
    }

    #[test]
    fn test_typed_counts_with_nuisance_rejects_lm() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..10).map(|i| 1.0 + (i as f64) * 0.5).collect();

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()));

        let input = InputData::CountsWithNuisance {
            sample_counts: vec![10.0; 10],
            flux: vec![100.0; 10],
            background: vec![0.0; 10],
        };

        let result = fit_spectrum_typed(&input, &config);
        assert!(result.is_err(), "CountsWithNuisance + LM should error");
    }

    /// Helper: build synthetic transmission at a given temperature.
    /// Deterministic ~N(0,1) samples via an LCG + Box–Muller. Test-only, so a
    /// fixed seed gives reproducible noise (no `rand` dev-dependency).
    fn seeded_gaussian(n: usize, seed: u64) -> Vec<f64> {
        let mut state = seed | 1;
        let mut unif = || {
            state = state
                .wrapping_mul(6364136223846793005)
                .wrapping_add(1442695040888963407);
            (((state >> 11) as f64) / ((1u64 << 53) as f64)).clamp(1e-12, 1.0 - 1e-12)
        };
        (0..n)
            .map(|_| {
                let u1 = unif();
                let u2 = unif();
                (-2.0 * u1.ln()).sqrt() * (std::f64::consts::TAU * u2).cos()
            })
            .collect()
    }

    fn synthetic_transmission_at_temp(
        data: &ResonanceData,
        true_density: f64,
        temperature_k: f64,
        energies: &[f64],
    ) -> (Vec<f64>, Vec<f64>) {
        let xs = phys_transmission::broadened_cross_sections(
            energies,
            std::slice::from_ref(data),
            temperature_k,
            None,
            None,
        )
        .unwrap();
        let model = PrecomputedTransmissionModel {
            cross_sections: Arc::new(xs),
            density_indices: Arc::new(vec![0]),
            instrument: None,
            resolution_plan: None,
            sparse_cubature_plan: None,
            sparse_scalar_plan: None,
            layout: Arc::new(WorkingGridLayout::identity(energies)),
        };
        let t = model.evaluate(&[true_density]).unwrap();
        let sigma: Vec<f64> = t.iter().map(|&v| 0.01 * v.max(0.01)).collect();
        (t, sigma)
    }

    #[test]
    fn test_typed_lm_with_temperature() {
        let data = u238_single_resonance();
        let true_density = 0.0005;
        let true_temp = 350.0;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, sigma) = synthetic_transmission_at_temp(&data, true_density, true_temp, &energies);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            300.0, // initial guess (off by 50 K)
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig {
            max_iter: 500,
            ..LmConfig::default()
        }))
        .with_fit_temperature(true);

        let input = InputData::Transmission {
            transmission: t,
            uncertainty: sigma,
        };

        let result = fit_spectrum_typed(&input, &config).unwrap();

        // Check density recovery (within 1%)
        let fitted_density = result.densities[0];
        assert!(
            (fitted_density - true_density).abs() / true_density < 0.01,
            "density: fitted={fitted_density}, true={true_density}, ratio={}",
            (fitted_density - true_density).abs() / true_density,
        );

        // Check temperature recovery (within 1 K)
        let fitted_temp = result
            .temperature_k
            .expect("temperature_k should be Some when fit_temperature=true");
        assert!(
            (fitted_temp - true_temp).abs() < 1.0,
            "temperature: fitted={fitted_temp}, true={true_temp}, delta={}",
            (fitted_temp - true_temp).abs(),
        );
    }

    #[test]
    fn test_typed_lm_with_temperature_and_background() {
        let data = u238_single_resonance();
        let true_density = 0.0005;
        let true_temp = 350.0;
        let true_b0 = 0.012;
        let true_b1 = 0.008;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, sigma) = synthetic_transmission_at_temp(&data, true_density, true_temp, &energies);
        let measured_t: Vec<f64> = t
            .iter()
            .zip(energies.iter())
            .map(|(&ti, &e)| ti + true_b0 + true_b1 / e.sqrt())
            .collect();

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            300.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig {
            max_iter: 120,
            ..LmConfig::default()
        }))
        .with_fit_temperature(true)
        .with_transmission_background(BackgroundConfig::default());

        let input = InputData::Transmission {
            transmission: measured_t,
            uncertainty: sigma,
        };

        let result = fit_spectrum_typed(&input, &config).unwrap();

        assert!(result.converged, "fit did not converge: {result:?}");
        assert!(
            result.iterations <= 80,
            "expected LM background+temperature fit to converge well before max_iter; got {}",
            result.iterations,
        );

        let fitted_density = result.densities[0];
        assert!(
            (fitted_density - true_density).abs() / true_density < 0.02,
            "density: fitted={fitted_density}, true={true_density}, ratio={}",
            (fitted_density - true_density).abs() / true_density,
        );

        let fitted_temp = result
            .temperature_k
            .expect("temperature_k should be Some when fit_temperature=true");
        assert!(
            (fitted_temp - true_temp).abs() < 3.0,
            "temperature: fitted={fitted_temp}, true={true_temp}, delta={}",
            (fitted_temp - true_temp).abs(),
        );

        assert!(
            (result.background[0] - true_b0).abs() < 5e-3,
            "background b0: fitted={}, true={}",
            result.background[0],
            true_b0,
        );
        assert!(
            (result.background[1] - true_b1).abs() < 5e-3,
            "background b1: fitted={}, true={}",
            result.background[1],
            true_b1,
        );
    }

    /// Round-trip test: create a group of 2 isotopes with known ratios,
    /// generate synthetic transmission, fit with group constraints,
    /// verify the fitted group density matches the true value.
    #[test]
    fn test_grouped_fit_spectrum_round_trip() {
        use nereids_core::types::IsotopeGroup;

        // Two synthetic isotopes with resonances at different energies
        let rd1 = synthetic_single_resonance(92, 235, 233.025, 5.0);
        let rd2 = synthetic_single_resonance(92, 238, 236.006, 7.0);

        // Group with 60/40 ratio
        let iso1 = nereids_core::types::Isotope::new(92, 235).unwrap();
        let iso2 = nereids_core::types::Isotope::new(92, 238).unwrap();
        let group =
            IsotopeGroup::custom("U (60/40)".into(), vec![(iso1, 0.6), (iso2, 0.4)]).unwrap();

        let energies: Vec<f64> = (0..301).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let true_density = 0.0005;

        // Generate synthetic transmission using effective densities
        let sample = nereids_physics::transmission::SampleParams::new(
            0.0,
            vec![
                (rd1.clone(), true_density * 0.6),
                (rd2.clone(), true_density * 0.4),
            ],
        )
        .unwrap();
        let transmission =
            nereids_physics::transmission::forward_model(&energies, &sample, None).unwrap();
        let uncertainty: Vec<f64> = transmission.iter().map(|&t| 0.01 * t.max(0.01)).collect();

        // Build config with group
        let config = UnifiedFitConfig::new(
            energies.clone(),
            vec![rd1.clone()],
            vec!["placeholder".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_groups(&[(&group, &[rd1, rd2])], vec![0.001])
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()));

        let input = InputData::Transmission {
            transmission,
            uncertainty,
        };

        let result = fit_spectrum_typed(&input, &config).unwrap();

        // Should recover true density within 1%
        assert_eq!(result.densities.len(), 1, "should have 1 group density");
        let fitted = result.densities[0];
        let rel_error = (fitted - true_density).abs() / true_density;
        assert!(
            rel_error < 0.01,
            "group density: fitted={fitted}, true={true_density}, rel_error={rel_error}"
        );
        assert!(result.converged, "fit should converge");
    }

    #[test]
    fn test_grouped_lm_with_temperature_and_background_noiseless() {
        use nereids_core::types::IsotopeGroup;

        let rd1 = synthetic_single_resonance(72, 176, 8.5, 5.0);
        let rd2 = synthetic_single_resonance(72, 178, 17.0, 7.5);
        let rd3 = synthetic_single_resonance(72, 180, 29.0, 6.0);

        let hf176 = nereids_core::types::Isotope::new(72, 176).unwrap();
        let hf178 = nereids_core::types::Isotope::new(72, 178).unwrap();
        let hf180 = nereids_core::types::Isotope::new(72, 180).unwrap();
        let group = IsotopeGroup::custom(
            "Hf-like (3 member)".into(),
            vec![(hf176, 0.2), (hf178, 0.5), (hf180, 0.3)],
        )
        .unwrap();

        let energies: Vec<f64> = (0..300).map(|i| 1.0 + (49.0 * i as f64) / 299.0).collect();
        let true_density = 0.001;
        let true_temp = 400.0;
        let true_b0 = 0.012;
        let true_b1 = 0.008;

        let sample = nereids_physics::transmission::SampleParams::new(
            true_temp,
            vec![
                (rd1.clone(), true_density * 0.2),
                (rd2.clone(), true_density * 0.5),
                (rd3.clone(), true_density * 0.3),
            ],
        )
        .unwrap();
        let pure_t =
            nereids_physics::transmission::forward_model(&energies, &sample, None).unwrap();
        let measured_t: Vec<f64> = pure_t
            .iter()
            .zip(energies.iter())
            .map(|(&t, &e)| t + true_b0 + true_b1 / e.sqrt())
            .collect();
        let sigma = vec![0.001; energies.len()];

        let config = UnifiedFitConfig::new(
            energies.clone(),
            vec![rd1.clone()],
            vec!["placeholder".into()],
            293.6,
            None,
            vec![0.0008],
        )
        .unwrap()
        .with_groups(&[(&group, &[rd1, rd2, rd3])], vec![0.0008])
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig {
            max_iter: 200,
            ..LmConfig::default()
        }))
        .with_fit_temperature(true)
        .with_transmission_background(BackgroundConfig::default());

        let input = InputData::Transmission {
            transmission: measured_t,
            uncertainty: sigma,
        };

        let result = fit_spectrum_typed(&input, &config).unwrap();

        assert!(result.converged, "fit did not converge: {result:?}");
        // Tolerance: 1% — the NormalizedTransmissionModel (4 background params)
        // has slightly different convergence than the old 2-param KL model.
        assert!(
            (result.densities[0] - true_density).abs() / true_density < 0.01,
            "density: fitted={}, true={true_density}",
            result.densities[0]
        );
        let fitted_temp = result
            .temperature_k
            .expect("temperature_k should be Some when fit_temperature=true");
        assert!(
            (fitted_temp - true_temp).abs() < 8.0,
            "temperature: fitted={fitted_temp}, true={true_temp}",
        );
        // Background: NormalizedTransmissionModel distributes the additive
        // background across Anorm + BackA/B/C.  Check that the total background
        // contribution is reasonable, not individual parameters.
        let e_mid: f64 = 10.0;
        let bg_total = (result.anorm - 1.0)
            + result.background[0]
            + result.background[1] / e_mid.sqrt()
            + result.background[2] * e_mid.sqrt();
        let true_bg_mid = true_b0 + true_b1 / e_mid.sqrt();
        assert!(
            (bg_total - true_bg_mid).abs() < 0.02,
            "total bg at E={e_mid}: fitted={bg_total:.6}, true={true_bg_mid:.6}",
        );
    }

    // ── Phase 2: KL fitting uncertainty tests ──────────────────────────────

    #[test]
    fn test_kl_counts_returns_density_uncertainty() {
        let data = u238_single_resonance();
        let true_density = 0.002;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (sample, open_beam) = synthetic_counts(&data, true_density, &energies, 1000.0);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()));

        let input = InputData::Counts {
            sample_counts: sample,
            open_beam_counts: open_beam,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(result.converged);
        let unc = result
            .uncertainties
            .as_ref()
            .expect("KL 1D fit should return density uncertainties");
        assert_eq!(unc.len(), 1);
        assert!(
            unc[0].is_finite() && unc[0] > 0.0,
            "density unc = {}",
            unc[0]
        );
        assert!(
            unc[0] < result.densities[0],
            "unc ({}) should be < density ({}) for high-count data",
            unc[0],
            result.densities[0]
        );
    }

    #[test]
    fn test_kl_counts_returns_temperature_uncertainty() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..201).map(|i| 4.0 + (i as f64) * 0.05).collect();
        let (sample, open_beam) = synthetic_counts(&data, 0.001, &energies, 1000.0);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            350.0,
            None,
            vec![0.0005],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_fit_temperature(true);

        let input = InputData::Counts {
            sample_counts: sample,
            open_beam_counts: open_beam,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(result.converged);
        let unc = result
            .uncertainties
            .as_ref()
            .expect("KL+temp fit should return density uncertainties");
        assert!(
            unc[0].is_finite() && unc[0] > 0.0,
            "density unc = {}",
            unc[0]
        );
        let t_unc = result
            .temperature_k_unc
            .expect("KL+temp fit should return temperature uncertainty");
        assert!(
            t_unc.is_finite() && t_unc > 0.0,
            "temperature unc = {t_unc}"
        );
    }

    /// Issue #638: `scale_by_chi2` inflates the joint-Poisson uncertainties by
    /// exactly `sqrt(deviance_per_dof)`, and `false` reproduces today's values.
    #[test]
    fn test_scale_by_chi2_inflates_joint_poisson_uncertainty() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..201).map(|i| 4.0 + (i as f64) * 0.05).collect();
        let (sample, open_beam) = synthetic_counts(&data, 0.001, &energies, 1000.0);
        let input = InputData::Counts {
            sample_counts: sample,
            open_beam_counts: open_beam,
        };

        let make_config = |scale: bool| {
            UnifiedFitConfig::new(
                energies.clone(),
                vec![data.clone()],
                vec!["U-238".into()],
                350.0,
                None,
                vec![0.0005],
            )
            .unwrap()
            .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
            .with_fit_temperature(true)
            .with_scale_by_chi2(scale)
        };

        let unscaled = fit_spectrum_typed(&input, &make_config(false)).unwrap();
        let scaled = fit_spectrum_typed(&input, &make_config(true)).unwrap();
        assert!(unscaled.converged && scaled.converged);

        // The flag only rescales the post-convergence covariance, so the fit
        // itself (parameters, deviance) is identical between the two runs.
        let dpd = unscaled
            .deviance_per_dof
            .expect("joint-Poisson must report deviance_per_dof");
        assert!(dpd.is_finite() && dpd > 0.0, "deviance_per_dof = {dpd}");
        let factor = dpd.sqrt();
        // The flag must move σ appreciably (guards against a silently-inert
        // flag). χ²-scaling is two-way: on real underfit data D/dof > 1 inflates
        // σ; on this near-noiseless synthetic fit D/dof < 1 shrinks it (standard
        // Numerical Recipes §15.6 behaviour). Direction-agnostic check:
        assert!(
            (factor - 1.0).abs() > 0.01,
            "expected D/dof to move σ by >1%, got factor {factor}"
        );

        // Temperature σ scales by exactly sqrt(D/dof).
        let t_unscaled = unscaled.temperature_k_unc.expect("σ_T unscaled");
        let t_scaled = scaled.temperature_k_unc.expect("σ_T scaled");
        let rel_t = (t_scaled - t_unscaled * factor).abs() / (t_unscaled * factor);
        assert!(
            rel_t < 1e-6,
            "σ_T: scaled {t_scaled} must equal unscaled {t_unscaled} × {factor}"
        );

        // Density σ scales by the same factor.
        let d_unscaled = unscaled.uncertainties.as_ref().expect("density σ unscaled")[0];
        let d_scaled = scaled.uncertainties.as_ref().expect("density σ scaled")[0];
        let rel_d = (d_scaled - d_unscaled * factor).abs() / (d_unscaled * factor);
        assert!(
            rel_d < 1e-6,
            "density σ: scaled {d_scaled} must equal unscaled {d_unscaled} × {factor}"
        );

        // No-regression: scale_by_chi2=false is the default, so the unscaled
        // run must match a plain (flag-absent) fit bit-for-bit.
        let default_cfg = UnifiedFitConfig::new(
            energies.clone(),
            vec![data.clone()],
            vec!["U-238".into()],
            350.0,
            None,
            vec![0.0005],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_fit_temperature(true);
        let default_run = fit_spectrum_typed(&input, &default_cfg).unwrap();
        assert_eq!(
            default_run.temperature_k_unc, unscaled.temperature_k_unc,
            "default (flag absent) must equal scale_by_chi2=false"
        );
    }

    /// Issue #638 (review R2): counts joint-Poisson `scale_by_chi2` DIRECTION
    /// guard. The self-consistency test above uses a near-noiseless synthetic
    /// (`deviance_per_dof < 1`, so σ shrinks); this exercises the paper's actual
    /// regime — a deliberately UNDER-fit spectrum (`D/dof > 1`) must GROW σ.
    /// A behavioural check (σ_scaled > σ_unscaled), not a re-derivation of the
    /// reported statistic, so a future refactor that inverted the counts-path
    /// factor would fail here.
    #[test]
    fn test_scale_by_chi2_joint_poisson_underfit_grows_sigma() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..201).map(|i| 4.0 + (i as f64) * 0.05).collect();
        let (sample, open_beam) = synthetic_counts(&data, 0.001, &energies, 1000.0);
        // ±30% zig-zag on the sample counts: a zero-mean high-frequency
        // perturbation the smooth density+temperature model cannot absorb,
        // driving the Poisson deviance per dof well above 1. Rounded and
        // floored ≥ 0 to stay a valid count spectrum.
        let sample: Vec<f64> = sample
            .iter()
            .enumerate()
            .map(|(i, &c)| {
                let k = if i % 2 == 0 { 1.30 } else { 0.70 };
                (c * k).round().max(0.0)
            })
            .collect();
        let input = InputData::Counts {
            sample_counts: sample,
            open_beam_counts: open_beam,
        };
        let make_config = |scale: bool| {
            UnifiedFitConfig::new(
                energies.clone(),
                vec![data.clone()],
                vec!["U-238".into()],
                350.0,
                None,
                vec![0.0005],
            )
            .unwrap()
            .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
            .with_fit_temperature(true)
            .with_scale_by_chi2(scale)
        };
        let unscaled = fit_spectrum_typed(&input, &make_config(false)).unwrap();
        let scaled = fit_spectrum_typed(&input, &make_config(true)).unwrap();
        assert!(unscaled.converged && scaled.converged);
        let dpd = unscaled
            .deviance_per_dof
            .expect("joint-Poisson must report deviance_per_dof");
        assert!(
            dpd > 1.0,
            "zig-zag counts must under-fit (D/dof > 1), got {dpd}"
        );
        let t_unscaled = unscaled.temperature_k_unc.expect("σ_T unscaled");
        let t_scaled = scaled.temperature_k_unc.expect("σ_T scaled");
        assert!(
            t_scaled > t_unscaled,
            "under-fit (D/dof {dpd} > 1) must GROW σ_T: scaled {t_scaled} \
             vs unscaled {t_unscaled}"
        );
    }

    #[test]
    fn test_kl_counts_with_background_returns_uncertainty() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..201).map(|i| 4.0 + (i as f64) * 0.05).collect();
        let (sample, open_beam) = synthetic_counts(&data, 0.001, &energies, 1000.0);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            300.0,
            None,
            vec![0.0005],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_fit_temperature(true)
        .with_transmission_background(BackgroundConfig::default());

        let input = InputData::Counts {
            sample_counts: sample,
            open_beam_counts: open_beam,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(result.converged);
        let unc = result
            .uncertainties
            .as_ref()
            .expect("KL+bg fit should return density uncertainties");
        assert!(
            unc[0].is_finite() && unc[0] > 0.0,
            "density unc = {}",
            unc[0]
        );
    }

    #[test]
    fn test_lm_uncertainty_not_regressed() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t_clean, sigma) = synthetic_transmission(&data, 0.001, &energies);
        // Deterministic pseudo-noise at ~0.2 % relative (σ is 1 % relative):
        // the covariance is scaled by χ²/ν (#108.1), so EXACTLY noise-free
        // data drives χ² → 0 once the analytic-Jacobian fit converges
        // machine-exactly, collapsing the scaled covariance to zero — a
        // degenerate oracle, not a solver regression.  Real data always has
        // χ² > 0; emulate that with a seed-free perturbation.
        let t: Vec<f64> = t_clean
            .iter()
            .enumerate()
            .map(|(i, &v)| v * (1.0 + 0.002 * (7.3 * i as f64).sin()))
            .collect();

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.0005],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()));

        let input = InputData::Transmission {
            transmission: t,
            uncertainty: sigma,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(result.converged);
        let unc = result
            .uncertainties
            .as_ref()
            .expect("LM should still return uncertainties");
        assert!(unc[0].is_finite() && unc[0] > 0.0);
    }

    // ── Energy-scale fitting tests ──

    /// Issue #634: fit_energy_scale + fit_temperature JOINTLY recovers the
    /// injected (t0, L_scale, T) in a single LM fit. Closed loop: synthesize
    /// on the TRUE corrected grid at the true T, report on the nominal grid,
    /// then fit from a cold energy-scale seed (0, 1) with T seeded 40 K off —
    /// so a no-op fit cannot pass (non-vacuity).
    ///
    /// Oracle-dependency note: the truth grid is built with the SAME
    /// `corrected_energy_grid` transform the fitter is pinned to, so a
    /// sign/convention error in that shared transform would cancel here.
    /// The convention itself is covered independently: the Python
    /// `TestFitEnergyScaleRecovery` derives measured energies through a
    /// hand-written inverse TOF map, and the `−t0` form is verified against
    /// SAMMY `dat/mdat0.f90:189`. This test targets the JOINT-recovery
    /// property (temperature wiring, FD column, index mapping), which the
    /// shared transform cannot mask.
    #[test]
    fn test_energy_scale_with_temperature_recovers_all_three() {
        // Three well-separated resonances break the (t0, L_scale) degeneracy
        // that a single dip leaves.
        let data = u238_three_resonances();
        let flight_path = 25.0_f64;
        let true_density = 0.002;
        let true_temp = 340.0;
        let true_t0 = 0.6_f64; // µs
        let true_l_scale = 1.004_f64;
        // Fine grid spanning all three resonances (6.674, 20.87, 36.68 eV).
        let nominal: Vec<f64> = (0..801).map(|i| 4.0 + (i as f64) * 0.05).collect();

        // TRUE corrected energies: each nominal bin's true physical energy.
        let e_true = nereids_fitting::resolution_calib::corrected_energy_grid(
            &nominal,
            true_t0,
            true_l_scale,
            flight_path,
        )
        .unwrap();
        // Clean transmission at the true energies + true T, indexed by bin.
        let (t_obs, sigma) =
            synthetic_transmission_at_temp(&data, true_density, true_temp, &e_true);

        let config = UnifiedFitConfig::new(
            nominal,
            vec![data],
            vec!["U-238".into()],
            true_temp - 40.0, // temperature seeded 40 K low
            None,
            vec![true_density],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(Default::default()))
        .with_fit_temperature(true)
        .with_energy_scale(0.0, 1.0, flight_path); // cold energy-scale seed

        let input = InputData::Transmission {
            transmission: t_obs,
            uncertainty: sigma,
        };
        let result = fit_spectrum_typed(&input, &config).expect("joint fit runs");
        assert!(result.converged, "joint (t0,L_scale,T) fit should converge");

        let t0 = result.t0_us.expect("t0_us populated");
        let ls = result.l_scale.expect("l_scale populated");
        let temp = result.temperature_k.expect("temperature_k populated");
        assert!(
            (t0 - true_t0).abs() < 0.05,
            "t0: fitted={t0}, true={true_t0}"
        );
        assert!(
            (ls - true_l_scale).abs() / true_l_scale < 1e-3,
            "l_scale: fitted={ls}, true={true_l_scale}"
        );
        assert!(
            (temp - true_temp).abs() < 3.0,
            "temperature: fitted={temp}, true={true_temp}"
        );
    }

    /// Optional energy-scale and temperature settings do not make a
    /// transmission Poisson/KL request statistically valid.
    #[test]
    fn test_energy_scale_with_temperature_does_not_enable_transmission_kl() {
        let data = u238_three_resonances();
        let flight_path = 25.0_f64;
        let true_density = 0.002;
        let true_temp = 340.0;
        let true_t0 = 0.6_f64;
        let true_l_scale = 1.004_f64;
        let nominal: Vec<f64> = (0..801).map(|i| 4.0 + (i as f64) * 0.05).collect();
        let e_true = nereids_fitting::resolution_calib::corrected_energy_grid(
            &nominal,
            true_t0,
            true_l_scale,
            flight_path,
        )
        .unwrap();
        let (t_obs, sigma) =
            synthetic_transmission_at_temp(&data, true_density, true_temp, &e_true);

        let config = UnifiedFitConfig::new(
            nominal,
            vec![data],
            vec!["U-238".into()],
            true_temp - 40.0,
            None,
            vec![true_density],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_fit_temperature(true)
        .with_energy_scale(0.0, 1.0, flight_path);

        let error = fit_spectrum_typed(
            &InputData::Transmission {
                transmission: t_obs,
                uncertainty: sigma,
            },
            &config,
        )
        .expect_err("transmission plus Poisson/KL must be rejected");
        assert!(error.to_string().contains("normalized transmission"));
    }

    /// Issue #634: the joint combination on the COUNTS joint-Poisson path —
    /// the third lifted guard. Deterministic counts (no sampling noise) at
    /// the true corrected grid; the joint fit must recover (t0, L_scale, T)
    /// and report a finite temperature σ through the joint-Poisson
    /// uncertainty extraction.
    #[test]
    fn test_energy_scale_with_temperature_recovers_all_three_counts() {
        let data = u238_three_resonances();
        let flight_path = 25.0_f64;
        let true_density = 0.002;
        let true_temp = 340.0;
        let true_t0 = 0.6_f64;
        let true_l_scale = 1.004_f64;
        let flux = 1.0e4_f64;
        let nominal: Vec<f64> = (0..801).map(|i| 4.0 + (i as f64) * 0.05).collect();
        let e_true = nereids_fitting::resolution_calib::corrected_energy_grid(
            &nominal,
            true_t0,
            true_l_scale,
            flight_path,
        )
        .unwrap();
        let (t_true, _) = synthetic_transmission_at_temp(&data, true_density, true_temp, &e_true);
        let open_beam = vec![flux; t_true.len()];
        let sample_counts: Vec<f64> = t_true.iter().map(|&t| flux * t).collect();

        let config = UnifiedFitConfig::new(
            nominal,
            vec![data],
            vec!["U-238".into()],
            true_temp - 40.0,
            None,
            vec![true_density],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_fit_temperature(true)
        .with_energy_scale(0.0, 1.0, flight_path);

        let result = fit_spectrum_typed(
            &InputData::Counts {
                sample_counts,
                open_beam_counts: open_beam,
            },
            &config,
        )
        .expect("counts joint-Poisson joint fit runs");
        assert!(result.converged, "counts joint fit should converge");
        let t0 = result.t0_us.expect("t0_us populated");
        let ls = result.l_scale.expect("l_scale populated");
        let temp = result.temperature_k.expect("temperature_k populated");
        assert!(
            (t0 - true_t0).abs() < 0.1,
            "counts t0: fitted={t0}, true={true_t0}"
        );
        assert!(
            (ls - true_l_scale).abs() / true_l_scale < 2e-3,
            "counts l_scale: fitted={ls}, true={true_l_scale}"
        );
        assert!(
            (temp - true_temp).abs() < 5.0,
            "counts temperature: fitted={temp}, true={true_temp}"
        );
        let t_unc = result
            .temperature_k_unc
            .expect("counts joint fit must report a temperature σ");
        assert!(
            t_unc.is_finite() && t_unc > 0.0,
            "counts joint temperature σ must be finite positive, got {t_unc}"
        );
    }

    /// Issue #634 (acceptance c, revised): two guarantees on the joint fit's
    /// temperature uncertainty.
    ///
    /// (c1) Physical invariant, no arbitrary threshold: on identical data the
    /// joint (T + t0 + L_scale) fit's σ_T is strictly LARGER than a
    /// no-energy-scale (T-only) fit's σ_T — the extra energy-scale parameters
    /// are not orthogonal to temperature. (The magnitude of the excess is
    /// dataset-dependent coupling, so pinning a % against a different model
    /// protects nothing; hence a strict inequality, not a bound.)
    ///
    /// (c2) Covariance plumbing, same model: at the joint solution, an
    /// INDEPENDENT reconstruction of the covariance — finite-difference the
    /// SAME model's predictions with the model's own steps, form (JᵀWJ)⁻¹ by
    /// hand, read the temperature diagonal, scale by reduced χ² — reproduces
    /// the solver-reported σ_T to <0.1%. This is the assertion that catches
    /// the #641-class bug where σ_T is read from the wrong free-parameter slot.
    /// Full-FD Jacobian so the reconstruction's steps match the solver's.
    #[test]
    fn test_energy_scale_temperature_sigma_covariance_plumbing() {
        let data = u238_three_resonances();
        let flight_path = 25.0_f64;
        let true_density = 0.002;
        let true_temp = 340.0;
        let true_t0 = 0.6_f64;
        let true_l_scale = 1.004_f64;
        let nominal: Vec<f64> = (0..801).map(|i| 4.0 + (i as f64) * 0.05).collect();
        let e_true = nereids_fitting::resolution_calib::corrected_energy_grid(
            &nominal,
            true_t0,
            true_l_scale,
            flight_path,
        )
        .unwrap();
        let (t_clean, sigma) =
            synthetic_transmission_at_temp(&data, true_density, true_temp, &e_true);
        // Matched Gaussian noise so both fits reach reduced_chi²≈1 and σ_T
        // reflects the Jacobian covariance (not a ~0 residual).
        let noise = seeded_gaussian(t_clean.len(), 0x6340_0000_0000_0634);
        let t_obs: Vec<f64> = t_clean
            .iter()
            .zip(sigma.iter())
            .zip(noise.iter())
            .map(|((&t, &s), &g)| t + s * g)
            .collect();

        // Joint fit — full-FD Jacobian so the independent reconstruction below
        // uses matching per-coordinate central differences (PartialGal would
        // derive the L_scale column by a rank-1 identity we do not replicate).
        let joint_cfg = UnifiedFitConfig::new(
            nominal.clone(),
            vec![data.clone()],
            vec!["U-238".into()],
            true_temp - 40.0,
            None,
            vec![true_density],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(Default::default()))
        .with_fit_temperature(true)
        .with_energy_scale(0.0, 1.0, flight_path)
        .with_tzero_jacobian_method(Some(EnergyScaleJacobianMethod::FiniteDifference));
        let joint = fit_spectrum_typed(
            &InputData::Transmission {
                transmission: t_obs.clone(),
                uncertainty: sigma.clone(),
            },
            &joint_cfg,
        )
        .unwrap();
        let sigma_t_joint = joint.temperature_k_unc.expect("joint σ_T");

        // Reference: temperature-only fit on the TRUE corrected grid (analytic
        // ∂σ/∂T path, no energy scale) — same data, same noise.
        let ref_cfg = UnifiedFitConfig::new(
            e_true,
            vec![data.clone()],
            vec!["U-238".into()],
            true_temp - 40.0,
            None,
            vec![true_density],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(Default::default()))
        .with_fit_temperature(true);
        let reference = fit_spectrum_typed(
            &InputData::Transmission {
                transmission: t_obs,
                uncertainty: sigma.clone(),
            },
            &ref_cfg,
        )
        .unwrap();
        let sigma_t_ref = reference.temperature_k_unc.expect("reference σ_T");

        // (c1) strict inequality.  NOTE: this compares σ_T across two
        // DIFFERENT models (4-param energy-scale on the nominal grid vs
        // 2-param fixed-grid on the true corrected grid), so the nested-
        // model Fisher argument does not make it a theorem — it is an
        // empirical property of THIS fixture (verified robust here). If a
        // future fixture change flips it, convert to the same-model form
        // (t0/L_scale frozen vs free), where the inequality is guaranteed.
        assert!(sigma_t_joint.is_finite() && sigma_t_joint > 0.0);
        assert!(sigma_t_ref.is_finite() && sigma_t_ref > 0.0);
        assert!(
            sigma_t_joint > sigma_t_ref,
            "joint σ_T ({sigma_t_joint:.5}) must strictly exceed no-energy-scale \
             σ_T ({sigma_t_ref:.5}): the extra t0/L_scale params are not \
             orthogonal to temperature"
        );

        // (c2) independent covariance reconstruction at the joint solution.
        // Param layout: [density(0), temperature(1), t0(2), l_scale(3)].
        let p = [
            joint.densities[0],
            joint.temperature_k.unwrap(),
            joint.t0_us.unwrap(),
            joint.l_scale.unwrap(),
        ];
        let model = EnergyScaleTransmissionModel::new(
            Arc::new(vec![data]),
            Arc::new(vec![0]),
            Arc::new(vec![1.0]),
            true_temp - 40.0,
            nominal.clone(),
            flight_path,
            2,
            3,
            None,
        )
        .with_temperature_index(Some(1))
        .expect("distinct temperature index")
        .with_jacobian_method(EnergyScaleJacobianMethod::FiniteDifference);

        // Central FD of the model predictions, per-coordinate steps matching
        // the model (t0 abs 1e-4, temperature rel 1e-4, L_scale abs 1e-7;
        // density is analytic in the model — FD it here with a tiny relative
        // step, its off-diagonal contribution to cov_TT is negligible).
        let steps = [1e-4 * p[0].max(1e-6), 1e-4 * p[1].max(1.0), 1e-4, 1e-7];
        let n_e = nominal.len();
        let mut jac = vec![[0.0f64; 4]; n_e];
        for (j, &h) in steps.iter().enumerate() {
            let mut pp = p;
            let mut pm = p;
            pp[j] += h;
            pm[j] -= h;
            let yp = model.evaluate(&pp).unwrap();
            let ym = model.evaluate(&pm).unwrap();
            for i in 0..n_e {
                jac[i][j] = (yp[i] - ym[i]) / (2.0 * h);
            }
        }
        // A = JᵀWJ, W = diag(1/σ²).
        let mut a = vec![vec![0.0f64; 4]; 4];
        for i in 0..n_e {
            let w = 1.0 / (sigma[i] * sigma[i]);
            for r in 0..4 {
                for c in 0..4 {
                    a[r][c] += jac[i][r] * w * jac[i][c];
                }
            }
        }
        let cov = invert_dense(&a).expect("covariance invertible");
        // #108.1: covariance is scaled by reduced χ².
        let sigma_t_recon = (cov[1][1] * joint.reduced_chi_squared).sqrt();
        let rel = (sigma_t_recon - sigma_t_joint).abs() / sigma_t_joint;
        assert!(
            rel < 1e-3,
            "independent covariance reconstruction σ_T={sigma_t_recon:.5} must match \
             the solver-reported σ_T={sigma_t_joint:.5} to <0.1%, got {rel:.3e} \
             (a mismatch means the solver read T's σ from the wrong covariance slot)"
        );
    }

    /// Issue #634: `SpectrumFitResult::corrected_energies` reuses the canonical
    /// transform and returns `None` when the energy scale was not fitted.
    #[test]
    fn test_spectrum_result_corrected_energies() {
        let nominal: Vec<f64> = (0..50).map(|i| 5.0 + i as f64 * 0.3).collect();
        let flight_path = 25.0;
        let (t0, ls) = (0.4_f64, 1.003_f64);
        // Hand-computed oracle — deliberately NOT `corrected_energy_grid`
        // (the very helper the accessor delegates to), so a sign flip,
        // argument swap, or wrong flight-path source in the accessor wiring
        // cannot cancel (issue #634 review: circular-oracle gap).  Formula
        // per SAMMY dat/mdat0.f90:189: E' = (kl·ls / (kl/√E − t0))².
        let kl = nereids_physics::resolution::TOF_FACTOR * flight_path;
        let expected: Vec<f64> = nominal
            .iter()
            .map(|&e| {
                let tof = kl / e.sqrt();
                (kl * ls / (tof - t0)).powi(2)
            })
            .collect();

        let mk = |t0: Option<f64>, ls: Option<f64>, fp: Option<f64>| SpectrumFitResult {
            densities: vec![0.001],
            uncertainties: None,
            reduced_chi_squared: 1.0,
            converged: true,
            iterations: 1,
            temperature_k: None,
            temperature_k_unc: None,
            anorm: 1.0,
            background: [0.0; 3],
            back_d: None,
            back_f: None,
            t0_us: t0,
            l_scale: ls,
            energy_scale_flight_path_m: fp,
            deviance_per_dof: None,
            baseline: None,
            baseline_e_ref_ev: None,
            warnings: Vec::new(),
        };

        // Fitted energy scale → Some(corrected grid) == the canonical
        // transform at the STORED flight path.
        let got = mk(Some(t0), Some(ls), Some(flight_path))
            .corrected_energies(&nominal)
            .expect("Some when energy scale fitted")
            .unwrap();
        assert_eq!(got, expected);
        // Not fitted → None (distinguishes "unfit" from "fitted to identity").
        assert!(mk(None, None, None).corrected_energies(&nominal).is_none());
        assert!(
            mk(Some(t0), None, None)
                .corrected_energies(&nominal)
                .is_none()
        );

        // Invalid scale values are REJECTED, not squared into plausible
        // grids (#634 review): the transform is even in l_scale (a negative
        // l_scale would silently return the same grid as its positive
        // counterpart), flight_path_m = 0 with t0 < 0 would return all
        // zeros, and a NaN l_scale would return Ok(NaN).
        assert!(
            mk(Some(t0), Some(ls), Some(0.0))
                .corrected_energies(&nominal)
                .unwrap()
                .is_err()
        );
        assert!(
            mk(Some(t0), Some(ls), Some(-25.0))
                .corrected_energies(&nominal)
                .unwrap()
                .is_err()
        );
        assert!(
            mk(Some(t0), Some(-1.0), Some(flight_path))
                .corrected_energies(&nominal)
                .unwrap()
                .is_err()
        );
        assert!(
            mk(Some(t0), Some(f64::NAN), Some(flight_path))
                .corrected_energies(&nominal)
                .unwrap()
                .is_err()
        );
        // A garbage NOMINAL grid is rejected too — including at the exact
        // identity (t0=0, ls=1), which previously passed the grid through
        // verbatim (#634 review: inconsistent Ok/Err contract).
        assert!(
            mk(Some(0.0), Some(1.0), Some(flight_path))
                .corrected_energies(&[1.0, f64::NAN, 3.0])
                .unwrap()
                .is_err()
        );
        assert!(
            mk(Some(t0), Some(ls), Some(flight_path))
                .corrected_energies(&[0.0, 1.0])
                .unwrap()
                .is_err()
        );
        // Non-ascending grids are rejected on the Rust surface too, matching
        // the Python binding's standard validation (#634 review R4).
        assert!(
            mk(Some(t0), Some(ls), Some(flight_path))
                .corrected_energies(&[5.0, 4.0, 6.0])
                .unwrap()
                .is_err()
        );
    }

    /// Energy-scale fitting returns t0_us and l_scale in the result.
    #[test]
    fn test_energy_scale_returns_fitted_params() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t_obs, sigma) = synthetic_transmission(&data, 0.002, &energies);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            293.6,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(Default::default()))
        .with_transmission_background(BackgroundConfig::default())
        .with_energy_scale(0.0, 1.0, 25.0);

        let input = InputData::Transmission {
            transmission: t_obs,
            uncertainty: sigma,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(result.converged, "Fit should converge");
        assert!(
            result.t0_us.is_some(),
            "t0_us should be Some when energy-scale is fitted"
        );
        assert!(
            result.l_scale.is_some(),
            "l_scale should be Some when energy-scale is fitted"
        );
        let t0 = result.t0_us.unwrap();
        let ls = result.l_scale.unwrap();
        // Values should be finite (not NaN/Inf) and within bounds
        assert!(t0.is_finite(), "t0 should be finite, got {t0}");
        assert!(ls.is_finite(), "l_scale should be finite, got {ls}");
        assert!(t0.abs() < 10.0, "t0 should be within bounds, got {t0}");
        assert!(
            ls > 0.98 && ls < 1.02,
            "l_scale should be within bounds, got {ls}"
        );
    }

    /// Without energy-scale fitting, t0_us and l_scale should be None.
    #[test]
    fn test_no_energy_scale_returns_none() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t_obs, sigma) = synthetic_transmission(&data, 0.002, &energies);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            293.6,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(Default::default()))
        .with_transmission_background(BackgroundConfig::default());

        let input = InputData::Transmission {
            transmission: t_obs,
            uncertainty: sigma,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(
            result.t0_us.is_none(),
            "t0_us should be None without energy-scale"
        );
        assert!(
            result.l_scale.is_none(),
            "l_scale should be None without energy-scale"
        );
    }

    // ==================================================================
    // Joint-Poisson solver integration tests
    // ==================================================================

    /// End-to-end: joint-Poisson density recovery at c = 5.98 on synthetic
    /// matched-model counts, via `fit_spectrum_typed`.  Verifies that
    /// `SpectrumFitResult.deviance_per_dof` is populated and that
    /// density is recovered to within 5% on a single-resonance spectrum
    /// under expected (noise-free) counts.
    #[test]
    fn test_joint_poisson_density_recovery_c_5_98() {
        let data = u238_single_resonance();
        let true_density = 0.0005_f64;
        let c = 5.98_f64;
        let lam_ob = 1000.0_f64; // expected open-beam counts per bin (O rate)
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, _) = synthetic_transmission(&data, true_density, &energies);

        // Noise-free expectations under joint-Poisson model:
        //   E[O] = lam_ob, E[S] = c · lam_ob · T
        let open_beam_counts: Vec<f64> = vec![lam_ob; energies.len()];
        let sample_counts: Vec<f64> = t.iter().map(|&ti| c * lam_ob * ti).collect();

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_counts_background(CountsBackgroundConfig {
            c,
            ..Default::default()
        });

        let input = InputData::Counts {
            sample_counts,
            open_beam_counts,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();

        // Deviance-based GOF is populated.
        let d_per_dof = result
            .deviance_per_dof
            .expect("joint-Poisson solver must populate deviance_per_dof");
        assert!(
            d_per_dof.is_finite() && d_per_dof >= 0.0,
            "deviance_per_dof = {d_per_dof} is not a valid GOF"
        );
        // On noise-free expected counts, D should be very small (approaches
        // zero in the matched-model limit; allow some slack for numerical
        // error in the forward model).
        assert!(
            d_per_dof < 0.5,
            "noise-free expected-counts fit should give D/dof ≈ 0, got {d_per_dof}"
        );
        // Density recovery.
        let rel_bias = (result.densities[0] - true_density) / true_density;
        assert!(
            rel_bias.abs() < 0.05,
            "density bias {rel_bias} > 5%: fitted={} truth={true_density}",
            result.densities[0]
        );
        // Back-compat: reduced_chi_squared mirrors deviance_per_dof.
        assert!((result.reduced_chi_squared - d_per_dof).abs() < 1e-12);
    }

    /// Counts-KL dispatch rejects `fit_alpha_1` / `fit_alpha_2` — the
    /// profile `λ̂` absorbs the global flux scale (alpha_1 redundant);
    /// alpha_2 / B_det wiring is not yet implemented (deferred).
    #[test]
    fn test_joint_poisson_rejects_alpha_fit() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, _) = synthetic_transmission(&data, 0.0005, &energies);
        let open_beam_counts: Vec<f64> = vec![500.0; energies.len()];
        let sample_counts: Vec<f64> = t.iter().map(|&ti| 500.0 * ti).collect();

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_counts_background(CountsBackgroundConfig {
            fit_alpha_1: true,
            c: 1.0,
            ..Default::default()
        });

        let input = InputData::Counts {
            sample_counts,
            open_beam_counts,
        };
        let err = fit_spectrum_typed(&input, &config).unwrap_err();
        let msg = err.to_string();
        assert!(
            msg.contains("fit_alpha_1") || msg.contains("alpha_1"),
            "expected alpha_1 rejection message, got: {msg}"
        );
    }

    /// A normalized transmission is not a Poisson count. The supplied
    /// uncertainty must not be silently ignored by a Poisson objective.
    #[test]
    fn test_transmission_poisson_kl_rejects_fractional_data() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, u) = synthetic_transmission(&data, 0.0005, &energies);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()));

        let input = InputData::Transmission {
            transmission: t,
            uncertainty: u,
        };
        let error = fit_spectrum_typed(&input, &config)
            .expect_err("transmission plus Poisson/KL must be rejected");
        assert!(error.to_string().contains("Poisson"));
    }

    /// Resolved counts require the source weights and measured time-bin edges.
    /// Omitting either must fail before model construction instead of falling
    /// back to the invalid post-hoc shortcut R[T].
    #[test]
    fn counts_resolution_requires_exact_count_response() {
        use nereids_physics::resolution::{
            ResolutionFunction, ResolutionParams, TabulatedResolution,
        };

        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..101).map(|i| 1.0 + (i as f64) * 0.1).collect();
        let (sample_counts, open_beam_counts) = synthetic_counts(&data, 0.0005, &energies, 1000.0);
        let tab_text = "header\n---\n\
             5.0 0.0\n\
             -0.01 0.0\n\
             0.0 1.0\n\
             0.01 0.0\n\
             \n\
             20.0 0.0\n\
             -0.02 0.0\n\
             0.0 1.0\n\
             0.02 0.0\n";
        let resolutions = [
            (
                "gaussian",
                ResolutionFunction::Gaussian(ResolutionParams::new(25.0, 0.5, 0.005, 0.0).unwrap()),
            ),
            (
                "tabulated",
                ResolutionFunction::Tabulated(Arc::new(
                    TabulatedResolution::from_text(tab_text, 25.0).unwrap(),
                )),
            ),
        ];
        let solvers = [
            ("auto", SolverConfig::Auto),
            ("kl", SolverConfig::PoissonKL(PoissonConfig::default())),
            ("lm", SolverConfig::LevenbergMarquardt(LmConfig::default())),
        ];

        for (resolution_name, resolution) in resolutions {
            for (solver_name, solver) in &solvers {
                let config = UnifiedFitConfig::new(
                    energies.clone(),
                    vec![data.clone()],
                    vec!["U-238".into()],
                    293.6,
                    Some(resolution.clone()),
                    vec![0.001],
                )
                .unwrap()
                .with_solver(solver.clone());
                let inputs = [
                    (
                        "counts",
                        InputData::Counts {
                            sample_counts: sample_counts.clone(),
                            open_beam_counts: open_beam_counts.clone(),
                        },
                    ),
                    (
                        "counts-with-nuisance",
                        InputData::CountsWithNuisance {
                            sample_counts: sample_counts.clone(),
                            flux: open_beam_counts.clone(),
                            background: vec![0.0; energies.len()],
                        },
                    ),
                ];

                for (input_name, input) in inputs {
                    let err = match fit_spectrum_typed(&input, &config) {
                        Ok(_) => panic!(
                            "{input_name} + {solver_name} + {resolution_name} resolution \
                             returned a scientifically invalid fit"
                        ),
                        Err(err) => err,
                    };
                    let msg = err.to_string();
                    assert!(
                        msg.contains("counts")
                            && msg.contains("instrument resolution")
                            && msg.contains("separate-arm model"),
                        "{input_name} + {solver_name} + {resolution_name}: expected \
                         physical counts-response rejection, got: {msg}"
                    );
                }
            }
        }
    }

    /// Shared closed loop for the resolved-count path: recover a known
    /// density from counts generated by the separate-arm detector equation.
    /// The true-energy quadrature and detector-time bin counts deliberately
    /// differ so a future ratio-on-one-grid shortcut cannot satisfy it.
    /// `timing_offset_us` is threaded through BOTH offset uses — the response
    /// kernel placement and the detector pseudo-energy for the fixed SAMMY
    /// background — so the two sign conventions are pinned together.
    fn run_exact_closed_loop(timing_offset_us: f64) {
        use nereids_physics::counts_response::two_arm_count_response;
        use nereids_physics::resolution::{ResolutionFunction, TabulatedResolution};

        let data = u238_single_resonance();
        let true_density = 5.0e-4;
        let energies: Vec<f64> = (0..80).map(|i| 5.0 + i as f64 * 3.0 / 79.0).collect();
        let (true_transmission, _) = synthetic_transmission(&data, true_density, &energies);
        let response = ResolutionFunction::Tabulated(Arc::new(
            TabulatedResolution::from_kernels(
                vec![6.5],
                vec![(vec![-3.0, 0.0, 3.0], vec![0.0, 1.0, 0.0])],
                25.0,
            )
            .expect("valid detector-time response"),
        ));
        let source: Vec<f64> = energies
            .iter()
            .enumerate()
            .map(|(index, _)| 4.0e4 * (1.0 + 0.4 * index as f64 / 79.0))
            .collect();
        // Shift the acquisition window with the offset so the delayed pulses
        // land in the same bins relative to the window.
        let detector_edges: Vec<f64> = (0..102)
            .map(|i| 630.0 + timing_offset_us + i as f64 * 2.5)
            .collect();
        let expected = two_arm_count_response(
            &energies,
            &source,
            &true_transmission,
            &detector_edges,
            timing_offset_us,
            &response,
        )
        .expect("valid synthetic count response");
        let fixed_anorm = 0.98;
        let fixed_back_a = 0.01;
        let fixed_back_b = 0.002;
        let sample_counts: Vec<f64> = expected
            .open_beam
            .iter()
            .zip(&expected.sample)
            .zip(detector_edges.windows(2))
            .map(|((&open, &sample), edges)| {
                if open == 0.0 {
                    0.0
                } else {
                    // Deliberately the SAME pseudo-energy convention the route
                    // implements (bin center in TIME, fixed offset subtracted,
                    // then TOF->energy) — the pinned contract for where SAMMY's
                    // apparent-transmission background is evaluated (Norm() in
                    // sammy/src/cro/mnrm1.f90 applies it per measured point).
                    // This closed loop pins fixture/implementation coherence of
                    // that convention; the implementation-independent numeric
                    // anchor for the response itself is the hand-computed test
                    // below. Do not "simplify" one side without the other.
                    let measured_energy =
                        tof_to_energy(0.5 * (edges[0] + edges[1]) - timing_offset_us, 25.0);
                    open * (fixed_anorm * sample / open
                        + fixed_back_a
                        + fixed_back_b / measured_energy.sqrt())
                }
            })
            .collect();

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            Some(response),
            vec![2.0e-4],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig {
            max_iter: 400,
            ..Default::default()
        }))
        .with_exact_count_response(ExactCountResponseConfig {
            incident_fluence_weights: source,
            detector_time_edges_us: detector_edges,
            timing_offset_us,
        })
        .with_transmission_background(BackgroundConfig {
            anorm_init: fixed_anorm,
            back_a_init: fixed_back_a,
            back_b_init: fixed_back_b,
            back_c_init: 0.0,
            // Both exponential-tail fit flags are false, which BackgroundConfig
            // documents as DISABLING the BackD/BackF term entirely — these two
            // seeds are inert here (the fixture correctly carries no tail).
            back_d_init: 0.01,
            back_f_init: 1.0,
            fit_anorm: false,
            fit_back_a: false,
            fit_back_b: false,
            fit_back_c: false,
            fit_back_d: false,
            fit_back_f: false,
        });
        let result = fit_spectrum_typed(
            &InputData::Counts {
                sample_counts,
                open_beam_counts: expected.open_beam,
            },
            &config,
        )
        .expect("exact resolved count fit");

        assert!(result.converged, "fit did not converge");
        assert!(
            (result.densities[0] - true_density).abs() < 2.0e-6,
            "recovered density {} differs from truth {true_density}",
            result.densities[0]
        );
        assert!(result.deviance_per_dof.unwrap_or(f64::INFINITY) < 1.0e-8);
    }

    #[test]
    fn exact_resolved_counts_closed_loop_recovers_density() {
        run_exact_closed_loop(0.0);
    }

    /// Nonzero fixed clock offset: pins the sign convention of the detector
    /// pseudo-energy mapping (`center − timing_offset_us`) together with the
    /// response-kernel placement — a wrong sign on either breaks recovery.
    #[test]
    fn exact_resolved_counts_closed_loop_with_timing_offset() {
        run_exact_closed_loop(5.0);
    }

    /// FREE normalization through the exact composition: Anorm and BackA are
    /// fitted (seeded off truth) on the detector-pseudo-energy side of the
    /// separate-arm ratio, exercising the NormalizedTransmissionModel
    /// analytical-Jacobian columns through the new stacking order rather
    /// than only frozen values.
    #[test]
    fn exact_resolved_counts_recovers_free_normalization() {
        use nereids_physics::counts_response::two_arm_count_response;
        use nereids_physics::resolution::{ResolutionFunction, TabulatedResolution};

        let data = u238_single_resonance();
        let true_density = 5.0e-4;
        let true_anorm = 0.97;
        let true_back_a = 0.015;
        let energies: Vec<f64> = (0..80).map(|i| 5.0 + i as f64 * 3.0 / 79.0).collect();
        let (true_transmission, _) = synthetic_transmission(&data, true_density, &energies);
        let response = ResolutionFunction::Tabulated(Arc::new(
            TabulatedResolution::from_kernels(
                vec![6.5],
                vec![(vec![-3.0, 0.0, 3.0], vec![0.0, 1.0, 0.0])],
                25.0,
            )
            .expect("valid detector-time response"),
        ));
        let source: Vec<f64> = energies
            .iter()
            .enumerate()
            .map(|(index, _)| 4.0e4 * (1.0 + 0.4 * index as f64 / 79.0))
            .collect();
        let detector_edges: Vec<f64> = (0..102).map(|i| 630.0 + i as f64 * 2.5).collect();
        let expected = two_arm_count_response(
            &energies,
            &source,
            &true_transmission,
            &detector_edges,
            0.0,
            &response,
        )
        .expect("valid synthetic count response");
        let sample_counts: Vec<f64> = expected
            .open_beam
            .iter()
            .zip(&expected.sample)
            .map(|(&open, &sample)| {
                if open == 0.0 {
                    0.0
                } else {
                    open * (true_anorm * sample / open + true_back_a)
                }
            })
            .collect();

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            Some(response),
            vec![2.0e-4],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig {
            max_iter: 600,
            ..Default::default()
        }))
        .with_exact_count_response(ExactCountResponseConfig {
            incident_fluence_weights: source,
            detector_time_edges_us: detector_edges,
            timing_offset_us: 0.0,
        })
        .with_transmission_background(BackgroundConfig {
            anorm_init: 1.0,  // seeded off truth
            back_a_init: 0.0, // seeded off truth
            back_b_init: 0.0,
            back_c_init: 0.0,
            back_d_init: 0.01,
            back_f_init: 1.0,
            fit_anorm: true,
            fit_back_a: true,
            fit_back_b: false,
            fit_back_c: false,
            fit_back_d: false,
            fit_back_f: false,
        });
        let result = fit_spectrum_typed(
            &InputData::Counts {
                sample_counts,
                open_beam_counts: expected.open_beam,
            },
            &config,
        )
        .expect("exact fit with free normalization");

        assert!(result.converged, "fit did not converge");
        assert!(
            (result.densities[0] - true_density).abs() / true_density < 1.0e-3,
            "density: fitted={}, true={true_density}",
            result.densities[0]
        );
        assert!(
            (result.anorm - true_anorm).abs() < 1.0e-3,
            "anorm: fitted={}, true={true_anorm}",
            result.anorm
        );
        assert!(
            (result.background[0] - true_back_a).abs() < 1.0e-3,
            "back_a: fitted={}, true={true_back_a}",
            result.background[0]
        );
        assert!(result.deviance_per_dof.unwrap_or(f64::INFINITY) < 1.0e-6);
    }

    /// FREE multiplicative baseline through the exact composition: a
    /// log-linear tilt `b1` is applied to the TRUE-ENERGY sample arm before
    /// detector response (a constant `b0` would be exactly degenerate with
    /// Anorm through the linear response, so the tilt is the identifiable
    /// probe of the inside-the-response placement) and must be recovered by
    /// the fit.
    #[test]
    fn exact_resolved_counts_recovers_free_baseline_tilt() {
        use nereids_physics::counts_response::two_arm_count_response;
        use nereids_physics::resolution::{ResolutionFunction, TabulatedResolution};

        let data = u238_single_resonance();
        let true_density = 5.0e-4;
        let true_b1 = 0.02;
        let energies: Vec<f64> = (0..80).map(|i| 5.0 + i as f64 * 3.0 / 79.0).collect();
        let (true_transmission, _) = synthetic_transmission(&data, true_density, &energies);
        // Baseline reference energy: the fit uses
        // baseline_reference_energy_active(energies, None); mirror it by
        // computing the same mid-grid reference the production helper uses.
        let e_ref =
            nereids_fitting::transmission_model::baseline_reference_energy_active(&energies, None);
        let baselined: Vec<f64> = energies
            .iter()
            .zip(&true_transmission)
            .map(|(&e, &t)| (1.0 + true_b1 * (e / e_ref).ln()) * t)
            .collect();
        let response = ResolutionFunction::Tabulated(Arc::new(
            TabulatedResolution::from_kernels(
                vec![6.5],
                vec![(vec![-3.0, 0.0, 3.0], vec![0.0, 1.0, 0.0])],
                25.0,
            )
            .expect("valid detector-time response"),
        ));
        let source: Vec<f64> = energies
            .iter()
            .enumerate()
            .map(|(index, _)| 4.0e4 * (1.0 + 0.4 * index as f64 / 79.0))
            .collect();
        let detector_edges: Vec<f64> = (0..102).map(|i| 630.0 + i as f64 * 2.5).collect();
        let expected = two_arm_count_response(
            &energies,
            &source,
            &baselined,
            &detector_edges,
            0.0,
            &response,
        )
        .expect("valid synthetic count response");

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            Some(response),
            vec![2.0e-4],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig {
            max_iter: 600,
            ..Default::default()
        }))
        .with_exact_count_response(ExactCountResponseConfig {
            incident_fluence_weights: source,
            detector_time_edges_us: detector_edges,
            timing_offset_us: 0.0,
        })
        .with_multiplicative_baseline(MultiplicativeBaselineConfig {
            b0_init: 1.0,
            b1_init: 0.0, // seeded off truth
            b2_init: 0.0,
            fit_b0: false,
            fit_b1: true,
            fit_b2: false,
            ..Default::default()
        });
        let result = fit_spectrum_typed(
            &InputData::Counts {
                sample_counts: expected.sample,
                open_beam_counts: expected.open_beam,
            },
            &config,
        )
        .expect("exact fit with free baseline tilt");

        assert!(result.converged, "fit did not converge");
        assert!(
            (result.densities[0] - true_density).abs() / true_density < 1.0e-3,
            "density: fitted={}, true={true_density}",
            result.densities[0]
        );
        let baseline = result.baseline.expect("baseline coefficients reported");
        assert!(
            (baseline[1] - true_b1).abs() < 1.0e-3,
            "b1: fitted={}, true={true_b1}",
            baseline[1]
        );
        assert!(result.deviance_per_dof.unwrap_or(f64::INFINITY) < 1.0e-6);
    }

    /// Every rejection arm of the exact-route validation surface, exercised.
    /// The occupied-dead-bin pre-check is the load-bearing one: it is the
    /// invariant ExactTwoArmRatioModel's rustdoc requires callers to enforce
    /// (observed counts in a bin outside the response support must be a hard
    /// error, never a silent comparison against the dead-bin T=1 filler).
    #[test]
    fn exact_route_validation_arms_reject_each_misuse() {
        use nereids_physics::resolution::{ResolutionFunction, TOF_FACTOR, TabulatedResolution};

        let make_response = || {
            ResolutionFunction::Tabulated(Arc::new(
                TabulatedResolution::from_kernels(
                    vec![25.0],
                    vec![(vec![-1.0, 0.0, 1.0], vec![0.0, 1.0, 0.0])],
                    25.0,
                )
                .expect("valid triangle response"),
            ))
        };
        let arrival = TOF_FACTOR * 25.0 / 25.0_f64.sqrt();
        let data = u238_single_resonance();
        let base_config = |resolution: Option<ResolutionFunction>| {
            UnifiedFitConfig::new(
                vec![25.0],
                vec![data.clone()],
                vec!["U-238".into()],
                0.0,
                resolution,
                vec![1.0e-4],
            )
            .unwrap()
            .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        };
        let exact = |edges: Vec<f64>| ExactCountResponseConfig {
            incident_fluence_weights: vec![100.0],
            detector_time_edges_us: edges,
            timing_offset_us: 0.0,
        };
        let two_bin_edges = vec![arrival - 1.0, arrival, arrival + 1.0];
        let counts_2 = InputData::Counts {
            sample_counts: vec![10.0, 10.0],
            open_beam_counts: vec![50.0, 50.0],
        };

        // (a) Occupied dead bin: window entirely outside the response
        // support, but the observed arrays carry counts.
        let err = fit_spectrum_typed(
            &counts_2,
            &base_config(Some(make_response())).with_exact_count_response(exact(vec![
                arrival + 10.0,
                arrival + 11.0,
                arrival + 12.0,
            ])),
        )
        .expect_err("occupied dead bin must be a hard error");
        assert!(
            err.to_string()
                .contains("zero detector response in occupied detector bin"),
            "{err}"
        );

        // (a2) The SAME dead bin, with a background declared: no longer an
        // error, because pure-background counts in a bin with no neutron
        // response are exactly what a declared background predicts. It must
        // still not be fitted — a free flux there would let background
        // fluctuations be read as neutrons — so it is dropped from the
        // active set, and with only two bins that leaves too few to fit.
        let err = fit_spectrum_typed(
            &InputData::CountsWithNuisance {
                sample_counts: vec![10.0, 10.0],
                flux: vec![50.0, 50.0],
                background: vec![5.0, 5.0],
            },
            &base_config(Some(make_response())).with_exact_count_response(exact(vec![
                arrival + 10.0,
                arrival + 11.0,
                arrival + 12.0,
            ])),
        )
        .expect_err("dropping every bin must be reported, not fitted");
        let message = err.to_string();
        assert!(
            message.contains("hold only background and cannot be fitted"),
            "a declared background must reclassify the dead bin rather than \
             rejecting the source: {message}"
        );
        assert!(
            !message.contains("zero detector response in occupied detector bin"),
            "the no-background rejection must not fire once a background is \
             declared: {message}"
        );

        // (a3) A background elsewhere in the spectrum explains nothing about
        // THIS bin. With background on one bin and none on the dead one, the
        // hard error must still fire — otherwise a single backgrounded bin
        // anywhere would silence the check for every bin.
        let err = fit_spectrum_typed(
            &InputData::CountsWithNuisance {
                sample_counts: vec![10.0, 10.0],
                flux: vec![50.0, 50.0],
                background: vec![0.0, 5.0],
            },
            &base_config(Some(make_response())).with_exact_count_response(exact(vec![
                arrival + 10.0,
                arrival + 11.0,
                arrival + 12.0,
            ])),
        )
        .expect_err("a dead bin with no background of its own is still unexplained");
        assert!(
            err.to_string()
                .contains("zero detector response in occupied detector bin 0"),
            "the bin without a local background must be the one reported: {err}"
        );

        // (b) Exact config attached to normalized transmission input.
        let err = fit_spectrum_typed(
            &InputData::Transmission {
                transmission: vec![0.9],
                uncertainty: vec![0.01],
            },
            &base_config(Some(make_response()))
                .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()))
                .with_exact_count_response(exact(two_bin_edges.clone())),
        )
        .expect_err("exact config on transmission must be rejected");
        assert!(
            err.to_string()
                .contains("cannot be attached to normalized transmission"),
            "{err}"
        );

        // (c) Exact config without any resolution model.
        let err = fit_spectrum_typed(
            &counts_2,
            &base_config(None).with_exact_count_response(exact(two_bin_edges.clone())),
        )
        .expect_err("exact config without resolution must be rejected");
        assert!(
            err.to_string()
                .contains("requires an instrument resolution model"),
            "{err}"
        );

        // (d) Fluence length != true-energy grid length.
        let err = fit_spectrum_typed(
            &counts_2,
            &base_config(Some(make_response())).with_exact_count_response(
                ExactCountResponseConfig {
                    incident_fluence_weights: vec![100.0, 100.0],
                    detector_time_edges_us: two_bin_edges.clone(),
                    timing_offset_us: 0.0,
                },
            ),
        )
        .expect_err("fluence length mismatch must be rejected");
        assert!(
            err.to_string().contains("incident_fluence_weights length"),
            "{err}"
        );

        // (e) Edge count != observed bins + 1.
        let err = fit_spectrum_typed(
            &counts_2,
            &base_config(Some(make_response()))
                .with_exact_count_response(exact(vec![arrival - 1.0, arrival])),
        )
        .expect_err("edge/bin length mismatch must be rejected");
        assert!(
            err.to_string().contains("detector_time_edges_us length"),
            "{err}"
        );

        // (f) Non-finite timing offset.
        let err = fit_spectrum_typed(
            &counts_2,
            &base_config(Some(make_response())).with_exact_count_response(
                ExactCountResponseConfig {
                    incident_fluence_weights: vec![100.0],
                    detector_time_edges_us: two_bin_edges.clone(),
                    timing_offset_us: f64::NAN,
                },
            ),
        )
        .expect_err("NaN timing offset must be rejected");
        assert!(
            err.to_string().contains("timing_offset_us must be finite"),
            "{err}"
        );

        // (g) Energy-scale fitting through the exact response.
        let err = fit_spectrum_typed(
            &counts_2,
            &base_config(Some(make_response()))
                .with_exact_count_response(exact(two_bin_edges.clone()))
                .with_energy_scale(0.0, 1.0, 25.0),
        )
        .expect_err("energy-scale through the exact response must be rejected");
        assert!(
            err.to_string()
                .contains("not yet connected to the exact two-arm"),
            "{err}"
        );

        // (h) fit_energy_range through the exact response.
        let err = fit_spectrum_typed(
            &counts_2,
            &base_config(Some(make_response()))
                .with_exact_count_response(exact(two_bin_edges.clone()))
                .with_fit_energy_range(Some((10.0, 30.0)))
                .unwrap(),
        )
        .expect_err("fit_energy_range through the exact response must be rejected");
        assert!(
            err.to_string()
                .contains("fit_energy_range is not yet supported"),
            "{err}"
        );

        // (i) Spatial mapping with an exact config: single-spectrum only.
        let sample = ndarray::Array3::from_elem((1, 2, 2), 10.0);
        let open_beam = ndarray::Array3::from_elem((1, 2, 2), 50.0);
        let err = crate::spatial::spatial_map_typed(
            &crate::spatial::InputData3D::Counts {
                sample_counts: sample.view(),
                open_beam_counts: open_beam.view(),
            },
            &base_config(Some(make_response())).with_exact_count_response(exact(two_bin_edges)),
            None,
            None,
            None,
        )
        .expect_err("spatial exact-count mapping must be rejected");
        assert!(
            err.to_string()
                .contains("single-spectrum count fitter only"),
            "{err}"
        );
    }

    /// Implementation-independent numeric anchor for the exact fit route,
    /// parameterized by the fixed clock offset.
    ///
    /// Every expected count is HAND-COMPUTED from the unit-triangle kernel
    /// (each pulse splits 0.5/0.5 across two adjacent 1 µs bins), not
    /// synthesized with `two_arm_count_response` — so a shared defect in
    /// `detector_bin_probabilities` cannot cancel between oracle and fit.
    /// The fixed SAMMY background uses `BackB/√E`, with the pseudo-energies
    /// written from the closed-form `E = (TOF_FACTOR·L/t)²` at
    /// `t = center − offset`, so BOTH uses of the offset (kernel placement
    /// and background pseudo-energy) are anchored without calling either
    /// production helper. Note the corrected times are offset-independent by
    /// construction: a sign flip in either use breaks recovery at offset ≠ 0.
    /// The inner physics is a precomputed cross-section stack chosen so the
    /// true transmission is exactly [0.2, 0.8] at the true density.
    fn run_hand_computed_anchor(timing_offset_us: f64) {
        use nereids_physics::resolution::{ResolutionFunction, TOF_FACTOR, TabulatedResolution};

        let flight_path_m = 25.0_f64;
        let arrival_0 = TOF_FACTOR * flight_path_m / 25.0_f64.sqrt();
        let energy_1 = (TOF_FACTOR * flight_path_m / (arrival_0 + 1.0)).powi(2);
        let energies = vec![25.0, energy_1];
        let response = ResolutionFunction::Tabulated(Arc::new(
            TabulatedResolution::from_kernels(
                vec![25.0],
                vec![(vec![-1.0, 0.0, 1.0], vec![0.0, 1.0, 0.0])],
                flight_path_m,
            )
            .expect("valid triangle response"),
        ));
        // Pulses sit at `offset + TOF(E)`, so the window shifts with the
        // offset and the hand-derived triangle bin probabilities on edges
        // [a-1, a, a+1, a+2] are unchanged:
        //   E0 -> [0.5, 0.5, 0], E1 -> [0, 0.5, 0.5].
        // With fluence F = [100, 200] and T = [0.2, 0.8]:
        //   open   = [50, 150, 100]   and   T_eff = [0.2, 0.6, 0.8].
        let base = timing_offset_us + arrival_0;
        let detector_edges = vec![base - 1.0, base, base + 1.0, base + 2.0];
        let open_beam_counts = vec![50.0, 150.0, 100.0];
        let t_eff = [0.2_f64, 0.6, 0.8];

        // Fixed SAMMY background on the measured bins: BackB/√E at the
        // hand-written pseudo-energy of each bin center, offset removed.
        let fixed_anorm = 1.0_f64;
        let fixed_back_b = 0.05_f64;
        let sample_counts: Vec<f64> = detector_edges
            .windows(2)
            .zip(t_eff)
            .zip(&open_beam_counts)
            .map(|((edges, t), &open)| {
                let corrected_tof_us = 0.5 * (edges[0] + edges[1]) - timing_offset_us;
                let pseudo_energy = (TOF_FACTOR * flight_path_m / corrected_tof_us).powi(2);
                open * (fixed_anorm * t + fixed_back_b / pseudo_energy.sqrt())
            })
            .collect();

        // Cross sections chosen so exp(-d_true * sigma_j) = [0.2, 0.8].
        let true_density = 1.0e-3;
        let data = u238_single_resonance();
        let xs: Vec<Vec<f64>> = vec![vec![
            -(0.2_f64.ln()) / true_density,
            -(0.8_f64.ln()) / true_density,
        ]];

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            Some(response),
            vec![5.0e-4], // seeded off truth so a no-op fit fails
        )
        .unwrap();
        let xs = table_on_data_grid(&config, xs);
        let config = config
            .with_precomputed_cross_sections(xs)
            .with_solver(SolverConfig::PoissonKL(PoissonConfig {
                max_iter: 200,
                ..Default::default()
            }))
            .with_exact_count_response(ExactCountResponseConfig {
                incident_fluence_weights: vec![100.0, 200.0],
                detector_time_edges_us: detector_edges,
                timing_offset_us,
            })
            .with_transmission_background(BackgroundConfig {
                anorm_init: fixed_anorm,
                back_a_init: 0.0,
                back_b_init: fixed_back_b,
                back_c_init: 0.0,
                back_d_init: 0.0,
                back_f_init: 1.0,
                fit_anorm: false,
                fit_back_a: false,
                fit_back_b: false,
                fit_back_c: false,
                fit_back_d: false,
                fit_back_f: false,
            });
        let result = fit_spectrum_typed(
            &InputData::Counts {
                sample_counts,
                open_beam_counts,
            },
            &config,
        )
        .expect("hand-anchored exact fit");

        assert!(result.converged, "fit did not converge");
        assert!(
            (result.densities[0] - true_density).abs() / true_density < 1.0e-6,
            "recovered density {} differs from hand-derived truth {true_density}",
            result.densities[0]
        );
        assert!(result.deviance_per_dof.unwrap_or(f64::INFINITY) < 1.0e-10);
    }

    #[test]
    fn exact_route_matches_hand_computed_detector_counts() {
        run_hand_computed_anchor(0.0);
    }

    /// Empty pre-trigger bins must not block a background fit.
    ///
    /// A real acquisition's time axis can start at the frame trigger, before
    /// the calibrated `timing_offset_us`, so leading bins have no physical
    /// pseudo-energy. They are also unoccupied and dead in response, hence
    /// contribute identically zero deviance — rejecting the whole fit for
    /// them would refuse a mainstream acquisition that fits fine WITHOUT
    /// background (the asymmetry a reviewer reproduced). An OCCUPIED bin
    /// with no physical energy still fails closed.
    #[test]
    fn exact_route_tolerates_empty_pre_trigger_bins_with_background() {
        use nereids_physics::counts_response::two_arm_count_response;
        use nereids_physics::resolution::{ResolutionFunction, TabulatedResolution};

        let timing_offset_us = 5.0_f64;
        let data = u238_single_resonance();
        let true_density = 5.0e-4;
        let energies: Vec<f64> = (0..60).map(|i| 5.0 + i as f64 * 3.0 / 59.0).collect();
        let (true_transmission, _) = synthetic_transmission(&data, true_density, &energies);
        let response = ResolutionFunction::Tabulated(Arc::new(
            TabulatedResolution::from_kernels(
                vec![6.5],
                vec![(vec![-3.0, 0.0, 3.0], vec![0.0, 1.0, 0.0])],
                25.0,
            )
            .expect("valid detector-time response"),
        ));
        let source: Vec<f64> = vec![4.0e4; energies.len()];
        // Window starts at t = 0 (frame trigger): the first two bin centers
        // (1.25 µs, 3.75 µs) precede the 5 µs offset.
        let detector_edges: Vec<f64> = (0..340).map(|i| i as f64 * 2.5).collect();
        let expected = two_arm_count_response(
            &energies,
            &source,
            &true_transmission,
            &detector_edges,
            timing_offset_us,
            &response,
        )
        .expect("valid synthetic count response");
        assert!(
            expected.open_beam[0] == 0.0 && expected.sample[0] == 0.0,
            "fixture must have an empty pre-trigger bin 0"
        );

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            Some(response),
            vec![2.0e-4],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig {
            max_iter: 400,
            ..Default::default()
        }))
        .with_exact_count_response(ExactCountResponseConfig {
            incident_fluence_weights: source,
            detector_time_edges_us: detector_edges,
            timing_offset_us,
        })
        // Background ON: this is the combination that used to be rejected.
        .with_transmission_background(BackgroundConfig {
            anorm_init: 1.0,
            back_a_init: 0.0,
            back_b_init: 0.0,
            back_c_init: 0.0,
            back_d_init: 0.0,
            back_f_init: 1.0,
            fit_anorm: false,
            fit_back_a: true,
            fit_back_b: false,
            fit_back_c: false,
            fit_back_d: false,
            fit_back_f: false,
        });
        let result = fit_spectrum_typed(
            &InputData::Counts {
                sample_counts: expected.sample,
                open_beam_counts: expected.open_beam,
            },
            &config,
        )
        .expect("empty pre-trigger bins must not reject a background fit");

        assert!(result.converged, "fit did not converge");
        assert!(
            (result.densities[0] - true_density).abs() / true_density < 1.0e-3,
            "density: fitted={}, true={true_density}",
            result.densities[0]
        );
    }

    /// The exact route accepts an analytical Ikeda–Carpenter response as
    /// well as a tabulated kernel, but every other exact-route test uses a
    /// tabulated triangle — this closes the IC branch end to end, through
    /// `DetectorBinResponseMatrix::new` -> `IkedaCarpenter::
    /// detector_bin_probabilities` (its per-bin tau-step accuracy gate
    /// included) and back out of the fit.
    ///
    /// Note the causal IC pulse rises FROM the nominal arrival onward, so
    /// the acquisition window is placed after it — unlike the mode-centred
    /// tabulated kernel, whose offset convention is not transferable.
    #[test]
    fn exact_resolved_counts_closed_loop_with_ikeda_carpenter() {
        use nereids_physics::counts_response::two_arm_count_response;
        use nereids_physics::ikeda_carpenter::{
            IkedaCarpenter, IkedaCarpenterParams, SynthesisGrid,
        };
        use nereids_physics::resolution::{ResolutionFunction, TOF_FACTOR};

        let flight_path_m = 25.0_f64;
        let data = u238_single_resonance();
        let true_density = 5.0e-4;
        let energies: Vec<f64> = (0..60).map(|i| 5.0 + i as f64 * 3.0 / 59.0).collect();
        let (true_transmission, _) = synthetic_transmission(&data, true_density, &energies);
        let response = ResolutionFunction::IkedaCarpenter(Arc::new(
            IkedaCarpenter::new(
                IkedaCarpenterParams::constant(2.0, 0.1, 0.0),
                flight_path_m,
                &SynthesisGrid::new(4.0, 9.0),
            )
            .expect("valid prompt-only IC model"),
        ));
        let source: Vec<f64> = vec![4.0e4; energies.len()];
        // Causal pulse: start the window at the earliest nominal arrival
        // (highest energy) and run past the latest one.
        let first_arrival = TOF_FACTOR * flight_path_m / 8.0_f64.sqrt();
        let detector_edges: Vec<f64> = (0..160).map(|i| first_arrival + i as f64 * 2.0).collect();
        let expected = two_arm_count_response(
            &energies,
            &source,
            &true_transmission,
            &detector_edges,
            0.0,
            &response,
        )
        .expect("valid IC synthetic count response");
        assert!(
            expected.open_beam.iter().any(|&v| v > 0.0),
            "IC fixture must deposit counts in the window"
        );

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            Some(response),
            vec![2.0e-4],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig {
            max_iter: 400,
            ..Default::default()
        }))
        .with_exact_count_response(ExactCountResponseConfig {
            incident_fluence_weights: source,
            detector_time_edges_us: detector_edges,
            timing_offset_us: 0.0,
        });
        let result = fit_spectrum_typed(
            &InputData::Counts {
                sample_counts: expected.sample,
                open_beam_counts: expected.open_beam,
            },
            &config,
        )
        .expect("exact resolved count fit with an IC response");

        assert!(result.converged, "IC exact fit did not converge");
        assert!(
            (result.densities[0] - true_density).abs() / true_density < 1.0e-3,
            "density: fitted={}, true={true_density}",
            result.densities[0]
        );
    }

    /// The pre-trigger tolerance above must NOT weaken the occupied case:
    /// counts in a bin with no physical energy remain a hard error.
    ///
    /// The fixture must reach the BACKGROUND pseudo-energy guard, not the
    /// earlier occupied-dead-bin pre-check, so bin 0 needs observed counts
    /// AND nonzero detector response while still preceding the offset. A
    /// mode-centred kernel whose negative half-width (20 µs) exceeds the
    /// true-energy flight time (~10 µs at 32.7 keV over 25 m) deposits
    /// probability before the trigger; the assertion therefore pins the
    /// pre-trigger message alone.
    #[test]
    fn exact_route_rejects_occupied_pre_trigger_bin_with_background() {
        use nereids_physics::counts_response::DetectorBinResponseMatrix;
        use nereids_physics::resolution::{ResolutionFunction, TOF_FACTOR, TabulatedResolution};

        let flight_path_m = 25.0_f64;
        let true_energy = 32_670.0_f64;
        let tof_us = TOF_FACTOR * flight_path_m / true_energy.sqrt();
        let timing_offset_us = 30.0_f64;
        let arrival = timing_offset_us + tof_us; // ≈ 40 µs
        assert!(
            tof_us < 20.0,
            "fixture needs a flight time inside the kernel half-width, got {tof_us}"
        );
        let response = ResolutionFunction::Tabulated(Arc::new(
            TabulatedResolution::from_kernels(
                vec![true_energy],
                vec![(vec![-20.0, 0.0, 20.0], vec![0.0, 1.0, 0.0])],
                flight_path_m,
            )
            .expect("valid wide triangle response"),
        ));
        // Bin 0 = [arrival-22, arrival-14]: inside the kernel's negative
        // tail (nonzero response) and entirely before the trigger offset.
        let detector_edges = vec![
            arrival - 22.0,
            arrival - 14.0,
            arrival - 6.0,
            arrival + 2.0,
            arrival + 10.0,
        ];
        // Guard the guard: prove bin 0 really has response, so this test
        // cannot silently degrade into the dead-bin pre-check again.
        let matrix = DetectorBinResponseMatrix::new(
            &[true_energy],
            &detector_edges,
            timing_offset_us,
            &response,
        )
        .expect("valid response matrix");
        assert!(
            matrix.probability(0, 0) > 0.0,
            "fixture bin 0 must have nonzero detector response"
        );
        assert!(
            0.5 * (detector_edges[0] + detector_edges[1]) < timing_offset_us,
            "fixture bin 0 must precede the timing offset"
        );

        let config = UnifiedFitConfig::new(
            vec![true_energy],
            vec![u238_single_resonance()],
            vec!["U-238".into()],
            0.0,
            Some(response),
            vec![1.0e-4],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_exact_count_response(ExactCountResponseConfig {
            incident_fluence_weights: vec![100.0],
            detector_time_edges_us: detector_edges,
            timing_offset_us,
        })
        .with_transmission_background(BackgroundConfig {
            fit_anorm: false,
            fit_back_a: true,
            ..BackgroundConfig::default()
        });
        let err = fit_spectrum_typed(
            &InputData::Counts {
                sample_counts: vec![5.0, 20.0, 20.0, 5.0],
                open_beam_counts: vec![10.0, 50.0, 50.0, 10.0],
            },
            &config,
        )
        .expect_err("occupied bin without a physical energy must fail closed");
        let msg = err.to_string();
        assert!(
            msg.contains("carries observed counts"),
            "expected the pre-trigger occupied-bin rejection, got: {msg}"
        );
    }

    /// Same hand-computed anchor at a nonzero clock offset: the only
    /// implementation-independent check of the offset conventions, covering
    /// kernel placement (`offset + TOF`) and background pseudo-energy
    /// (`center − offset`) simultaneously.
    #[test]
    fn exact_route_matches_hand_computed_counts_with_timing_offset() {
        run_hand_computed_anchor(7.5);
    }

    // ──────────────────────────────────────────────────────────────────
    // transmission_background through the joint-Poisson path.
    // ──────────────────────────────────────────────────────────────────

    /// End-to-end: joint-Poisson with A_n + B_A + B_B + B_C free on
    /// noise-free synthetic counts with known background.  On 201 bins
    /// with 5 free params the (n, A_n) correlation is non-trivial so we
    /// assert the *wiring* is correct (bg reaches the fit, D/dof → 0,
    /// A_n + B_A near truth, density within 10%) rather than benchmark-grade
    #[test]
    fn test_joint_poisson_with_transmission_background() {
        let data = u238_single_resonance();
        let true_density = 0.0005_f64;
        let true_anorm = 0.85_f64;
        let true_ba = 0.03_f64;
        let true_bb = -0.01_f64;
        let true_bc = 0.0_f64;
        let c = 5.98_f64;
        let lam_ob = 2000.0_f64;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t_inner, _) = synthetic_transmission(&data, true_density, &energies);
        let t_out: Vec<f64> = t_inner
            .iter()
            .zip(energies.iter())
            .map(|(&ti, &e)| true_anorm * ti + true_ba + true_bb / e.sqrt() + true_bc * e.sqrt())
            .collect();
        let open_beam_counts: Vec<f64> = vec![lam_ob; energies.len()];
        let sample_counts: Vec<f64> = t_out.iter().map(|&ti| c * lam_ob * ti).collect();

        let bg = BackgroundConfig {
            anorm_init: 1.0,
            back_a_init: 0.0,
            back_b_init: 0.0,
            back_c_init: 0.0,
            back_d_init: 0.01,
            back_f_init: 1.0,
            fit_anorm: true,
            fit_back_a: true,
            fit_back_b: true,
            fit_back_c: true,
            fit_back_d: false,
            fit_back_f: false,
        };

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_counts_background(CountsBackgroundConfig {
            c,
            ..Default::default()
        })
        .with_transmission_background(bg)
        // #486: polish defaults off for real-data regimes where its
        // `fatol = 1e-10` is sub-ULP.  This noise-free synthetic fit
        // is exactly the regime polish was designed for (D → 0
        // achievable, `fatol` physically meaningful) and the test
        // asserts `D/dof < 1.0` which Gauss-Newton alone cannot reach
        // on this 5-free-parameter fit due to the documented n ↔ A_n
        // correlation stall.  Opt in explicitly.
        .with_counts_enable_polish(Some(true));

        let input = InputData::Counts {
            sample_counts,
            open_beam_counts,
        };
        let r = fit_spectrum_typed(&input, &config).unwrap();

        // The invariant the background wiring is supposed to produce is: the 4 bg
        // parameters *actually reach the objective* (the fit produces a
        // near-zero deviance on noise-free expected counts) and the
        // fitter moves them off their initial values.  Density / A_n /
        // B_A recovery at unit-test scale (201 bins, 5 free params)
        // inherits the classic n ↔ A_n correlation — the realistic

        // Deviance-based GOF populated and → 0 on noise-free expected counts.
        // Requires polish (see `with_counts_enable_polish(Some(true))` above).
        let dpd = r.deviance_per_dof.expect("joint-Poisson must report D/dof");
        assert!(
            dpd < 1.0,
            "D/dof = {dpd} unexpectedly large on noise-free fit — bg params not reaching objective?"
        );
        // Density didn't rail to zero.
        assert!(r.densities[0] > 1e-5, "density railed: {}", r.densities[0]);
        // A_n moved off its initial 1.0 toward truth 0.85.
        assert!(
            (r.anorm - 1.0).abs() > 0.05,
            "A_n did not move from init 1.0 (fitted={})",
            r.anorm
        );
        // Background triplet moved off zero at least in one component.
        let bg_moved = r.background.iter().any(|v| v.abs() > 1e-4);
        assert!(
            bg_moved,
            "no bg parameter moved from init 0: {:?}",
            r.background
        );
    }

    /// Operational rule: `B_B` or `B_C` free → `B_A` must be free too.
    #[test]
    fn test_joint_poisson_requires_back_a_when_back_b_enabled() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, _) = synthetic_transmission(&data, 0.0005, &energies);
        let ob: Vec<f64> = vec![500.0; energies.len()];
        let s: Vec<f64> = t.iter().map(|&ti| 500.0 * ti).collect();

        let bg = BackgroundConfig {
            // B_B enabled without B_A → must be rejected.
            fit_anorm: true,
            fit_back_a: false,
            fit_back_b: true,
            fit_back_c: false,
            fit_back_d: false,
            fit_back_f: false,
            ..BackgroundConfig::default()
        };

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_counts_background(CountsBackgroundConfig {
            c: 1.0,
            ..Default::default()
        })
        .with_transmission_background(bg);

        let input = InputData::Counts {
            sample_counts: s,
            open_beam_counts: ob,
        };
        let err = fit_spectrum_typed(&input, &config).unwrap_err();
        let msg = err.to_string();
        assert!(
            msg.contains("B_A"),
            "expected B_A pairing-rule rejection message, got: {msg}"
        );
    }

    /// A detector background is now fitted through, and ignoring one biases
    /// density.
    ///
    /// Counts are built WITH a background in both arms. Fitting them while
    /// telling the solver the background is zero must recover a worse density
    /// than fitting them while declaring it — otherwise the background is not
    /// reaching the likelihood.
    #[test]
    fn test_joint_poisson_uses_the_detector_background() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let true_density = 0.001;
        let (t, _) = synthetic_transmission(&data, true_density, &energies);
        let b_det = 60.0_f64;
        // Expected counts with a background present in BOTH arms.
        let flux: Vec<f64> = vec![2000.0 + b_det; energies.len()];
        let s: Vec<f64> = t.iter().map(|&ti| 2000.0 * ti + b_det).collect();

        let fit = |background: Vec<f64>| {
            let config = UnifiedFitConfig::new(
                energies.clone(),
                vec![data.clone()],
                vec!["U-238".into()],
                0.0,
                None,
                vec![0.0005],
            )
            .unwrap()
            .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
            .with_counts_background(CountsBackgroundConfig {
                c: 1.0,
                ..Default::default()
            });
            let input = InputData::CountsWithNuisance {
                sample_counts: s.clone(),
                flux: flux.clone(),
                background,
            };
            let result = fit_spectrum_typed(&input, &config).expect("counts-KL fit runs");
            (result.densities[0] - true_density).abs() / true_density
        };

        let declared = fit(vec![b_det; energies.len()]);
        let ignored = fit(vec![0.0; energies.len()]);

        assert!(
            declared < 0.02,
            "declaring the background must recover density; bias {:.3} %",
            100.0 * declared
        );
        assert!(
            ignored > 4.0 * declared,
            "ignoring a background that IS in the counts gave bias {:.3} % against \
             {:.3} % when declared — the background is not reaching the likelihood",
            100.0 * ignored,
            100.0 * declared
        );
    }

    /// A malformed background is still refused.
    #[test]
    fn test_joint_poisson_rejects_malformed_detector_background() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, _) = synthetic_transmission(&data, 0.0005, &energies);
        let flux: Vec<f64> = vec![500.0; energies.len()];
        let s: Vec<f64> = t.iter().map(|&ti| 500.0 * ti).collect();

        for bad in [f64::NAN, f64::INFINITY, -1.0] {
            let config = UnifiedFitConfig::new(
                energies.clone(),
                vec![data.clone()],
                vec!["U-238".into()],
                0.0,
                None,
                vec![0.001],
            )
            .unwrap()
            .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
            .with_counts_background(CountsBackgroundConfig {
                c: 1.0,
                ..Default::default()
            });
            let input = InputData::CountsWithNuisance {
                sample_counts: s.clone(),
                flux: flux.clone(),
                background: vec![bad; energies.len()],
            };
            let msg = fit_spectrum_typed(&input, &config).unwrap_err().to_string();
            assert!(
                msg.contains("finite and non-negative"),
                "expected a malformed-background rejection for {bad}, got: {msg}"
            );
        }
    }

    /// Joint-Poisson rejects BackD/BackF exponential tail (support is deferred).
    #[test]
    fn test_joint_poisson_rejects_back_d_f() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, _) = synthetic_transmission(&data, 0.0005, &energies);
        let ob: Vec<f64> = vec![500.0; energies.len()];
        let s: Vec<f64> = t.iter().map(|&ti| 500.0 * ti).collect();

        let bg = BackgroundConfig {
            fit_back_d: true,
            ..BackgroundConfig::default()
        };

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_counts_background(CountsBackgroundConfig {
            c: 1.0,
            ..Default::default()
        })
        .with_transmission_background(bg);

        let input = InputData::Counts {
            sample_counts: s,
            open_beam_counts: ob,
        };
        let err = fit_spectrum_typed(&input, &config).unwrap_err();
        assert!(
            err.to_string().contains("BackD"),
            "expected BackD/BackF rejection, got: {err}"
        );
    }

    /// Partial BackD/BackF configurations are rejected with a clear error
    /// on the LM transmission path.  Regression:
    /// pre-fix, `append_background_params` allocated a free index for the
    /// enabled tail parameter but `NormalizedTransmissionModel::new`
    /// (4-term wrapper, fall-back when only one of back_d/back_f was
    /// `Some`) ignored it — the parameter sat at its initial value and
    /// fitter reported it as the "fitted" result.
    #[test]
    fn test_lm_transmission_rejects_partial_back_d_only() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, u) = synthetic_transmission(&data, 0.0005, &energies);

        let bg = BackgroundConfig {
            // BackD enabled, BackF disabled — the partial config the
            // pre-fix code silently accepted.
            fit_back_d: true,
            fit_back_f: false,
            ..BackgroundConfig::default()
        };

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()))
        .with_transmission_background(bg);

        let input = InputData::Transmission {
            transmission: t,
            uncertainty: u,
        };
        let err = fit_spectrum_typed(&input, &config).unwrap_err();
        let msg = err.to_string();
        assert!(
            msg.contains("fit_back_d") && msg.contains("fit_back_f"),
            "expected partial-BackD/F rejection mentioning both flags, got: {msg}"
        );
    }

    /// Symmetric case: BackF enabled without BackD — same rejection.
    #[test]
    fn test_lm_transmission_rejects_partial_back_f_only() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, u) = synthetic_transmission(&data, 0.0005, &energies);

        let bg = BackgroundConfig {
            fit_back_d: false,
            fit_back_f: true,
            ..BackgroundConfig::default()
        };

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()))
        .with_transmission_background(bg);

        let input = InputData::Transmission {
            transmission: t,
            uncertainty: u,
        };
        let err = fit_spectrum_typed(&input, &config).unwrap_err();
        let msg = err.to_string();
        assert!(
            msg.contains("fit_back_d") && msg.contains("fit_back_f"),
            "expected partial-BackD/F rejection mentioning both flags, got: {msg}"
        );
    }

    // ------------------------------------------------------------------
    // Fit-energy-range provenance + masked equivalence (#514).
    // ------------------------------------------------------------------

    /// `with_fit_energy_range(...)` round-trips through the accessor.
    #[test]
    fn test_unified_fit_config_fit_energy_range_round_trips() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..21).map(|i| 1.0 + (i as f64) * 0.1).collect();
        let cfg = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap();
        assert_eq!(cfg.fit_energy_range(), None);

        let cfg = cfg.with_fit_energy_range(Some((5.0, 50.0))).unwrap();
        assert_eq!(cfg.fit_energy_range(), Some((5.0, 50.0)));

        // Setting back to None clears it.
        let cfg = cfg.with_fit_energy_range(None).unwrap();
        assert_eq!(cfg.fit_energy_range(), None);
    }

    /// `with_fit_energy_range` rejects non-finite or reversed bounds
    /// rather than silently producing an empty active-bin mask
    /// downstream.
    #[test]
    fn test_unified_fit_config_fit_energy_range_rejects_invalid() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..21).map(|i| 1.0 + (i as f64) * 0.1).collect();
        let cfg = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap();

        // Reversed range (lo > hi) is rejected.
        let err = cfg
            .clone()
            .with_fit_energy_range(Some((10.0, 5.0)))
            .unwrap_err();
        assert!(matches!(err, FitConfigError::InvalidFitEnergyRange(_)));

        // Empty range (lo == hi) is rejected — `lo < hi` strictly required.
        let err = cfg
            .clone()
            .with_fit_energy_range(Some((5.0, 5.0)))
            .unwrap_err();
        assert!(matches!(err, FitConfigError::InvalidFitEnergyRange(_)));

        // Non-finite bounds are rejected.
        let err = cfg
            .clone()
            .with_fit_energy_range(Some((f64::NAN, 5.0)))
            .unwrap_err();
        assert!(matches!(err, FitConfigError::InvalidFitEnergyRange(_)));

        let err = cfg
            .clone()
            .with_fit_energy_range(Some((5.0, f64::INFINITY)))
            .unwrap_err();
        assert!(matches!(err, FitConfigError::InvalidFitEnergyRange(_)));
    }

    /// LM fit with `fit_energy_range = Some((min, max))` on the full
    /// grid must yield the same density as the same fit run on the
    /// `[min, max]` slice directly when the residual outside the range
    /// is negligible (SAMMY EMIN/EMAX semantics, paper-acceptance test).
    #[test]
    fn test_fit_energy_range_lm_matches_subset_when_outside_negligible() {
        let data = u238_single_resonance();
        let true_density = 0.002;
        // Wide grid: 0.5..10.5 eV in 0.05 eV steps.  The U-238 single
        // resonance sits well inside [4, 8] eV, so a fit restricted to
        // that range should recover the same density as the full-grid
        // fit (residual outside is negligible).
        let energies: Vec<f64> = (0..201).map(|i| 0.5 + (i as f64) * 0.05).collect();
        let (t, sigma) = synthetic_transmission(&data, true_density, &energies);

        let cfg_full = UnifiedFitConfig::new(
            energies.clone(),
            vec![data.clone()],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()));

        let cfg_masked = UnifiedFitConfig::new(
            energies.clone(),
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()))
        .with_fit_energy_range(Some((4.0, 8.0)))
        .unwrap();

        let input = InputData::Transmission {
            transmission: t,
            uncertainty: sigma,
        };
        let r_full = fit_spectrum_typed(&input, &cfg_full).unwrap();
        let r_masked = fit_spectrum_typed(&input, &cfg_masked).unwrap();
        assert!(r_full.converged && r_masked.converged);

        let d_full = r_full.densities[0];
        let d_masked = r_masked.densities[0];
        let rel_err = (d_full - d_masked).abs() / d_full.abs();
        assert!(
            rel_err < 0.01,
            "fit_energy_range LM density {d_masked} should match full-grid {d_full} \
             within 1% (got rel_err = {rel_err})"
        );
    }

    /// Transmission + PoissonKL with `fit_energy_range` set must be
    /// hard-rejected at dispatch.  The legacy `poisson_fit` does not
    /// honour the active-bin mask, so silently fitting on the
    /// (margin-extended) grid would bias the result.  Joint-Poisson
    /// (counts) and LM transmission both honour the mask correctly.
    /// Regression for #514.
    #[test]
    fn test_fit_energy_range_does_not_enable_transmission_kl() {
        let data = u238_single_resonance();
        let true_density = 0.002;
        let energies: Vec<f64> = (0..201).map(|i| 0.5 + (i as f64) * 0.05).collect();
        let (t, sigma) = synthetic_transmission(&data, true_density, &energies);

        let cfg = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_fit_energy_range(Some((4.0, 8.0)))
        .unwrap();

        let input = InputData::Transmission {
            transmission: t,
            uncertainty: sigma,
        };
        let err = fit_spectrum_typed(&input, &cfg).unwrap_err();
        let msg = err.to_string();
        assert!(
            msg.contains("normalized transmission") && msg.contains("Poisson"),
            "transmission plus Poisson/KL must be rejected as a route regardless \
             of fit_energy_range; got: {msg}"
        );
    }

    /// LM dispatcher must reject `fit_energy_range` that selects fewer
    /// than 2 active bins on the configured grid with a clear
    /// "range too narrow" error — instead of a confusing non-converged
    /// LM result.  Regression for #517.
    #[test]
    fn test_fit_energy_range_lm_rejects_too_narrow() {
        let data = u238_single_resonance();
        // 0.5..10.5 eV in 0.5 eV steps.  Range [4.6, 4.7] selects
        // exactly zero bins (no grid point inside; closest are 4.5
        // and 5.0).
        let energies: Vec<f64> = (0..21).map(|i| 0.5 + (i as f64) * 0.5).collect();
        let (t, sigma) = synthetic_transmission(&data, 0.002, &energies);
        let cfg = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()))
        .with_fit_energy_range(Some((4.6, 4.7)))
        .unwrap();
        let input = InputData::Transmission {
            transmission: t,
            uncertainty: sigma,
        };
        let err = fit_spectrum_typed(&input, &cfg).unwrap_err();
        let msg = err.to_string();
        assert!(
            msg.contains("fit_energy_range") && msg.contains("active bin"),
            "expected too-narrow-range rejection; got: {msg}"
        );
    }

    /// Joint-Poisson dispatcher must reject too-narrow ranges with the
    /// same clear error.  Regression for #517.
    #[test]
    fn test_fit_energy_range_jp_rejects_too_narrow() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..21).map(|i| 0.5 + (i as f64) * 0.5).collect();
        let (sample, open_beam) = synthetic_counts(&data, 0.002, &energies, 1000.0);
        let cfg = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_fit_energy_range(Some((4.6, 4.7)))
        .unwrap();
        let input = InputData::Counts {
            sample_counts: sample,
            open_beam_counts: open_beam,
        };
        let err = fit_spectrum_typed(&input, &cfg).unwrap_err();
        let msg = err.to_string();
        assert!(
            msg.contains("fit_energy_range") && msg.contains("active bin"),
            "expected too-narrow-range rejection; got: {msg}"
        );
    }

    // ── Issue #608: Rust coverage for paths previously exercised only
    //    via Python / the spatial-identity path (codecov/patch gap) ───────────

    /// The research Fisher helper is a counts-space model.  It must reject
    /// instrument resolution for the same separate-arm reason as the production
    /// optimizer, rather than exposing a wrong-but-finite Jacobian/Fisher for
    /// `R[T]`.
    #[test]
    fn evaluate_jacobian_and_fisher_rejects_resolution() {
        use nereids_physics::resolution::{ResolutionFunction, ResolutionParams};
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..101).map(|i| 1.0 + (i as f64) * 0.1).collect();
        let n_e = energies.len();
        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            300.0,
            Some(ResolutionFunction::Gaussian(
                ResolutionParams::new(25.0, 0.5, 0.005, 0.0).unwrap(),
            )),
            vec![0.001],
        )
        .unwrap();
        let flux = vec![5000.0; n_e];
        let background = vec![10.0; n_e];
        let err = match evaluate_jacobian_and_fisher(&config, &flux, &background) {
            Ok(_) => panic!("counts-space Fisher helper accepted instrument resolution"),
            Err(err) => err,
        };
        let msg = err.to_string();
        assert!(
            msg.contains("instrument resolution") && msg.contains("separate-arm model"),
            "expected physical counts-response rejection, got: {msg}"
        );
    }

    /// Non-spatial energy-scale fit through `fit_spectrum_typed` (LM
    /// transmission): exercises `seed_energy_scale_in_params` +
    /// `build_energy_scale_transmission_model` + the energy-scale LM path +
    /// `t0_us` / `l_scale` result population.  Prior Rust coverage was
    /// spatial-only on IDENTITY data; here we inject a NON-identity (t0,
    /// L_scale) and confirm the wiring recovers the density (the (t0, L_scale)
    /// valley is shallow, so we assert the physically-observable density, not
    /// tight individual parameters — cf. the Python `TestFitEnergyScaleRecovery`
    /// rationale).
    #[test]
    fn fit_spectrum_typed_energy_scale_lm_recovers_calibration() {
        let data = hf178_mlbw_two_resonances(); // s-waves @ 7.8 + 16.9 eV
        let energies: Vec<f64> = (0..700).map(|i| 4.0 + (i as f64) * 0.025).collect();
        let true_density = 0.05_f64;
        let (t0_true, ls_true) = (1.5_f64, 1.004_f64);
        // Synthesize measured data with the injected calibration via the model
        // (no resolution: dip POSITIONS drive the seed).
        let model = EnergyScaleTransmissionModel::new(
            Arc::new(vec![data.clone()]),
            Arc::new(vec![0]),
            Arc::new(vec![1.0]),
            293.6,
            energies.clone(),
            25.0,
            1,
            2,
            None,
        );
        let measured = model.evaluate(&[true_density, t0_true, ls_true]).unwrap();
        let uncertainty = vec![1e-3; energies.len()];
        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["Hf-178".into()],
            293.6,
            None,
            vec![0.04], // start density away from truth (0.05) so recovery is real
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()))
        .with_energy_scale(0.0, 1.0, 25.0); // cold (t0,L) start ⇒ the seed must correct it
        let input = InputData::Transmission {
            transmission: measured,
            uncertainty,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();
        let t0 = result
            .t0_us
            .expect("t0_us populated when fit_energy_scale=true");
        let ls = result
            .l_scale
            .expect("l_scale populated when fit_energy_scale=true");
        assert!(t0.is_finite() && ls.is_finite(), "t0={t0}, L={ls}");
        assert!(result.converged, "energy-scale LM fit should converge");
        assert!(
            (result.densities[0] - true_density).abs() / true_density < 0.10,
            "density: fitted={}, true={true_density}",
            result.densities[0]
        );
    }

    /// Non-spatial counts-KL energy-scale fit through `fit_spectrum_typed`:
    /// exercises `seed_energy_scale_in_params`' KL transmission proxy
    /// `(sample − bg)/(flux − bg)` + the counts-KL energy-scale dispatch —
    /// uncovered by the Rust suite (Python + spatial-identity only).
    #[test]
    fn fit_spectrum_typed_energy_scale_counts_kl_seeds_via_proxy() {
        let data = hf178_mlbw_two_resonances();
        let energies: Vec<f64> = (0..700).map(|i| 4.0 + (i as f64) * 0.025).collect();
        let true_density = 0.05_f64;
        let (t0_true, ls_true) = (1.0_f64, 1.003_f64);
        let model = EnergyScaleTransmissionModel::new(
            Arc::new(vec![data.clone()]),
            Arc::new(vec![0]),
            Arc::new(vec![1.0]),
            293.6,
            energies.clone(),
            25.0,
            1,
            2,
            None,
        );
        let t = model.evaluate(&[true_density, t0_true, ls_true]).unwrap();
        // Counts: sample = flux·T.  Zero detector background — the joint-Poisson
        // KL path does not yet wire B_det; the seed proxy
        // (sample − 0)/(flux − 0) = T still reconstructs the dip positions.
        let flux: Vec<f64> = vec![5000.0; energies.len()];
        let background: Vec<f64> = vec![0.0; energies.len()];
        let sample: Vec<f64> = t
            .iter()
            .zip(flux.iter())
            .map(|(&ti, &fi)| fi * ti)
            .collect();
        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["Hf-178".into()],
            293.6,
            None,
            vec![0.04],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_energy_scale(0.0, 1.0, 25.0);
        let input = InputData::CountsWithNuisance {
            sample_counts: sample,
            flux,
            background,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();
        let t0 = result
            .t0_us
            .expect("t0_us populated when fit_energy_scale=true");
        let ls = result
            .l_scale
            .expect("l_scale populated when fit_energy_scale=true");
        assert!(t0.is_finite() && ls.is_finite(), "t0={t0}, L={ls}");
    }

    #[test]
    fn validate_precomputed_cross_sections_error_branches() {
        use nereids_physics::resolution::{ResolutionFunction, ResolutionParams};
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..11).map(|i| 1.0 + (i as f64) * 0.1).collect();
        let n_e = energies.len();
        let base = UnifiedFitConfig::new(
            energies.clone(),
            vec![data.clone()],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap();
        let identity = || Arc::new(WorkingGridLayout::identity(&energies));
        let cfg =
            |base: &UnifiedFitConfig, sigma: Vec<Vec<f64>>, layout: Arc<WorkingGridLayout>| {
                base.clone().with_precomputed_cross_sections(PrecomputedXs {
                    sigma: Arc::new(sigma),
                    layout,
                })
            };
        let expect =
            |c: &UnifiedFitConfig, needle: &str| match validate_precomputed_cross_sections(c) {
                Err(PipelineError::ShapeMismatch(m)) => {
                    assert!(m.contains(needle), "expected {needle:?}, got: {m}")
                }
                other => panic!("expected ShapeMismatch({needle:?}), got {other:?}"),
            };
        assert!(
            validate_precomputed_cross_sections(&cfg(&base, vec![vec![1.0; n_e]], identity()))
                .is_ok()
        );
        expect(&cfg(&base, vec![], identity()), "must not be empty");
        expect(
            &cfg(&base, vec![vec![1.0; n_e - 1]], identity()),
            "its grid has",
        );
        let mut nan_row = vec![1.0; n_e];
        nan_row[3] = f64::NAN;
        expect(&cfg(&base, vec![nan_row], identity()), "non-finite");
        expect(
            &cfg(&base, vec![vec![1.0; n_e], vec![1.0; n_e]], identity()),
            "rows but expected",
        );
        let extended = Arc::new(WorkingGridLayout {
            energies: {
                let mut e = energies.clone();
                e.insert(0, 0.95);
                e.push(2.05);
                e
            },
            data_indices: (1..=n_e).collect(),
        });
        expect(
            &cfg(&base, vec![vec![1.0; n_e + 2]], extended),
            "is not the working grid",
        );

        let res =
            ResolutionFunction::Gaussian(ResolutionParams::new(25.0, 0.5, 0.005, 0.0).unwrap());
        let with_res = UnifiedFitConfig::new(
            energies.clone(),
            vec![data.clone()],
            vec!["U-238".into()],
            0.0,
            Some(res.clone()),
            vec![0.001],
        )
        .unwrap();
        expect(
            &cfg(&with_res, vec![vec![1.0; n_e]], identity()),
            "is not the working grid",
        );
        let working = Arc::new(
            phys_transmission::resolution_working_grid(
                &energies,
                Some(&InstrumentParams { resolution: res }),
                &[&data],
            )
            .unwrap(),
        );
        assert!(!working.is_identity());
        let n_work = working.energies.len();
        assert!(
            validate_precomputed_cross_sections(&cfg(
                &with_res,
                vec![vec![1.0; n_work]],
                Arc::clone(&working)
            ))
            .is_ok()
        );
        let with_indices = |data_indices: Vec<usize>| {
            Arc::new(WorkingGridLayout {
                energies: working.energies.clone(),
                data_indices,
            })
        };
        let mut shortened = working.data_indices.clone();
        shortened.pop();
        let mut out_of_range = working.data_indices.clone();
        out_of_range[0] = n_work + 5;
        let mut permuted = working.data_indices.clone();
        permuted.reverse();
        for bad in [shortened, out_of_range, permuted] {
            expect(
                &cfg(&with_res, vec![vec![1.0; n_work]], with_indices(bad)),
                "is not the working grid",
            );
        }
    }

    #[test]
    fn evaluate_jacobian_and_fisher_identity_and_temperature_paths() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..101).map(|i| 1.0 + (i as f64) * 0.1).collect();
        let n_e = energies.len();
        let flux = vec![5000.0; n_e];
        let background = vec![10.0; n_e];
        // (a) No resolution ⇒ identity working-grid layout.
        let cfg_id = UnifiedFitConfig::new(
            energies.clone(),
            vec![data.clone()],
            vec!["U-238".into()],
            300.0,
            None,
            vec![0.001],
        )
        .unwrap();
        let r_id = evaluate_jacobian_and_fisher(&cfg_id, &flux, &background).unwrap();
        assert_eq!(r_id.model_prediction.len(), n_e);
        let f00 = r_id.fisher.get(0, 0);
        assert!(
            f00.is_finite() && f00 > 0.0,
            "identity-path Fisher[0,0]={f00}"
        );
        let cfg_t = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            300.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_fit_temperature(true);
        let r_t = evaluate_jacobian_and_fisher(&cfg_t, &flux, &background).unwrap();
        assert_eq!(
            r_t.param_names.len(),
            2,
            "density + temperature free params"
        );
        assert!(r_t.model_prediction.iter().all(|v| v.is_finite()));
    }

    /// Cover `build_transmission_model`'s group-collapse path: a grouped config
    /// (two isotopes → one density param) carrying PRECOMPUTED per-member σ is
    /// collapsed to per-group effective σ before the model build (the grouped +
    /// precomputed path the spatial pipeline drives per pixel).
    #[test]
    fn fit_spectrum_typed_grouped_precomputed_collapses_by_groups() {
        use nereids_core::types::{Isotope, IsotopeGroup};
        let rd1 = synthetic_single_resonance(92, 235, 233.025, 5.0);
        let rd2 = synthetic_single_resonance(92, 238, 236.006, 7.0);
        let energies: Vec<f64> = (0..301).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let true_density = 0.0005_f64;
        let sample = phys_transmission::SampleParams::new(
            0.0,
            vec![
                (rd1.clone(), true_density * 0.6),
                (rd2.clone(), true_density * 0.4),
            ],
        )
        .unwrap();
        let transmission = phys_transmission::forward_model(&energies, &sample, None).unwrap();
        let uncertainty: Vec<f64> = transmission.iter().map(|&t| 0.01 * t.max(0.01)).collect();
        // Per-member precomputed σ (2 rows) ⇒ triggers the group collapse.
        let per_member = phys_transmission::broadened_cross_sections(
            &energies,
            &[rd1.clone(), rd2.clone()],
            0.0,
            None,
            None,
        )
        .unwrap();
        let iso1 = Isotope::new(92, 235).unwrap();
        let iso2 = Isotope::new(92, 238).unwrap();
        let group = IsotopeGroup::custom("U".into(), vec![(iso1, 0.6), (iso2, 0.4)]).unwrap();
        let config = UnifiedFitConfig::new(
            energies,
            vec![rd1.clone()],
            vec!["placeholder".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_groups(&[(&group, &[rd1, rd2])], vec![0.001])
        .unwrap();
        let per_member = table_on_data_grid(&config, per_member);
        let config = config
            .with_precomputed_cross_sections(per_member)
            .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()));
        let input = InputData::Transmission {
            transmission,
            uncertainty,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert_eq!(result.densities.len(), 1, "one group density");
        assert!(
            (result.densities[0] - true_density).abs() / true_density < 0.01,
            "grouped+precomputed density: fitted={}, true={true_density}",
            result.densities[0]
        );
    }

    /// `peak_match_energy_scale_seed` rejects (→ keeps the cold start) a fit that
    /// lands OUTSIDE the parameter bounds rather than clamping onto a bound
    /// (issue #608): inject an L_scale (1.03) beyond the seed's (0.99, 1.01).
    #[test]
    fn peak_match_energy_scale_seed_rejects_out_of_bounds() {
        let data = hf178_mlbw_two_resonances();
        let energies: Vec<f64> = (0..900).map(|i| 4.0 + (i as f64) * 0.02).collect();
        let model = EnergyScaleTransmissionModel::new(
            Arc::new(vec![data.clone()]),
            Arc::new(vec![0]),
            Arc::new(vec![1.0]),
            293.6,
            energies.clone(),
            25.0,
            1,
            2,
            None,
        );
        // L_scale = 1.03 is well outside (0.99, 1.01); the seed would fit ≈1.03.
        let t_obs = model.evaluate(&[0.05, 0.0, 1.03]).unwrap();
        let config = UnifiedFitConfig::new(
            energies.clone(),
            vec![data],
            vec!["Hf-178".into()],
            293.6,
            None,
            vec![0.05],
        )
        .unwrap()
        .with_energy_scale(0.0, 1.0, 25.0);
        assert!(
            peak_match_energy_scale_seed(
                &t_obs,
                config.energies(),
                &config,
                25.0,
                (-10.0, 10.0),
                (0.99, 1.01),
            )
            .is_none(),
            "an out-of-bounds calibration fit must be rejected (cold-start fallback)"
        );
    }

    // ── Issue #633: per-parameter density freeze ──

    /// `count_free_params` must drop frozen densities: a fixed density
    /// holds a parameter slot but gets no Jacobian column, so the
    /// underdetermined-system guard must not count it.
    #[test]
    fn test_count_free_params_drops_fixed_densities() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.1).collect();
        let base = UnifiedFitConfig::new(
            energies,
            vec![data.clone(), data],
            vec!["a".into(), "b".into()],
            300.0,
            None,
            vec![0.001, 0.001],
        )
        .unwrap()
        .with_fit_temperature(true);

        // 2 densities + temperature = 3 free.
        assert_eq!(count_free_params(&base), 3);
        // Freeze all densities → only temperature is free.
        assert_eq!(count_free_params(&base.clone().with_fix_densities(true)), 1);
        // Freeze one of two densities → 1 density + temperature = 2 free.
        let one_fixed = base.with_density_free(vec![false, true]).unwrap();
        assert_eq!(count_free_params(&one_fixed), 2);
    }

    /// `with_density_free` validates the mask length and normalises an
    /// all-free mask back to the historic `None` (no behavioural change).
    #[test]
    fn test_with_density_free_validates_and_normalises() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.1).collect();
        let cfg = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["a".into()],
            300.0,
            None,
            vec![0.001],
        )
        .unwrap();
        // Wrong length is rejected.
        assert!(matches!(
            cfg.clone().with_density_free(vec![true, false]),
            Err(FitConfigError::DensityCountMismatch { .. })
        ));
        // All-free mask leaves every density free (same as no mask).
        let all_free = cfg.with_density_free(vec![true]).unwrap();
        assert_eq!(all_free.n_free_density_params(), 1);
        assert!(!all_free.density_is_fixed(0));
    }

    /// `with_groups` must REJECT a freeze mask set before grouping — the mask
    /// indexes the pre-group density layout, and silently clearing it would
    /// leave the new group densities unexpectedly free (a silently-wrong fit).
    /// Regression for the review's stale-mask finding: the mis-ordered chain
    /// errors instead of silently changing behavior in either direction.
    #[test]
    fn test_with_groups_rejects_prior_density_freeze() {
        use nereids_core::types::{Isotope, IsotopeGroup};
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.1).collect();
        let iso = Isotope::new(92, 238).unwrap();
        let group = IsotopeGroup::custom("U-238".into(), vec![(iso, 1.0)]).unwrap();

        let cfg = UnifiedFitConfig::new(
            energies,
            vec![data.clone()],
            vec!["placeholder".into()],
            300.0,
            None,
            vec![0.001],
        )
        .unwrap()
        // Freeze all densities BEFORE grouping (the problematic order).
        .with_fix_densities(true);
        assert!(cfg.density_is_fixed(0), "mask set before grouping");

        // Grouping after a freeze is rejected (freeze must follow with_groups).
        assert!(matches!(
            cfg.with_groups(&[(&group, &[data])], vec![0.001]),
            Err(FitConfigError::DensityFreezeBeforeGroups)
        ));
    }

    /// The intended order — group first, THEN freeze — succeeds and freezes
    /// the group density parameter.
    #[test]
    fn test_freeze_after_groups_succeeds() {
        use nereids_core::types::{Isotope, IsotopeGroup};
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.1).collect();
        let iso = Isotope::new(92, 238).unwrap();
        let group = IsotopeGroup::custom("U-238".into(), vec![(iso, 1.0)]).unwrap();

        let cfg = UnifiedFitConfig::new(
            energies,
            vec![data.clone()],
            vec!["placeholder".into()],
            300.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_groups(&[(&group, &[data])], vec![0.001])
        .unwrap()
        .with_fix_densities(true);
        assert_eq!(cfg.n_density_params(), 1);
        assert!(
            cfg.density_is_fixed(0),
            "group density frozen when freeze follows grouping"
        );
        assert_eq!(cfg.n_free_density_params(), 0);
    }

    /// #633 (review R4): a fully-constrained fit — every density frozen and
    /// no other free parameter — must be rejected up front, not silently
    /// reported as a converged no-op by the solver's all-fixed fast path.
    #[test]
    fn test_all_frozen_no_free_param_rejected() {
        let data = u238_single_resonance();
        let true_density = 0.0005;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, sigma) = synthetic_transmission_at_temp(&data, true_density, 300.0, &energies);
        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            300.0,
            None,
            vec![true_density],
        )
        .unwrap()
        // Freeze the only parameter; fit_temperature stays false → 0 free.
        .with_fix_densities(true);
        assert_eq!(count_free_params(&config), 0);
        let input = InputData::Transmission {
            transmission: t,
            uncertainty: sigma,
        };
        assert!(matches!(
            fit_spectrum_typed(&input, &config),
            Err(PipelineError::InvalidParameter(_))
        ));
    }

    /// Closed-loop (issue #633 acceptance): synthetic spectrum at a known
    /// (n, T); freeze n at truth and fit temperature only. Temperature is
    /// recovered and the frozen density is held EXACTLY at its initial
    /// value (no Jacobian column).
    #[test]
    fn test_fix_densities_recovers_temperature_holds_density() {
        let data = u238_single_resonance();
        let true_density = 0.0005;
        let true_temp = 350.0;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, sigma) = synthetic_transmission_at_temp(&data, true_density, true_temp, &energies);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            300.0, // temperature initial guess (off by 50 K)
            None,
            vec![true_density], // density initial = truth, and frozen below
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(Default::default()))
        .with_fit_temperature(true)
        .with_fix_densities(true);

        let input = InputData::Transmission {
            transmission: t,
            uncertainty: sigma,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(result.converged, "T-only fit should converge");

        // Frozen density is held bit-exactly at its initial value.
        assert_eq!(
            result.densities[0], true_density,
            "frozen density must not move"
        );
        // Temperature (the sole free parameter) is recovered.
        let fitted_temp = result
            .temperature_k
            .expect("temperature_k should be Some when fit_temperature=true");
        assert!(
            (fitted_temp - true_temp).abs() < 1.0,
            "temperature: fitted={fitted_temp}, true={true_temp}"
        );

        // #633 P0 regression: with the density frozen, temperature is the
        // sole free parameter. Its 1-σ must be finite and positive (read
        // from the correct free slot); the frozen density reports NaN (it
        // has no covariance column). Before the free-index mapping fix this
        // silently returned a NaN temperature σ and a misassigned density σ.
        let t_unc = result
            .temperature_k_unc
            .expect("temperature_k_unc should be Some for a converged T fit");
        assert!(
            t_unc.is_finite() && t_unc > 0.0,
            "frozen-density thermometry must report a finite positive temperature σ, got {t_unc}"
        );
        let dens_unc = result
            .uncertainties
            .as_ref()
            .expect("converged fit has density uncertainties");
        assert!(
            dens_unc[0].is_nan(),
            "frozen density must report NaN σ (no covariance column), got {}",
            dens_unc[0]
        );
    }

    /// Freezing density does not make fractional transmission valid Poisson
    /// count data.
    #[test]
    fn test_fix_densities_does_not_enable_transmission_kl() {
        let data = u238_single_resonance();
        let true_density = 0.0005;
        let true_temp = 350.0;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, sigma) = synthetic_transmission_at_temp(&data, true_density, true_temp, &energies);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            300.0,
            None,
            vec![true_density],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_fit_temperature(true)
        .with_fix_densities(true);

        let input = InputData::Transmission {
            transmission: t,
            uncertainty: sigma,
        };
        let error = fit_spectrum_typed(&input, &config)
            .expect_err("transmission plus Poisson/KL must be rejected");
        assert!(error.to_string().contains("normalized transmission"));
    }

    /// Regression for the #633 P0: with a FROZEN leading density, result
    /// extraction must map the solver's FREE-only uncertainty vector through
    /// free positions. The free density and temperature take σ from the right
    /// free slots; the frozen density reports NaN. Pre-fix this indexed σ by
    /// full-layout position and silently misassigned temperature σ → NaN and
    /// density σ → a neighbouring parameter's value.
    #[test]
    fn test_extract_result_maps_uncertainties_past_frozen_density() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..21).map(|i| 1.0 + (i as f64) * 0.1).collect();
        // Densities: index 0 FROZEN, index 1 free; + fit_temperature.
        let config = UnifiedFitConfig::new(
            energies,
            vec![data.clone(), data],
            vec!["a".into(), "b".into()],
            300.0,
            None,
            vec![0.001, 0.002],
        )
        .unwrap()
        .with_fit_temperature(true)
        .with_density_free(vec![false, true])
        .unwrap();

        // Full layout: [d0(fixed), d1(free), temp(free)] → free_indices [1, 2];
        // solver uncertainties are FREE-only, ordered [σ_d1, σ_temp].
        let result = LmResult {
            chi_squared: 1.0,
            reduced_chi_squared: 1.0,
            iterations: 5,
            converged: true,
            params: vec![0.001, 0.002, 350.0],
            covariance: Some(lm::FlatMatrix::zeros(2, 2)),
            uncertainties: Some(vec![0.02, 4.0]),
        };

        let extracted = extract_result(&config, &result, 2, &[1, 2], None, None).unwrap();
        let unc = extracted
            .uncertainties
            .expect("converged fit surfaces density uncertainties");
        assert!(
            unc[0].is_nan(),
            "frozen density d0 must report NaN σ, got {}",
            unc[0]
        );
        assert_eq!(unc[1], 0.02, "free density d1 σ must come from free slot 0");
        assert_eq!(
            extracted.temperature_k_unc,
            Some(4.0),
            "temperature σ must come from free slot 1, not the missing full index 2"
        );
    }

    /// Closed-loop (issue #633 acceptance): freezing n at 0.9× truth must
    /// produce a converged, finite (biased) temperature — a documented
    /// bias, never silent NaN/nonsense.
    #[test]
    fn test_fix_densities_biased_density_gives_finite_documented_bias() {
        let data = u238_single_resonance();
        let true_density = 0.0005;
        let true_temp = 350.0;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t, sigma) = synthetic_transmission_at_temp(&data, true_density, true_temp, &energies);

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            300.0,
            None,
            vec![0.9 * true_density], // frozen 10% low
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(Default::default()))
        .with_fit_temperature(true)
        .with_fix_densities(true);

        let input = InputData::Transmission {
            transmission: t,
            uncertainty: sigma,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();
        let fitted_temp = result.temperature_k.expect("temperature_k should be Some");
        // Frozen density unchanged; temperature finite (biased, not NaN).
        assert_eq!(result.densities[0], 0.9 * true_density);
        assert!(
            fitted_temp.is_finite() && fitted_temp > 1.0,
            "biased-density fit must yield a finite temperature, got {fitted_temp}"
        );
    }

    // ── Issue #635: bounded multiplicative baseline ─────────────────────────

    /// Truth baseline used by the closed loops: a few % off unity, curved,
    /// strictly positive over the test grids, inside the DEFAULT bounds.
    const BL_TRUE: [f64; 3] = [1.02, -0.03, 0.01];

    fn baseline_at(e: f64, e_ref: f64, b: &[f64; 3]) -> f64 {
        let z = (e / e_ref).ln();
        b[0] + b[1] * z + b[2] * z * z
    }

    /// Multiply a clean transmission by the truth baseline, with a
    /// non-vacuity pre-check: the injected baseline must actually move the
    /// data, otherwise the closed-loop oracle is trivially satisfiable.
    fn apply_truth_baseline(t: &[f64], energies: &[f64]) -> Vec<f64> {
        let e_ref = nereids_fitting::transmission_model::baseline_reference_energy(energies);
        let out: Vec<f64> = t
            .iter()
            .zip(energies.iter())
            .map(|(&ti, &e)| ti * baseline_at(e, e_ref, &BL_TRUE))
            .collect();
        let max_rel = t
            .iter()
            .zip(out.iter())
            .map(|(&a, &b)| ((b - a) / a.max(1e-12)).abs())
            .fold(0.0_f64, f64::max);
        assert!(
            max_rel > 0.01,
            "non-vacuity pre-check: injected baseline moved the data by only \
             {max_rel:.2e} (max relative) — the closed loop would not \
             distinguish baseline-on from baseline-off"
        );
        out
    }

    #[test]
    fn baseline_lm_closed_loop_recovers_temperature_and_coefficients() {
        let data = u238_single_resonance();
        let true_density = 0.002;
        let true_temp = 600.0;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t_pure, _) = synthetic_transmission_at_temp(&data, true_density, true_temp, &energies);
        let measured = apply_truth_baseline(&t_pure, &energies);
        let sigma: Vec<f64> = measured.iter().map(|&v| 0.01 * v.max(0.01)).collect();
        let e_ref = nereids_fitting::transmission_model::baseline_reference_energy(&energies);

        // Density frozen at truth (the production thermometry pattern the
        // baseline was designed for); temperature seeded 100 K low; baseline
        // seeded at the identity (1, 0, 0) — all seeds away from truth.
        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            500.0,
            None,
            vec![true_density],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()))
        .with_fit_temperature(true)
        .with_fix_densities(true)
        .with_multiplicative_baseline(MultiplicativeBaselineConfig::default());

        let input = InputData::Transmission {
            transmission: measured,
            uncertainty: sigma,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(result.converged, "baseline LM closed loop should converge");

        let fitted_temp = result.temperature_k.expect("temperature fitted");
        assert!(
            (fitted_temp - true_temp).abs() < 10.0,
            "temperature: fitted={fitted_temp}, true={true_temp}"
        );

        let b = result.baseline.expect("baseline fitted");
        for (i, (&fitted, &truth)) in b.iter().zip(BL_TRUE.iter()).enumerate() {
            assert!(
                (fitted - truth).abs() < 1e-2,
                "b{i}: fitted={fitted}, true={truth}"
            );
        }
        let bl_cfg = MultiplicativeBaselineConfig::default();
        for (i, (&fitted, bounds)) in b
            .iter()
            .zip([bl_cfg.b0_bounds, bl_cfg.b1_bounds, bl_cfg.b2_bounds].iter())
            .enumerate()
        {
            assert!(
                fitted >= bounds.0 && fitted <= bounds.1,
                "b{i} = {fitted} escaped its bounds {bounds:?}"
            );
        }
        let reported_e_ref = result.baseline_e_ref_ev.expect("e_ref reported");
        assert!(
            (reported_e_ref - e_ref).abs() < 1e-12,
            "reported E_ref {reported_e_ref} != geometric midpoint {e_ref}"
        );
        assert!(
            result.warnings.is_empty(),
            "no degenerate trio here — warnings should be empty, got {:?}",
            result.warnings
        );
    }

    #[test]
    fn baseline_does_not_enable_transmission_kl() {
        let data = u238_single_resonance();
        let true_density = 0.002;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t_pure, _) = synthetic_transmission(&data, true_density, &energies);
        let measured = apply_truth_baseline(&t_pure, &energies);
        let sigma: Vec<f64> = measured.iter().map(|&v| 0.01 * v.max(0.01)).collect();

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig {
            max_iter: 500,
            ..PoissonConfig::default()
        }))
        .with_multiplicative_baseline(MultiplicativeBaselineConfig::default());

        let input = InputData::Transmission {
            transmission: measured,
            uncertainty: sigma,
        };
        let error = fit_spectrum_typed(&input, &config)
            .expect_err("a baseline must not enable transmission plus Poisson/KL");
        assert!(error.to_string().contains("normalized transmission"));
    }

    #[test]
    fn baseline_counts_jp_closed_loop() {
        let data = u238_single_resonance();
        let true_density = 0.002;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t_pure, _) = synthetic_transmission(&data, true_density, &energies);
        let t_baselined = apply_truth_baseline(&t_pure, &energies);
        let i0 = 10_000.0;
        let open_beam: Vec<f64> = vec![i0; t_baselined.len()];
        let sample: Vec<f64> = t_baselined
            .iter()
            .map(|&v| (v * i0).round().max(0.0))
            .collect();

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::PoissonKL(PoissonConfig::default()))
        .with_multiplicative_baseline(MultiplicativeBaselineConfig::default());

        let input = InputData::Counts {
            sample_counts: sample,
            open_beam_counts: open_beam,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(result.converged, "baseline JP closed loop should converge");
        assert!(
            result.deviance_per_dof.is_some(),
            "counts-KL path reports deviance"
        );
        let fitted = result.densities[0];
        assert!(
            (fitted - true_density).abs() / true_density < 0.02,
            "density: fitted={fitted}, true={true_density}"
        );
        let b = result.baseline.expect("baseline fitted");
        for (i, (&fit_b, &truth)) in b.iter().zip(BL_TRUE.iter()).enumerate() {
            assert!(
                (fit_b - truth).abs() < 1e-2,
                "b{i}: fitted={fit_b}, true={truth}"
            );
        }
    }

    /// b0 and Anorm are degenerate normalizations — a free Anorm alongside
    /// the baseline must be rejected on EVERY solver path (the #641 lesson:
    /// audit all parallel dispatches, not just the one under edit).
    #[test]
    fn baseline_rejects_free_anorm_on_all_paths() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.2).collect();
        let (t, sigma) = synthetic_transmission(&data, 0.002, &energies);

        let base_config = UnifiedFitConfig::new(
            energies.clone(),
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        // BackgroundConfig::default() has fit_anorm = true — the rejected combo.
        .with_transmission_background(BackgroundConfig::default())
        .with_multiplicative_baseline(MultiplicativeBaselineConfig::default());

        let transmission_input = InputData::Transmission {
            transmission: t.clone(),
            uncertainty: sigma,
        };
        let counts_input = InputData::Counts {
            sample_counts: t.iter().map(|&v| (v * 1000.0).round()).collect(),
            open_beam_counts: vec![1000.0; energies.len()],
        };

        for (label, input, solver) in [
            (
                "LM transmission",
                &transmission_input,
                SolverConfig::LevenbergMarquardt(LmConfig::default()),
            ),
            (
                "joint-Poisson counts",
                &counts_input,
                SolverConfig::PoissonKL(PoissonConfig::default()),
            ),
        ] {
            let config = base_config.clone().with_solver(solver);
            let err = fit_spectrum_typed(input, &config)
                .expect_err(&format!("{label}: free Anorm + baseline must be rejected"));
            let msg = err.to_string();
            assert!(
                msg.contains("Anorm") && msg.contains("fit_anorm = false"),
                "{label}: rejection must name the degeneracy and the fix, got: {msg}"
            );
        }
    }

    /// The additive ABC background WITH Anorm HELD FIXED is the sanctioned
    /// combination alongside the baseline — it must fit, and report both
    /// parameter blocks.
    #[test]
    fn baseline_with_fixed_anorm_abc_accepted() {
        let data = u238_single_resonance();
        let true_density = 0.002;
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let (t_pure, _) = synthetic_transmission(&data, true_density, &energies);
        let measured = apply_truth_baseline(&t_pure, &energies);
        let sigma: Vec<f64> = measured.iter().map(|&v| 0.01 * v.max(0.01)).collect();

        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()))
        .with_transmission_background(BackgroundConfig {
            fit_anorm: false,
            ..BackgroundConfig::default()
        })
        .with_multiplicative_baseline(MultiplicativeBaselineConfig::default());

        let input = InputData::Transmission {
            transmission: measured,
            uncertainty: sigma,
        };
        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(result.converged, "fixed-Anorm + ABC + baseline should fit");
        assert!(
            (result.anorm - 1.0).abs() < f64::EPSILON,
            "Anorm was frozen at 1.0, got {}",
            result.anorm
        );
        assert!(result.baseline.is_some(), "baseline block reported");
        // The truth signal is purely multiplicative, so the additive ABC
        // terms should stay small and the baseline should carry the shape.
        let b = result.baseline.unwrap();
        assert!(
            (b[0] - BL_TRUE[0]).abs() < 0.02,
            "b0: fitted={}, true={}",
            b[0],
            BL_TRUE[0]
        );
    }

    #[test]
    fn baseline_validation_rejects_bad_configs() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.2).collect();
        let (t, sigma) = synthetic_transmission(&data, 0.002, &energies);
        let input = InputData::Transmission {
            transmission: t,
            uncertainty: sigma,
        };
        let mk_config = |bl: MultiplicativeBaselineConfig| {
            UnifiedFitConfig::new(
                energies.clone(),
                vec![data.clone()],
                vec!["U-238".into()],
                0.0,
                None,
                vec![0.001],
            )
            .unwrap()
            .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()))
            .with_multiplicative_baseline(bl)
        };

        // Non-finite init.
        let err = fit_spectrum_typed(
            &input,
            &mk_config(MultiplicativeBaselineConfig {
                b0_init: f64::NAN,
                ..MultiplicativeBaselineConfig::default()
            }),
        )
        .expect_err("NaN b0_init must be rejected");
        assert!(err.to_string().contains("b0_init must be finite"));

        // Reversed bounds.
        let err = fit_spectrum_typed(
            &input,
            &mk_config(MultiplicativeBaselineConfig {
                b1_bounds: (0.05, -0.05),
                ..MultiplicativeBaselineConfig::default()
            }),
        )
        .expect_err("reversed b1_bounds must be rejected");
        assert!(err.to_string().contains("b1_bounds"));

        // Init outside bounds (no silent clamping).
        let err = fit_spectrum_typed(
            &input,
            &mk_config(MultiplicativeBaselineConfig {
                b0_init: 1.5,
                ..MultiplicativeBaselineConfig::default()
            }),
        )
        .expect_err("out-of-bounds b0_init must be rejected");
        assert!(err.to_string().contains("outside"));

        // Initial B(E) <= 0 somewhere on the grid: legal coefficients under
        // WIDENED bounds, but the slope drives B negative at the low edge
        // (grid 1..11 eV, e_ref ~ 3.3 eV, z_min ~ -1.2: 0.3 + 0.4*(-1.2) < 0
        // ... need |b1*z| > b0; use b1 = 0.4, b0 = 0.3 on a wider grid).
        let wide_energies: Vec<f64> = (0..51).map(|i| 1.0 * 1.1f64.powi(i)).collect();
        let (wt, ws) = synthetic_transmission(&data, 0.002, &wide_energies);
        let wide_input = InputData::Transmission {
            transmission: wt,
            uncertainty: ws,
        };
        let wide_config = UnifiedFitConfig::new(
            wide_energies,
            vec![data.clone()],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_solver(SolverConfig::LevenbergMarquardt(LmConfig::default()))
        .with_multiplicative_baseline(MultiplicativeBaselineConfig {
            b0_init: 0.3,
            b1_init: 0.4,
            b0_bounds: (0.1, 1.1),
            b1_bounds: (-1.0, 1.0),
            ..MultiplicativeBaselineConfig::default()
        });
        let err = fit_spectrum_typed(&wide_input, &wide_config)
            .expect_err("non-positive initial B(E) must be rejected");
        assert!(err.to_string().contains("not strictly"), "got: {err}");
    }

    #[test]
    fn degenerate_trio_produces_warning() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..51).map(|i| 1.0 + (i as f64) * 0.2).collect();

        let trio = UnifiedFitConfig::new(
            energies.clone(),
            vec![data.clone()],
            vec!["U-238".into()],
            300.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_fit_temperature(true)
        .with_transmission_background(BackgroundConfig::default());
        let w = degenerate_normalization_warning(&trio)
            .expect("free Anorm + free T + free density must warn");
        assert!(w.contains("degenerate"), "warning names the failure: {w}");

        // Removing ANY leg of the trio silences the warning.
        let frozen_density = trio.clone().with_fix_densities(true);
        assert!(degenerate_normalization_warning(&frozen_density).is_none());
        let no_temp = trio.clone().with_fit_temperature(false);
        assert!(degenerate_normalization_warning(&no_temp).is_none());
        let fixed_anorm = trio.clone().with_transmission_background(BackgroundConfig {
            fit_anorm: false,
            ..BackgroundConfig::default()
        });
        assert!(degenerate_normalization_warning(&fixed_anorm).is_none());

        // End-to-end: the warning must surface on the fit RESULT (the whole
        // point — the field failure was silent).
        let (t, sigma) = synthetic_transmission(&data, 0.002, &energies);
        let input = InputData::Transmission {
            transmission: t,
            uncertainty: sigma,
        };
        let config = trio.with_solver(SolverConfig::LevenbergMarquardt(LmConfig {
            max_iter: 5,
            ..LmConfig::default()
        }));
        let result = fit_spectrum_typed(&input, &config).unwrap();
        assert!(
            result.warnings.iter().any(|w| w.contains("degenerate")),
            "fit result must carry the degenerate-trio warning, got {:?}",
            result.warnings
        );
    }

    #[test]
    fn count_free_params_includes_baseline_flags() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..11).map(|i| 1.0 + (i as f64) * 0.1).collect();
        let base = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap();
        let n0 = count_free_params(&base);

        let all_free = base
            .clone()
            .with_multiplicative_baseline(MultiplicativeBaselineConfig::default());
        assert_eq!(count_free_params(&all_free), n0 + 3);

        let one_frozen = base
            .clone()
            .with_multiplicative_baseline(MultiplicativeBaselineConfig {
                fit_b1: false,
                ..MultiplicativeBaselineConfig::default()
            });
        assert_eq!(count_free_params(&one_frozen), n0 + 2);

        let frozen = base
            .clone()
            .with_multiplicative_baseline(MultiplicativeBaselineConfig {
                fit_b0: false,
                fit_b1: false,
                fit_b2: false,
                ..MultiplicativeBaselineConfig::default()
            });
        assert_eq!(count_free_params(&frozen), n0);
    }

    #[test]
    fn evaluate_jacobian_and_fisher_rejects_baseline() {
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..11).map(|i| 1.0 + (i as f64) * 0.1).collect();
        let n = energies.len();
        let config = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_multiplicative_baseline(MultiplicativeBaselineConfig::default());
        // `.err().expect(...)` — ModelJacobianResult is not Debug, so
        // `expect_err` is unavailable.
        let err = evaluate_jacobian_and_fisher(&config, &vec![1000.0; n], &vec![0.0; n])
            .err()
            .expect("research Fisher helper must reject a baseline config");
        assert!(err.to_string().contains("multiplicative"), "got: {err}");
    }

    /// Review R2: initial-point positivity validation is scoped to the fit
    /// window.  Inits that dip negative only at bins EXCLUDED by
    /// fit_energy_range are legal; the same inits without the window are
    /// rejected (non-vacuity control).
    #[test]
    fn baseline_init_positivity_scoped_to_fit_window() {
        let data = u238_single_resonance();
        // Wide log grid: z spans ±6.9 around the geometric midpoint, so
        // in-bounds coefficients (b0 = 0.9, b2 = -0.05) drive B_init < 0 at
        // the outer decades while staying positive near mid-grid.
        let energies: Vec<f64> = (0..61)
            .map(|i| 1e-3 * 10f64.powf(i as f64 / 10.0))
            .collect();
        let bl = MultiplicativeBaselineConfig {
            b0_init: 0.9,
            b2_init: -0.05,
            ..MultiplicativeBaselineConfig::default()
        };
        let base = UnifiedFitConfig::new(
            energies,
            vec![data],
            vec!["U-238".into()],
            0.0,
            None,
            vec![0.001],
        )
        .unwrap()
        .with_multiplicative_baseline(bl);

        // Full grid: rejected (B_init <= 0 at the edges).
        let err = validate_multiplicative_baseline(&base)
            .expect_err("negative B_init at unmasked edge bins must reject");
        assert!(err.to_string().contains("not strictly positive"), "{err}");

        // Narrow window where B_init > 0 everywhere active: accepted.
        let windowed = base
            .with_fit_energy_range(Some((0.5, 2.0)))
            .expect("valid range");
        validate_multiplicative_baseline(&windowed)
            .expect("inits positive inside the fit window must be accepted");
    }

    /// Review R2: committed parity pin for the #635
    /// `build_transmission_model` rewiring.  The no-temperature /
    /// no-precomputed-σ path now returns `PrecomputedTransmissionModel`
    /// (for its analytic Jacobian) instead of falling through to
    /// `TransmissionFitModel` — this test pins the load-bearing property
    /// that the MODEL OUTPUT is bit-identical to the canonical
    /// `forward_model` on both resolution arms, so only the optimizer
    /// quality changed.  If a future intentional physics change breaks
    /// bit-equality, re-anchoring THIS test forces the rationale to be
    /// written down (the VENUS anchors alone are machine-generated by the
    /// code under test and cannot distinguish "optimizer moved" from
    /// "model moved").
    #[test]
    fn build_transmission_model_no_temp_matches_forward_model_bit_exact() {
        use nereids_physics::transmission::SampleParams;
        let data = u238_single_resonance();
        let energies: Vec<f64> = (0..201).map(|i| 1.0 + (i as f64) * 0.05).collect();
        let density = 0.002;

        // Arm 1: no resolution (identity working grid).
        let config = UnifiedFitConfig::new(
            energies.clone(),
            vec![data.clone()],
            vec!["U-238".into()],
            293.6,
            None,
            vec![density],
        )
        .unwrap();
        let model = build_transmission_model(&config, 1, None).unwrap();
        let t_model = model.evaluate(&[density]).unwrap();
        let sample = SampleParams::new(293.6, vec![(data.clone(), density)]).unwrap();
        let t_fwd = phys_transmission::forward_model(&energies, &sample, None).unwrap();
        assert_eq!(t_model.len(), t_fwd.len());
        for (i, (a, b)) in t_model.iter().zip(t_fwd.iter()).enumerate() {
            assert_eq!(
                a.to_bits(),
                b.to_bits(),
                "no-resolution arm, bin {i}: {a:e} != {b:e}"
            );
        }

        // Arm 2: Gaussian resolution (auxiliary extended working grid, #608).
        let res = nereids_physics::resolution::ResolutionFunction::Gaussian(
            nereids_physics::resolution::ResolutionParams::new(25.0, 0.5, 0.005, 0.0).unwrap(),
        );
        let config_res = UnifiedFitConfig::new(
            energies.clone(),
            vec![data.clone()],
            vec!["U-238".into()],
            293.6,
            Some(res.clone()),
            vec![density],
        )
        .unwrap();
        let model_res = build_transmission_model(&config_res, 1, None).unwrap();
        let t_model_res = model_res.evaluate(&[density]).unwrap();
        let inst = InstrumentParams { resolution: res };
        let sample_res = SampleParams::new(293.6, vec![(data.clone(), density)]).unwrap();
        let t_fwd_res =
            phys_transmission::forward_model(&energies, &sample_res, Some(&inst)).unwrap();
        assert_eq!(t_model_res.len(), t_fwd_res.len());
        for (i, (a, b)) in t_model_res.iter().zip(t_fwd_res.iter()).enumerate() {
            assert_eq!(
                a.to_bits(),
                b.to_bits(),
                "Gaussian-resolution arm, bin {i}: {a:e} != {b:e}"
            );
        }

        let working = phys_transmission::broadened_cross_sections_on_working_grid(
            &energies,
            std::slice::from_ref(&data),
            293.6,
            Some(&inst),
            None,
        )
        .unwrap();
        assert!(!working.layout.is_identity());
        let config_given = config_res
            .clone()
            .with_precomputed_cross_sections(PrecomputedXs::from(working));
        let t_given = build_transmission_model(&config_given, 1, None)
            .unwrap()
            .evaluate(&[density])
            .unwrap();
        for (i, (a, b)) in t_given.iter().zip(t_fwd_res.iter()).enumerate() {
            assert_eq!(
                a.to_bits(),
                b.to_bits(),
                "Gaussian-resolution arm with a supplied table, bin {i}: {a:e} != {b:e}"
            );
        }

        let tab_text = "header\n---\n\
             5.0 0.0\n\
             -0.01 0.0\n\
             -0.005 0.5\n\
             0.0 1.0\n\
             0.005 0.5\n\
             0.01 0.0\n\
             \n\
             200.0 0.0\n\
             -0.02 0.0\n\
             -0.01 0.5\n\
             0.0 1.0\n\
             0.01 0.5\n\
             0.02 0.0\n";
        let tab = nereids_physics::resolution::TabulatedResolution::from_text(tab_text, 25.0)
            .expect("synthetic tabulated kernel parses");
        let res_tab = nereids_physics::resolution::ResolutionFunction::Tabulated(Arc::new(tab));
        let config_tab = UnifiedFitConfig::new(
            energies.clone(),
            vec![data.clone()],
            vec!["U-238".into()],
            293.6,
            Some(res_tab.clone()),
            vec![density],
        )
        .unwrap();
        let model_tab = build_transmission_model(&config_tab, 1, None).unwrap();
        let t_model_tab = model_tab.evaluate(&[density]).unwrap();
        let inst_tab = InstrumentParams {
            resolution: res_tab,
        };
        let sample_tab = SampleParams::new(293.6, vec![(data, density)]).unwrap();
        let t_fwd_tab =
            phys_transmission::forward_model(&energies, &sample_tab, Some(&inst_tab)).unwrap();
        assert_eq!(t_model_tab.len(), t_fwd_tab.len());
        for (i, (a, b)) in t_model_tab.iter().zip(t_fwd_tab.iter()).enumerate() {
            assert_eq!(
                a.to_bits(),
                b.to_bits(),
                "tabulated-resolution arm, bin {i}: {a:e} != {b:e}"
            );
        }
        let working_tab = phys_transmission::broadened_cross_sections_on_working_grid(
            &energies,
            std::slice::from_ref(&sample_tab.isotopes()[0].0),
            293.6,
            Some(&inst_tab),
            None,
        )
        .unwrap();
        assert!(!working_tab.layout.is_identity());
        let config_given_tab = config_tab
            .clone()
            .with_precomputed_cross_sections(PrecomputedXs::from(working_tab));
        let t_given_tab = build_transmission_model(&config_given_tab, 1, None)
            .unwrap()
            .evaluate(&[density])
            .unwrap();
        for (i, (a, b)) in t_given_tab.iter().zip(t_fwd_tab.iter()).enumerate() {
            assert_eq!(
                a.to_bits(),
                b.to_bits(),
                "tabulated-resolution arm with a supplied table, bin {i}: {a:e} != {b:e}"
            );
        }
    }
}