gam-sae 0.3.154

use super::*;
// #2598 — the all-zero-gated-design and total-co-collapse refusals interpolate
// their classifier marker rather than restating it.
use super::outer_objective::ProbeRefusalKind;
use crate::chart_coordinate_solve::PeriodicCurveExtrema;
use opt::{BacktrackConfig, RidgeSchedule, backtracking_line_search, escalate_ridge};

/// Maximum number of LM ridge-escalation attempts before declaring the per-row
/// Hessian unfactorable.
const SAE_MANIFOLD_ROW_RIDGE_MAX_ATTEMPTS: usize = 12;

const SAE_MANIFOLD_LM_RATIO_LOW: f64 = 0.25;
const SAE_MANIFOLD_LM_RATIO_HIGH: f64 = 0.75;
const SAE_MANIFOLD_LM_RIDGE_FACTOR: f64 = 4.0;

impl InnerGlobalizationHint {
    pub(crate) fn cold(step_size: f64, ridge_ext_coord: f64, ridge_beta: f64) -> Self {
        Self {
            warm_step: step_size,
            lm_ridge_t: ridge_ext_coord,
            lm_ridge_b: ridge_beta,
        }
    }

    pub(crate) fn resume(
        carried: Option<Self>,
        step_size: f64,
        ridge_ext_coord: f64,
        ridge_beta: f64,
    ) -> Self {
        carried.map_or_else(
            || Self::cold(step_size, ridge_ext_coord, ridge_beta),
            |hint| Self {
                warm_step: hint.warm_step.max(step_size),
                lm_ridge_t: hint.lm_ridge_t.max(ridge_ext_coord),
                lm_ridge_b: hint.lm_ridge_b.max(ridge_beta),
            },
        )
    }

    pub(crate) fn record_accepted_step(
        &mut self,
        accepted_step: f64,
        warm_growth: f64,
        unit_step_ceiling: f64,
        gain_ratio: f64,
        ridge_ext_coord: f64,
        ridge_beta: f64,
    ) {
        let clean_acceptance = accepted_step >= self.warm_step;
        self.warm_step = if clean_acceptance {
            (self.warm_step * warm_growth).min(unit_step_ceiling)
        } else {
            (accepted_step * warm_growth).min(unit_step_ceiling)
        };
        if gain_ratio < SAE_MANIFOLD_LM_RATIO_LOW {
            self.lm_ridge_t *= SAE_MANIFOLD_LM_RIDGE_FACTOR;
            self.lm_ridge_b *= SAE_MANIFOLD_LM_RIDGE_FACTOR;
        } else if gain_ratio > SAE_MANIFOLD_LM_RATIO_HIGH {
            self.lm_ridge_t =
                (self.lm_ridge_t / SAE_MANIFOLD_LM_RIDGE_FACTOR).max(ridge_ext_coord);
            self.lm_ridge_b =
                (self.lm_ridge_b / SAE_MANIFOLD_LM_RIDGE_FACTOR).max(ridge_beta);
        }
    }

    pub(crate) fn reset(
        &mut self,
        step_size: f64,
        ridge_ext_coord: f64,
        ridge_beta: f64,
    ) {
        *self = Self::cold(step_size, ridge_ext_coord, ridge_beta);
    }
}

/// Floor on the per-axis coordinate spread used to guard the ARD moment-match
/// (`α' = α · spread_pre / spread_post`, F3). Below this the spread is
/// numerically degenerate (a near-constant coordinate) and the ratio is
/// meaningless, so the untransformed precision is stamped instead. Not a tuning
/// knob — it only fences the division against a vanishing denominator at f64
/// resolution.
const ARD_SPREAD_FLOOR: f64 = 1.0e-12;

/// Why one bounded joint-fit chunk returned. Ordinary fits may use the two
/// heuristic exits; evidence is certified only by [`Self::NoStrictDecrease`].
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum JointFitTermination {
    Frozen,
    Heuristic,
    NoStrictDecrease,
    IterationGrantExhausted,
}

pub(crate) struct JointFitOutcome {
    pub(crate) loss: SaeManifoldLoss,
    pub(crate) termination: JointFitTermination,
    pub(crate) state_moved: bool,
    /// The FIRST site that moved state, for the evidence lane's refusal
    /// to name (see [`StateMoveSite`]).
    pub(crate) moved_at: Option<StateMoveSite>,
}

pub(crate) struct EvidenceJointFitOutcome {
    pub(crate) loss: SaeManifoldLoss,
    /// A whole evidence-only re-entry started at the current state and found no
    /// strict objective decrease, with no temperature/polish state transition.
    pub(crate) fixed_point: bool,
}

/// Which clause of the idempotent-re-entry certificate a pass failed.
///
/// `fixed_point` is a four-way conjunction, and the four clauses have four
/// different causes and four different remedies — a settled-but-annealing
/// schedule is not the same defect as a Newton walk that is still descending,
/// which is not the same as a pass that ran a full sweep and wrote back a state
/// differing in its last bits. A caller that exhausts its re-entry budget can
/// only report "did not reach an idempotent fixed point", which names none of
/// them; and `gam-sae` test binaries install no logger backend, so a `log::`
/// line would not surface it either. Carrying the clause makes the refusal
/// actionable at the point it is raised.
/// WHERE a pass moved model state.
///
/// `state_moved` is an OR over the whole call, but `termination` is assigned only
/// inside the Newton loop — four of the eight move sites are OUTSIDE it (one
/// before, three after). So "settled-root termination AND state_moved" is not a
/// contradiction and neither signal is lying: they quantify over different spans
/// of the pass, and without the site the pair cannot be read at all.
///
/// Two of the out-of-loop sites are RESTORES, which put the model back to a
/// banked state — they set `state_moved` while potentially leaving the state
/// bit-identical to entry, which `entry_state_recurred` already tests exactly.
/// Distinguishing a restore from the exit block sweep is therefore the whole
/// diagnosis: a restore means the certificate is refusing an idempotent pass,
/// the exit sweep means the state genuinely was not a fixed point of the map.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum StateMoveSite {
    /// The block sweep that runs BEFORE the Newton loop.
    EntryBlockSweep,
    /// The annealing schedule emitted a new temperature.
    TemperatureSchedule,
    /// The line search accepted a Newton step.
    AcceptedNewtonStep,
    /// The proximal-correction fallback accepted a step, inside the loop. This
    /// path runs when the ordinary Armijo line search could not find a
    /// sufficient directional decrease, and it commits only a decrease that
    /// clears the evidence lane's MATERIAL floor
    /// (`SAE_MANIFOLD_INNER_OBJECTIVE_STALL_REL_TOL * (1 + |objective|)`).
    ProximalCorrectionStep,
    /// Active frames were refreshed from data inside the loop.
    FrameRefresh,
    /// AFTER the loop: the banked inner incumbent was restored (#1026).
    InnerIncumbentRestore,
    /// AFTER the loop: the exit block sweep committed a material decrease.
    ExitBlockSweep,
    /// AFTER the loop: the exit objective warranty restored a banked state (#2228).
    ExitWarrantyRestore,
    /// The gauge-orbit block descent committed a decrease, inside the loop
    /// (#2762). Reached only after the Newton line search AND the proximal
    /// correction both failed to find one, so it is the same "a real objective
    /// improvement was still available" statement as `ProximalCorrectionStep`,
    /// in the block where the Newton model is structurally unable to look.
    GaugeOrbitDescent,
}

/// What one [`SaeManifoldTerm::descend_gauge_orbit`] call did (#2762). All
/// fields are measurements, not requests: `rounds == 0` with a large
/// `max_directional_derivative` is the honest report that the removed span
/// carries live slope no FINITE motion along it can cash in.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub(crate) struct GaugeOrbitDescent {
    /// Rounds that committed a decrease clearing the material floor.
    pub(crate) rounds: usize,
    /// Total penalized-objective decrease committed across those rounds.
    pub(crate) objective_decrease: f64,
    /// Dimension of the removed span at the last round examined.
    pub(crate) dimension: usize,
    /// `maxᵢ |gᵀvᵢ|` over the removed span at the last round examined — the
    /// precondition `quotient_residual_norm_sq`'s removal assumes.
    pub(crate) max_directional_derivative: f64,
    /// Objective evaluations spent. Each is one `penalized_objective_total`.
    pub(crate) evaluations: usize,
    /// The objective at entry, evaluated under the barrier/repulsion gates the
    /// descent itself froze (its first `assemble_arrow_schur`). The value the
    /// caller measured BEFORE calling is under whatever gate its last assembly
    /// left behind, and the two differ at the gate-shift scale (measured
    /// `1.9e-6` at an objective of `2.3e7`, `4.5e-7` on the exit-state fixture),
    /// so `objective_decrease` telescopes against THIS number, not the caller's.
    /// `None` when no round reached an evaluation.
    pub(crate) entry_objective: Option<f64>,
    /// The committed objective after the last accepted round, under the same
    /// gate as `entry_objective` for that round. `None` when nothing committed.
    pub(crate) exit_objective: Option<f64>,
}

impl GaugeOrbitDescent {
    pub(crate) fn moved(&self) -> bool {
        self.rounds > 0 && self.objective_decrease > 0.0
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum EvidenceFixedPointGap {
    /// No clause failed: the pass recurred its entry state exactly.
    None,
    /// The pass left through a route that is not a settled root (it exhausted
    /// its iteration budget, or took a descent step it accepted).
    NotASettledRoot,
    /// The pass reported that it moved model state, at the named site.
    StateMoved(StateMoveSite),
    /// The pass reported no move, yet the model state is not bit-identical to
    /// the entry snapshot — the re-entry wrote back a perturbed state.
    StateNotRecurred,
    /// The annealing schedule will emit a different temperature on the next
    /// re-entry, so the objective this pass settled on is not the objective the
    /// next one would see.
    TemperatureStillAnnealing,
}

/// Put one softmax-logit row in the reference-logit chart used by the joint
/// solver. Kept row-local so Newton's disjoint row update can canonicalize in
/// the same worker instead of making another serial `N × K` pass.
#[inline]
fn canonicalize_softmax_logit_row(logits: &mut [f64]) {
    match logits.len() {
        0 => {}
        1 => logits[0] = 0.0,
        k => {
            let reference = logits[k - 1];
            for logit in &mut logits[..k - 1] {
                *logit -= reference;
            }
            logits[k - 1] = 0.0;
        }
    }
}

/// Per-axis spread of a coordinate column used for the ARD moment-match (F3): the
/// population variance on a flat axis, and the circular variance `1 − R`
/// (`R = |mean e^{iθ}|`, `θ = 2π t / period`) on a periodic axis — the wrap-aware
/// second moment, so a seam-straddling circle coordinate is measured by its true
/// angular concentration rather than a spuriously large linear variance. `NaN`
/// for an empty column or an out-of-range axis (the caller then leaves the
/// precision untransformed).
fn axis_coordinate_spread(coords: ArrayView2<'_, f64>, axis: usize, period: Option<f64>) -> f64 {
    let n = coords.nrows();
    if n == 0 || axis >= coords.ncols() {
        return f64::NAN;
    }
    match period {
        Some(p) if p.is_finite() && p > 0.0 => {
            let w = std::f64::consts::TAU / p;
            let mut cs = 0.0;
            let mut sn = 0.0;
            for row in 0..n {
                let ang = coords[[row, axis]] * w;
                cs += ang.cos();
                sn += ang.sin();
            }
            let r = (cs * cs + sn * sn).sqrt() / n as f64;
            (1.0 - r).max(0.0)
        }
        _ => {
            let mut mean = 0.0;
            for row in 0..n {
                mean += coords[[row, axis]];
            }
            mean /= n as f64;
            let mut var = 0.0;
            for row in 0..n {
                let d = coords[[row, axis]] - mean;
                var += d * d;
            }
            var / n as f64
        }
    }
}

/// Per-fit-constant centered statistics of the reconstruction target, shared by
/// reconstruction telemetry and #2362 union-output-span evidence.
///
/// The target does not change across the outer loop of
/// [`SaeManifoldTerm::run_joint_fit_arrow_schur`], so its per-column means and
/// total centered sum-of-squares are invariants of the whole joint fit. The
/// guard formerly re-derived them from the full `n × p` target on every accepted
/// outer iteration. That `O(n·p)` column-major reduction dominated the
/// single-threaded inner-loop profile. Computing it once per joint fit and
/// handing it to each iteration's guard call removes the repeated work.
///
/// The values are BIT-IDENTICAL to the historical per-call computation:
/// [`Self::compute`] reuses the exact Welford per-column mean and the exact
/// single-accumulator column-major total, so every EV value a guard derives from
/// a cached instance equals the value the uncached path would have produced.
pub(crate) struct TargetCenteredColStats {
    /// Per-column Welford running mean, in column order (`col_means[col]`).
    col_means: Vec<f64>,
    /// `Σ_col Σ_row (target[row, col] − mean_col)²`, accumulated with a single
    /// running total in column-major order — the exact historical reduction.
    ss_tot: f64,
}

impl TargetCenteredColStats {
    /// Reduce the centered column statistics with the historical loop order, so
    /// every EV value derived from the result is bit-for-bit the
    /// value the former inline per-call reduction produced. Column means use
    /// Welford's running update so a huge-but-finite target column cannot overflow
    /// the total sum of squares.
    pub(crate) fn compute(target: ArrayView2<'_, f64>) -> Self {
        let n = target.nrows();
        let p = target.ncols();
        let mut col_means = vec![0.0_f64; p];
        let mut ss_tot = 0.0_f64;
        for col in 0..p {
            let mut mean = 0.0_f64;
            for (count, row) in (0..n).enumerate() {
                let x = target[[row, col]];
                mean += (x - mean) / (count as f64 + 1.0);
            }
            for row in 0..n {
                let dev = target[[row, col]] - mean;
                ss_tot += dev * dev;
            }
            col_means[col] = mean;
        }
        Self { col_means, ss_tot }
    }

    /// Centered total sum of squares `Σ_col Σ_row (y − mean_col)²` — the EV
    /// normalizer. Exposed for the basin-identity reconstruction distance in
    /// [`SaeManifoldOuterObjective`] (#2230/#2087).
    pub(crate) fn ss_tot(&self) -> f64 {
        self.ss_tot
    }
}

/// #2362 shared-output-subspace collapse evidence.
#[derive(Clone, Copy, Debug)]
pub(crate) struct StructuralCoCollapseEvidence {
    pub(crate) decoder_span_rank: usize,
    pub(crate) target_reach: f64,
    pub(crate) random_subspace_null: f64,
}

/// One same-state dictionary-collapse verdict.
///
/// The hard decision is deliberately independent of training `R²`. A
/// signal-free fit statistic can diagnose estimator behavior after convergence,
/// but it cannot prove that decoder parameters disappeared during an inner
/// optimization. The two admissible hard arms are therefore:
///
/// * every atom's actual gated reconstruction signal is below the boundary
///   derived from the floating-point residual backward-error envelope; or
/// * #2362's distinct union-output-subspace collapse.
///
/// `explained_variance` remains telemetry and keep-best ordering only. The
/// reconstruction, assignments, gated Grams, decoders, and output frames are all
/// derived from the same `self + target + rho` state; callers cannot splice an
/// arbitrary fitted matrix onto live decoder frames.
#[derive(Clone, Debug)]
pub(crate) struct DictionaryCollapseVerdict {
    pub(crate) explained_variance: f64,
    pub(crate) decoder_vanishing: super::construction::VanishedAtomsProof,
    pub(crate) structural_collapse: Option<StructuralCoCollapseEvidence>,
}

impl DictionaryCollapseVerdict {
    pub(crate) fn all_decoders_vanished(&self, atom_count: usize) -> bool {
        self.decoder_vanishing.all_atoms_vanished(atom_count)
    }

    pub(crate) fn structurally_collapsed(&self) -> bool {
        self.structural_collapse.is_some()
    }

    pub(crate) fn degenerate(&self, atom_count: usize) -> bool {
        self.all_decoders_vanished(atom_count) || self.structurally_collapsed()
    }

    pub(crate) fn proof_unavailable_reason(&self) -> Option<&str> {
        self.decoder_vanishing.unavailable_reason()
    }

    pub(crate) fn collapse_event_floor(&self, atom_count: usize) -> Option<f64> {
        if self.all_decoders_vanished(atom_count) {
            self.decoder_vanishing.signal_vanish_boundary()
        } else {
            self.structural_collapse
                .map(|evidence| evidence.random_subspace_null)
        }
    }
}

/// Killing fields of `Isom(S²) = O(3)` at an ambient unit vector: `K_a(u) = e_a × u`.
///
/// Shared by `S²` and `RP²` because they share a group and a cover — the deck
/// `u ~ −u` commutes with every rotation, so the quotient inherits the
/// generators unchanged. Linear in the coordinate and defined everywhere, where
/// the superseded `(lat, lon)` cover velocities were nonlinear and could not be
/// evaluated at the cover's own poles (longitude has a nontrivial stabiliser
/// there).
pub(crate) fn ambient_sphere_killing_directions(u: [f64; 3]) -> [[f64; 3]; 3] {
    [
        [0.0, -u[2], u[1]],
        [u[2], 0.0, -u[0]],
        [-u[1], u[0], 0.0],
    ]
}

impl SaeManifoldTerm {
    /// Compute [`DictionaryCollapseVerdict`] from one internally consistent
    /// fitted state.
    pub(crate) fn dictionary_collapse_verdict(
        &self,
        target: ArrayView2<'_, f64>,
        rho: &SaeManifoldRho,
        target_col_stats: Option<&TargetCenteredColStats>,
    ) -> Result<DictionaryCollapseVerdict, String> {
        let fitted = self.try_fitted_target_aware(target, Some(rho))?;
        let (n, p) = target.dim();
        let residual = &fitted - &target;
        let residual_energy = self.residual_energy_for_vanishing(residual.view())?;
        let explained_variance = self.dictionary_reconstruction_ev_from_residual_sum_squares(
            residual_energy.sum_squares(),
            target,
            target_col_stats,
        )?;
        let mut grams = self.empty_decoder_gram_accumulator();
        self.accumulate_decoder_gram(&mut grams)?;
        let n_eff = self.per_atom_effective_sample_size();
        let decoder_vanishing = self.vanished_atoms_from_signal_upper_bound(
            &grams,
            &n_eff,
            residual_energy.mean_square(),
        )?;
        let k = self.k_atoms();

        // #2362 — structural co-collapse is distinct from numerical decoder
        // disappearance. With `Q` an orthonormal basis of the union decoder
        // output span (rank `R_dec`), the best amplitude-free reconstruction in
        // that span captures `reach = ||Q^T T_c||_F^2 / ss_tot`. A dictionary
        // whose atoms have piled into `R_dec < K` directions no more informative
        // than a random output subspace of that rank is structurally collapsed.
        //
        // #2756 — `R_dec` is a rank in the OUTPUT space, so its ceiling is
        // `min(K, p)`, not `K`. When `p < K` a healthy dictionary saturates at
        // `R_dec = p` and can never reach `K`, so the `R_dec >= K` exemption
        // never fires; and at `R_dec == p` the rank-matched random-subspace null
        // is `R_dec/p = 1`, which `reach = ||QᵀT_c||_F²/ss_tot ≤ 1` meets
        // IDENTICALLY — `Q` spans the whole output space, so there is no subspace
        // for the dictionary to be worse than. The comparison has zero
        // discriminating power there and fires on every state, which is how the
        // #2756 witness (`p = 1`, `K = 2`, decoders spanning all of R¹) was
        // certified "structurally collapsed" at `decoder_span_rank = 1,
        // target_reach = 1.0000, null = 1.0000` — the MAXIMUM span its output
        // dimension admits. Exempt the saturated case for the same reason
        // `R_dec >= K` is exempt: the evidence is unobtainable, not absent. The
        // discriminating regime `R_dec < min(K, p)` — where a rank-matched random
        // subspace really does leave energy outside the span — is untouched, and
        // `decoder_norm_guard_reseeds_all_atoms_on_total_co_collapse_k3`
        // (`p = 3`, `K = 3`, `R_dec = 1`) still refuses.
        let frames_sc = (0..k)
            .map(|atom| crate::manifold::certificate::certificate_output_frame(self, atom))
            .collect::<Result<Vec<_>, String>>()?;
        let r_dec_sc = union_output_frame_rank(&frames_sc, p);
        let structural_collapse = if r_dec_sc == 0 || r_dec_sc >= k || p == 0 || r_dec_sc >= p {
            None
        } else {
            let owned_stats;
            let stats = match target_col_stats {
                Some(stats) => stats,
                None => {
                    owned_stats = TargetCenteredColStats::compute(target);
                    &owned_stats
                }
            };
            if !(stats.ss_tot > 0.0) {
                None
            } else {
                let q = union_output_frame_basis(&frames_sc, p);
                let qc = q.ncols();
                let mut in_span = 0.0_f64;
                for row in 0..n {
                    for c in 0..qc {
                        let mut projection = 0.0_f64;
                        for output in 0..p {
                            projection += q[[output, c]]
                                * (target[[row, output]] - stats.col_means[output]);
                        }
                        in_span += projection * projection;
                    }
                }
                let target_reach = in_span / stats.ss_tot;
                let random_subspace_null = r_dec_sc as f64 / p as f64;
                (target_reach <= random_subspace_null).then_some(
                    StructuralCoCollapseEvidence {
                        decoder_span_rank: r_dec_sc,
                        target_reach,
                        random_subspace_null,
                    },
                )
            }
        };
        Ok(DictionaryCollapseVerdict {
            explained_variance,
            decoder_vanishing,
            structural_collapse,
        })
    }

    pub fn apply_newton_step(
        &mut self,
        delta_ext_coord: ArrayView1<'_, f64>,
        delta_beta: ArrayView1<'_, f64>,
        step_size: f64,
    ) -> Result<(), String> {
        self.apply_newton_step_impl(delta_ext_coord, delta_beta, step_size, true)
    }

    /// Capture the mutable state perturbed by an `apply_newton_step` +
    /// `loss` line-search trial, plus the row-layout state read by
    /// `apply_newton_step` when unpacking compact Newton steps. See
    /// [`SaeManifoldMutableState`].
    pub(crate) fn snapshot_mutable_state(&self) -> SaeManifoldMutableState {
        let atoms = self
            .atoms
            .iter()
            .map(|atom| SaeManifoldAtomSnapshot {
                decoder_coefficients: atom.decoder_coefficients().clone(),
                decoder_frame: atom.decoder_frame.clone(),
                smooth_penalty: atom.smooth_penalty().clone(),
                // Pointer-cheap handle clones; `basis_values`/`basis_jacobian`
                // are rebuilt from these + coords on restore, avoiding the
                // dominant `O(N·M·(1+d))` snapshot copy (see
                // `SaeManifoldMutableState`).
                basis_evaluator: atom.basis_evaluator.clone(),
                basis_second_jet: atom.basis_second_jet.clone(),
                homotopy_eta: atom.homotopy_eta,
                chart_canonicalized: atom.chart_canonicalized,
                reduced_column_map: atom.reduced_column_map.clone(),
                caller_managed_basis: atom.basis_evaluator.is_none().then(|| {
                    (
                        atom.basis_values.clone(),
                        atom.basis_jacobian.clone(),
                    )
                }),
            })
            .collect();
        SaeManifoldMutableState {
            atoms,
            logits: self.assignment.logits.clone(),
            coords: self.assignment.coords.clone(),
            last_row_layout: self.last_row_layout.clone(),
        }
    }

    /// Whether the term is exactly at a saved fitted-model state.
    ///
    /// Evaluator-backed snapshots omit basis caches because they are deterministic
    /// functions of the coordinates, evaluator, and homotopy dial. Caller-managed
    /// snapshots carry their authoritative caches. Comparing those fields plus the
    /// decoder/logits is therefore an exact model-state identity test.
    pub(crate) fn matches_mutable_state(&self, snapshot: &SaeManifoldMutableState) -> bool {
        let atoms_match = self.atoms.len() == snapshot.atoms.len()
            && self
                .atoms
                .iter()
                .zip(snapshot.atoms.iter())
                .all(|(atom, saved)| {
                    let evaluator_matches = match (&atom.basis_evaluator, &saved.basis_evaluator) {
                        (Some(current), Some(expected)) => Arc::ptr_eq(current, expected),
                        (None, None) => true,
                        _ => false,
                    };
                    let second_jet_matches = match (&atom.basis_second_jet, &saved.basis_second_jet)
                    {
                        (Some(current), Some(expected)) => Arc::ptr_eq(current, expected),
                        (None, None) => true,
                        _ => false,
                    };
                    let decoder_frame_matches = match (&atom.decoder_frame, &saved.decoder_frame) {
                        (Some(current), Some(expected)) => {
                            current.frame() == expected.frame()
                                && current.gauge_singular_values()
                                    == expected.gauge_singular_values()
                        }
                        (None, None) => true,
                        _ => false,
                    };
                    atom.decoder_coefficients() == &saved.decoder_coefficients
                        && atom.chart_canonicalized == saved.chart_canonicalized
                        && atom.reduced_column_map == saved.reduced_column_map
                        && match &saved.caller_managed_basis {
                            Some((basis, jet)) => {
                                atom.basis_evaluator.is_none()
                                    && atom.basis_values == *basis
                                    && atom.basis_jacobian == *jet
                            }
                            None => atom.basis_evaluator.is_some(),
                        }
                        && decoder_frame_matches
                        && atom.smooth_penalty() == &saved.smooth_penalty
                        && atom.homotopy_eta.to_bits() == saved.homotopy_eta.to_bits()
                        && evaluator_matches
                        && second_jet_matches
                });
        let coords_match = self.assignment.coords.len() == snapshot.coords.len()
            && self
                .assignment
                .coords
                .iter()
                .zip(snapshot.coords.iter())
                .all(|(current, expected)| {
                    current.latent_id() == expected.latent_id()
                        && current.as_flat() == expected.as_flat()
                });
        let row_layout_matches = match (&self.last_row_layout, &snapshot.last_row_layout) {
            (Some(current), Some(expected)) => {
                current.active_atoms == expected.active_atoms
                    && current.coord_starts == expected.coord_starts
                    && current.coord_offsets_full == expected.coord_offsets_full
                    && current.coord_dims == expected.coord_dims
            }
            (None, None) => true,
            _ => false,
        };
        atoms_match
            && self.assignment.logits == snapshot.logits
            && coords_match
            && row_layout_matches
    }

    /// Restore the mutable state captured by [`Self::snapshot_mutable_state`].
    ///
    /// This is a total structural inverse. Cardinalities and row topology are
    /// validated first, then every atom is evaluated into detached prepared
    /// state at the snapshot evaluator's own width. Only after every fallible
    /// operation succeeds are atoms, logits, coordinates, and row layout
    /// replaced. A stale or incompatible snapshot therefore returns a typed
    /// invariant error without a broadcast, panic, fallback, or partial restore.
    pub(crate) fn restore_mutable_state(
        &mut self,
        snapshot: &SaeManifoldMutableState,
    ) -> Result<(), SaeMutableStateRestoreError> {
        let incompatible = |
            component: &'static str,
            expected: Vec<usize>,
            observed: Vec<usize>,
        | SaeMutableStateRestoreError::IncompatibleCardinality {
            component,
            expected,
            observed,
        };
        let k = self.atoms.len();
        if snapshot.atoms.len() != k {
            return Err(incompatible(
                "atom",
                vec![k],
                vec![snapshot.atoms.len()],
            ));
        }
        if self.assignment.coords.len() != k {
            return Err(incompatible(
                "live coordinate-block",
                vec![k],
                vec![self.assignment.coords.len()],
            ));
        }
        if snapshot.coords.len() != k {
            return Err(incompatible(
                "snapshot coordinate-block",
                vec![k],
                vec![snapshot.coords.len()],
            ));
        }
        if snapshot.logits.dim() != self.assignment.logits.dim() {
            return Err(incompatible(
                "logit shape",
                self.assignment.logits.shape().to_vec(),
                snapshot.logits.shape().to_vec(),
            ));
        }
        let n = snapshot.logits.nrows();
        for atom_idx in 0..k {
            let atom = &self.atoms[atom_idx];
            let coord = &snapshot.coords[atom_idx];
            if atom.n_obs() != n {
                return Err(incompatible(
                    "atom row",
                    vec![n],
                    vec![atom.n_obs()],
                ));
            }
            if coord.n_obs() != n || coord.latent_dim() != atom.latent_dim() {
                return Err(incompatible(
                    "coordinate shape",
                    vec![n, atom.latent_dim()],
                    vec![coord.n_obs(), coord.latent_dim()],
                ));
            }
        }

        if let Some(layout) = snapshot.last_row_layout.as_ref() {
            if layout.active_atoms.len() != n || layout.coord_starts.len() != n {
                return Err(incompatible(
                    "row-layout row",
                    vec![n, n],
                    vec![layout.active_atoms.len(), layout.coord_starts.len()],
                ));
            }
            if layout.coord_dims.len() != k || layout.coord_offsets_full.len() != k {
                return Err(incompatible(
                    "row-layout atom",
                    vec![k, k],
                    vec![layout.coord_dims.len(), layout.coord_offsets_full.len()],
                ));
            }
            let mut full_offset = 0usize;
            for atom_idx in 0..k {
                let expected_dim = snapshot.coords[atom_idx].latent_dim();
                if layout.coord_dims[atom_idx] != expected_dim
                    || layout.coord_offsets_full[atom_idx] != full_offset
                {
                    return Err(SaeMutableStateRestoreError::InvalidTopology {
                        component: "row layout".to_string(),
                        detail: format!(
                            "atom {atom_idx} has dim/offset ({}, {}), expected ({expected_dim}, {full_offset})",
                            layout.coord_dims[atom_idx],
                            layout.coord_offsets_full[atom_idx]
                        ),
                    });
                }
                full_offset += expected_dim;
            }
            for row in 0..n {
                let active = &layout.active_atoms[row];
                let starts = &layout.coord_starts[row];
                if starts.len() != active.len() {
                    return Err(incompatible(
                        "row-layout active block",
                        vec![active.len()],
                        vec![starts.len()],
                    ));
                }
                let mut compact_offset = 0usize;
                let mut previous = None;
                for (&atom_idx, &start) in active.iter().zip(starts.iter()) {
                    if atom_idx >= k || previous.is_some_and(|prior| prior >= atom_idx) {
                        return Err(SaeMutableStateRestoreError::InvalidTopology {
                            component: "row layout".to_string(),
                            detail: format!(
                                "row {row} active atoms are not strict sorted indices below {k}: {active:?}"
                            ),
                        });
                    }
                    if start != compact_offset {
                        return Err(SaeMutableStateRestoreError::InvalidTopology {
                            component: "row layout".to_string(),
                            detail: format!(
                                "row {row}, atom {atom_idx} starts at {start}, expected {compact_offset}"
                            ),
                        });
                    }
                    compact_offset += layout.coord_dims[atom_idx];
                    previous = Some(atom_idx);
                }
            }
        }

        let restored_logits = snapshot.logits.clone();
        let restored_coords = snapshot.coords.clone();
        let restored_row_layout = snapshot.last_row_layout.clone();
        let mut prepared = Vec::with_capacity(k);
        for atom_idx in 0..k {
            let coords = snapshot.coords[atom_idx].as_matrix();
            prepared.push(
                self.atoms[atom_idx]
                    .prepare_mutable_state_restore(&snapshot.atoms[atom_idx], coords.view())
                    .map_err(|detail| SaeMutableStateRestoreError::InvalidTopology {
                        component: format!("atom {atom_idx}"),
                        detail,
                    })?,
            );
        }

        // Commit is deliberately infallible. Every allocation, evaluator call,
        // shape check, and topology check completed above against detached state.
        for (atom_idx, restored) in prepared.into_iter().enumerate() {
            self.atoms[atom_idx].commit_prepared_mutable_state(restored);
        }
        self.assignment.logits = restored_logits;
        self.assignment.coords = restored_coords;
        self.last_row_layout = restored_row_layout;
        Ok(())
    }

    pub(crate) fn refresh_basis_from_current_coords(&mut self) -> Result<(), String> {
        let parallel = self.n_obs() >= SAE_LOSS_PARALLEL_ROW_MIN
            && self.k_atoms() > 1
            && rayon::current_thread_index().is_none();
        self.refresh_basis_from_current_coords_with_parallelism(parallel)
    }

    /// Refresh every atom's basis cache from its matching coordinate block.
    ///
    /// Atoms are independent: atom `k` reads only coordinate block `k` and
    /// writes only basis cache `k`. Rayon indexed collection preserves atom
    /// order, and errors are inspected serially afterward so the lowest-indexed
    /// failure remains deterministic. The explicit policy argument lets the
    /// parallelism-invariance regression exercise both paths without changing
    /// the process-global Rayon pool.
    pub(crate) fn refresh_basis_from_current_coords_with_parallelism(
        &mut self,
        parallel: bool,
    ) -> Result<(), String> {
        if self.atoms.len() != self.assignment.coords.len() {
            return Err(format!(
                "SaeManifoldTerm::refresh_basis_from_current_coords: {} atoms but {} coordinate blocks",
                self.atoms.len(),
                self.assignment.coords.len()
            ));
        }
        if parallel {
            use rayon::prelude::*;
            let outcomes: Vec<Result<(), String>> = self
                .atoms
                .par_iter_mut()
                .zip(self.assignment.coords.par_iter())
                .map(|(atom, coord)| {
                    with_nested_parallel(|| {
                        let coords = coord.as_matrix();
                        atom.refresh_basis(coords.view())
                    })
                })
                .collect();
            for outcome in outcomes {
                outcome?;
            }
        } else {
            for (atom, coord) in self.atoms.iter_mut().zip(&self.assignment.coords) {
                let coords = coord.as_matrix();
                atom.refresh_basis(coords.view())?;
            }
        }
        Ok(())
    }

    /// Retract every atom's coordinate block by its disjoint slice of a
    /// row-major Newton step, then optionally refresh that atom's basis cache.
    /// The indexed parallel path changes scheduling only: no atom reads or
    /// writes another atom's coordinates, evaluator, or cache, and no
    /// floating-point reduction crosses atom boundaries.
    fn apply_coordinate_step_from_rows<F>(
        &mut self,
        n: usize,
        q: usize,
        coord_offsets: &[usize],
        step_size: f64,
        delta_at: F,
        refresh_basis: bool,
        parallel: bool,
    ) -> Result<(), String>
    where
        F: Fn(usize, usize) -> f64 + Sync,
    {
        if self.atoms.len() != self.assignment.coords.len() {
            return Err(format!(
                "SaeManifoldTerm::apply_newton_step: {} atoms but {} coordinate blocks",
                self.atoms.len(),
                self.assignment.coords.len()
            ));
        }
        if coord_offsets.len() != self.atoms.len() {
            return Err(format!(
                "SaeManifoldTerm::apply_newton_step: {} coordinate offsets for {} atoms",
                coord_offsets.len(),
                self.atoms.len()
            ));
        }
        let update_atom = |atom_idx: usize,
                           atom: &mut SaeManifoldAtom,
                           coord: &mut LatentCoordValues,
                           nested_parallel: bool|
         -> Result<(), String> {
            let d = coord.latent_dim();
            let mut delta_coord = Array1::<f64>::zeros(n * d);
            for row in 0..n {
                let row_base = row * q + coord_offsets[atom_idx];
                for axis in 0..d {
                    delta_coord[row * d + axis] = step_size * delta_at(row, row_base + axis);
                }
            }
            coord.retract_flat_delta(delta_coord.view());
            if refresh_basis {
                let coords = coord.as_matrix();
                if nested_parallel {
                    with_nested_parallel(|| atom.refresh_basis(coords.view()))?;
                } else {
                    atom.refresh_basis(coords.view())?;
                }
            }
            Ok(())
        };

        if parallel {
            use rayon::prelude::*;
            let outcomes: Vec<Result<(), String>> = self
                .atoms
                .par_iter_mut()
                .zip(self.assignment.coords.par_iter_mut())
                .enumerate()
                .map(|(atom_idx, (atom, coord))| update_atom(atom_idx, atom, coord, true))
                .collect();
            for outcome in outcomes {
                outcome?;
            }
        } else {
            for (atom_idx, (atom, coord)) in self
                .atoms
                .iter_mut()
                .zip(self.assignment.coords.iter_mut())
                .enumerate()
            {
                update_atom(atom_idx, atom, coord, false)?;
            }
        }
        Ok(())
    }

    /// Add one flat full-decoder Newton step directly into the per-atom decoder
    /// matrices. Atom coefficient blocks are disjoint and the flat indexing is
    /// identical to [`Self::flatten_beta`], so the indexed parallel path is
    /// byte-identical while avoiding the old flatten/add/copy-back allocation.
    fn apply_decoder_step_from_flat(
        &mut self,
        delta_beta: ArrayView1<'_, f64>,
        step_size: f64,
        parallel: bool,
    ) -> Result<(), String> {
        let expected = self.beta_dim();
        if delta_beta.len() != expected {
            return Err(format!(
                "SaeManifoldTerm::apply_newton_step: full decoder step length {} != expected {expected}",
                delta_beta.len()
            ));
        }
        let p = self.output_dim();
        let offsets = self.beta_offsets();
        let update_atom = |atom_idx: usize, atom: &mut SaeManifoldAtom| {
            let m = atom.basis_size();
            let offset = offsets[atom_idx];
            for basis_col in 0..m {
                for out_col in 0..p {
                    let flat_idx = offset + basis_col * p + out_col;
                    atom.decoder_coefficients_mut()[[basis_col, out_col]] +=
                        step_size * delta_beta[flat_idx];
                }
            }
        };
        if parallel {
            use rayon::prelude::*;
            self.atoms
                .par_iter_mut()
                .enumerate()
                .for_each(|(atom_idx, atom)| update_atom(atom_idx, atom));
        } else {
            for (atom_idx, atom) in self.atoms.iter_mut().enumerate() {
                update_atom(atom_idx, atom);
            }
        }
        Ok(())
    }

    pub(crate) fn canonicalize_affine_gauge_after_accept(
        &mut self,
        rho: Option<&SaeManifoldRho>,
    ) -> Result<(), String> {
        for atom_idx in 0..self.k_atoms() {
            if !matches!(
                self.atoms[atom_idx].basis_kind(),
                SaeAtomBasisKind::Linear
                    | SaeAtomBasisKind::EuclideanPatch
                    | SaeAtomBasisKind::Duchon
                    | SaeAtomBasisKind::Poincare
            ) {
                continue;
            }
            self.canonicalize_atom_affine_gauge(atom_idx, rho)?;
        }
        Ok(())
    }

    pub(crate) fn canonicalize_atom_affine_gauge(
        &mut self,
        atom_idx: usize,
        rho: Option<&SaeManifoldRho>,
    ) -> Result<(), String> {
        let n = self.n_obs();
        let d = self.assignment.coords[atom_idx].latent_dim();
        if n == 0 || d == 0 {
            return Ok(());
        }
        let Some(evaluator) = self.atoms[atom_idx].basis_evaluator.as_ref() else {
            return Ok(());
        };
        let coords = self.assignment.coords[atom_idx].as_matrix();
        let weights = self.atom_affine_gauge_weights(atom_idx, rho)?;
        let weight_sum: f64 = weights.iter().sum();
        if !(weight_sum.is_finite() && weight_sum > 0.0) {
            return Ok(());
        }

        let mut shift = vec![0.0_f64; d];
        for row in 0..n {
            let w = weights[row];
            for axis in 0..d {
                shift[axis] += w * coords[[row, axis]];
            }
        }
        for value in &mut shift {
            *value /= weight_sum;
        }

        let mut scale = vec![1.0_f64; d];
        let mut changed = false;
        for axis in 0..d {
            let mut var = 0.0_f64;
            for row in 0..n {
                let centered = coords[[row, axis]] - shift[axis];
                var += weights[row] * centered * centered;
            }
            let rms = (var / weight_sum).sqrt();
            if rms.is_finite() && rms > 1.0e-12 {
                scale[axis] = rms;
            }
            if shift[axis].abs() > 1.0e-12 || (scale[axis] - 1.0).abs() > 1.0e-12 {
                changed = true;
            }
        }
        if !changed {
            return Ok(());
        }

        let Some(new_evaluator) = evaluator.affine_transformed_evaluator(
            &shift,
            &scale,
            self.atoms[atom_idx].basis_size(),
        )?
        else {
            return Ok(());
        };

        let mut new_coords = coords.clone();
        for row in 0..n {
            for axis in 0..d {
                new_coords[[row, axis]] = (coords[[row, axis]] - shift[axis]) / scale[axis];
            }
        }
        let (new_phi, new_jet) = if self.atoms[atom_idx].homotopy_eta == 1.0 {
            new_evaluator.evaluate(new_coords.view())?
        } else {
            let evaluated = new_evaluator
                .evaluate_phi_eta(new_coords.view(), self.atoms[atom_idx].homotopy_eta)?;
            (evaluated.phi, evaluated.jet)
        };
        let old_phi = self.atoms[atom_idx].basis_values.clone();
        if new_phi.dim() != old_phi.dim() {
            return Err(format!(
                "SaeManifoldTerm::canonicalize_atom_affine_gauge: transformed basis shape {:?} != {:?}",
                new_phi.dim(),
                old_phi.dim()
            ));
        }
        let transport = solve_basis_transport(new_phi.view(), old_phi.view())?;
        let old_decoder = self.atoms[atom_idx].decoder_coefficients().clone();
        let old_smooth_penalty = self.atoms[atom_idx].smooth_penalty().clone();
        let new_decoder = fast_ab(&transport, &old_decoder);
        let old_fit = fast_ab(&old_phi, &old_decoder);
        let new_fit = fast_ab(&new_phi, &new_decoder);
        let fit_scale = old_fit
            .iter()
            .chain(new_fit.iter())
            .fold(1.0_f64, |acc, &v| acc.max(v.abs()));
        let max_abs = old_fit
            .iter()
            .zip(new_fit.iter())
            .fold(0.0_f64, |acc, (&a, &b)| acc.max((a - b).abs()));
        if max_abs > 1.0e-8 * fit_scale {
            return Ok(());
        }

        let flat = Array1::from_iter(new_coords.iter().copied());
        self.assignment.coords[atom_idx].set_flat(flat.view());
        let atom = &mut self.atoms[atom_idx];
        let base: Arc<dyn SaeBasisEvaluator> = new_evaluator.clone();
        atom.basis_evaluator = Some(base);
        atom.basis_second_jet = Some(new_evaluator);
        let transported_penalty =
            transport_smooth_penalty_for_decoder(transport.view(), old_smooth_penalty.view())?;
        atom.install_reparameterized_basis(
            new_phi,
            new_jet,
            new_decoder,
            transported_penalty,
        )?;
        Ok(())
    }

    pub(crate) fn atom_affine_gauge_weights(
        &self,
        atom_idx: usize,
        rho: Option<&SaeManifoldRho>,
    ) -> Result<Array1<f64>, String> {
        let n = self.n_obs();
        let mut weights = Array1::<f64>::zeros(n);
        // #1557 — reuse a single K-sized scratch row across all N rows instead of
        // allocating a fresh `Array1` per row. The row is consumed immediately
        // (only `assignments[atom_idx]` is read), so reuse is alias-free.
        let mut scratch = vec![0.0_f64; self.k_atoms()];
        for row in 0..n {
            match rho {
                Some(_) => self
                    .assignment
                    .try_assignments_row_into(row, &mut scratch)?,
                None => {
                    let a = self.assignment.try_assignments_row(row)?;
                    scratch.copy_from_slice(a.as_slice().expect("contiguous assignment row"));
                }
            };
            let assignments = &scratch;
            let mut w = assignments[atom_idx].max(0.0);
            if let Some(row_weights) = self.row_loss_weights.as_ref() {
                w *= row_weights[row].max(0.0);
            }
            weights[row] = if w.is_finite() { w } else { 0.0 };
        }
        Ok(weights)
    }

    /// #1019 stage 1 — post-fit arc-length (unit-speed) chart canonicalization
    /// for every fitted `d = 1` atom with circle or interval topology.
    ///
    /// Image-frozen and gauge-legal: each eligible atom's latent chart is
    /// replaced by the canonical representative of its `Diff(M)` orbit — the
    /// unit-speed (arc-length) chart for `d = 1` circle/interval atoms, the
    /// minimum-isometry-defect flow chart for `d = 2` torus atoms (#1019
    /// stage 2) — and the decoder is recomposed by exact least squares so the
    /// decoded image is unchanged
    /// ([`crate::chart_canonicalization`]). Atoms whose basis
    /// cannot absorb the reparameterized image within the recomposition
    /// tolerance are left untouched (honest fallback, recorded by the flag
    /// staying `false`).
    ///
    /// The whole pass is additionally gated on the penalized objective: the
    /// canonical state is kept only when the same scalar the line search
    /// minimized does not increase beyond the image-invariance tolerance. The
    /// structural basis change transports `S_ref` by congruence, so the declared
    /// function seminorm is preserved; a genuine increase means that transport
    /// went numerically wrong and the fitted state is restored verbatim.
    ///
    /// Runs automatically from `into_fitted` after the joint fit converges,
    /// before the payload / residual-gauge certificate is assembled — never
    /// a flag (magic-by-default).
    pub fn canonicalize_charts_post_fit(
        &mut self,
        target: ArrayView2<'_, f64>,
        rho: &SaeManifoldRho,
        analytic_penalties: Option<&AnalyticPenaltyRegistry>,
    ) -> Result<(), String> {
        use crate::chart_canonicalization::{CHART_RECOMPOSITION_REL_TOL, CanonicalChartTopology};

        self.assignment.validate_rho_domain(rho)?;

        // #F3 — capture the PRE-canonicalization coordinate spread per atom/axis.
        // The ARD precisions are stamped AFTER the reparameterization below (see the
        // end of this fn), MOMENT-MATCHED into the canonical chart: a coordinate
        // prior `½ α t²` whose `α` was REML-calibrated to the FIT-chart coordinate
        // spread must preserve its mass against the realized spread, so
        // `α' = α · spread_pre / spread_post`. This is exact for any linear rescale
        // `t' = c·t` (`α/c²` — e.g. the affine `d = 1` arc-length map) and is the
        // natural second-moment-matched correction for the nonlinear `d = 2` flows;
        // non-canonicalized atoms have `spread_post == spread_pre`, so the ratio is
        // 1 and `α` is unchanged. Periodic axes use the circular variance.
        let ard_pre_spread: Vec<Vec<f64>> = (0..self.k_atoms())
            .map(|k| {
                let coords = self.assignment.coords[k].as_matrix();
                let periods = self.assignment.coords[k].effective_axis_periods();
                (0..coords.ncols())
                    .map(|axis| {
                        axis_coordinate_spread(
                            coords.view(),
                            axis,
                            periods.get(axis).copied().flatten(),
                        )
                    })
                    .collect()
            })
            .collect();

        /// Which canonical-representative construction applies to an atom:
        /// arc length for `d = 1` (#1019 stage 1), the minimum-isometry-defect
        /// flow for `d = 2` torus atoms (#1019 stage 2), and the same flow
        /// against the flat reference for `d = 2` free/patch atoms (#1019
        /// free-chart arm — a contractible Euclidean patch admits a global
        /// polynomial flow basis, no hairy-ball obstruction).
        enum ChartPlan {
            UnitSpeed(CanonicalChartTopology),
            TorusFlow { period: f64 },
            PatchFlow,
            SphereFlow,
        }
        let mut eligible: Vec<(usize, ChartPlan)> = Vec::new();
        for atom_idx in 0..self.k_atoms() {
            let atom = &self.atoms[atom_idx];
            if atom.basis_evaluator.is_none()
                || atom.homotopy_eta != 1.0
                || self.assignment.coords[atom_idx].latent_dim() != atom.latent_dim()
            {
                continue;
            }
            // Same fraction-of-period convention as the latent manifold
            // wiring (`SaeAtomBasisKind::latent_manifold`): the harmonic
            // evaluators read `t` as a fraction of one period.
            let plan = match (atom.basis_kind(), atom.latent_dim()) {
                (SaeAtomBasisKind::Periodic | SaeAtomBasisKind::Torus, 1) => {
                    ChartPlan::UnitSpeed(CanonicalChartTopology::Circle { period: 1.0 })
                }
                (
                    SaeAtomBasisKind::Linear
                    | SaeAtomBasisKind::Duchon
                    | SaeAtomBasisKind::EuclideanPatch,
                    1,
                ) => ChartPlan::UnitSpeed(CanonicalChartTopology::Interval),
                // #1019 stage 2: d = 2 torus atoms pin to the
                // minimum-isometry-defect flow representative.
                (SaeAtomBasisKind::Torus, 2) => ChartPlan::TorusFlow { period: 1.0 },
                // #1019 free-chart arm: d = 2 free/patch (Euclidean-patch)
                // atoms admit a global polynomial flow basis (contractible —
                // no hairy ball), so they pin to the flat uniform-speed
                // minimum-anisotropy-defect representative.
                (
                    SaeAtomBasisKind::Linear
                    | SaeAtomBasisKind::Duchon
                    | SaeAtomBasisKind::EuclideanPatch,
                    2,
                ) => ChartPlan::PatchFlow,
                // #1019 sphere arm: d = 2 sphere atoms pin to the
                // minimum-isometry-defect conformal-boost flow against the
                // round-sphere reference. The pin is scoped to data away from
                // the poles (the `1/cos lat` boost singularity — the residue of
                // the hairy-ball obstruction); an at-pole chart is honestly
                // refused by the reparameterization (Ok(false) → left as
                // fitted) rather than pinned with a near-singular flow.
                (SaeAtomBasisKind::Sphere, 2) => ChartPlan::SphereFlow,
                // d = 1 never matches Sphere; Precomputed bases carry no
                // evaluator semantics to re-express the image in.
                _ => continue,
            };
            eligible.push((atom_idx, plan));
        }

        // #1019 sphere arm: d = 2 sphere atoms are now first-class flow-pinned
        // above (ChartPlan::SphereFlow → the round-sphere conformal-boost flow),
        // so the isometry defect is the objective the pin descends rather than a
        // read-only side log. Data inside the pole-band guard (the `1/cos lat`
        // boost singularity — the scoped residue of the hairy-ball obstruction)
        // is honestly refused by the reparameterization and left as fitted.

        // #1227 — canonicalize charts FIRST, then compute every
        // chart-dependent diagnostic (Θ, LOAO ΔEV, hybrid split). The chart
        // canonicalization below is a (generally nonlinear) reparameterization
        // of each eligible atom's latent coordinate: a straight line `b0 + (t −
        // t̄) b1` fit in the OLD coordinate `t` is NOT a straight line in the
        // canonical coordinate `u`. The hybrid split stores exactly such an
        // `AtomLinearImage` and later evaluates it in the CURRENT coordinate, so
        // computing the split before canonicalization records the linear image
        // in a coordinate system that is about to be replaced. Run the
        // reparameterization here, then the diagnostics, so every stored
        // chart-dependent quantity is expressed in the canonical coordinate.
        if !eligible.is_empty() {
            let snapshot = self.snapshot_mutable_state();
            let pre_total = self.penalized_objective_total(target, rho, analytic_penalties, 1.0)?;

            let mut any_changed = false;
            for (atom_idx, plan) in &eligible {
                let outcome = match plan {
                    ChartPlan::UnitSpeed(topology) => {
                        self.canonicalize_atom_unit_speed_chart(*atom_idx, topology)
                    }
                    ChartPlan::TorusFlow { period } => {
                        self.canonicalize_atom_torus_flow_chart(*atom_idx, *period)
                    }
                    ChartPlan::PatchFlow => self.canonicalize_atom_patch_flow_chart(*atom_idx),
                    ChartPlan::SphereFlow => self.canonicalize_atom_sphere_flow_chart(*atom_idx),
                };
                match outcome {
                    Ok(changed) => any_changed |= changed,
                    Err(err) => {
                        self.restore_mutable_state(&snapshot)?;
                        return Err(err);
                    }
                }
            }
            if any_changed {
                // Keep the canonical state only when the optimized scalar is
                // preserved within the image-invariance tolerance (the data fit
                // moved by at most the certified recomposition residual; the
                // intrinsic penalty is reparameterization-invariant, transported
                // exactly).
                let canonical_total =
                    self.penalized_objective_total(target, rho, analytic_penalties, 1.0);
                let keep = match canonical_total {
                    Ok(total) => {
                        total.is_finite()
                            && total
                                <= pre_total + CHART_RECOMPOSITION_REL_TOL * (1.0 + pre_total.abs())
                    }
                    Err(_) => false,
                };
                if !keep {
                    self.restore_mutable_state(&snapshot)?;
                }
            }
        }

        // #1026 EV-vs-Θ measurement: log each d = 1 atom's fitted TURNING
        // `Θ = ∫κ ds` (integrated curvature of its decoded curve). A linear SAE
        // shatters a curved feature of turning Θ into `N(ε) ≈ Θ/(2√(2ε))` rank-1
        // atoms at relative error ε, so the curved win is concentrated on high-Θ
        // features and vanishes as Θ → 0. Pairing this with the atom's EV
        // contribution (held-out reconstruction) is the discriminating
        // hybrid-vs-shatter signal: a Θ ≈ 0 atom that still earns EV is a linear
        // direction wearing a curved basis; a high-Θ atom earning EV is a genuine
        // curved family. Pure read-only diagnostic, never mutates the atom.
        //
        // The held-out EV half of the pair is the per-atom leave-one-atom-out
        // (LOAO) explained-variance drop `ΔEV_k` (see
        // [`Self::per_atom_loao_explained_variance`]): the EV lost when atom `k`
        // is withheld from the assembled reconstruction. Logging `(Θ, ΔEV)`
        // together per d = 1 atom is the discriminating EV-vs-Θ signal — a
        // Θ ≈ 0 atom earning a large ΔEV is a linear-tail direction, a high-Θ
        // atom earning a large ΔEV is a genuine curved family.
        let loao_ev = self
            .per_atom_loao_explained_variance(target, rho)
            .unwrap_or_else(|err| {
                log::warn!("[#1026] per-atom LOAO EV unavailable: {err}");
                vec![None; self.k_atoms()]
            });
        for atom_idx in 0..self.k_atoms() {
            let atom = &self.atoms[atom_idx];
            if atom.latent_dim() != 1
                || atom.homotopy_eta != 1.0
                || self.assignment.coords[atom_idx].latent_dim() != atom.latent_dim()
            {
                continue;
            }
            let Some(evaluator) = atom.basis_evaluator.as_ref().cloned() else {
                continue;
            };
            let coords = self.assignment.coords[atom_idx].as_matrix();
            let row_coords = coords.column(0);
            let dev = loao_ev
                .get(atom_idx)
                .copied()
                .flatten()
                .map_or_else(|| "unavailable".to_string(), |d| format!("{d:.6e}"));
            match crate::chart_canonicalization::d1_atom_fitted_turning(
                evaluator.as_ref(),
                atom.decoder_coefficients().view(),
                row_coords,
            ) {
                Ok(Some(theta)) => log::info!(
                    "[#1026] atom '{}' fitted turning Θ = {theta:.6e} rad, \
                     training LOAO ΔEV = {dev} \
                     (∫κ ds; 0 = linear-tail direction, 2π = full curved loop; \
                     Θ≈0 + large ΔEV = linear direction, high-Θ + large ΔEV = \
                     genuine curved family — the hybrid-vs-shatter signal)",
                    atom.name
                ),
                Ok(None) => log::info!(
                    "[#1026] atom '{}' fitted turning unavailable, training LOAO ΔEV = {dev} \
                     (no analytic second jet or degenerate curve)",
                    atom.name
                ),
                Err(err) => {
                    log::warn!("[#1026] atom '{}' fitted turning errored: {err}", atom.name)
                }
            }
        }

        // #1026 — make the curved-vs-linear split LOAD-BEARING. The Θ log above
        // is the read-only diagnostic; here we adjudicate, per eligible d = 1
        // atom, the fitted curved image against its straight (linear
        // special-case) sub-model on the common rank-aware quasi-Laplace score
        // scale and record the verdict. This is closed-form per atom (the
        // collapsed linear lane — exact penalized LS through the fitted decoded
        // points), so it does NOT re-enter the broken euclidean outer fit path
        // (#1051): no continuation spine, no joint Hessian. The dictionary now
        // honestly reports which atoms earn their curvature and which collapse to
        // the linear tail.
        match self.compute_hybrid_split_report(rho, Some(target)) {
            Ok(report) => {
                if let Some(report) = &report {
                    log::info!(
                        "[#1026] hybrid split: {} curved / {} linear atoms (Σ NLE = {:.6e})",
                        report.selection.curved_atom_count,
                        report.selection.linear_atom_count(),
                        report.selection.total_negative_log_evidence,
                    );
                }
                self.hybrid_split_report = report;
            }
            Err(err) => {
                log::warn!("[#1026] hybrid split report unavailable: {err}");
                self.hybrid_split_report = None;
            }
        }

        // #F3 — stamp the MOMENT-MATCHED ARD precisions from the TERMINAL rho, now
        // that the reparameterization above has settled the canonical chart the
        // encode uses (see the pre-spread capture at the top of this fn).
        // `α_a = exp(log_ard[k][a])` is the REML precision in the FIT chart;
        // `α'_a = α_a · spread_pre / spread_post` re-expresses it against the
        // canonical chart's realized coordinate spread. Uses the identical
        // exact exponential map as the fit's `ArdAxisPrior`; an atom with no
        // fitted coordinate prior (`rho.log_ard[k]` empty) is left `None`
        // (prior-free encode, unchanged). A degenerate/non-finite spread on either
        // side leaves that axis' `α` untransformed. A malformed rho is rejected
        // by the structural precision-table certificate before finalization.
        let ard_precisions = self.validated_ard_precisions(rho)?;
        for atom_idx in 0..self.k_atoms() {
            let log_ard = &rho.log_ard[atom_idx];
            self.atoms[atom_idx].ard_precisions = if log_ard.is_empty() {
                None
            } else {
                let coords = self.assignment.coords[atom_idx].as_matrix();
                let periods = self.assignment.coords[atom_idx].effective_axis_periods();
                let pre = &ard_pre_spread[atom_idx];
                let stamped: Array1<f64> = (0..log_ard.len())
                    .map(|axis| {
                        let alpha = ard_precisions[atom_idx][axis];
                        let sp_pre = pre.get(axis).copied().unwrap_or(f64::NAN);
                        let sp_post = axis_coordinate_spread(
                            coords.view(),
                            axis,
                            periods.get(axis).copied().flatten(),
                        );
                        if sp_pre.is_finite()
                            && sp_post.is_finite()
                            && sp_pre > ARD_SPREAD_FLOOR
                            && sp_post > ARD_SPREAD_FLOOR
                        {
                            alpha * sp_pre / sp_post
                        } else {
                            alpha
                        }
                    })
                    .collect();
                Some(stamped)
            };
        }

        Ok(())
    }

    /// Apply the arc-length reparameterization to one eligible `d = 1` atom.
    /// Returns `Ok(true)` when the atom was canonicalized, `Ok(false)` on an
    /// honest skip (degenerate chart, basis not closed under the
    /// reparameterization, or per-row image drift above tolerance).
    pub(crate) fn canonicalize_atom_unit_speed_chart(
        &mut self,
        atom_idx: usize,
        topology: &crate::chart_canonicalization::CanonicalChartTopology,
    ) -> Result<bool, String> {
        use crate::chart_canonicalization::{CHART_RECOMPOSITION_REL_TOL, unit_speed_retraction};
        let n = self.n_obs();
        if n == 0 {
            return Ok(false);
        }
        let Some(evaluator) = self.atoms[atom_idx].basis_evaluator.as_ref().cloned() else {
            return Ok(false);
        };
        let coords = self.assignment.coords[atom_idx].as_matrix();
        let row_coords = coords.column(0).to_owned();
        let Some(repar) = unit_speed_retraction(
            evaluator.as_ref(),
            self.atoms[atom_idx].decoder_coefficients().view(),
            row_coords.view(),
            topology,
        )?
        else {
            return Ok(false);
        };

        // Per-row basis/jet at the canonical coordinates.
        let mut new_coords = Array2::<f64>::zeros((n, 1));
        for row in 0..n {
            new_coords[[row, 0]] = repar.new_row_coords[row];
        }
        let (new_phi, new_jet) = if self.atoms[atom_idx].homotopy_eta == 1.0 {
            evaluator.evaluate(new_coords.view())?
        } else {
            let evaluated =
                evaluator.evaluate_phi_eta(new_coords.view(), self.atoms[atom_idx].homotopy_eta)?;
            (evaluated.phi, evaluated.jet)
        };
        if new_phi.dim() != self.atoms[atom_idx].basis_values.dim()
            || new_jet.dim() != self.atoms[atom_idx].basis_jacobian.dim()
        {
            return Err(format!(
                "SaeManifoldTerm::canonicalize_atom_unit_speed_chart: canonical basis {:?} / jet {:?} must match the fitted shapes {:?} / {:?}",
                new_phi.dim(),
                new_jet.dim(),
                self.atoms[atom_idx].basis_values.dim(),
                self.atoms[atom_idx].basis_jacobian.dim()
            ));
        }

        // Per-row image-invariance gate: the grid gate certified the curve at
        // the audit nodes; this certifies it at the coordinates the fit
        // actually sits on. Same honest-fallback contract.
        let old_fit = fast_ab(
            &self.atoms[atom_idx].basis_values,
            self.atoms[atom_idx].decoder_coefficients(),
        );
        let new_fit = fast_ab(&new_phi, &repar.new_decoder);
        let mut fit_scale = 0.0_f64;
        let mut max_abs = 0.0_f64;
        for (a, b) in old_fit.iter().zip(new_fit.iter()) {
            fit_scale = fit_scale.max(a.abs()).max(b.abs());
            max_abs = max_abs.max((a - b).abs());
        }
        if !(fit_scale.is_finite() && max_abs.is_finite()) {
            return Ok(false);
        }
        if fit_scale > 0.0 && max_abs > CHART_RECOMPOSITION_REL_TOL * fit_scale {
            return Ok(false);
        }

        // Commit: canonical coordinates, basis, decoder, and the congruence-
        // transported smoothness Gram (`B̃ᵀ S̃ B̃ = Bᵀ S B`, same as the affine
        // gauge pass).
        let old_smooth_penalty = self.atoms[atom_idx].smooth_penalty().clone();
        let flat = Array1::from_iter(new_coords.iter().copied());
        self.assignment.coords[atom_idx].set_flat(flat.view());
        let atom = &mut self.atoms[atom_idx];
        let transported_penalty = transport_smooth_penalty_for_decoder(
            repar.decoder_transport.view(),
            old_smooth_penalty.view(),
        )?;
        atom.install_reparameterized_basis(
            new_phi,
            new_jet,
            repar.new_decoder,
            transported_penalty,
        )?;
        atom.chart_canonicalized = true;
        Ok(true)
    }

    /// #2022 — the `d = 1` arc-length canonical-chart topology for one atom, or
    /// `None` when the atom has no unit-speed chart (no evaluator, an active
    /// curvature homotopy, a coord/atom latent-dim mismatch, or `d ≠ 1`). Same
    /// selection as `canonicalize_charts_post_fit`'s `ChartPlan::UnitSpeed` arm.
    pub(crate) fn d1_unit_speed_topology(
        &self,
        atom_idx: usize,
    ) -> Option<crate::chart_canonicalization::CanonicalChartTopology> {
        use crate::chart_canonicalization::CanonicalChartTopology;
        let atom = &self.atoms[atom_idx];
        if atom.basis_evaluator.is_none()
            || atom.homotopy_eta != 1.0
            || self.assignment.coords[atom_idx].latent_dim() != atom.latent_dim()
        {
            return None;
        }
        match (atom.basis_kind(), atom.latent_dim()) {
            (SaeAtomBasisKind::Periodic | SaeAtomBasisKind::Torus, 1) => {
                Some(CanonicalChartTopology::Circle { period: 1.0 })
            }
            (
                SaeAtomBasisKind::Linear
                | SaeAtomBasisKind::Duchon
                | SaeAtomBasisKind::EuclideanPatch,
                1,
            ) => Some(CanonicalChartTopology::Interval),
            _ => None,
        }
    }

    /// #2022 — enforce unit-speed charts IN-LOOP: at a chart-refresh boundary,
    /// re-gauge every `d = 1` atom to its arc-length representative via the exact,
    /// image-frozen retraction
    /// ([`crate::chart_canonicalization::unit_speed_retraction`], applied through
    /// [`Self::canonicalize_atom_unit_speed_chart`]). Image-frozen ⇒ the data-fit
    /// and intrinsic-smoothness objective are untouched; the ARD coordinate prior
    /// re-evaluates at the canonical chart (the term that pins the residual gauge to
    /// `t → ±t + c`). MUST NOT be called inside a line search — it changes the ARD
    /// objective term, which would break Armijo bookkeeping. Runs post-acceptance at
    /// the same cadence as [`Self::enforce_active_mass_guard`] /
    /// [`Self::enforce_decoder_norm_guard`]. Returns the number of atoms re-gauged.
    pub(crate) fn retract_unit_speed_charts_in_loop(&mut self) -> Result<usize, String> {
        let mut retracted = 0usize;
        for atom_idx in 0..self.atoms.len() {
            let Some(topology) = self.d1_unit_speed_topology(atom_idx) else {
                continue;
            };
            if self.canonicalize_atom_unit_speed_chart(atom_idx, &topology)? {
                retracted += 1;
            }
        }
        Ok(retracted)
    }

    /// Apply the minimum-isometry-defect flow reparameterization (#1019
    /// stage 2) to one eligible `d = 2` torus atom. Returns `Ok(true)` when
    /// the atom was canonicalized, `Ok(false)` on an honest skip (degenerate
    /// or already-canonical chart, only folded/non-improving flow candidates,
    /// basis not closed under the reparameterization, or per-row image drift
    /// above tolerance).
    pub(crate) fn canonicalize_atom_torus_flow_chart(
        &mut self,
        atom_idx: usize,
        period: f64,
    ) -> Result<bool, String> {
        use crate::chart_canonicalization::{
            CHART_RECOMPOSITION_REL_TOL, torus_isometry_flow_reparameterization,
        };
        let n = self.n_obs();
        if n == 0 {
            return Ok(false);
        }
        let Some(evaluator) = self.atoms[atom_idx].basis_evaluator.as_ref().cloned() else {
            return Ok(false);
        };
        let coords = self.assignment.coords[atom_idx].as_matrix();
        let Some(repar) = torus_isometry_flow_reparameterization(
            evaluator.as_ref(),
            self.atoms[atom_idx].decoder_coefficients().view(),
            coords.view(),
            period,
        )?
        else {
            return Ok(false);
        };

        // Per-row basis/jet at the canonical coordinates (eligibility pins
        // `homotopy_eta == 1.0`, so the plain evaluate IS the dialed path).
        let new_coords = repar.new_row_coords.clone();
        let (new_phi, new_jet) = evaluator.evaluate(new_coords.view())?;
        if new_phi.dim() != self.atoms[atom_idx].basis_values.dim()
            || new_jet.dim() != self.atoms[atom_idx].basis_jacobian.dim()
        {
            return Err(format!(
                "SaeManifoldTerm::canonicalize_atom_torus_flow_chart: canonical basis {:?} / jet {:?} must match the fitted shapes {:?} / {:?}",
                new_phi.dim(),
                new_jet.dim(),
                self.atoms[atom_idx].basis_values.dim(),
                self.atoms[atom_idx].basis_jacobian.dim()
            ));
        }

        // Per-row image-invariance gate: the audit grid certified the image
        // at the transport nodes; this certifies it at the coordinates the
        // fit actually sits on. Same honest-fallback contract as d = 1.
        let old_fit = fast_ab(
            &self.atoms[atom_idx].basis_values,
            self.atoms[atom_idx].decoder_coefficients(),
        );
        let new_fit = fast_ab(&new_phi, &repar.new_decoder);
        let mut fit_scale = 0.0_f64;
        let mut max_abs = 0.0_f64;
        for (a, b) in old_fit.iter().zip(new_fit.iter()) {
            fit_scale = fit_scale.max(a.abs()).max(b.abs());
            max_abs = max_abs.max((a - b).abs());
        }
        if !(fit_scale.is_finite() && max_abs.is_finite()) {
            return Ok(false);
        }
        if fit_scale > 0.0 && max_abs > CHART_RECOMPOSITION_REL_TOL * fit_scale {
            return Ok(false);
        }

        // Commit: canonical coordinates, basis, decoder, and the congruence-
        // transported smoothness Gram (`B̃ᵀ S̃ B̃ = Bᵀ S B`, same as the affine
        // gauge pass and the d = 1 path).
        let old_smooth_penalty = self.atoms[atom_idx].smooth_penalty().clone();
        let flat = Array1::from_iter(new_coords.iter().copied());
        self.assignment.coords[atom_idx].set_flat(flat.view());
        let atom = &mut self.atoms[atom_idx];
        let transported_penalty = transport_smooth_penalty_for_decoder(
            repar.decoder_transport.view(),
            old_smooth_penalty.view(),
        )?;
        atom.install_reparameterized_basis(
            new_phi,
            new_jet,
            repar.new_decoder,
            transported_penalty,
        )?;
        atom.chart_canonicalized = true;
        Ok(true)
    }

    /// Apply the minimum-isometry-defect flow reparameterization against the
    /// flat reference (#1019 free-chart arm) to one eligible `d = 2` free/patch
    /// (Euclidean-patch) atom. Returns `Ok(true)` when the atom was
    /// canonicalized, `Ok(false)` on an honest skip (degenerate or
    /// already-canonical chart, only folded/non-improving flow candidates,
    /// basis not closed under the reparameterization, or per-row image drift
    /// above tolerance).
    pub(crate) fn canonicalize_atom_patch_flow_chart(
        &mut self,
        atom_idx: usize,
    ) -> Result<bool, String> {
        use crate::chart_canonicalization::{
            CHART_RECOMPOSITION_REL_TOL, patch_isometry_flow_reparameterization,
        };
        let n = self.n_obs();
        if n == 0 {
            return Ok(false);
        }
        let Some(evaluator) = self.atoms[atom_idx].basis_evaluator.as_ref().cloned() else {
            return Ok(false);
        };
        let coords = self.assignment.coords[atom_idx].as_matrix();
        let Some(repar) = patch_isometry_flow_reparameterization(
            evaluator.as_ref(),
            self.atoms[atom_idx].decoder_coefficients().view(),
            coords.view(),
        )?
        else {
            return Ok(false);
        };

        // Per-row basis/jet at the canonical coordinates (eligibility pins
        // `homotopy_eta == 1.0`, so the plain evaluate IS the dialed path).
        let new_coords = repar.new_row_coords.clone();
        let (new_phi, new_jet) = evaluator.evaluate(new_coords.view())?;
        if new_phi.dim() != self.atoms[atom_idx].basis_values.dim()
            || new_jet.dim() != self.atoms[atom_idx].basis_jacobian.dim()
        {
            return Err(format!(
                "SaeManifoldTerm::canonicalize_atom_patch_flow_chart: canonical basis {:?} / jet {:?} must match the fitted shapes {:?} / {:?}",
                new_phi.dim(),
                new_jet.dim(),
                self.atoms[atom_idx].basis_values.dim(),
                self.atoms[atom_idx].basis_jacobian.dim()
            ));
        }

        // Per-row image-invariance gate: the audit grid certified the image at
        // the transport nodes; this certifies it at the coordinates the fit
        // actually sits on. Same honest-fallback contract as the torus path.
        let old_fit = fast_ab(
            &self.atoms[atom_idx].basis_values,
            self.atoms[atom_idx].decoder_coefficients(),
        );
        let new_fit = fast_ab(&new_phi, &repar.new_decoder);
        let mut fit_scale = 0.0_f64;
        let mut max_abs = 0.0_f64;
        for (a, b) in old_fit.iter().zip(new_fit.iter()) {
            fit_scale = fit_scale.max(a.abs()).max(b.abs());
            max_abs = max_abs.max((a - b).abs());
        }
        if !(fit_scale.is_finite() && max_abs.is_finite()) {
            return Ok(false);
        }
        if fit_scale > 0.0 && max_abs > CHART_RECOMPOSITION_REL_TOL * fit_scale {
            return Ok(false);
        }

        // Commit: canonical coordinates, basis, decoder, and the congruence-
        // transported smoothness Gram (`B̃ᵀ S̃ B̃ = Bᵀ S B`, same as every other
        // canonicalization path).
        let old_smooth_penalty = self.atoms[atom_idx].smooth_penalty().clone();
        let flat = Array1::from_iter(new_coords.iter().copied());
        self.assignment.coords[atom_idx].set_flat(flat.view());
        let atom = &mut self.atoms[atom_idx];
        let transported_penalty = transport_smooth_penalty_for_decoder(
            repar.decoder_transport.view(),
            old_smooth_penalty.view(),
        )?;
        atom.install_reparameterized_basis(
            new_phi,
            new_jet,
            repar.new_decoder,
            transported_penalty,
        )?;
        atom.chart_canonicalized = true;
        Ok(true)
    }

    /// Apply the minimum-isometry-defect conformal-boost flow reparameterization
    /// against the round-sphere reference (#1019 sphere arm) to one eligible
    /// `d = 2` sphere (`S²`) atom. Returns `Ok(true)` when the atom was
    /// canonicalized, `Ok(false)` on an honest skip (degenerate or
    /// already-canonical chart, data inside the pole-band guard, only
    /// folded/non-improving flow candidates, basis not closed under the
    /// reparameterization, or per-row image drift above tolerance).
    pub(crate) fn canonicalize_atom_sphere_flow_chart(
        &mut self,
        atom_idx: usize,
    ) -> Result<bool, String> {
        use crate::chart_canonicalization::{
            CHART_RECOMPOSITION_REL_TOL, sphere_isometry_flow_reparameterization,
        };
        let n = self.n_obs();
        if n == 0 {
            return Ok(false);
        }
        let Some(evaluator) = self.atoms[atom_idx].basis_evaluator.as_ref().cloned() else {
            return Ok(false);
        };
        let coords = self.assignment.coords[atom_idx].as_matrix();
        let Some(repar) = sphere_isometry_flow_reparameterization(
            evaluator.as_ref(),
            self.atoms[atom_idx].decoder_coefficients().view(),
            coords.view(),
        )?
        else {
            return Ok(false);
        };

        // Per-row basis/jet at the canonical coordinates (eligibility pins
        // `homotopy_eta == 1.0`, so the plain evaluate IS the dialed path).
        let new_coords = repar.new_row_coords.clone();
        let (new_phi, new_jet) = evaluator.evaluate(new_coords.view())?;
        if new_phi.dim() != self.atoms[atom_idx].basis_values.dim()
            || new_jet.dim() != self.atoms[atom_idx].basis_jacobian.dim()
        {
            return Err(format!(
                "SaeManifoldTerm::canonicalize_atom_sphere_flow_chart: canonical basis {:?} / jet {:?} must match the fitted shapes {:?} / {:?}",
                new_phi.dim(),
                new_jet.dim(),
                self.atoms[atom_idx].basis_values.dim(),
                self.atoms[atom_idx].basis_jacobian.dim()
            ));
        }

        // Per-row image-invariance gate: the audit grid certified the image at
        // the transport nodes; this certifies it at the coordinates the fit
        // actually sits on. Same honest-fallback contract as the torus path.
        let old_fit = fast_ab(
            &self.atoms[atom_idx].basis_values,
            self.atoms[atom_idx].decoder_coefficients(),
        );
        let new_fit = fast_ab(&new_phi, &repar.new_decoder);
        let mut fit_scale = 0.0_f64;
        let mut max_abs = 0.0_f64;
        for (a, b) in old_fit.iter().zip(new_fit.iter()) {
            fit_scale = fit_scale.max(a.abs()).max(b.abs());
            max_abs = max_abs.max((a - b).abs());
        }
        if !(fit_scale.is_finite() && max_abs.is_finite()) {
            return Ok(false);
        }
        if fit_scale > 0.0 && max_abs > CHART_RECOMPOSITION_REL_TOL * fit_scale {
            return Ok(false);
        }

        // Commit: canonical coordinates, basis, decoder, and the congruence-
        // transported smoothness Gram (`B̃ᵀ S̃ B̃ = Bᵀ S B`, same as every other
        // canonicalization path).
        let old_smooth_penalty = self.atoms[atom_idx].smooth_penalty().clone();
        let flat = Array1::from_iter(new_coords.iter().copied());
        self.assignment.coords[atom_idx].set_flat(flat.view());
        let atom = &mut self.atoms[atom_idx];
        let transported_penalty = transport_smooth_penalty_for_decoder(
            repar.decoder_transport.view(),
            old_smooth_penalty.view(),
        )?;
        atom.install_reparameterized_basis(
            new_phi,
            new_jet,
            repar.new_decoder,
            transported_penalty,
        )?;
        atom.chart_canonicalized = true;
        Ok(true)
    }

    /// The iterate scale `1 + ‖(logits, coords, decoder)‖` used to make the
    /// inner KKT gradient and Newton-step tolerances relative. This is the
    /// SINGLE source of truth for that scale: `penalized_quasi_laplace_criterion`'s convergence
    /// gate and `run_joint_fit_arrow_schur`'s non-descent stationarity gate
    /// must agree on it, or a point one of them calls converged is mid-flight
    /// to the other (the objective↔gradient desync class).
    pub(crate) fn inner_iterate_scale(&self) -> f64 {
        let mut iterate_norm_sq = 0.0_f64;
        for &v in self.assignment.logits.iter() {
            iterate_norm_sq += v * v;
        }
        for coords in &self.assignment.coords {
            let matrix = coords.as_matrix();
            for &v in matrix.iter() {
                iterate_norm_sq += v * v;
            }
        }
        for atom in &self.atoms {
            for &v in atom.decoder_coefficients().iter() {
                iterate_norm_sq += v * v;
            }
        }
        1.0 + iterate_norm_sq.sqrt()
    }

    /// Intensive companion to [`Self::inner_iterate_scale`] for a
    /// componentwise, curvature-scaled KKT certificate.
    ///
    /// A decoder gradient component and its curvature are both sums over rows;
    /// their ratio is therefore a displacement in decoder-parameter space, not
    /// a gradient-space quantity. Comparing the largest such displacement with
    /// `1 + max |parameter|` keeps the two sides in the same units and removes
    /// row-count, atom-count, and basis-scale extensivity. Non-finite installed
    /// state is a typed refusal, never an infinite bound that certifies
    /// everything.
    pub(crate) fn inner_iterate_max(&self) -> Result<f64, SaeInnerKktScaleError> {
        let mut max_abs = 0.0_f64;
        for (component, &value) in self.assignment.logits.iter().enumerate() {
            if !value.is_finite() {
                return Err(SaeInnerKktScaleError::NonFiniteIterate {
                    family: "assignment-logit",
                    group: 0,
                    component,
                    value,
                });
            }
            max_abs = max_abs.max(value.abs());
        }
        for (atom, coords) in self.assignment.coords.iter().enumerate() {
            let matrix = coords.as_matrix();
            for (component, &value) in matrix.iter().enumerate() {
                if !value.is_finite() {
                    return Err(SaeInnerKktScaleError::NonFiniteIterate {
                        family: "coordinate",
                        group: atom,
                        component,
                        value,
                    });
                }
                max_abs = max_abs.max(value.abs());
            }
        }
        for (atom, manifold_atom) in self.atoms.iter().enumerate() {
            for (component, &value) in manifold_atom.decoder_coefficients().iter().enumerate() {
                if !value.is_finite() {
                    return Err(SaeInnerKktScaleError::NonFiniteIterate {
                        family: "decoder",
                        group: atom,
                        component,
                        value,
                    });
                }
                max_abs = max_abs.max(value.abs());
            }
        }
        let scale = 1.0 + max_abs;
        if !scale.is_finite() {
            return Err(SaeInnerKktScaleError::IterateScaleOverflow { max_abs });
        }
        Ok(scale)
    }

    /// Machine-null eigenspace of a finite symmetric PSD decoder operator.
    ///
    /// The admissible floor is the standard floating-point dot-product backward
    /// error `γ_d = d·ε/(1-d·ε)` times the operator norm. Candidates must pass
    /// both the Rayleigh test and the stronger residual test `‖Hv‖₂ ≤ γ_d‖H‖₂`;
    /// a merely small model direction is therefore never promoted to a gauge.
    fn machine_null_eigenvectors(
        mut operator: Array2<f64>,
        context: &str,
    ) -> Result<Vec<Array1<f64>>, String> {
        let dim = operator.nrows();
        if operator.ncols() != dim {
            return Err(format!(
                "{context}: decoder operator must be square, got {:?}",
                operator.dim()
            ));
        }
        if dim == 0 {
            return Ok(Vec::new());
        }
        for row in 0..dim {
            for col in 0..row {
                let sym = 0.5 * (operator[[row, col]] + operator[[col, row]]);
                operator[[row, col]] = sym;
                operator[[col, row]] = sym;
            }
        }
        if !operator.iter().all(|value| value.is_finite()) {
            return Err(format!("{context}: non-finite decoder operator entry"));
        }
        let (evals, evecs) = operator
            .eigh(Side::Lower)
            .map_err(|err| format!("{context}: eigh failed: {err}"))?;
        let operator_norm = evals
            .iter()
            .fold(0.0_f64, |scale, &value| scale.max(value.abs()));
        let d_eps = dim as f64 * f64::EPSILON;
        let gamma_d = if d_eps < 1.0 {
            d_eps / (1.0 - d_eps)
        } else {
            return Err(format!(
                "{context}: decoder operator dimension {dim} exceeds the f64 backward-error domain"
            ));
        };
        let null_floor = gamma_d * operator_norm;
        let mut out = Vec::new();
        for eig_idx in 0..dim {
            let eigenvalue = evals[eig_idx];
            if !(eigenvalue.is_finite() && eigenvalue.abs() <= null_floor) {
                continue;
            }
            let direction = evecs.column(eig_idx).to_owned();
            let applied = operator.dot(&direction);
            let rayleigh = direction.dot(&applied).abs();
            let residual_norm = applied
                .iter()
                .map(|value| value * value)
                .sum::<f64>()
                .sqrt();
            if rayleigh.is_finite()
                && residual_norm.is_finite()
                && rayleigh <= null_floor
                && residual_norm <= null_floor
            {
                out.push(direction);
            }
        }
        Ok(out)
    }

    /// Full-length decoder flat directions of the **joint** weighted dictionary
    /// operator (#1051/#2080).
    ///
    /// Let `D_k = diag(a_·k) Φ_k`. The production decoder Hessian is not the
    /// block-diagonal collection `D_kᵀD_k`: it contains every cross-atom block
    /// `D_jᵀD_k`. Consequently two individually full-rank atoms can still carry
    /// the exact redistribution gauge
    ///
    /// `D_j A_j = D_k A_k  ⇒  (δB_j, δB_k) = (A_j C, −A_k C)`.
    ///
    /// The former atom-local eigensolves could never emit that coupled vector,
    /// which left the K≥2 shared-subspace Newton walk crawling along a flat
    /// direction. This compiler diagonalizes the same joint weighted
    /// decoder-plus-smoothness operator used by the β tier. On the full-`B`
    /// isotropic path the output factor is `I_p`, so it diagonalizes the compact
    /// joint basis operator once and tensors its machine-null space across output
    /// channels. With active decoder frames it diagonalizes the exact factored
    /// operator `G_jk ⊗ (U_jᵀU_k) + blockdiag(λ_k S_k ⊗ I_rk)`; under likelihood
    /// whitening the per-row `U_jᵀM_nU_k` sandwich is accumulated exactly.
    ///
    /// Every returned vector lives in the CURRENT arrow border coordinate
    /// (full `B` or factored `C`) and has passed the machine-scale Rayleigh and
    /// null-residual certificates in [`Self::machine_null_eigenvectors`].
    pub(crate) fn joint_decoder_beta_null_directions(
        &self,
        penalized_gram_scale: &[f64],
    ) -> Result<Vec<Array1<f64>>, String> {
        let n = self.n_obs();
        let q = self.assignment.row_block_dim();
        let p = self.output_dim();
        let k_atoms = self.k_atoms();
        if penalized_gram_scale.len() != k_atoms {
            return Err(format!(
                "joint_decoder_beta_null_directions: {} smooth scales for {k_atoms} atoms",
                penalized_gram_scale.len()
            ));
        }
        let basis_sizes: Vec<usize> = self.atoms.iter().map(|atom| atom.basis_size()).collect();
        let mut basis_offsets = Vec::with_capacity(k_atoms);
        let mut basis_dim = 0usize;
        for &m in &basis_sizes {
            basis_offsets.push(basis_dim);
            basis_dim += m;
        }
        let border_dim = self.factored_border_dim();
        if p == 0 || basis_dim == 0 || border_dim == 0 {
            return Ok(Vec::new());
        }

        let assignments = self.assignment.assignments();
        let mut joint_basis = Array2::<f64>::zeros((basis_dim, basis_dim));
        let mut weighted_basis = vec![0.0_f64; basis_dim];
        for row in 0..n {
            for atom_idx in 0..k_atoms {
                let atom = &self.atoms[atom_idx];
                let off = basis_offsets[atom_idx];
                let weight = assignments[[row, atom_idx]];
                for basis_col in 0..basis_sizes[atom_idx] {
                    weighted_basis[off + basis_col] = weight * atom.basis_values[[row, basis_col]];
                }
            }
            for col in 0..basis_dim {
                let value = weighted_basis[col];
                if value == 0.0 {
                    continue;
                }
                for row_idx in 0..basis_dim {
                    joint_basis[[row_idx, col]] += weighted_basis[row_idx] * value;
                }
            }
        }
        let joint_data_basis = joint_basis.clone();
        for atom_idx in 0..k_atoms {
            let m = basis_sizes[atom_idx];
            let penalty = self.atoms[atom_idx].smooth_penalty();
            if penalty.dim() != (m, m) {
                return Err(format!(
                    "joint_decoder_beta_null_directions: atom {atom_idx} penalty shape {:?} != ({m}, {m})",
                    penalty.dim()
                ));
            }
            let off = basis_offsets[atom_idx];
            let scale = penalized_gram_scale[atom_idx];
            if !scale.is_finite() || scale < 0.0 {
                return Err(format!(
                    "joint_decoder_beta_null_directions: atom {atom_idx} smooth scale must be finite and nonnegative, got {scale}"
                ));
            }
            for row in 0..m {
                for col in 0..m {
                    joint_basis[[off + row, off + col]] += scale * penalty[[row, col]];
                }
            }
        }

        let coord_base = n * q;
        if !self.any_frame_active() {
            let null_basis = Self::machine_null_eigenvectors(
                joint_basis,
                "joint_decoder_beta_null_directions(full-B)",
            )?;
            let mut out = Vec::with_capacity(null_basis.len() * p);
            for basis_direction in null_basis {
                for out_col in 0..p {
                    let mut direction = Array1::<f64>::zeros(coord_base + border_dim);
                    for basis_col in 0..basis_dim {
                        direction[coord_base + basis_col * p + out_col] =
                            basis_direction[basis_col];
                    }
                    out.push(direction);
                }
            }
            return Ok(out);
        }

        let border_offsets = self.factored_border_offsets();
        let frame_ranks: Vec<usize> = self
            .atoms
            .iter()
            .map(SaeManifoldAtom::border_frame_rank)
            .collect();
        let mut joint_border = Array2::<f64>::zeros((border_dim, border_dim));
        let whitens_likelihood = self
            .row_metric
            .as_ref()
            .is_some_and(|metric| metric.whitens_likelihood());
        if whitens_likelihood {
            let metric = self
                .row_metric
                .as_ref()
                .expect("whitens_likelihood implies a row metric");
            let metric_rank = metric.metric_rank();
            let frames: Vec<Array2<f64>> = (0..k_atoms)
                .map(|atom_idx| self.frame_output_matrix(atom_idx))
                .collect();
            let mut whitened_jacobian = Array2::<f64>::zeros((metric_rank, border_dim));
            for row in 0..n {
                whitened_jacobian.fill(0.0);
                for atom_idx in 0..k_atoms {
                    let m = basis_sizes[atom_idx];
                    let rank = frame_ranks[atom_idx];
                    let border_off = border_offsets[atom_idx];
                    let weight = assignments[[row, atom_idx]];
                    for frame_col in 0..rank {
                        for metric_col in 0..metric_rank {
                            let mut projected = 0.0_f64;
                            for out_col in 0..p {
                                projected += frames[atom_idx][[out_col, frame_col]]
                                    * metric.factor_entry(row, out_col, metric_col);
                            }
                            if projected == 0.0 {
                                continue;
                            }
                            for basis_col in 0..m {
                                whitened_jacobian
                                    [[metric_col, border_off + basis_col * rank + frame_col]] =
                                    weight
                                        * self.atoms[atom_idx].basis_values[[row, basis_col]]
                                        * projected;
                            }
                        }
                    }
                }
                for col in 0..border_dim {
                    for row_idx in 0..border_dim {
                        let mut value = 0.0_f64;
                        for metric_col in 0..metric_rank {
                            value += whitened_jacobian[[metric_col, row_idx]]
                                * whitened_jacobian[[metric_col, col]];
                        }
                        joint_border[[row_idx, col]] += value;
                    }
                }
            }
        } else {
            for atom_j in 0..k_atoms {
                let mj = basis_sizes[atom_j];
                let rj = frame_ranks[atom_j];
                let basis_j = basis_offsets[atom_j];
                let border_j = border_offsets[atom_j];
                for atom_k in 0..k_atoms {
                    let mk = basis_sizes[atom_k];
                    let rk = frame_ranks[atom_k];
                    let basis_k = basis_offsets[atom_k];
                    let border_k = border_offsets[atom_k];
                    let frame_overlap = self.frame_cross_factor(atom_j, atom_k);
                    for col_j in 0..mj {
                        for col_k in 0..mk {
                            let gram = joint_data_basis[[basis_j + col_j, basis_k + col_k]];
                            for channel_j in 0..rj {
                                for channel_k in 0..rk {
                                    joint_border[[
                                        border_j + col_j * rj + channel_j,
                                        border_k + col_k * rk + channel_k,
                                    ]] += gram * frame_overlap[[channel_j, channel_k]];
                                }
                            }
                        }
                    }
                }
            }
        }
        for atom_idx in 0..k_atoms {
            let m = basis_sizes[atom_idx];
            let rank = frame_ranks[atom_idx];
            let off = border_offsets[atom_idx];
            let penalty = self.atoms[atom_idx].smooth_penalty();
            let scale = penalized_gram_scale[atom_idx];
            for basis_row in 0..m {
                for basis_col in 0..m {
                    let value = scale * penalty[[basis_row, basis_col]];
                    for channel in 0..rank {
                        joint_border[[
                            off + basis_row * rank + channel,
                            off + basis_col * rank + channel,
                        ]] += value;
                    }
                }
            }
        }
        let null_border = Self::machine_null_eigenvectors(
            joint_border,
            "joint_decoder_beta_null_directions(factored)",
        )?;
        Ok(null_border
            .into_iter()
            .map(|beta_direction| {
                let mut direction = Array1::<f64>::zeros(coord_base + border_dim);
                direction
                    .slice_mut(s![coord_base..])
                    .assign(&beta_direction);
                direction
            })
            .collect())
    }

    /// Deflation candidates for a rank-deficient decoder **column span** (the
    /// ambient output-channel deficiency #1051/#1273 — distinct from the
    /// basis-column deficiency [`Self::joint_decoder_beta_null_directions`] handles).
    ///
    /// [`Self::joint_decoder_beta_null_directions`] is channel-free on the
    /// unframed path: it replicates a
    /// single `M_k`-vector basis-null across all `p` output channels, so it can
    /// only see a basis column the data never excites (e.g. an unused `t²`
    /// monomial). It is structurally blind to a decoder whose `p` output
    /// channels are linearly dependent — a rank-deficient `B_k` (M_k × p) whose
    /// realised reconstruction `Φ_k B_k` lives on a proper subspace of `R^p`.
    /// Then an entire ambient channel direction `c ∈ R^p` orthogonal to the
    /// decoder's row space is unidentified, and the joint Hessian carries a
    /// genuine near-null direction OUTSIDE both the chart gauge orbit and the
    /// basis-null span. This is the rank-1-decoder-line geometry the
    /// circle/Euclidean demos hit (#1273): the outer gate saw a sub-floor pivot
    /// it had no candidate to deflate and rejected the trial ρ with
    /// `RemlConvergenceError`.
    ///
    /// We emit one full-length candidate per (atom, sub-floor ambient channel,
    /// basis row): the ambient channel direction `c` placed at that basis row's
    /// coefficient slot, lifted into the `(n·q + β)` coordinate. The shared
    /// Gram-Schmidt + Rayleigh-floor pass in the outer-gradient solver keeps
    /// only the candidates that are genuinely flat against the actual cached
    /// Hessian, so a full-rank decoder contributes nothing.
    pub(crate) fn decoder_channel_null_directions(&self) -> Result<Vec<Array1<f64>>, String> {
        let p = self.output_dim();
        let n = self.n_obs();
        let q = self.assignment.row_block_dim();
        let border_dim = self.factored_border_dim();
        let total_len = n * q + border_dim;
        if p == 0 || border_dim == 0 {
            return Ok(Vec::new());
        }
        let beta_offsets = self.factored_border_offsets();
        let mut out = Vec::new();
        for atom_idx in 0..self.k_atoms() {
            let atom = &self.atoms[atom_idx];
            // A framed atom's border contains only its realised `C_k`
            // coordinates. Ambient directions orthogonal to `U_k` are not
            // decoder-border coordinates at all; frame orientation is handled
            // by the separate Grassmann block update.
            if atom.decoder_frame.is_some() {
                continue;
            }
            let m = atom.basis_size();
            if m == 0 {
                continue;
            }
            // Right-singular vectors of `B_k` (M_k × p) span the ambient
            // channel space; those with a sub-floor singular value are the
            // unrealised output channels (the decoder's column-span deficiency).
            let (_u, sv, vt_opt) = match atom.decoder_coefficients().svd(false, true) {
                Ok(parts) => parts,
                Err(_) => continue,
            };
            let Some(vt) = vt_opt else {
                continue;
            };
            let max_sv = sv.iter().fold(0.0_f64, |acc, &v| acc.max(v));
            // Relative cutoff on the SINGULAR values (the channel curvature
            // scales like the square of the decoder singular value, so this is
            // the sqrt of the curvature-scale floor used elsewhere).
            let sv_floor = SAE_DECODER_BETA_NULL_RELATIVE_FLOOR.sqrt() * max_sv;
            let beta_base = n * q + beta_offsets[atom_idx];
            // `vt` is the thin right factor with `rank = min(m, p)` rows, each a
            // length-`p` ambient channel direction. A channel is realised iff it
            // has an above-floor singular value; a sub-floor (or zero) singular
            // value marks an unidentified output channel of the rank-deficient
            // decoder.
            for c_idx in 0..vt.nrows() {
                let realised = c_idx < sv.len() && max_sv > 0.0 && sv[c_idx] > sv_floor;
                if realised {
                    continue;
                }
                let channel = vt.row(c_idx);
                if channel.len() != p {
                    continue;
                }
                let norm_sq = channel.iter().map(|v| v * v).sum::<f64>();
                if !(norm_sq.is_finite() && norm_sq > 1.0e-24) {
                    continue;
                }
                // One candidate per basis row carrying this ambient channel.
                for col in 0..m {
                    let mut dir = Array1::<f64>::zeros(total_len);
                    for out_col in 0..p {
                        dir[beta_base + col * p + out_col] = channel[out_col];
                    }
                    out.push(dir);
                }
            }
        }
        Ok(out)
    }

    pub(crate) fn quotient_newton_step_norm_sq(
        &self,
        delta_ext_coord: ArrayView1<'_, f64>,
        delta_beta: ArrayView1<'_, f64>,
        raw_step_norm_sq: f64,
        penalized_gram_scale: &[f64],
    ) -> Result<f64, String> {
        let n = self.n_obs();
        let q = self.assignment.row_block_dim();
        let border_dim = self.factored_border_dim();
        if delta_ext_coord.len() != n * q || delta_beta.len() != border_dim {
            return Ok(raw_step_norm_sq);
        }
        let mut residual = Array1::<f64>::zeros(delta_ext_coord.len() + delta_beta.len());
        for i in 0..delta_ext_coord.len() {
            residual[i] = delta_ext_coord[i];
        }
        let beta_base = delta_ext_coord.len();
        for i in 0..delta_beta.len() {
            residual[beta_base + i] = delta_beta[i];
        }
        let quotient = self.quotient_residual_norm_sq(residual, penalized_gram_scale)?;
        Ok(if quotient.is_finite() {
            quotient.max(0.0).min(raw_step_norm_sq)
        } else {
            raw_step_norm_sq
        })
    }

    /// Norm² of a full-length `(n·q + β)` residual vector after projecting out
    /// the rank-deficient decoder null space (#1051/#1117). Shared by the
    /// convergence STEP gate ([`Self::quotient_newton_step_norm_sq`]) and the
    /// convergence GRADIENT gate ([`Self::quotient_gradient_norm_sq`]) so both
    /// measure progress on the SAME identified quotient — otherwise a
    /// rank-deficient circle whose only remaining motion is null crawl is
    /// recognised as converged by the step measure but rejected forever by the
    /// raw-gradient measure, burning the inner refine budget (the #1117 stall).
    ///
    /// ## WHY THE CHART ORBIT IS NOT IN THIS SPAN (gam#2720)
    ///
    /// It used to be, on the premise that "along either the penalised joint
    /// objective is flat, so a component there is gauge freedom, not
    /// un-converged motion". The premise is false, and the measurement that
    /// settles it is a per-objective-term central difference of the VALUE
    /// functions along every direction this span used to contain
    /// (`tests_gauge_posterior_flatness_2720`, on the planted-circle fixture at
    /// four atom kinds):
    ///
    /// | family | directions | worst \|d f\| / tolerance |
    /// |---|---|---|
    /// | `dense_step_gauge_vectors` (chart orbit) | 7 | **76 170** |
    /// | `joint_decoder_beta_null_directions` | 704 | 0.00003 |
    /// | `decoder_channel_null_directions` (raw) | — | 0.00003 (duchon only; the torus cell was unseedable before `72dda02` — 26 of 392 directions carry live slope, see `tests_channel_null_currency_2720`) |
    /// | `decoder_channel_null_quotient_directions` (screened) | — | flat by the closed-form screen, `λ·(S B c)[col] ≤ tol` |
    ///
    /// The two kinds of direction are not the same object:
    ///
    /// * the decoder nulls are machine-null eigenvectors of the **penalized**
    ///   Gram `DᵀD + λS`, so the data fit AND the smoothness prior are flat
    ///   along them by construction — measured at `3e-9` absolute, i.e. the
    ///   roundoff of the value function. They are genuine posterior nulls and
    ///   they belong in a convergence quotient.
    /// * the chart orbit is a symmetry of the **likelihood** only. The
    ///   compensating decoder solve makes the reconstruction change vanish to
    ///   `1e-16` relative — re-measured through the value function, at
    ///   `n_active = 42` against `M ∈ {2,3,32}`, so it is not the rank-trivial
    ///   regime where that solve is exact for any field whatever. But the ARD
    ///   prior on `t` and the smoothness prior on `β` are written on the chart
    ///   coordinates, and they move: the constant-shift field moves ARD alone,
    ///   the dilation field `δt = t` moves the smoothness prior by `−7.82` on an
    ///   objective of `165` because shrinking the chart while inflating the
    ///   decoder buys smoothness at no cost in fit.
    ///
    /// ### The modelling question #2720 asked, and its answer
    ///
    /// "Make the orbit a genuine posterior symmetry" would mean deleting the
    /// prior's dependence on the chart coordinates. It cannot be done, and
    /// should not be: the ARD coordinate prior IS the chart's identifiability
    /// device — the standard mean-zero random-effect convention, with the
    /// decoder's constant column absorbing the location — and the smoothness
    /// prior is what fixes the chart's scale. A prior made invariant under
    /// translation and dilation of `t` is improper along exactly those
    /// directions and cannot shrink an unused axis, which is the entire purpose
    /// of ARD. **There is no posterior gauge here and there should not be one.**
    ///
    /// ### Why removing it can only help, stated exactly
    ///
    /// The gradient quotient removes `Σᵢ (gᵀvᵢ)²` from `‖g‖²`, so the
    /// precondition `maxᵢ |gᵀvᵢ| ≤ τ` bounds what it can ever remove at
    /// `√m · τ` over `m` directions — the gate is then at worst `√m`-loose, and
    /// on the measured span that bound is `√704 · 3e-9 = 8e-8` against
    /// `τ = 7.5e-5`, i.e. nothing. Where the precondition FAILS the removal is
    /// unbounded, and it failed here by four orders of magnitude. So the chart
    /// orbit's presence in this span bought the gate nothing it did not already
    /// have and cost it everything at exactly the states where the gate was
    /// right.
    ///
    /// For the STEP gate the quotient is not bounded that way — a step along a
    /// genuinely flat direction is genuinely not progress, and removing it is
    /// the point — but that argument needs the direction to BE flat, which is
    /// what the table above refutes for the chart orbit and confirms for the
    /// decoder nulls.
    ///
    /// ### What the orbit gets instead
    ///
    /// A mover, not a blindfold: [`Self::descend_gauge_orbit`] minimizes the
    /// penalized objective over [`Self::likelihood_flat_block_basis`], which
    /// still contains the chart orbit. That is block-coordinate descent on the
    /// real objective, so the orbit component of the residual is reduced rather
    /// than hidden, and the raw gate can then see a genuinely stationary point.
    pub(crate) fn quotient_residual_norm_sq(
        &self,
        mut residual: Array1<f64>,
        penalized_gram_scale: &[f64],
    ) -> Result<f64, String> {
        for basis in self.posterior_null_quotient_basis(penalized_gram_scale)? {
            if basis.len() != residual.len() {
                continue;
            }
            let coeff = residual.dot(&basis);
            for i in 0..residual.len() {
                residual[i] -= coeff * basis[i];
            }
        }
        Ok(residual.iter().map(|v| v * v).sum::<f64>())
    }

    /// The channel-null family **screened for convergence-quotient admission**
    /// (#2720): same stream as [`Self::decoder_channel_null_directions`], but a
    /// direction enters the quotient only if the smoothness prior cannot see it
    /// at the tolerance the accept path itself uses.
    ///
    /// The raw stream is admitted on a DATA-FIT test alone — a right-singular
    /// channel of `B_k` with sub-floor singular value `σ_k` — while the
    /// flatness a convergence quotient certifies is a PENALIZED-objective
    /// claim. Along the emitted direction `δβ = e_col ⊗ c` the smoothness
    /// value `0.5·λ·tr(BᵀSB)` has the exact slope (`tests_channel_null_currency_2720`,
    /// verified against central differences to ~1e-9 on all 392 torus
    /// directions):
    ///
    /// ```text
    /// d/dε smoothness = λ_k · (S_k B_k c)[col] = λ_k · σ_k · (S_k u)[col]
    /// ```
    ///
    /// A sub-floor `σ` therefore converts into penalty currency through the
    /// roughness Gram: the slope vanishes only at `σ = 0` exactly, which the
    /// relative floor does not require. It is kind-dependent — the torus
    /// tensor-product roughness `(k² + l²)²` reaches `324` at default `H=3`
    /// while duchon's `‖S‖₂` stays near `8e-2` — so the landed flatness
    /// evidence, sampled only on duchon, certified the family in general from
    /// its flat member.
    ///
    /// The screen is computed WITHOUT dividing by `σ_k` (`(S B c)[col]`
    /// directly), so a denormal singular value cannot amplify roundoff into a
    /// verdict. A zero `λ_k` admits the whole atom's family, which is correct:
    /// with the smoothness prior off, those directions are flat for the
    /// penalized objective. Rejected directions are NOT lost to the solver —
    /// [`Self::likelihood_flat_block_basis`] still chains the RAW stream, so
    /// the descent block keeps every direction the quotient drops. That is the
    /// same division of labor the chart orbit received (`ec18eac`): a
    /// direction leaves the convergence measure only when the posterior cannot
    /// see it, and is descended otherwise.
    pub(crate) fn decoder_channel_null_quotient_directions(
        &self,
        penalized_gram_scale: &[f64],
    ) -> Result<Vec<Array1<f64>>, String> {
        let k_atoms = self.k_atoms();
        if penalized_gram_scale.len() != k_atoms {
            return Err(format!(
                "decoder_channel_null_quotient_directions: {} smooth scales for {k_atoms} atoms",
                penalized_gram_scale.len()
            ));
        }
        // The tolerance currency of every convergence quotient in this file:
        // relative tolerance x iterate scale, the single source of truth the
        // inner accept gate denominates itself in (`construction_quasi_laplace.rs:937`).
        let slope_bound = SAE_MANIFOLD_INNER_GRAD_REL_TOL * self.inner_iterate_scale();
        let p = self.output_dim();
        let n = self.n_obs();
        let q = self.assignment.row_block_dim();
        let border_dim = self.factored_border_dim();
        let total_len = n * q + border_dim;
        if p == 0 || border_dim == 0 {
            return Ok(Vec::new());
        }
        let beta_offsets = self.factored_border_offsets();
        let mut out = Vec::new();
        for atom_idx in 0..k_atoms {
            let atom = &self.atoms[atom_idx];
            // Framed atoms do not emit this family at all (see the raw stream).
            if atom.decoder_frame.is_some() {
                continue;
            }
            let m = atom.basis_size();
            if m == 0 {
                continue;
            }
            let lambda = penalized_gram_scale[atom_idx];
            if !lambda.is_finite() || lambda < 0.0 {
                return Err(format!(
                    "decoder_channel_null_quotient_directions: atom {atom_idx} smooth scale must \
                     be finite and nonnegative, got {lambda}"
                ));
            }
            let (_u, sv, vt_opt) = match atom.decoder_coefficients().svd(false, true) {
                Ok(parts) => parts,
                Err(_) => continue,
            };
            let Some(vt) = vt_opt else {
                continue;
            };
            let max_sv = sv.iter().fold(0.0_f64, |acc, &v| acc.max(v));
            let sv_floor = SAE_DECODER_BETA_NULL_RELATIVE_FLOOR.sqrt() * max_sv;
            let beta_base = n * q + beta_offsets[atom_idx];
            let s_gram = atom.smooth_penalty();
            if s_gram.dim() != (m, m) {
                return Err(format!(
                    "decoder_channel_null_quotient_directions: atom {atom_idx} penalty shape \
                     {:?} != ({m}, {m})",
                    s_gram.dim()
                ));
            }
            for c_idx in 0..vt.nrows() {
                let realised = c_idx < sv.len() && max_sv > 0.0 && sv[c_idx] > sv_floor;
                if realised {
                    continue;
                }
                let channel = vt.row(c_idx);
                if channel.len() != p {
                    continue;
                }
                let norm_sq = channel.iter().map(|v| v * v).sum::<f64>();
                if !(norm_sq.is_finite() && norm_sq > 1.0e-24) {
                    continue;
                }
                // `S (B c)` carries every column's slope at once:
                // slope[col] = lambda * (S B c)[col] — the closed form, without
                // dividing by the sub-floor sigma.
                let mut b_c = Array1::<f64>::zeros(m);
                for row in 0..m {
                    let mut acc = 0.0_f64;
                    for out_col in 0..p {
                        acc += atom.decoder_coefficients()[[row, out_col]] * channel[out_col];
                    }
                    b_c[row] = acc;
                }
                let mut s_b_c = Array1::<f64>::zeros(m);
                for row in 0..m {
                    let mut acc = 0.0_f64;
                    for col in 0..m {
                        acc += s_gram[[row, col]] * b_c[col];
                    }
                    s_b_c[row] = acc;
                }
                for col in 0..m {
                    let slope = (lambda * s_b_c[col]).abs();
                    if slope > slope_bound {
                        // The smoothness prior sees this direction above the
                        // accept path's own tolerance: it is live posterior
                        // descent, not gauge freedom. The descent block still
                        // receives it (raw stream).
                        continue;
                    }
                    let mut dir = Array1::<f64>::zeros(total_len);
                    for out_col in 0..p {
                        dir[beta_base + col * p + out_col] = channel[out_col];
                    }
                    out.push(dir);
                }
            }
        }
        Ok(out)
    }

    /// The ORTHONORMAL basis of the span every convergence quotient removes,
    /// and the SINGLE source of truth for it (#2762/#2720).
    ///
    /// Membership is decided by one question — **is the PENALIZED objective flat
    /// along this direction at the accept path's own tolerance?** The β-null
    /// family answers it structurally: machine-null directions of the penalized
    /// Gram `DᵀD + λS` (basis-column deficiency). The channel-null family
    /// answers it by SCREEN: the raw emission is flat for the data fit alone,
    /// and the smoothness prior sees it through `λ·(S B c)[col]` — kind-dependent,
    /// pinned by `tests_channel_null_currency_2720` — so
    /// [`Self::decoder_channel_null_quotient_directions`] admits only the
    /// directions whose closed-form slope is within tolerance.
    ///
    /// The chart reparametrisation orbit is deliberately NOT here; see
    /// [`Self::quotient_residual_norm_sq`] for the measurement and the modelling
    /// argument. It lives in [`Self::likelihood_flat_block_basis`], which is
    /// what the descent block minimizes over.
    ///
    /// Order is load-bearing (Gram--Schmidt is order-dependent) and is the
    /// historical one within these two families: the penalized joint decoder
    /// β-null, then the decoder column-span channel null (#1051/#1273).
    pub(crate) fn posterior_null_quotient_basis(
        &self,
        penalized_gram_scale: &[f64],
    ) -> Result<Vec<Array1<f64>>, String> {
        Ok(Self::orthonormalized(
            self.joint_decoder_beta_null_directions(penalized_gram_scale)?
                .into_iter()
                .chain(self.decoder_channel_null_quotient_directions(
                    penalized_gram_scale,
                )?),
        ))
    }

    /// The ORTHONORMAL basis of the span the penalized objective is flat along
    /// **as a function of the reconstruction** — the chart reparametrisation
    /// orbit followed by the posterior nulls (#2720).
    ///
    /// This is the block [`Self::descend_gauge_orbit`] minimizes over, and it is
    /// deliberately WIDER than [`Self::posterior_null_quotient_basis`]. The two
    /// spans answer two different questions and conflating them is what #2720
    /// was opened on:
    ///
    /// * *what may be REMOVED from a convergence measure* — only directions the
    ///   posterior cannot see, or the measure certifies non-stationary points;
    /// * *what should be DESCENDED as its own block* — every direction the
    ///   LIKELIHOOD cannot see, because those carry no data-fit curvature, so
    ///   the only curvature on them is the priors' (tiny next to the transverse
    ///   block) and every globalization in this solver is a step-SHORTENING
    ///   device. Descending a direction is never unsound: it only ever lowers
    ///   the same scalar every other mover lowers.
    ///
    /// Chart gauges come first so the Gram--Schmidt keeps the historical
    /// ordering of the decoder-null families relative to each other.
    pub(crate) fn likelihood_flat_block_basis(
        &self,
        penalized_gram_scale: &[f64],
    ) -> Result<Vec<Array1<f64>>, String> {
        Ok(Self::orthonormalized(
            self.dense_step_gauge_vectors()?
                .into_iter()
                .chain(self.joint_decoder_beta_null_directions(penalized_gram_scale)?)
                .chain(self.decoder_channel_null_directions()?),
        ))
    }

    /// Modified Gram--Schmidt over a candidate stream, dropping anything that
    /// collapses into the span already accumulated. Shared by the two span
    /// constructors above so that "the descent block contains the quotient
    /// span" is a property of one algorithm run on two inputs, not of two
    /// implementations that agree today.
    fn orthonormalized(candidates: impl Iterator<Item = Array1<f64>>) -> Vec<Array1<f64>> {
        let mut orthonormal: Vec<Array1<f64>> = Vec::new();
        for mut candidate in candidates {
            for basis in &orthonormal {
                let coeff = candidate.dot(basis);
                for i in 0..candidate.len() {
                    candidate[i] -= coeff * basis[i];
                }
            }
            let norm_sq = candidate.iter().map(|v| v * v).sum::<f64>();
            if norm_sq <= 1.0e-24 || !norm_sq.is_finite() {
                continue;
            }
            let inv_norm = norm_sq.sqrt().recip();
            for v in candidate.iter_mut() {
                *v *= inv_norm;
            }
            orthonormal.push(candidate);
        }
        orthonormal
    }

    /// #2762 — MINIMIZE the penalized objective over the span the LIKELIHOOD is
    /// flat along ([`Self::likelihood_flat_block_basis`]), instead of removing
    /// it from a convergence measure and hoping it was flat for the posterior
    /// too.
    ///
    /// # Why this block exists at all
    ///
    /// The chart-gauge orbit is an exact first-order symmetry of the
    /// RECONSTRUCTION (measured reconstruction-invariant to `~1e-16` relative
    /// over 1333 constructions) and NOT of the penalized objective: the ARD
    /// prior on `t` and the smoothness prior on `β` are written on the chart
    /// coordinates, so a reparametrisation moves them. That asymmetry is what
    /// makes this subspace pathological for every mover in the inner solve, and
    /// it is a curvature statement, not a bookkeeping one:
    ///
    /// * the data-fit Hessian contributes NOTHING along the orbit, so the only
    ///   curvature there is the priors' — tiny next to the transverse block;
    /// * a direction with tiny curvature and a live gradient needs a LONG step;
    /// * and every globalization in this solver is a step-SHORTENING device.
    ///   Armijo backtracks, the LM gain ratio grows the ridge, the terminal
    ///   polish's damping ladder suppresses exactly the near-null modes. None of
    ///   them can take a long step, so the orbit component of the residual is
    ///   the one part of `g` no mover reduces.
    ///
    /// Measured at the `zz2015_tiny_inner_crawl_terminates` refusal (#2762),
    /// `‖g‖ = 2.075e-1` of which `‖Π∥gauge g‖ = 2.016e-1` — 94% of the residual
    /// ENERGY inside a 4-dimensional span:
    ///
    /// | direction | best objective drop | at α |
    /// |---|---|---|
    /// | steepest descent `−g/‖g‖` | `1.879e-4` | `1e-3` |
    /// | the removed span | `1.090e-1` | `1.0` |
    ///
    /// against a material floor of `1.949e-4`. Steepest descent lands BELOW the
    /// floor — the stall detector was right — while the orbit buys 580x more at
    /// a 1000x longer step, because the 6% transverse component of `−g` is stiff
    /// enough to cap the ambient line search three decades early. The solve then
    /// refuses at `intensive_over_bound = 5.8e3` having declared an objective
    /// stall while holding 559 stall-resolutions of realizable decrease.
    ///
    /// # What this does, and why it changes no estimand
    ///
    /// It is plain block-coordinate descent on the objective's own parameter
    /// space: minimize `f` over the likelihood-flat block, let the Newton/MM
    /// movers have the transverse block where they are well-conditioned. Both
    /// blocks decrease the SAME scalar (`penalized_objective_total`, the exact
    /// function the inner Armijo line search descends and the KKT gradient
    /// differentiates), so the composition is monotone and a joint fixed point
    /// is stationary in both — which is full stationarity. Nothing about the
    /// model, the priors, or the likelihood changes; the gauge coordinate stops
    /// being arbitrary and starts being CHOSEN by the objective.
    ///
    /// The consequence for the gate is the point of the exercise, and #2720
    /// sharpened what that consequence is. This block is the ONLY thing that
    /// reduces the orbit component of `g`, because the orbit is no longer
    /// removed from any convergence measure: at a state this has converged on,
    /// `Π∥gauge g ≈ 0` is a MEASURED property of the iterate rather than an
    /// assumption a projection made on its behalf, and the raw gate reads it
    /// directly.
    ///
    /// # The line search, and why every bound in it is derived
    ///
    /// Along `d̂ = −Π_V g/‖Π_V g‖` the objective is swept geometrically between
    /// two ENDPOINTS THE STATE ITSELF SUPPLIES, not between chosen constants:
    ///
    /// * the far end is [`Self::inner_iterate_scale`] — one step may not move
    ///   the iterate further than the iterate's own magnitude, the same
    ///   scale-free trust radius the Newton step already clips against and the
    ///   same one the KKT tolerance is measured in;
    /// * the near end is `material_floor / ‖Π_V g‖`, below which the FIRST-ORDER
    ///   model itself predicts less than the objective's own resolution — so no
    ///   shorter step could be committed even if it were exact. That is a proof
    ///   that the sweep is complete, not a cap on it.
    ///
    /// The best bracket is then refined once by the parabola through
    /// `(α/2, α, 2α)`, which is exact for a quadratic and is accepted only if it
    /// measures better. A round commits only a decrease clearing the material
    /// floor `SAE_MANIFOLD_INNER_OBJECTIVE_STALL_REL_TOL · (1 + |f|)` — the same
    /// floor the evidence lane's Armijo and proximal gates use — so a committed
    /// move is never the ε-harvest that makes an inner map non-idempotent, and
    /// rounds are strictly decreasing in `f` and therefore finite.
    ///
    /// Every rejected trial restores the snapshot bit-for-bit; a round that
    /// commits nothing leaves the state exactly as it found it.
    pub(crate) fn descend_gauge_orbit(
        &mut self,
        target: ArrayView2<'_, f64>,
        rho: &SaeManifoldRho,
        registry: Option<&AnalyticPenaltyRegistry>,
        penalized_gram_scale: &[f64],
        max_rounds: usize,
    ) -> Result<GaugeOrbitDescent, String> {
        let mut outcome = GaugeOrbitDescent::default();
        let n = self.n_obs();
        let q = self.assignment.row_block_dim();
        let dense_len = n.saturating_mul(q);
        let border_dim = self.factored_border_dim();
        if dense_len + border_dim == 0 {
            return Ok(outcome);
        }
        for _ in 0..max_rounds {
            let system = match self.assemble_arrow_schur(target, rho, registry) {
                Ok(system) => system,
                Err(_) => return Ok(outcome),
            };
            if system.rows.len() != n
                || system.row_offsets.len() != n + 1
                || system.gb.len() != border_dim
            {
                return Ok(outcome);
            }
            let mut gradient = Array1::<f64>::zeros(dense_len + border_dim);
            for (row_index, row) in system.rows.iter().enumerate() {
                let base = system.row_offsets[row_index];
                let dim = system.row_dims[row_index];
                if base + dim > dense_len || row.gt.len() < dim {
                    return Ok(outcome);
                }
                for axis in 0..dim {
                    gradient[base + axis] = row.gt[axis];
                }
            }
            for (index, &value) in system.gb.iter().enumerate() {
                gradient[dense_len + index] = value;
            }
            drop(system);
            if !gradient.iter().all(|value| value.is_finite()) {
                return Ok(outcome);
            }

            let basis = self.likelihood_flat_block_basis(penalized_gram_scale)?;
            outcome.dimension = basis.len();
            let mut direction = Array1::<f64>::zeros(gradient.len());
            let mut max_directional = 0.0_f64;
            for vector in &basis {
                if vector.len() != gradient.len() {
                    continue;
                }
                let coeff = gradient.dot(vector);
                max_directional = max_directional.max(coeff.abs());
                for index in 0..direction.len() {
                    direction[index] -= coeff * vector[index];
                }
            }
            outcome.max_directional_derivative = max_directional;
            let slope = direction.dot(&direction).sqrt();
            if !(slope.is_finite() && slope > 0.0) {
                return Ok(outcome);
            }
            for value in direction.iter_mut() {
                *value /= slope;
            }

            let base_objective = self.penalized_objective_total(target, rho, registry, 1.0)?;
            if outcome.entry_objective.is_none() {
                outcome.entry_objective = Some(base_objective);
            }
            if !base_objective.is_finite() {
                return Ok(outcome);
            }
            let material_floor =
                SAE_MANIFOLD_INNER_OBJECTIVE_STALL_REL_TOL * (1.0 + base_objective.abs());
            // Both ends of the sweep come from the state: the far end is the
            // iterate's own magnitude, the near end is where the first-order
            // model stops predicting a committable decrease.
            let far_alpha = self.inner_iterate_scale();
            let near_alpha = material_floor / slope;
            if !(far_alpha.is_finite() && far_alpha > 0.0 && near_alpha.is_finite()) {
                return Ok(outcome);
            }
            let snapshot = self.snapshot_mutable_state();
            let evaluate = |term: &mut Self, alpha: f64| -> Result<f64, String> {
                if !(alpha.is_finite() && alpha > 0.0) {
                    return Ok(f64::INFINITY);
                }
                let value = term
                    .apply_newton_step(
                        direction.slice(s![..dense_len]),
                        direction.slice(s![dense_len..]),
                        alpha,
                    )
                    .and_then(|()| term.penalized_objective_total(target, rho, registry, 1.0))
                    .unwrap_or(f64::INFINITY);
                term.restore_mutable_state(&snapshot).map_err(|err| {
                    format!(
                        "SaeManifoldTerm::descend_gauge_orbit: restoring the pre-round state \
                         after the speculative trial at alpha={alpha:.6e} failed: {err}"
                    )
                })?;
                Ok(if value.is_finite() {
                    value
                } else {
                    f64::INFINITY
                })
            };

            let mut best_alpha = 0.0_f64;
            let mut best_value = base_objective;
            let mut alpha = far_alpha;
            while alpha >= near_alpha {
                outcome.evaluations += 1;
                let value = evaluate(self, alpha)?;
                if value < best_value {
                    best_value = value;
                    best_alpha = alpha;
                }
                alpha *= 0.5;
            }
            if best_alpha > 0.0 {
                // GOLDEN-SECTION REFINEMENT of the bracket the halving grid
                // located, run to the limit of what f64 function VALUES can
                // resolve.
                //
                // A grid minimum plus one parabolic step is not enough here, and
                // the trail says so: with that refinement the block committed a
                // decrease on 603 consecutive calls and `maxᵢ|gᵀvᵢ|` never fell
                // below `1.33e-1` — the round kept leaving slope behind because
                // it stopped at a grid point, so the next round re-descended the
                // same trough. A block step that does not leave its block
                // stationary is not a block step.
                //
                // The bracket is `[α/2, 2α]` around the grid minimum and shrinks
                // by the golden ratio, which is the optimal derivative-free
                // contraction. It stops at `√ε` RELATIVE width: a smooth
                // function's minimum cannot be located more precisely than that
                // from values alone (near the minimum `f` varies quadratically,
                // so a displacement of `√ε·α` changes `f` by `ε`-level noise) —
                // an information bound of the f64 evaluation, not a chosen
                // iteration count.
                const GOLDEN_RATIO_INVERSE: f64 = 0.618_033_988_749_894_9;
                let mut low = best_alpha * 0.5;
                let mut high = best_alpha * 2.0;
                let resolution = f64::EPSILON.sqrt() * best_alpha;
                let mut inner_low = high - GOLDEN_RATIO_INVERSE * (high - low);
                let mut inner_high = low + GOLDEN_RATIO_INVERSE * (high - low);
                let mut value_low = evaluate(self, inner_low)?;
                let mut value_high = evaluate(self, inner_high)?;
                outcome.evaluations += 2;
                while high - low > resolution {
                    if value_low <= value_high {
                        high = inner_high;
                        inner_high = inner_low;
                        value_high = value_low;
                        inner_low = high - GOLDEN_RATIO_INVERSE * (high - low);
                        value_low = evaluate(self, inner_low)?;
                    } else {
                        low = inner_low;
                        inner_low = inner_high;
                        value_low = value_high;
                        inner_high = low + GOLDEN_RATIO_INVERSE * (high - low);
                        value_high = evaluate(self, inner_high)?;
                    }
                    outcome.evaluations += 1;
                }
                if value_low < best_value {
                    best_value = value_low;
                    best_alpha = inner_low;
                }
                if value_high < best_value {
                    best_value = value_high;
                    best_alpha = inner_high;
                }
            }

            let trial_decrease = base_objective - best_value;
            if !(best_alpha > 0.0 && trial_decrease > material_floor) {
                self.restore_mutable_state(&snapshot)
                    .map_err(|err| format!("SaeManifoldTerm::descend_gauge_orbit: {err}"))?;
                return Ok(outcome);
            }
            if let Err(err) = self.apply_newton_step(
                direction.slice(s![..dense_len]),
                direction.slice(s![dense_len..]),
                best_alpha,
            ) {
                self.restore_mutable_state(&snapshot).map_err(|restore_err| {
                    format!(
                        "SaeManifoldTerm::descend_gauge_orbit: committed step application failed \
                         ({err}); restoring the pre-round state also failed ({restore_err})"
                    )
                })?;
                return Err(format!(
                    "SaeManifoldTerm::descend_gauge_orbit: committed step application: {err}"
                ));
            }
            // The speculative trial value is evidence for choosing `best_alpha`,
            // not the value authority for the state we actually retain. A trial
            // is evaluated and then restored through the canonical mutable-state
            // seam; rebuilding evaluator-backed basis caches on that restore can
            // change the subsequently committed state's objective at floating-
            // point resolution. Summing `base_objective - best_value` therefore
            // need not telescope to entry minus exit, and—more importantly—could
            // call a move material even when the retained state did not clear the
            // material floor. Re-evaluate the committed state, apply the same
            // acceptance law to that authoritative value, and report exactly the
            // decrease that the retained transition made.
            let committed_objective =
                match self.penalized_objective_total(target, rho, registry, 1.0) {
                    Ok(value) => value,
                    Err(err) => {
                        self.restore_mutable_state(&snapshot).map_err(|restore_err| {
                            format!(
                                "SaeManifoldTerm::descend_gauge_orbit: committed objective \
                                 evaluation failed ({err}); restoring the pre-round state also \
                                 failed ({restore_err})"
                            )
                        })?;
                        return Err(format!(
                            "SaeManifoldTerm::descend_gauge_orbit: committed objective \
                             evaluation: {err}"
                        ));
                    }
                };
            let decrease = base_objective - committed_objective;
            if !(committed_objective.is_finite() && decrease > material_floor) {
                self.restore_mutable_state(&snapshot)
                    .map_err(|err| format!("SaeManifoldTerm::descend_gauge_orbit: {err}"))?;
                return Ok(outcome);
            }
            outcome.rounds += 1;
            outcome.objective_decrease += decrease;
            outcome.exit_objective = Some(committed_objective);
            log::debug!(
                "SAE gauge-orbit descent: round {} committed {decrease:.6e} at α={best_alpha:.6e} \
                 (objective {base_objective:.9e} → {committed_objective:.9e}, span dim {}, \
                 maxᵢ|gᵀvᵢ|={max_directional:.6e}, floor {material_floor:.6e})",
                outcome.rounds,
                outcome.dimension,
            );
        }
        Ok(outcome)
    }

    /// Quotient KKT-gradient norm² for the inner convergence gate (#1117): the
    /// joint gradient `[g_t (per row); g_β]` with the chart-gauge orbit and the
    /// rank-deficient decoder β-null projected out, so a rank-deficient atom
    /// whose residual gradient lives ONLY in those flat directions is recognised
    /// as stationary on the identified quotient manifold.
    ///
    /// `grad_ext_coord` is the per-row `g_t` flattened into the dense `n·q`
    /// coordinate layout (row `i` axis `a` at `i·q + a`); `grad_beta` is `g_β`.
    /// Falls back to the raw norm when the layout does not match the dense gauge
    /// basis (e.g. a streaming/heterogeneous system), exactly as the step measure
    /// does, so non-dense paths are unaffected.
    pub(crate) fn quotient_gradient_norm_sq(
        &self,
        grad_ext_coord: ArrayView1<'_, f64>,
        grad_beta: ArrayView1<'_, f64>,
        raw_grad_norm_sq: f64,
        penalized_gram_scale: &[f64],
    ) -> Result<f64, String> {
        let n = self.n_obs();
        let q = self.assignment.row_block_dim();
        let border_dim = self.factored_border_dim();
        if grad_ext_coord.len() != n * q || grad_beta.len() != border_dim {
            return Ok(raw_grad_norm_sq);
        }
        let mut residual = Array1::<f64>::zeros(grad_ext_coord.len() + grad_beta.len());
        for i in 0..grad_ext_coord.len() {
            residual[i] = grad_ext_coord[i];
        }
        let beta_base = grad_ext_coord.len();
        for i in 0..grad_beta.len() {
            residual[beta_base + i] = grad_beta[i];
        }
        let quotient = self.quotient_residual_norm_sq(residual, penalized_gram_scale)?;
        Ok(if quotient.is_finite() {
            quotient.max(0.0).min(raw_grad_norm_sq)
        } else {
            raw_grad_norm_sq
        })
    }

    pub(crate) fn quotient_gradient_norm_from_system(
        &self,
        sys: &ArrowSchurSystem,
        raw_grad_norm_sq: f64,
        penalized_gram_scale: &[f64],
    ) -> f64 {
        let n = self.n_obs();
        let q = self.assignment.row_block_dim();
        let dense_len = n.saturating_mul(q);
        let mut grad_ext_coord = Array1::<f64>::zeros(dense_len);
        let mut dense_layout_ok = sys.rows.len() == n && sys.row_offsets.len() == n + 1;
        if dense_layout_ok {
            for (row_idx, row) in sys.rows.iter().enumerate() {
                let base = sys.row_offsets[row_idx];
                let di = sys.row_dims[row_idx];
                if base + di > dense_len || row.gt.len() < di {
                    dense_layout_ok = false;
                    break;
                }
                for axis in 0..di {
                    grad_ext_coord[base + axis] = row.gt[axis];
                }
            }
        }
        let raw_grad_norm = raw_grad_norm_sq.sqrt();
        if dense_layout_ok {
            self.quotient_gradient_norm_sq(
                grad_ext_coord.view(),
                sys.gb.view(),
                raw_grad_norm_sq,
                penalized_gram_scale,
            )
            .map(|v| v.sqrt())
            .unwrap_or(raw_grad_norm)
        } else {
            raw_grad_norm
        }
    }

    pub(crate) fn dense_step_gauge_vectors(&self) -> Result<Vec<Array1<f64>>, String> {
        let n = self.n_obs();
        let q = self.assignment.row_block_dim();
        let p = self.output_dim();
        let coord_offsets = self.assignment.coord_offsets();
        let beta_offsets = self.factored_border_offsets();
        let total_len = n * q + self.factored_border_dim();
        let mut out = Vec::new();
        for atom_idx in 0..self.k_atoms() {
            let d = self.assignment.coords[atom_idx].latent_dim();
            let coords = self.assignment.coords[atom_idx].as_matrix();
            match self.atoms[atom_idx].basis_kind() {
                // The Poincaré tangent patch shares the Euclidean patch's
                // translation + scale gauge orbit on the tangent coordinate
                // (the hyperbolic structure lives in the penalty, not the
                // gauge), so it deflates the same step-gauge vectors.
                // The genuinely-linear (affine) atom shares the Euclidean patch's
                // translation + scale gauge orbit on its tangent coordinate (its
                // constant column carries the translation gauge, its `t` column
                // the scale gauge), so it deflates the same step-gauge vectors.
                SaeAtomBasisKind::Linear
                | SaeAtomBasisKind::EuclideanPatch
                | SaeAtomBasisKind::Poincare => {
                    for axis in 0..d {
                        let mut field = Array2::<f64>::zeros((n, d));
                        field.column_mut(axis).fill(1.0);
                        if let Some(g) = self.dense_step_gauge_vector_from_field(
                            atom_idx,
                            field.view(),
                            &coord_offsets,
                            &beta_offsets,
                            total_len,
                        )? {
                            out.push(g);
                        }
                    }
                    for axis in 0..d {
                        let mut field = Array2::<f64>::zeros((n, d));
                        for row in 0..n {
                            field[[row, axis]] = coords[[row, axis]];
                        }
                        if let Some(g) = self.dense_step_gauge_vector_from_field(
                            atom_idx,
                            field.view(),
                            &coord_offsets,
                            &beta_offsets,
                            total_len,
                        )? {
                            out.push(g);
                        }
                    }
                }
                SaeAtomBasisKind::Duchon => {
                    for axis in 0..d {
                        let mut field = Array2::<f64>::zeros((n, d));
                        field.column_mut(axis).fill(1.0);
                        if let Some(g) = self.dense_step_gauge_vector_from_field(
                            atom_idx,
                            field.view(),
                            &coord_offsets,
                            &beta_offsets,
                            total_len,
                        )? {
                            out.push(g);
                        }
                    }
                    for axis in 0..d {
                        let mut field = Array2::<f64>::zeros((n, d));
                        for row in 0..n {
                            field[[row, axis]] = coords[[row, axis]];
                        }
                        if let Some(g) = self.dense_step_gauge_vector_from_field(
                            atom_idx,
                            field.view(),
                            &coord_offsets,
                            &beta_offsets,
                            total_len,
                        )? {
                            out.push(g);
                        }
                    }
                }
                SaeAtomBasisKind::Periodic | SaeAtomBasisKind::Torus => {
                    for axis in 0..d {
                        let mut field = Array2::<f64>::zeros((n, d));
                        field.column_mut(axis).fill(1.0);
                        if let Some(g) = self.dense_step_gauge_vector_from_field(
                            atom_idx,
                            field.view(),
                            &coord_offsets,
                            &beta_offsets,
                            total_len,
                        )? {
                            out.push(g);
                        }
                    }
                }
                SaeAtomBasisKind::KleinBottle => {
                    if d != 2 {
                        return Err(format!(
                            "dense_step_gauge_vectors: Klein atom {atom_idx} requires latent dimension 2, got {d}"
                        ));
                    }
                    let mut field = Array2::<f64>::zeros((n, d));
                    field.column_mut(0).fill(1.0);
                    if let Some(g) = self.dense_step_gauge_vector_from_field(
                        atom_idx,
                        field.view(),
                        &coord_offsets,
                        &beta_offsets,
                        total_len,
                    )? {
                        out.push(g);
                    }
                }
                SaeAtomBasisKind::Sphere | SaeAtomBasisKind::ProjectivePlane => {
                    if d != 3 {
                        return Err(format!(
                            "dense_step_gauge_vectors: spherical atom {atom_idx} rides the ambient cover and requires latent dimension 3, got {d}"
                        ));
                    }
                    let mut fields = [
                        Array2::<f64>::zeros((n, d)),
                        Array2::<f64>::zeros((n, d)),
                        Array2::<f64>::zeros((n, d)),
                    ];
                    for row in 0..n {
                        let directions = ambient_sphere_killing_directions([
                            coords[[row, 0]],
                            coords[[row, 1]],
                            coords[[row, 2]],
                        ]);
                        for generator in 0..3 {
                            for axis in 0..3 {
                                fields[generator][[row, axis]] = directions[generator][axis];
                            }
                        }
                    }
                    for field in fields {
                        if let Some(g) = self.dense_step_gauge_vector_from_field(
                            atom_idx,
                            field.view(),
                            &coord_offsets,
                            &beta_offsets,
                            total_len,
                        )? {
                            out.push(g);
                        }
                    }
                }
                // `Cylinder` (`S¹ × ℝ`) carries exactly one continuous gauge: the
                // shift (rotation) of the periodic axis 0. The line axis 1 has no
                // rotational gauge and its translation is pinned by the constant
                // column, so we deflate only the axis-0 constant-shift field —
                // matching the `AtomTopology::Circle` identifiability choice.
                SaeAtomBasisKind::Cylinder => {
                    let mut field = Array2::<f64>::zeros((n, d));
                    if d > 0 {
                        field.column_mut(0).fill(1.0);
                    }
                    if let Some(g) = self.dense_step_gauge_vector_from_field(
                        atom_idx,
                        field.view(),
                        &coord_offsets,
                        &beta_offsets,
                        total_len,
                    )? {
                        out.push(g);
                    }
                }
                // The remaining kinds deflate no dense step gauge, each for its
                // own reason — spelled out as named arms so a new topology has
                // to state its gauge orbit here instead of silently inheriting
                // "none" from a wildcard.
                //
                // * `Mobius`: the half-twist lives in the parity culling of the
                //   basis (`trig(πks)·wᵐ`, `k + m` even), so a constant shift of
                //   the double-cover phase is NOT a symmetry of the culled span
                //   the way it is for `Periodic`/`Torus`; there is no enumerated
                //   continuous orbit to project out.
                // * `FiniteSet`: the latent is CATEGORICAL (anchor indicators),
                //   so there is no continuous coordinate to move along at all.
                // * `Precomputed`: the basis is supplied from outside this
                //   module and carries no declared gauge structure, so nothing
                //   may be assumed deflatable.
                SaeAtomBasisKind::Mobius
                | SaeAtomBasisKind::FiniteSet
                | SaeAtomBasisKind::Precomputed(_) => {}
            }
        }
        if p == 0 {
            return Ok(Vec::new());
        }
        Ok(out)
    }

    /// Put a dense-product-chart joint vector into the exact variable-stride
    /// arrow layout used by one assembled system/cache.
    ///
    /// Hard TopK removes inactive coordinate blocks row by row but retains the
    /// global decoder border.  All joint gauge/null producers naturally emit
    /// the full `n * q + beta` chart, so every consumer must cross this one seam
    /// before applying an arrow operator.  A stale layout or any shape mismatch
    /// is an invariant error; silently dropping the direction changes the
    /// quotient and can turn a chart null into a reported physical saddle.
    pub(crate) fn dense_joint_vector_in_arrow_layout(
        &self,
        dense: ArrayView1<'_, f64>,
        row_offsets: &[usize],
        border_dim: usize,
        owner: &str,
    ) -> Result<Array1<f64>, String> {
        let n = self.n_obs();
        let q = self.assignment.row_block_dim();
        let declared_border = self.factored_border_dim();
        if border_dim != declared_border {
            return Err(format!(
                "{owner}: arrow border dimension {border_dim} != term border dimension {declared_border}"
            ));
        }
        if row_offsets.len() != n + 1 || row_offsets.first() != Some(&0) {
            return Err(format!(
                "{owner}: arrow row offsets must have length {} and start at zero, got {:?}",
                n + 1,
                row_offsets
            ));
        }
        if let Some(layout) = self.last_row_layout.as_ref() {
            return layout.restrict_dense_joint_vector(
                dense,
                q,
                row_offsets,
                border_dim,
                owner,
            );
        }

        for row in 0..n {
            let span = row_offsets[row + 1]
                .checked_sub(row_offsets[row])
                .ok_or_else(|| format!("{owner}: arrow row offsets decrease at row {row}"))?;
            if span != q {
                return Err(format!(
                    "{owner}: dense arrow row {row} has width {span}, expected full chart width {q}"
                ));
            }
        }
        let expected = row_offsets[n]
            .checked_add(border_dim)
            .ok_or_else(|| format!("{owner}: arrow joint length overflows usize"))?;
        if dense.len() != expected {
            return Err(format!(
                "{owner}: dense joint vector has length {}, but the dense arrow layout has length {expected}",
                dense.len()
            ));
        }
        Ok(dense.to_owned())
    }

    /// Orthonormal analytic chart-gauge basis in one assembled arrow layout.
    /// Both dense exact-A quotient geometry and matrix-free arrow consumers use
    /// this basis, so the physical subspace cannot depend on representation.
    pub(crate) fn joint_chart_gauge_basis_for_arrow_layout(
        &self,
        row_offsets: &[usize],
        border_dim: usize,
        owner: &str,
    ) -> Result<Vec<Array1<f64>>, String> {
        let mut basis = Vec::<Array1<f64>>::new();
        // #2653 — a BORDER-dimension disagreement is not a stale layout, it is a
        // different chart. Hard TopK compaction drops inactive per-row coordinate
        // BLOCKS and retains the decoder border unchanged, so a genuine
        // full-to-compact map always agrees on the border; only the row widths
        // move (the filed 132 -> 84 case). When the border itself differs, this
        // operator is not a compaction of the joint chart at all and the
        // closed-form chart gauges simply do not live in its space. That is the
        // "no matching gauge" condition the caller already diagnoses as
        // `NonIdentifiable` — reporting it as an internal invariant error instead
        // converts a legitimate, more specific refusal into a bug report
        // (regression: `outer_gradient_solver_rejects_near_singular_cache_without_matching_gauge`
        // saw `arrow border dimension 1 != term border dimension 3`).
        // Row-layout disagreement stays a typed invariant error below, because
        // there the gauge IS mappable and silently skipping it would put an
        // analytic chart null back into the physical spectrum.
        if border_dim != self.factored_border_dim() {
            return Ok(Vec::new());
        }
        for dense in self.dense_step_gauge_vectors()? {
            let mut gauge = self.dense_joint_vector_in_arrow_layout(
                dense.view(),
                row_offsets,
                border_dim,
                owner,
            )?;
            let original_norm = gauge.dot(&gauge).max(0.0).sqrt();
            if !(original_norm.is_finite() && original_norm > 0.0) {
                continue;
            }
            // Two-pass MGS gives the same stable quotient basis to the dense and
            // matrix-free paths.  The numerical-rank decision is relative to
            // the candidate's own norm and derived from machine precision.
            for _ in 0..2 {
                for kept in &basis {
                    let coefficient = gauge.dot(kept);
                    gauge.scaled_add(-coefficient, kept);
                }
            }
            let residual_norm = gauge.dot(&gauge).max(0.0).sqrt();
            if !(residual_norm.is_finite()
                && residual_norm > f64::EPSILON.sqrt() * original_norm)
            {
                continue;
            }
            gauge.mapv_inplace(|value| value / residual_norm);
            basis.push(gauge);
        }
        Ok(basis)
    }

    /// Closed-form chart-gauge directions restricted to the reduced β border.
    ///
    /// Each returned vector is the β (decoder-border) component of a
    /// [`Self::dense_step_gauge_vectors`] orbit — the exact decoder compensation
    /// `δβ` that, paired with the coordinate motion `δt`, leaves the atom
    /// reconstruction invariant (`Φ(t+δt)·(β+δβ) = Φ(t)·β` to first order).
    ///
    /// By the arrow-Schur identity these β-components are exactly the null
    /// directions of the reduced β-Schur complement `S_β = H_ββ − H_βt H_tt⁻¹
    /// H_tβ`: from `H·(δt,δβ)ᵀ = 0` the elimination `δt = −H_tt⁻¹ H_tβ δβ` gives
    /// `S_β δβ = 0`. Installing them as an [`ArrowBetaGaugeQuotient`] therefore
    /// gauge-fixes the reduced Newton solve to the Faddeev–Popov quotient
    /// `P S_β P + Q Qᵀ` (`P = I − Q Qᵀ`), replacing an exactly-singular `S_β`
    /// with a well-conditioned operator whose gauge directions carry curvature
    /// `1`. The identifiable complement is untouched, so the step is unchanged
    /// off the orbit — only the orbit drift (the #2228 circle-rotation crawl that
    /// walks `t` off the manifold over the outer ρ-walk) is removed.
    ///
    /// The count is a structural property of the chart menu (one per circle /
    /// torus phase, translation+scale for the linear/euclidean/Duchon patches),
    /// so — unlike a spectral-floor discovery — it does not flicker across the
    /// ρ-walk (#2253).
    pub(crate) fn closed_form_beta_gauge_directions(&self) -> Result<Vec<Array1<f64>>, String> {
        let border = self.factored_border_dim();
        if border == 0 {
            return Ok(Vec::new());
        }
        let coord_len = self.n_obs() * self.assignment.row_block_dim();
        let mut out = Vec::new();
        // Independence probe for the emitted set. `ArrowBetaGaugeQuotient::new`
        // treats a linearly dependent direction as a MALFORMED DECLARATION and
        // refuses the whole solve — the right contract, since a caller that
        // declares a redundant generator has mis-specified its gauge. Honoring
        // it is the producer's job: the closed-form chart menu below is a
        // GENERATING SET, and a generating set can become dependent once
        // decoder frames compress the border. Two chart symmetries whose
        // decoder compensations are distinct in the full-`B` border can have
        // the SAME image in the factored `M_k × r_k` border (an atom whose
        // decoder is rank-deficient inside its own frame collapses its
        // per-axis translation/scale compensations onto each other), and the
        // fit then dies on `direction j is zero or linearly dependent` rather
        // than solving.
        //
        // Emit a maximal independent subset. This is exactly equivalent, not a
        // relaxation: the Faddeev–Popov pin `P S_β P + Q Qᵀ` with
        // `P = I − Q Qᵀ` is a function of the gauge SPAN alone, so dropping a
        // generator that adds nothing to the span leaves `P`, the pin, and the
        // projected step unchanged. The surviving vectors are pushed in their
        // ORIGINAL form (the probe basis is internal), so a set that was
        // already independent — every full-`B` fit — reaches the constructor
        // byte-for-byte as before and its quotient is bit-identical.
        //
        // Drop predicate: EXACTLY the constructor's own, `‖residual‖² > 0`
        // after modified Gram–Schmidt in the same order. Not a tolerance of
        // ours — deliberately not, because any stricter floor would be an
        // invented threshold that silently re-shapes the quotient on fits that
        // were solving perfectly well.
        //
        // Matching the predicate makes the change provably behavior-preserving
        // wherever it was not fatal. A dropped candidate contributed no vector
        // to the probe basis (its residual was zero), so the probe basis
        // evolves identically with or without it, and the constructor re-running
        // MGS over the survivors reproduces its previous arithmetic step for
        // step. The ONLY fits that move are the ones that previously died.
        let mut probe: Vec<Array1<f64>> = Vec::new();
        for gauge in self.dense_step_gauge_vectors()? {
            if gauge.len() != coord_len + border {
                continue;
            }
            let beta_part = gauge.slice(s![coord_len..]).to_owned();
            let norm_sq = beta_part.iter().map(|&v| v * v).sum::<f64>();
            // A gauge whose reconstruction motion is entirely absorbed by the
            // coordinate block (no decoder compensation) contributes no β-Schur
            // null direction; skip it so the quotient stays exactly the reduced
            // border nullspace.
            if !(norm_sq.is_finite() && norm_sq > 1.0e-24) {
                continue;
            }
            let mut residual = beta_part.clone();
            for basis in &probe {
                let coefficient = residual.dot(basis);
                residual.scaled_add(-coefficient, basis);
            }
            let residual_norm_sq = residual.dot(&residual);
            if !(residual_norm_sq.is_finite() && residual_norm_sq > 0.0) {
                continue;
            }
            residual *= residual_norm_sq.sqrt().recip();
            probe.push(residual);
            out.push(beta_part);
        }
        Ok(out)
    }

    pub(crate) fn row_gauge_deflation_for_layout(
        &self,
        row_layout: Option<&SaeRowLayout>,
    ) -> Result<Option<ArrowRowGaugeDeflation>, String> {
        let n = self.n_obs();
        let mut rows: Vec<Vec<Array1<f64>>> = Vec::with_capacity(n);
        for row in 0..n {
            let q_row = match row_layout {
                Some(layout) => layout.row_q_active(row),
                None => self.assignment.row_block_dim(),
            };
            rows.push(Vec::with_capacity(self.k_atoms().min(4)));
            match row_layout {
                Some(layout) => {
                    for (active_pos, &atom_idx) in layout.active_atoms[row].iter().enumerate() {
                        let start = layout.coord_starts[row][active_pos];
                        self.push_atom_row_gauge_deflations(
                            &mut rows[row],
                            row,
                            atom_idx,
                            start,
                            q_row,
                        )?;
                    }
                }
                None => {
                    let coord_offsets = self.assignment.coord_offsets();
                    for atom_idx in 0..self.k_atoms() {
                        self.push_atom_row_gauge_deflations(
                            &mut rows[row],
                            row,
                            atom_idx,
                            coord_offsets[atom_idx],
                            q_row,
                        )?;
                    }
                }
            }
        }
        if rows.iter().all(Vec::is_empty) {
            Ok(None)
        } else {
            Ok(Some(ArrowRowGaugeDeflation::new(rows)))
        }
    }

    pub(crate) fn push_atom_row_gauge_deflations(
        &self,
        row_dirs: &mut Vec<Array1<f64>>,
        row: usize,
        atom_idx: usize,
        coord_start: usize,
        q_row: usize,
    ) -> Result<(), String> {
        let d = self.assignment.coords[atom_idx].latent_dim();
        let mut tangent = vec![0.0_f64; self.output_dim()];
        match self.atoms[atom_idx].basis_kind() {
            SaeAtomBasisKind::Linear
            | SaeAtomBasisKind::EuclideanPatch
            | SaeAtomBasisKind::Duchon
            | SaeAtomBasisKind::Poincare => {
                for axis in 0..d {
                    self.atoms[atom_idx].fill_decoded_derivative_row(row, axis, &mut tangent);
                    if tangent.iter().map(|&v| v * v).sum::<f64>() <= 1.0e-24 {
                        continue;
                    }
                    let mut translation = Array1::<f64>::zeros(q_row);
                    translation[coord_start + axis] = 1.0;
                    row_dirs.push(translation);

                    let coord_value = self.assignment.coords[atom_idx].as_matrix()[[row, axis]];
                    let mut scale = Array1::<f64>::zeros(q_row);
                    scale[coord_start + axis] = coord_value;
                    row_dirs.push(scale);
                }
            }
            SaeAtomBasisKind::Periodic | SaeAtomBasisKind::Torus => {
                for axis in 0..d {
                    self.atoms[atom_idx].fill_decoded_derivative_row(row, axis, &mut tangent);
                    if tangent.iter().map(|&v| v * v).sum::<f64>() <= 1.0e-24 {
                        continue;
                    }
                    let mut phase = Array1::<f64>::zeros(q_row);
                    phase[coord_start + axis] = 1.0;
                    row_dirs.push(phase);
                }
            }
            SaeAtomBasisKind::KleinBottle => {
                if d != 2 {
                    return Err(format!(
                        "push_atom_row_gauge_deflations: Klein atom {atom_idx} requires latent dimension 2, got {d}"
                    ));
                }
                self.atoms[atom_idx].fill_decoded_derivative_row(row, 0, &mut tangent);
                if tangent.iter().map(|&v| v * v).sum::<f64>() > 1.0e-24 {
                    let mut phase = Array1::<f64>::zeros(q_row);
                    phase[coord_start] = 1.0;
                    row_dirs.push(phase);
                }
            }
            SaeAtomBasisKind::Sphere | SaeAtomBasisKind::ProjectivePlane => {
                if d != 3 {
                    return Err(format!(
                        "push_atom_row_gauge_deflations: spherical atom {atom_idx} rides the ambient cover and requires latent dimension 3, got {d}"
                    ));
                }
                let coords = self.assignment.coords[atom_idx].as_matrix();
                let directions = ambient_sphere_killing_directions([
                    coords[[row, 0]],
                    coords[[row, 1]],
                    coords[[row, 2]],
                ]);
                for direction in directions {
                    let mut decoded_motion = vec![0.0_f64; self.output_dim()];
                    for axis in 0..3 {
                        self.atoms[atom_idx].fill_decoded_derivative_row(row, axis, &mut tangent);
                        for output in 0..decoded_motion.len() {
                            decoded_motion[output] += direction[axis] * tangent[output];
                        }
                    }
                    if decoded_motion.iter().map(|&v| v * v).sum::<f64>() <= 1.0e-24 {
                        continue;
                    }
                    let mut rotation = Array1::<f64>::zeros(q_row);
                    for axis in 0..2 {
                        rotation[coord_start + axis] = direction[axis];
                    }
                    row_dirs.push(rotation);
                }
            }
            // `Cylinder` (`S¹ × ℝ`): only the periodic axis 0 carries a phase
            // (rotation) gauge; the line axis 1 has none (matching the
            // `AtomTopology::Circle` choice). Deflate the axis-0 phase only.
            SaeAtomBasisKind::Cylinder => {
                if d > 0 {
                    self.atoms[atom_idx].fill_decoded_derivative_row(row, 0, &mut tangent);
                    if tangent.iter().map(|&v| v * v).sum::<f64>() > 1.0e-24 {
                        let mut phase = Array1::<f64>::zeros(q_row);
                        phase[coord_start] = 1.0;
                        row_dirs.push(phase);
                    }
                }
            }
            // No row gauge direction, for the same per-kind reasons spelled out
            // in `dense_step_gauge_vectors`: `Mobius`'s parity-culled basis has
            // no enumerated continuous phase orbit, `FiniteSet`'s latent is
            // categorical rather than continuous, and `Precomputed` carries no
            // declared gauge structure. Named so a new topology cannot inherit
            // "none" silently.
            SaeAtomBasisKind::Mobius
            | SaeAtomBasisKind::FiniteSet
            | SaeAtomBasisKind::Precomputed(_) => {}
        }
        Ok(())
    }

    pub(crate) fn dense_step_gauge_vector_from_field(
        &self,
        atom_idx: usize,
        field: ArrayView2<'_, f64>,
        coord_offsets: &[usize],
        beta_offsets: &[usize],
        total_len: usize,
    ) -> Result<Option<Array1<f64>>, String> {
        let n = self.n_obs();
        let q = self.assignment.row_block_dim();
        let p = self.output_dim();
        let atom = &self.atoms[atom_idx];
        let m = atom.basis_size();
        let d = self.assignment.coords[atom_idx].latent_dim();
        if field.dim() != (n, d) {
            return Err(format!(
                "dense_step_gauge_vector_from_field: field shape {:?} != ({n}, {d})",
                field.dim()
            ));
        }
        let mut design = Array2::<f64>::zeros((n, m));
        let mut motion = Array2::<f64>::zeros((n, p));
        for row in 0..n {
            let assignments = self.assignment.try_assignments_row(row)?;
            let a = assignments[atom_idx];
            if a == 0.0 {
                continue;
            }
            for col in 0..m {
                design[[row, col]] = a * atom.basis_values[[row, col]];
            }
            for axis in 0..d {
                let dt = field[[row, axis]];
                if dt == 0.0 {
                    continue;
                }
                for col in 0..m {
                    let w = a * dt * atom.basis_jacobian[[row, col, axis]];
                    if w == 0.0 {
                        continue;
                    }
                    for out_col in 0..p {
                        motion[[row, out_col]] += w * atom.decoder_coefficients()[[col, out_col]];
                    }
                }
            }
        }
        let raw = motion.iter().map(|v| v * v).sum::<f64>();
        if raw <= f64::MIN_POSITIVE || !raw.is_finite() {
            return Ok(None);
        }
        motion.mapv_inplace(|v| -v);
        let delta_b = solve_design_least_squares(design.view(), motion.view())?;
        let mut gauge = Array1::<f64>::zeros(total_len);
        for row in 0..n {
            let row_base = row * q + coord_offsets[atom_idx];
            for axis in 0..d {
                gauge[row_base + axis] = field[[row, axis]];
            }
        }
        let beta_base = n * q + beta_offsets[atom_idx];
        let delta_border = match atom.decoder_frame.as_ref() {
            Some(frame) => delta_b.dot(&frame.frame()),
            None => delta_b,
        };
        let border_rank = delta_border.ncols();
        for col in 0..m {
            for channel in 0..border_rank {
                gauge[beta_base + col * border_rank + channel] = delta_border[[col, channel]];
            }
        }
        Ok(Some(gauge))
    }

    /// #976 Layer-1 guard ledger for the most recent joint fit (empty when no
    /// atom ever breached the active-mass floor). A terminal event here is the
    /// canonical death-proposal feed for the structure search.
    pub fn collapse_events(&self) -> &[CollapseEvent] {
        &self.collapse_events
    }

    /// #1023 final same-state dictionary guard.
    ///
    /// Record terminal [`CollapseEvent`]s only when the shared structural
    /// verdict proves all gated decoder signals numerically vanished or #2362's
    /// union-output-subspace arm fires. Training EV is payload telemetry, never
    /// the decision. Reconstruction, assignments, Grams, and decoder frames are
    /// derived internally from the same `self + target + rho` state.
    pub fn record_fit_data_collapse_if_needed(
        &mut self,
        target: ArrayView2<'_, f64>,
        rho: &SaeManifoldRho,
        iteration: usize,
    ) -> Result<bool, String> {
        let (n, p) = target.dim();
        if n == 0 || p == 0 || self.k_atoms() == 0 {
            return Ok(false);
        }
        let atom_count = self.k_atoms();
        let verdict = self.dictionary_collapse_verdict(target, rho, None)?;
        if let Some(reason) = verdict.proof_unavailable_reason() {
            return Err(format!(
                "SaeManifoldTerm::record_fit_data_collapse_if_needed: \
                 decoder-vanishing proof unavailable: {reason}"
            ));
        }
        if !verdict.degenerate(atom_count) {
            return Ok(false);
        }

        let assignments = self.assignment.try_assignments()?;
        let event_floor = verdict.collapse_event_floor(atom_count).ok_or_else(|| {
            "collapse verdict was degenerate without a certified event boundary".to_string()
        })?;
        let mut collapsed_active_atom = false;
        for atom in 0..atom_count {
            let active_mass = assignments
                .column(atom)
                .iter()
                .copied()
                .fold(0.0_f64, f64::max);
            if active_mass == 0.0 {
                continue;
            }
            collapsed_active_atom = true;
            let already_terminal = self
                .collapse_events
                .iter()
                .any(|e| e.atom == atom && e.action == CollapseAction::Terminal);
            if already_terminal {
                continue;
            }
            self.collapse_events.push(CollapseEvent {
                iteration,
                atom,
                // Historical field name; final collapse events carry the
                // reconstruction EV as diagnostic payload.
                max_active_mass: verdict.explained_variance,
                // Vanishing arm: the signal boundary derived from the residual
                // roundoff envelope. Structural arm: rank-matched random-subspace reach.
                floor: event_floor,
                action: CollapseAction::Terminal,
            });
        }
        Ok(collapsed_active_atom)
    }

    /// The most recent curvature-homotopy entry walk outcome (#1007), or `None`
    /// when no walk has run on this term. Read off the fitted term so the
    /// arrival / bifurcation / collapse outcome is observable.
    pub fn curvature_walk_report(&self) -> Option<&CurvatureWalkReport> {
        self.curvature_walk_report.as_ref()
    }

    /// Per-row reconstruction residual `r_i = fitted_i − z_i` of the current
    /// `(gates, coords, decoder)` state against `target`, in the term's native
    /// `(n, p)` layout. The curvature-homotopy predictor (#1007) contracts this
    /// against `∂Φ/∂η` to form the data-fit half of `∂g_β/∂η`.
    pub(crate) fn reconstruction_residual(
        &self,
        target: ArrayView2<'_, f64>,
        rho: &SaeManifoldRho,
    ) -> Result<Array2<f64>, String> {
        let fitted = self.try_fitted_for_rho(rho)?;
        if fitted.dim() != target.dim() {
            return Err(format!(
                "SaeManifoldTerm::reconstruction_residual: fitted {:?} != target {:?}",
                fitted.dim(),
                target.dim()
            ));
        }
        Ok(&fitted - &target)
    }

    /// #976 Layer-1 guard 3: the per-atom active-mass floor, checked once per
    /// accepted outer iteration of the joint fit.
    ///
    /// The collapse statistic is each atom's MAXIMUM assignment mass over rows
    /// (the per-atom max mass, not mean, is the collapse statistic). A breach is
    /// answered with a gate-logit re-seed — once per atom per fit
    /// ([`SAE_ATOM_COLLAPSE_RESEED_BUDGET`]) — and recorded as a
    /// [`CollapseEvent`]; a breach after the budget is recorded once as
    /// terminal and otherwise left alone: at that point the collapse is the
    /// objective's (local) verdict at the current hyperparameters, and the
    /// keep-or-kill decision belongs to the evidence-gated structure search,
    /// not to an inner-loop heuristic. Observable events, never silent deaths,
    /// never fit errors.
    pub(crate) fn enforce_active_mass_guard(
        &mut self,
        iteration: usize,
        rho: Option<&SaeManifoldRho>,
    ) -> Result<(), String> {
        // SAC — the K=1 stagewise lane disarms the guard stack: a single atom has
        // no dictionary peer to collapse against, so the reseed machinery is a
        // no-op there, and disarming keeps the per-atom / backfitting refits
        // provably reseed-free (block-coordinate monotonicity).
        if !self.guards_enabled {
            return Ok(());
        }
        let n = self.n_obs();
        let k = self.k_atoms();
        if n == 0 || k == 0 {
            return Ok(());
        }
        let mut max_mass = vec![0.0_f64; k];
        // #1557 — reuse a single K-sized scratch row across all N rows; only
        // `a[atom]` is read per row (alias-free reuse).
        let mut a = vec![0.0_f64; k];
        for row in 0..n {
            match rho {
                Some(_) => self.assignment.try_assignments_row_into(row, &mut a),
                None => self
                    .assignment
                    .try_assignments_row(row)
                    .map(|row_a| a.copy_from_slice(row_a.as_slice().expect("contiguous row"))),
            }
            .map_err(|e| format!("SaeManifoldTerm::enforce_active_mass_guard: {e}"))?;
            for atom in 0..k {
                if a[atom] > max_mass[atom] {
                    max_mass[atom] = a[atom];
                }
            }
        }
        // The per-atom collapse statistic is each atom's MAXIMUM assignment mass
        // over rows; an atom whose strongest gate has fallen below the active-mass
        // floor has lost all material support and must be re-seeded. The floor is
        // the production trust threshold ([`SAE_TRUST_ACTIVE_MASS_FLOOR`]) — the
        // same bar the atom-lens uses to decide an atom carries usable signal.
        // (A blind `max_mass.is_finite()` test does NOT detect this: a gate-
        // collapsed atom still has a finite, merely tiny, max mass, so a finiteness
        // check waves the exact #976 mass-collapse mode straight through.)
        let active_mass_floor = crate::inference::atom_lens::SAE_TRUST_ACTIVE_MASS_FLOOR;
        for atom in 0..k {
            // Healthy atom: its strongest gate clears the floor. A non-finite max
            // mass fails `>= floor` and so is treated as a breach (correctly).
            if max_mass[atom] >= active_mass_floor {
                continue;
            }
            let reseeds_used = self
                .collapse_events
                .iter()
                .filter(|e| e.atom == atom && e.action == CollapseAction::Reseeded)
                .count();
            if reseeds_used < SAE_ATOM_COLLAPSE_RESEED_BUDGET {
                self.reseed_collapsed_atom_logits(atom);
                self.collapse_events.push(CollapseEvent {
                    iteration,
                    atom,
                    max_active_mass: max_mass[atom],
                    floor: active_mass_floor,
                    action: CollapseAction::Reseeded,
                });
            } else {
                let already_terminal = self
                    .collapse_events
                    .iter()
                    .any(|e| e.atom == atom && e.action == CollapseAction::Terminal);
                if !already_terminal {
                    self.collapse_events.push(CollapseEvent {
                        iteration,
                        atom,
                        max_active_mass: max_mass[atom],
                        floor: active_mass_floor,
                        action: CollapseAction::Terminal,
                    });
                }
            }
        }
        Ok(())
    }

    /// Re-seed one collapsed atom's gate logits to the mode-appropriate
    /// neutral that restores material support — the data-fit term can then
    /// hold the atom active iff it carries signal. Latent coordinates are
    /// deliberately left untouched: gate-driven collapse kills the support,
    /// not the (still data-adjacent) coordinates, and a coordinate re-seed
    /// would discard exactly the warm state that makes the second chance
    /// cheap.
    pub(crate) fn reseed_collapsed_atom_logits(&mut self, atom: usize) {
        let n = self.n_obs();
        match self.assignment.mode {
            AssignmentMode::Softmax { .. } => {
                // Tie the re-seeded atom with each row's current winner so it
                // re-enters the simplex at parity instead of inheriting a
                // saturated deficit.
                for row in 0..n {
                    let row_max = self
                        .assignment
                        .logits
                        .row(row)
                        .iter()
                        .copied()
                        .fold(f64::NEG_INFINITY, f64::max);
                    self.assignment.logits[[row, atom]] =
                        if row_max.is_finite() { row_max } else { 0.0 };
                }
                canonicalize_softmax_logits(&mut self.assignment.logits);
            }
            AssignmentMode::OrderedBetaBernoulli { .. } => {
                // σ(0/τ) = ½ — the sigmoid gate's neutral point.
                for row in 0..n {
                    self.assignment.logits[[row, atom]] = 0.0;
                }
            }
            AssignmentMode::ThresholdGate {
                temperature,
                threshold,
            } => {
                // One temperature unit above the smooth gate center:
                // just-active, inside the smooth transition band.
                for row in 0..n {
                    self.assignment.logits[[row, atom]] = threshold + temperature;
                }
            }
            AssignmentMode::TopK { .. } => {
                // The support is a deterministic top-k of the ROUTING logits, so
                // "re-seed to neutral" means routing parity: tie the atom with
                // each row's current winner so the next support refresh can admit
                // it wherever it carries signal (the analogue of the Softmax
                // parity re-seed, without any simplex canonicalization).
                for row in 0..n {
                    let row_max = self
                        .assignment
                        .logits
                        .row(row)
                        .iter()
                        .copied()
                        .fold(f64::NEG_INFINITY, f64::max);
                    self.assignment.logits[[row, atom]] =
                        if row_max.is_finite() { row_max } else { 0.0 };
                }
            }
        }
    }

    /// #2015 decoder-scaling-gauge fix (the inner-solve stability keystone).
    ///
    /// The joint `(t, β)` reconstruction is invariant under the per-atom amplitude
    /// gauge `a_k·B_k` (assignment mass × decoder): a DYING atom whose mass
    /// `a_{ik} → 0` can send its decoder `B_k → ∞` with the product `a_k·B_k` —
    /// hence the reconstruction and the whole penalized objective — UNCHANGED, so
    /// the Armijo line search happily accepts it (the objective is flat along the
    /// gauge). But the KKT stationarity gradient with respect to the assignment
    /// logit / coordinate is proportional to `Φᵀ B_k`, so an unbounded decoder
    /// makes `‖g‖` EXPLODE while the fit stays objective-good — measured in the
    /// #2015 probe as `‖g‖ = 2.887e8` at a decoder norm of `1.6e11` (objective
    /// flat at ~40, coordinates modest, no reseed), a spurious non-stationarity the
    /// inner solve then has to grind back down over many iterations (the real
    /// 600-row `qwen_real_activation_behavior_fit` stall). The coordinate-gauge
    /// quotient `‖Π⊥null g‖` does NOT capture this DECODER-amplitude gauge (a
    /// different flat direction), which is why raw ≈ quotient at the stall.
    ///
    /// This re-gauges any atom whose decoder norm has run past the dictionary's
    /// robust scale back ONTO that scale, moving the reciprocal factor into the
    /// softmax logits so the physical contribution `a_k·B_k` is preserved. In the
    /// dying-atom limit `a_{ik} ≪ 1` — exactly where the runaway lives — the
    /// softmax normalizer is unchanged by a shift in one column, so `z_{·k} +=
    /// ln s` reproduces `a_k → s·a_k` and the compensation is EXACT. The caller
    /// applies this inside the objective-guarded retraction hook, which reverts it
    /// if it perturbs the objective, so it is safe for any atom. Bounding the
    /// decoder norm bounds the gradient.
    ///
    /// Reuses the collapse guard's robust MEDIAN scale and its single ratio
    /// constant: an atom fires when its norm exceeds `median /
    /// SAE_ATOM_DECODER_NORM_COLLAPSE_RATIO` — the exact MIRROR of the collapse
    /// floor `SAE_ATOM_DECODER_NORM_COLLAPSE_RATIO · median` — and is re-gauged
    /// back to the median (the same robust scale the collapse arm reseeds onto). No
    /// new tuning knob. Softmax-only: other assignment modes have no free
    /// multiplicative amplitude to absorb the scale, so `z += ln s` would not
    /// reproduce `a → s·a` there. Skipped when decoder frames are active (a
    /// factored-frame decoder must not be rescaled out from under its frame — the
    /// same conservative choice `refit_decoder_least_squares` makes). K=1 is a
    /// strict no-op: mass ≡ 1 (data-fit-pins the scale) and there is no peer
    /// median.
    pub(crate) fn fix_decoder_scale_gauge(&mut self) -> Result<(), String> {
        let k = self.k_atoms();
        if k < 2 || self.frames_active() {
            return Ok(());
        }
        if !matches!(self.assignment.mode, AssignmentMode::Softmax { .. }) {
            return Ok(());
        }
        let norms: Vec<f64> = self
            .atoms
            .iter()
            .map(|atom| atom.contribution_frobenius_scale())
            .collect();
        let mut sorted = norms.clone();
        sorted.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
        let median = if k % 2 == 1 {
            sorted[k / 2]
        } else {
            0.5 * (sorted[k / 2 - 1] + sorted[k / 2])
        };
        if !(median > 0.0) {
            return Ok(());
        }
        let ceiling = median / SAE_ATOM_DECODER_NORM_COLLAPSE_RATIO;
        let n = self.n_obs();
        let mut any_regauged = false;
        for atom in 0..k {
            if !(norms[atom] > ceiling) {
                continue;
            }
            // Re-gauge the runaway decoder back to the robust median scale and put
            // the reciprocal into the logits so `a_k·B_k` is preserved.
            let s = norms[atom] / median;
            if !(s.is_finite() && s > 1.0) {
                continue;
            }
            self.atoms[atom]
                .decoder_coefficients_mut()
                .mapv_inplace(|v| v / s);
            let ln_s = s.ln();
            for row in 0..n {
                self.assignment.logits[[row, atom]] += ln_s;
            }
            any_regauged = true;
        }
        if any_regauged {
            canonicalize_softmax_logits(&mut self.assignment.logits);
        }
        Ok(())
    }

    /// #976 Layer-1 guard (decoder arm): the per-atom **decoder-norm** floor,
    /// checked once per accepted outer iteration of the joint K>1 fit.
    ///
    /// The gate-mass guard ([`Self::enforce_active_mass_guard`]) catches an atom
    /// whose *assignment* support vanished, but it is blind to the real-data K>1
    /// failure (#853/#976 class) where the assignment gates stay spread across
    /// rows yet every atom's *decoder* `B_k` collapses to ≈0. A zero decoder
    /// decodes nothing, so the dictionary explains nothing (EV≈0) and every
    /// per-row coordinate Hessian `H_tt` — whose curvature is carried by `Φ·B`
    /// — goes rank-deficient at once, surfacing as the `0 → K·n` evidence
    /// gauge-deflation jump that aborts `penalized_quasi_laplace_criterion`. The decoder-norm guard
    /// closes that blind spot.
    ///
    /// The collapse statistic is each atom's decoder Frobenius norm as a RATIO
    /// to the dictionary's MEDIAN decoder norm (scale-free: a uniformly small
    /// but well-conditioned decoder never trips it; only an atom that has fallen
    /// far behind its peers does). A breach is answered, within the SAME shared
    /// per-atom budget as the mass guard, by re-diversifying the atom's latent
    /// coordinates onto a distinct, currently-unexplained direction of the
    /// reconstruction residual and re-fitting all decoders by joint least
    /// squares so the reseeded atom claims real signal rather than re-collapsing
    /// — then recorded as a [`CollapseEvent`]. After the budget a breach is
    /// recorded once as terminal and left for the evidence-gated structure
    /// search, exactly like the mass arm.
    ///
    /// **K=1 is a strict no-op**: with a single atom there is no peer to fall
    /// behind, the median equals the atom's own norm, the ratio is exactly `1`,
    /// and the early return below fires before any state is touched. The K=1
    /// fit path is therefore byte-for-byte unchanged.
    pub(crate) fn enforce_decoder_norm_guard(
        &mut self,
        target: ArrayView2<'_, f64>,
        iteration: usize,
        rho: &SaeManifoldRho,
        target_col_stats: Option<&TargetCenteredColStats>,
    ) -> Result<(), String> {
        // SAC — the stagewise lane disarms the guard stack (see
        // `enforce_active_mass_guard`); a disarmed term never reseeds.
        if !self.guards_enabled {
            return Ok(());
        }
        let n = self.n_obs();
        let k = self.k_atoms();
        // A single atom has no dictionary peer to be distinct from, so the
        // decoder-incoherence failure mode this guard catches cannot exist;
        // returning here keeps the K=1 path untouched.
        if n == 0 || k < 2 {
            return Ok(());
        }
        let norms: Vec<f64> = self
            .atoms
            .iter()
            .map(|atom| atom.contribution_frobenius_scale())
            .collect();
        // Median physical decoder norm: the robust dictionary scale.
        let mut sorted = norms.clone();
        sorted.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
        let median = if k % 2 == 1 {
            sorted[k / 2]
        } else {
            0.5 * (sorted[k / 2 - 1] + sorted[k / 2])
        };
        // No usable scale (every decoder is ≈0). At ENTRY (iteration 0) this is the
        // cold-start zero seed — the joint solve has not placed any signal yet, so
        // there is nothing to be "behind"; defer to the mass guard / inner solve
        // rather than reseed against an all-zero reference.
        //
        // #2027: at iteration > 0 a zero median is NOT cold — the joint solve has
        // run and still left every decoder vanished. Fall through: the relative
        // floor is zero, so `breached` remains empty, and the same-state absolute
        // arm below can certify disappearance from the gated signal itself.
        if !(median > 0.0) && iteration == 0 {
            return Ok(());
        }
        let floor = SAE_ATOM_DECODER_NORM_COLLAPSE_RATIO * median;
        let mut breached: Vec<usize> = Vec::new();
        for atom in 0..k {
            if norms[atom] < floor {
                breached.push(atom);
            }
        }
        if breached.is_empty() {
            // The median-relative test found no atom "behind" its peers, but the
            // whole dictionary can still have co-collapsed: every decoder can
            // disappear together, collapsing the median with them, or the #2362
            // union-output-span arm can prove that the atoms merged structurally.
            //
            // Never apply this absolute arm at iteration zero. That state is a
            // cold seed, not evidence that an optimization basin is stalled. Once
            // an accepted step exists, make the hard decision from the actual
            // gated decoder signal and the live union output span. Training EV is
            // retained only to order and report basin candidates.
            if iteration == 0 {
                return Ok(());
            }
            let verdict = self.dictionary_collapse_verdict(target, rho, target_col_stats)?;
            if let Some(reason) = verdict.proof_unavailable_reason() {
                return Err(format!(
                    "SaeManifoldTerm::enforce_decoder_norm_guard: \
                     decoder-vanishing proof unavailable: {reason}"
                ));
            }
            let ev = verdict.explained_variance;
            let dictionary_degenerate = verdict.degenerate(k);
            if !dictionary_degenerate
                && let Some((j, kk, coherence)) = self.structural_coherence_collapse_detected()?
            {
                log::warn!(
                    "SaeManifoldTerm: structural coherence collapse — atoms ({j}, {kk}) decode a \
                     shared output subspace (μ̂={coherence:.4} above the derived random-subspace \
                     null) at healthy EV={ev:.4}; diagnostic only, deferred to the structure search"
                );
            }
            if !dictionary_degenerate {
                return Ok(());
            }
            let collapse_event_floor = verdict.collapse_event_floor(k).ok_or_else(|| {
                "degenerate dictionary verdict omitted its certified boundary".to_string()
            })?;
            let max_signal_upper_bound = verdict
                .decoder_vanishing
                .max_signal_upper_bound()
                .ok_or_else(|| {
                    "certified decoder-vanishing verdict omitted signal bounds".to_string()
                })?;
            let residual_roundoff_floor = verdict
                .decoder_vanishing
                .residual_roundoff_floor()
                .ok_or_else(|| {
                    "certified decoder-vanishing verdict omitted its roundoff floor".to_string()
                })?;
            let residual_scale_upper = verdict
                .decoder_vanishing
                .residual_scale_upper()
                .ok_or_else(|| {
                    "certified decoder-vanishing verdict omitted its residual scale".to_string()
                })?;
            let signal_vanish_boundary = verdict
                .decoder_vanishing
                .signal_vanish_boundary()
                .ok_or_else(|| {
                    "certified decoder-vanishing verdict omitted its signal boundary".to_string()
                })?;
            let collapse_arm = if verdict.all_decoders_vanished(k) {
                "all gated decoder signals vanished at floating-point resolution"
            } else {
                "the decoder union output span collapsed structurally"
            };
            // #1026 keep-best multi-start: the current (pre-reseed) state is a
            // candidate basin. A blind reseed can replace it with a STRICTLY worse
            // basin (real OLMo K=4: the seed explains EV 0.127 but successive
            // reseeds fall to −1.01), so before perturbing, retain this state as
            // the incumbent whenever its EV beats the best seen this optimization.
            // On budget exhaustion we restore the incumbent rather than leaving the
            // last (often catastrophic) reseed — a multi-start must never return a
            // basin worse than one it already visited.
            // #2081 — the incumbent comparison prices reconstruction EV FIRST and,
            // at (near-)equal EV, breaks the tie on coordinate uniformity: EV
            // provably does not certify the coordinate, so a reseed that ties on EV
            // but reads a more uniform angle is the better basin.
            let candidate_uniformity = self.coordinate_uniformity_aggregate();
            let prefer = match self.best_cocollapse_incumbent.as_ref() {
                None => ev.is_finite(),
                Some((best_ev, best_uniformity, _)) => prefer_candidate_basin(
                    ev,
                    candidate_uniformity,
                    *best_ev,
                    *best_uniformity,
                    SAE_FINAL_EV_DEGRADATION_TOL,
                ),
            };
            if prefer {
                self.best_cocollapse_incumbent =
                    Some((ev, candidate_uniformity, self.snapshot_mutable_state()));
            }
            // Co-collapsed numerically or structurally. Reseed ALL atoms onto
            // DISTINCT residual PCs — keeping no "anchor", because the same-state
            // proof says there is no distinct healthy atom worth anchoring. The two
            // properties an anchor was meant to provide are already supplied by
            // the residual seeding itself:
            // (1) the residual is computed from the current (degenerate) fit, so
            // with EV≈0 it is ≈ the target and therefore non-degenerate; and
            // (2) `reseed_atoms_onto_distinct_residual_pcs` assigns each atom slot
            // its OWN disjoint residual-PC pair (the #671 rule), so the set cannot
            // re-symmetrise into one basin in a single step. Reseeding all K onto K
            // distinct PC pairs is the maximal-diversity multi-start — the
            // strongest basin break available.
            //
            // Budget: a SINGLE maximal-diversity reseed still cannot always break a
            // K≥3 basin — one freshly-diversified start can re-symmetrise back into
            // a shared basin under the joint LSQ refit (#1117 K>1 robustness:
            // identical (K=3, seed) flipped EV≈0.40 ↔ 0.00 across runs). This arm
            // is therefore a bounded DICTIONARY multi-start, NOT the per-atom
            // mass-guard loop: each retry recomputes the residual from the
            // (still-degenerate) current fit and seeds onto the NEW distinct PCs, so
            // successive attempts explore genuinely different basins rather than
            // fighting the optimizer over one atom. It gets its OWN budget
            // (`SAE_DICTIONARY_COCOLLAPSE_RESEED_BUDGET`), distinct from the
            // per-atom `SAE_ATOM_COLLAPSE_RESEED_BUDGET` (which stays 1 for the
            // reasons in its doc). The branch is a no-op unless the same-state
            // proof above establishes numerical or structural disappearance.
            if self.dictionary_cocollapse_reseeds >= SAE_DICTIONARY_COCOLLAPSE_RESEED_BUDGET {
                // Multi-start budget spent. #1026: restore the BEST basin seen
                // across all reseeds (including the original seed) before giving up
                // — the current state is the last reseed, which the keep-best
                // ledger may show was strictly worse than an earlier attempt. This
                // converts the catastrophic-last-reseed outcome (EV −1.01) back to
                // the best basin found (EV 0.127), so the evidence-gated structure
                // search ranks the dictionary's real best, not its worst attempt.
                if let Some((best_ev, best_uniformity, best_state)) =
                    self.best_cocollapse_incumbent.take()
                {
                    // #2081 — restore the incumbent when it is the better basin under
                    // the same EV-then-uniformity ordering used to bank it: strictly
                    // higher EV, or (near-)equal EV with a more uniform coordinate.
                    let current_uniformity = self.coordinate_uniformity_aggregate();
                    if prefer_candidate_basin(
                        best_ev,
                        best_uniformity,
                        ev,
                        current_uniformity,
                        SAE_FINAL_EV_DEGRADATION_TOL,
                    ) {
                        self.restore_mutable_state(&best_state)?;
                        log::warn!(
                            "SaeManifoldTerm: dictionary co-collapse multi-start budget spent; \
                             restoring best basin (EV={best_ev:.4}) over last reseed (EV={ev:.4})"
                        );
                    }
                }
                // Multi-start budget spent: record a terminal event for each atom
                // once and leave the keep-or-kill verdict to the evidence-gated
                // structure search, exactly as the per-atom arm does on its budget.
                for atom in 0..k {
                    let already_terminal = self
                        .collapse_events
                        .iter()
                        .any(|e| e.atom == atom && e.action == CollapseAction::Terminal);
                    if !already_terminal {
                        self.collapse_events.push(CollapseEvent {
                            iteration,
                            atom,
                            max_active_mass: ev,
                            floor: collapse_event_floor,
                            action: CollapseAction::Terminal,
                        });
                    }
                }
                return Ok(());
            }
            self.dictionary_cocollapse_reseeds += 1;
            log::warn!(
                "SaeManifoldTerm: dictionary co-collapse ({collapse_arm}; EV telemetry={ev:.4}, \
                 max gated-signal upper bound={max_signal_upper_bound:.3e}, residual scale \
                 upper bound={residual_scale_upper:.3e}, residual roundoff floor=\
                 {residual_roundoff_floor:.3e}, derived signal boundary=\
                 {signal_vanish_boundary:.3e}) with no relative-norm breach; \
                 reseeding all {k} atoms onto distinct residual PCs (dictionary multi-start \
                 {}/{SAE_DICTIONARY_COCOLLAPSE_RESEED_BUDGET}: total co-collapse, no atom \
                 carries material signal to anchor)",
                self.dictionary_cocollapse_reseeds
            );
            let all: Vec<usize> = (0..k).collect();
            // Each multi-start RETRY reads a DISJOINT principal subspace: attempt
            // 1 (the first reseed) uses the top PC pairs (offset 0), attempt 2 the
            // next pairs (offset 1), etc. Without this rotation every retry re-reads
            // the same leading residual PCs — the residual is ≈ the target on every
            // co-collapsed attempt — so the joint LSQ relaxes back into the SAME
            // degenerate basin and the budget-N multi-start is N IDENTICAL attempts
            // (the K=3 coin-flip). `dictionary_cocollapse_reseeds` was just
            // incremented to this attempt's 1-based count, so the 0-based offset is
            // `… − 1`.
            let pc_pair_offset = self.dictionary_cocollapse_reseeds.saturating_sub(1);
            self.reseed_atoms_onto_distinct_residual_pcs(&all, target, rho, pc_pair_offset)?;
            for atom in 0..k {
                self.reseed_collapsed_atom_logits(atom);
                self.collapse_events.push(CollapseEvent {
                    iteration,
                    atom,
                    max_active_mass: ev,
                    floor: collapse_event_floor,
                    action: CollapseAction::Reseeded,
                });
            }
            // #2027 — a GREEDY DISJOINT-SUBSPACE (matching-pursuit) decoder refit
            // REPLACES the joint least-squares refit here. The joint refit's
            // minimum-norm solution re-spreads the leading residual direction across
            // atoms at the near-degenerate co-collapsed Gram, undoing the disjoint
            // coordinate reseed above; the deflation refit instead makes each atom
            // claim residual variance no other atom already took, so the dictionary
            // cannot re-collapse onto one shared direction in a single refit. The
            // freshly-fit decoders are consistent with the reseeded gates (the LSQ was
            // solved AT those gates), so the reconstruction EV strictly improves over
            // the degenerate incumbent — the keep-best multi-start below then banks or
            // restores it as usual.
            self.refit_decoder_sequential_deflation(target)?;
            // #2082 anchor-then-refit: with disjoint decoders now placed, pin each row
            // (softly) to the atom that best explains it, THEN re-fit the decoders AT
            // the anchored gates so decoders and gates stay consistent (anchoring after
            // a single refit desyncs them and degrades EV — the ordering is what makes
            // the anchor safe). Gives each atom a stable territory the outer Newton
            // descent starts from, without breaking the reseed-improves-EV contract.
            self.anchor_logits_to_residual_ownership(target)?;
            self.refit_decoder_sequential_deflation(target)?;
            // #2089 — enforce the #1026 keep-best contract on the STATE between
            // reseeds, not only at budget exhaustion. A reseed refit at the
            // near-singular co-collapsed Gram can return a huge-norm decoder
            // least-squares solution whose reconstruction EV plunges catastrophically
            // below the incumbent (observed −0.0004 → −2.33 → −625 across successive
            // reseeds on a tiny circle fit over featureless input). If that blown-up
            // state is allowed to PERSIST it becomes the base the NEXT multi-start
            // reseed computes its residual from, so `residual = target − (huge fit)`
            // grows geometrically and the "residual ≈ target" invariant every reseed
            // relies on (see the reseed rationale above) is violated — the bounded
            // multi-start degenerates into a runaway whose blown-up decoders also
            // corrupt the outer penalized quasi-Laplace score, and the host process is SIGKILLed
            // (OOM / watchdog, exit 137) before any model or error is returned.
            //
            // A reseed is therefore RETAINED only when it is the new best basin under
            // the SAME EV-then-uniformity ordering used to bank the incumbent
            // ([`prefer_candidate_basin`]); otherwise restore the incumbent so the
            // next distinct-subspace retry (a fresh `pc_pair_offset`) reads the clean
            // degenerate residual rather than a spiralling one. This never blocks a
            // genuine basin break — an improving reseed clears the guard and is kept,
            // exactly as the #2027 disjoint-signal fixtures require — and it is inert
            // on any fit that never co-collapses (this whole arm is gated on
            // `dictionary_degenerate`). The reseed budget is still consumed on every attempt,
            // so the multi-start terminates as designed; the numerics simply can no
            // longer spiral into a non-finite / catastrophic-negative EV.
            let revert_to_incumbent = if let Some((incumbent_ev, incumbent_uniformity, _)) =
                self.best_cocollapse_incumbent.as_ref()
            {
                let incumbent_ev = *incumbent_ev;
                let incumbent_uniformity = *incumbent_uniformity;
                let reseeded_ev =
                    self.dictionary_reconstruction_ev_maybe(target, rho, target_col_stats)?;
                let reseeded_uniformity = self.coordinate_uniformity_aggregate();
                !prefer_candidate_basin(
                    reseeded_ev,
                    reseeded_uniformity,
                    incumbent_ev,
                    incumbent_uniformity,
                    SAE_FINAL_EV_DEGRADATION_TOL,
                )
            } else {
                false
            };
            if revert_to_incumbent {
                // `take` releases the shared borrow of `best_cocollapse_incumbent` so
                // the mutable restore can run, then the incumbent is banked again for
                // the budget-exhaustion arm and any later reseed.
                let incumbent = self.best_cocollapse_incumbent.take();
                if let Some((_, _, ref state)) = incumbent {
                    self.restore_mutable_state(state)?;
                }
                self.best_cocollapse_incumbent = incumbent;
            }
            return Ok(());
        }
        // Decide which breached atoms still have reseed budget (recording a
        // Reseeded or Terminal collapse event for each), then reseed the budgeted
        // set onto DISTINCT residual PCs in ONE pass. A per-atom top-PC reseed
        // would collide multiple simultaneously-collapsed atoms onto the same
        // residual direction and re-collapse them, so the batch seed (the #671
        // disjoint-PC rule across atom slots) is what actually breaks the basin.
        let mut to_reseed: Vec<usize> = Vec::new();
        for &atom in &breached {
            let reseeds_used = self
                .collapse_events
                .iter()
                .filter(|e| e.atom == atom && e.action == CollapseAction::Reseeded)
                .count();
            if reseeds_used < SAE_ATOM_COLLAPSE_RESEED_BUDGET {
                to_reseed.push(atom);
                self.collapse_events.push(CollapseEvent {
                    iteration,
                    atom,
                    max_active_mass: norms[atom] / median,
                    floor: SAE_ATOM_DECODER_NORM_COLLAPSE_RATIO,
                    action: CollapseAction::Reseeded,
                });
            } else {
                let already_terminal = self
                    .collapse_events
                    .iter()
                    .any(|e| e.atom == atom && e.action == CollapseAction::Terminal);
                if !already_terminal {
                    self.collapse_events.push(CollapseEvent {
                        iteration,
                        atom,
                        max_active_mass: norms[atom] / median,
                        floor: SAE_ATOM_DECODER_NORM_COLLAPSE_RATIO,
                        action: CollapseAction::Terminal,
                    });
                }
            }
        }
        if !to_reseed.is_empty() {
            // Per-atom breach arm: a single budgeted reseed onto the top distinct
            // residual PCs — no multi-start rotation (offset 0).
            self.reseed_atoms_onto_distinct_residual_pcs(&to_reseed, target, rho, 0)?;
            for &atom in &to_reseed {
                self.reseed_collapsed_atom_logits(atom);
            }
            // One joint least-squares decoder refit at the re-diversified state
            // gives every atom — the reseeded ones especially — a fresh,
            // non-degenerate decoder that distributes the available signal across
            // the dictionary. Cheap (one n×ΣM_k design solve), run at most once
            // per outer iteration, only when an atom actually breached.
            self.refit_decoder_least_squares_at_current_state(target, Some(rho))?;
        }
        Ok(())
    }

    /// Fraction of the centered target variance the current dictionary explains
    /// (`EV = 1 − ‖fitted − target‖² / ‖target − mean‖²`). Collapse guards use
    /// this only as telemetry and basin ordering; hard disappearance is decided
    /// from gated signal and structural evidence. Column means use Welford's
    /// running update so a huge-but-finite target column cannot overflow the
    /// total-sum-of-squares.
    pub(crate) fn dictionary_reconstruction_ev(
        &self,
        target: ArrayView2<'_, f64>,
        rho: &SaeManifoldRho,
    ) -> Result<f64, String> {
        self.dictionary_reconstruction_ev_maybe(target, rho, None)
    }

    /// [`Self::dictionary_reconstruction_ev`] with an optional PRECOMPUTED target
    /// variance. `precomputed = Some(stats)` reuses the once-per-fit centered
    /// total-sum-of-squares instead of re-reducing the full `n × p` target
    /// (`None` reproduces the historical inline reduction bit-for-bit). Only the
    /// residual sum-of-squares — which depends on the CURRENT dictionary state —
    /// is recomputed per call; the target variance is a fit invariant.
    pub(crate) fn dictionary_reconstruction_ev_maybe(
        &self,
        target: ArrayView2<'_, f64>,
        rho: &SaeManifoldRho,
        precomputed: Option<&TargetCenteredColStats>,
    ) -> Result<f64, String> {
        let residual = self.reconstruction_residual(target, rho)?;
        let residual_energy = self.residual_energy_for_vanishing(residual.view())?;
        self.dictionary_reconstruction_ev_from_residual_sum_squares(
            residual_energy.sum_squares(),
            target,
            precomputed,
        )
    }

    /// EV reduction over an already-computed residual sum of squares. The
    /// same-state collapse verdict shares that positive reduction with its
    /// backward-error certificate, so the hot guard performs one reconstruction
    /// and one residual pass.
    fn dictionary_reconstruction_ev_from_residual_sum_squares(
        &self,
        ss_res: f64,
        target: ArrayView2<'_, f64>,
        precomputed: Option<&TargetCenteredColStats>,
    ) -> Result<f64, String> {
        if !(ss_res.is_finite() && ss_res >= 0.0) {
            return Err(format!(
                "dictionary reconstruction residual sum of squares must be finite and \
                 non-negative; got {ss_res}"
            ));
        }
        let owned;
        let ss_tot = match precomputed {
            Some(stats) => stats.ss_tot,
            None => {
                owned = TargetCenteredColStats::compute(target);
                owned.ss_tot
            }
        };
        if !(ss_tot > 0.0) {
            // A constant target has zero variance to explain; treat a zero
            // residual as fully explained and anything else as collapsed.
            return Ok(if ss_res > 0.0 { 0.0 } else { 1.0 });
        }
        Ok(1.0 - ss_res / ss_tot)
    }

    /// Reseed a set of collapsed atoms onto DISTINCT principal directions of the
    /// current reconstruction residual in one pass, reusing the production #671
    /// disjoint-PC seeding ([`sae_pca_seed_initial_coords`], which assigns atom
    /// slot `j` its own PC pair). Seeding each collapsed atom independently would
    /// hand them all the SAME top residual PC and re-collapse the set, so the
    /// simultaneous-collapse arm seeds them together. A single-element `atoms`
    /// slice is the one-atom case (the atom seeded onto the top residual PC).
    /// Only the reseeded atoms' coordinates and basis caches move; decoders are
    /// left for the caller's joint LSQ refit.
    pub(crate) fn reseed_atoms_onto_distinct_residual_pcs(
        &mut self,
        atoms: &[usize],
        target: ArrayView2<'_, f64>,
        rho: &SaeManifoldRho,
        pc_pair_offset: usize,
    ) -> Result<(), String> {
        if atoms.is_empty() {
            return Ok(());
        }
        let residual = self.reconstruction_residual(target, rho)?;
        let basis_kinds: Vec<SaeAtomBasisKind> = atoms
            .iter()
            .map(|&a| self.atoms[a].basis_kind().clone())
            .collect();
        let dims: Vec<usize> = atoms.iter().map(|&a| self.atoms[a].latent_dim()).collect();
        // `pc_pair_offset` rotates the residual-PC assignment so a co-collapse
        // multi-start RETRY (offset = retry index) reads a disjoint principal
        // subspace from the previous attempt; the per-atom breach arm passes 0
        // (its single reseed needs no rotation).
        let n = self.n_obs();
        // #2023 dead-atom DATA-ROW reseed (default-off via GAM_SAE_DATA_ROW_RESEED).
        // The PCA reseed's diversity is capped at pc_pairs ≈ min(n, p)/2 principal
        // pairs; a co-collapsed dictionary leaves residual ≈ target, so once a
        // multi-start RETRY exhausts that pool (pc_pair_offset ≥ pc_pairs) it
        // re-reads the SAME leading PCs → the same degenerate basin → the
        // reseed-duplication spiral. When the lever is on AND every reseeded atom
        // is a FLAT kind (EuclideanPatch | Linear — the only kinds whose PCA seed
        // is the euclidean score-projection this data-row path mirrors), draw the
        // exhausted-pool retries from DISTINCT DATA ROWS (n ≫ p, unbounded
        // diversity) instead. Unset (default) ⇒ this branch never runs and the
        // seed is bit-identical to the historical PCA path. Chart kinds
        // (Periodic/Sphere/Torus/Cylinder/…) always fall through to the PCA seed
        // — their data-row anchoring is the curved-tier follow-up.
        let pc_pairs = (residual.ncols().min(n)) / 2;
        // #2023 — typed per-fit opt-in (was the GAM_SAE_DATA_ROW_RESEED env lever).
        let data_row_reseed = self.data_row_reseed;
        let all_flat = basis_kinds.iter().all(|k| {
            matches!(
                k,
                SaeAtomBasisKind::EuclideanPatch | SaeAtomBasisKind::Linear
            )
        });
        let seeded = if data_row_reseed && all_flat && n > 0 && pc_pair_offset >= pc_pairs.max(1) {
            // Distinct anchor row per (atom, retry), spanning the full n-row range
            // so successive exhausted-pool retries never re-anchor identically.
            let anchor_rows: Vec<usize> = (0..atoms.len())
                .map(|slot| (slot + pc_pair_offset.wrapping_mul(atoms.len().max(1))) % n)
                .collect();
            sae_data_row_anchored_euclidean_coords(residual.view(), &dims, &anchor_rows)?
        } else {
            sae_pca_seed_initial_coords_with_pc_offset(
                residual.view(),
                &basis_kinds,
                &dims,
                pc_pair_offset,
            )?
        };
        for (slot, &atom) in atoms.iter().enumerate() {
            let d = dims[slot];
            let mut flat = Array1::<f64>::zeros(n * d);
            for row in 0..n {
                for axis in 0..d {
                    flat[row * d + axis] = seeded[[slot, row, axis]];
                }
            }
            self.assignment.coords[atom].set_flat(flat.view());
            let coords = self.assignment.coords[atom].as_matrix();
            self.atoms[atom].refresh_basis(coords.view())?;
        }
        Ok(())
    }

    /// #2132 — is there residual structure ABOVE the measured noise floor for a
    /// co-collapse reseed to land on? The residual `target − current
    /// reconstruction` is what the WHOLE dictionary leaves uncovered; a collapsed
    /// (duplicate) atom should be reseeded onto it only when it carries real,
    /// distinct signal. If the residual is at the noise floor the collapsed atoms
    /// are genuinely REDUNDANT — nothing distinct is left to represent — so
    /// reseeding would only re-plant a duplicate onto noise (the reseed-duplication
    /// spiral). They are demoted (terminal) instead. This is the decidable,
    /// measured counterpart to the post-hoc disjoint-support detector that
    /// provably cannot separate duplication from benign tiling.
    ///
    /// The floor is MEASURED, not tuned. The residual output-Gram
    /// (`residualᵀ·residual`, `p×p`) eigenvalues are the per-direction residual
    /// energies; the leading direction carries signal iff it clears
    /// [`leading_direction_above_noise_floor`] — `lower-quartile · log2(#dirs)`, a
    /// robust-quantile Bonferroni floor whose noise estimate survives signal
    /// spanning up to ~3/4 of the (few) output directions.
    pub(crate) fn residual_has_uncovered_signal(
        &self,
        target: ArrayView2<'_, f64>,
        rho: &SaeManifoldRho,
    ) -> Result<bool, String> {
        let residual = self.reconstruction_residual(target, rho)?;
        self.residual_view_has_uncovered_signal(residual.view())
    }

    /// [`Self::residual_has_uncovered_signal`] on an EXPLICIT residual matrix.
    /// The whole-guard gate recomputes the residual from `rho`; the sequential
    /// co-collapse reseed instead peels the residual atom-by-atom and needs the
    /// SAME measured-noise-floor test on each intermediate remainder, so the
    /// floor logic lives here and both callers share it.
    fn residual_view_has_uncovered_signal(
        &self,
        residual: ArrayView2<'_, f64>,
    ) -> Result<bool, String> {
        if residual.nrows() == 0 || residual.ncols() == 0 {
            return Ok(false);
        }
        // `residualᵀ·residual` (p×p, PSD symmetric): its singular values ARE its
        // eigenvalues, i.e. the residual's per-direction energies (squared singular
        // values). p×p keeps the cost off `n` for the wide-output regime.
        let gram = fast_atb(&residual, &residual);
        let (_u, energies, _vt) = gram
            .svd(false, false)
            .map_err(|e| format!("residual_has_uncovered_signal: residual-Gram SVD failed: {e}"))?;
        let energies: Vec<f64> = energies
            .iter()
            .copied()
            .filter(|v| v.is_finite() && *v >= 0.0)
            .collect();
        Ok(leading_direction_above_noise_floor(&energies))
    }

    /// #2132 — SEQUENTIAL-DEFLATION birth reseed for CURVED co-collapsed atoms.
    ///
    /// The co-collapse guard reseeds SEVERAL duplicate atoms in one call. Seeding
    /// them all from the SAME residual re-reads its one leading structure for
    /// every atom, so they re-collide immediately — the disjoint-PC offset only
    /// helps when the uncovered residual is high rank, but a co-collapsed
    /// dictionary typically leaves ONE low-rank structure uncovered (`pc_pairs = 1`
    /// ⇒ every atom draws PC-pair 0). Peel instead: seed atom 0's chart from the
    /// current residual via the shared chart-aware curved seed
    /// ([`Self::seed_atom_chart_coords`]), fit its provisional gated decoder,
    /// SUBTRACT its fit, and seed atom 1 from what atom 0 left behind — the
    /// block-nursery sequential-composition principle, so each reborn atom charts
    /// a DISJOINT chunk of the uncovered residual. The measured noise-floor
    /// terminator ([`Self::residual_view_has_uncovered_signal`]) breaks the
    /// sequence the moment the peeled remainder hits the floor: the remaining
    /// duplicates carry nothing distinct, so reseeding them would only re-plant a
    /// duplicate onto noise. The provisional decoders exist only to deflate; the
    /// guard's subsequent [`Self::refit_decoder_sequential_deflation`] fits the
    /// final decoders on these freshly-separated charts. Returns the atoms
    /// actually reseeded (the prefix before the terminator fired).
    ///
    /// Seeds through the SHARED seed entrypoint, so when the curved seed's backend
    /// gains an intrinsic-metric embedding the reseed inherits it unchanged; the
    /// disjointness MECHANISM (sequential deflation) is independent of the seed
    /// SOURCE (PC read or geodesic embedding).
    pub(crate) fn reseed_curved_atoms_sequential_deflation(
        &mut self,
        atoms: &[usize],
        target: ArrayView2<'_, f64>,
        rho: &SaeManifoldRho,
    ) -> Result<Vec<usize>, String> {
        if atoms.is_empty() {
            return Ok(Vec::new());
        }
        let n = self.n_obs();
        let p = self.output_dim();
        if n == 0 || p == 0 {
            return Ok(Vec::new());
        }
        // Peel from the WHOLE-dictionary residual: the KEPT atoms' structure is
        // already subtracted, so each reborn atom charts a disjoint chunk of what
        // the dictionary as a whole leaves uncovered.
        let mut residual = self.reconstruction_residual(target, rho)?;
        let mut reseeded = Vec::new();
        for &atom in atoms {
            // Terminator: once the peeled remainder is at the measured noise floor
            // there is no distinct structure left for the remaining duplicates to
            // chart — stop rather than re-plant a duplicate onto noise.
            if !self.residual_view_has_uncovered_signal(residual.view())? {
                break;
            }
            // 1. Seed THIS atom's chart from the current (peeled) residual via the
            //    shared chart-aware seed, then refresh its basis at the new chart.
            self.seed_atom_chart_coords(atom, n, residual.view(), None)?;
            // 2. Fit a provisional gated decoder (`diag(a_·atom)·Φ_atom`) on the
            //    fresh chart and deflate the residual by its fit, so the NEXT atom
            //    reads a disjoint remainder.
            let m = self.atoms[atom].basis_size();
            let mut design = Array2::<f64>::zeros((n, m));
            for row in 0..n {
                let assignments = self.assignment.try_assignments_row(row)?;
                let gate = assignments[atom];
                for col in 0..m {
                    design[[row, col]] = gate * self.atoms[atom].basis_values[[row, col]];
                }
            }
            let beta = solve_design_least_squares(design.view(), residual.view())?;
            if beta.dim() != (m, p) {
                return Err(format!(
                    "SaeManifoldTerm::reseed_curved_atoms_sequential_deflation: atom {atom} \
                     beta shape {:?} != ({m}, {p})",
                    beta.dim()
                ));
            }
            let fit = design.dot(&beta);
            residual = &residual - &fit;
            for col in 0..m {
                for out in 0..p {
                    self.atoms[atom].decoder_coefficients_mut()[[col, out]] = beta[[col, out]];
                }
            }
            reseeded.push(atom);
        }
        Ok(reseeded)
    }

    /// #2027 co-collapse fix, Part A — GREEDY DISJOINT-SUBSPACE decoder refit.
    ///
    /// The joint decoder least-squares
    /// ([`Self::refit_decoder_least_squares_at_current_state`]) fits ALL atoms
    /// against the SAME target in ONE normal-equations solve. At a co-collapsed
    /// state the freshly reseeded atoms sit on distinct residual PC pairs, but the
    /// joint Gram is near-degenerate (the atoms' gated designs overlap heavily on
    /// the leading residual direction), and the minimum-norm joint solution spreads
    /// that SAME direction across several atoms — re-symmetrising the very basin the
    /// reseed just broke. This is the mechanism behind the K≥2 co-collapse: disjoint
    /// COORDINATE seeds are not enough while the DECODER refit is free to re-share
    /// one direction.
    ///
    /// This greedy matching-pursuit refit instead lets every atom claim a DISJOINT
    /// chunk of the residual. Repeatedly: single-atom-fit each not-yet-committed atom
    /// against the CURRENT residual, commit the one whose gated fit explains the most
    /// residual energy, subtract its contribution, and continue. Each atom therefore
    /// lands on residual variance no already-committed atom took, so the dictionary
    /// cannot collapse back onto one shared direction in a single refit — the
    /// block-nursery sequential-composition principle, applied in-loop. The per-atom
    /// design is the identical gated `diag(a_·k)·Φ_k` the joint audit and joint refit
    /// use, so on a healthy, well-separated dictionary the deflation reproduces the
    /// joint least-squares fit up to block-coordinate ordering. Deterministic: ties
    /// resolve to the lower atom index.
    pub(crate) fn refit_decoder_sequential_deflation(
        &mut self,
        target: ArrayView2<'_, f64>,
    ) -> Result<(), String> {
        let n = self.n_obs();
        let p = self.output_dim();
        if target.dim() != (n, p) {
            return Err(format!(
                "SaeManifoldTerm::refit_decoder_sequential_deflation: target shape {:?} != ({n}, {p})",
                target.dim()
            ));
        }
        let k = self.k_atoms();
        if k == 0 || n == 0 {
            return Ok(());
        }
        // Per-row gate weights, rho-keyed exactly as the joint refit reads them, so
        // the deflation design matches the joint audit's `diag(a_·k)·Φ_k` blocks.
        let mut gates = Array2::<f64>::zeros((n, k));
        for row in 0..n {
            let assignments = self.assignment.try_assignments_row(row)?;
            for atom in 0..k {
                gates[[row, atom]] = assignments[atom];
            }
        }
        // Gated single-atom design `D_k = diag(a_·k)·Φ_k` (n × M_k).
        let gated_design = |slf: &Self, atom: usize| -> Array2<f64> {
            let m = slf.atoms[atom].basis_size();
            let mut d = Array2::<f64>::zeros((n, m));
            for row in 0..n {
                let w = gates[[row, atom]];
                for col in 0..m {
                    d[[row, col]] = w * slf.atoms[atom].basis_values[[row, col]];
                }
            }
            d
        };
        let mut residual = target.to_owned();
        let mut remaining: Vec<usize> = (0..k).collect();
        while !remaining.is_empty() {
            let mut best_atom = remaining[0];
            let mut best_energy = f64::NEG_INFINITY;
            let mut best_beta: Option<Array2<f64>> = None;
            for &atom in &remaining {
                let d = gated_design(self, atom);
                // A gated design `D_k = diag(a_·k)·Φ_k` that is all-zero means atom
                // `k` is gated OFF at every row: its reconstruction is identically
                // zero for ANY decoder, so the reduced joint problem this seed ρ
                // presents is rank-deficient and its closed-form quasi-Laplace score is
                // undefined — the SAME infeasible-ρ class as the non-PD Schur /
                // per-row Hessian refusals (#1782). It arises for a legitimate seed
                // state (a threshold gate that numerically underflows on every row at an
                // off-optimum seed ρ), NOT a coding defect, and fitting the resulting
                // all-off (zero) dictionary just makes the outer optimizer grind on a
                // gradient-free landscape. Surface a DISTINCT, classifiable refusal so
                // `is_recoverable_value_probe_refusal` reads it as the finite collapse
                // wall and the outer solver steers ρ back to where atoms turn on (or
                // ships best-so-far), instead of `solve_design_least_squares`'s
                // generic "zero numerical rank" error aborting the whole fit ("no
                // candidate seeds passed outer startup validation"). The generic error
                // stays fatal for every other (genuinely defective) caller.
                if d.iter().all(|&v| v == 0.0) {
                    return Err(format!(
                        "refit_decoder_sequential_deflation: atom {atom} is {}; the seed ρ \
                         leaves the reduced problem rank-deficient (recoverable \
                         infeasible-ρ probe)",
                        ProbeRefusalKind::all_zero_gated_design_marker()
                    ));
                }
                let beta = solve_design_least_squares(d.view(), residual.view())?;
                let fit = d.dot(&beta);
                let energy: f64 = fit.iter().map(|v| v * v).sum();
                // Strict `>` keeps the tie-break at the lower index (deterministic).
                if energy > best_energy {
                    best_energy = energy;
                    best_atom = atom;
                    best_beta = Some(beta);
                }
            }
            let beta = best_beta.expect("remaining is non-empty so a best atom was chosen");
            let m = self.atoms[best_atom].basis_size();
            if beta.dim() != (m, p) {
                return Err(format!(
                    "SaeManifoldTerm::refit_decoder_sequential_deflation: atom {best_atom} beta shape {:?} != ({m}, {p})",
                    beta.dim()
                ));
            }
            // Deflate the residual by this atom's committed gated contribution.
            let d = gated_design(self, best_atom);
            let fit = d.dot(&beta);
            residual = &residual - &fit;
            for col in 0..m {
                for out in 0..p {
                    self.atoms[best_atom].decoder_coefficients_mut()[[col, out]] = beta[[col, out]];
                }
            }
            remaining.retain(|&a| a != best_atom);
        }
        Ok(())
    }

    /// #2082 — soft ROW-OWNERSHIP ANCHOR (used ONLY in the co-collapse reseed arm,
    /// between two deflation refits: deflate → anchor → refit). For each row, find the
    /// atom whose current decoder best matches that row's target direction (the
    /// alignment `⟨target_row, Φ_k(t)·B_k⟩`) and NUDGE that atom's gate logit up by one
    /// temperature unit, the others down by one — a relative bias in the gate's own
    /// logit scale, NOT a hard partition. On its own this DESYNCS the gates from the
    /// decoders the prior deflation fit to the OLD gates (EV degrades — the reason it
    /// was pulled from the #2027 arm); the caller therefore RE-FITS the decoders at the
    /// anchored gates immediately after, restoring the reseed-improves-EV contract while
    /// giving each atom a stable territory the subsequent Newton descent starts from.
    /// K=1 has no ownership to contest, so this is a no-op there.
    pub(crate) fn anchor_logits_to_residual_ownership(
        &mut self,
        target: ArrayView2<'_, f64>,
    ) -> Result<(), String> {
        let n = self.n_obs();
        let p = self.output_dim();
        let k = self.k_atoms();
        if n == 0 || k < 2 {
            return Ok(());
        }
        let mut owner = vec![0usize; n];
        for row in 0..n {
            let mut best = 0usize;
            let mut best_align = f64::NEG_INFINITY;
            for atom in 0..k {
                let m = self.atoms[atom].basis_size();
                let phi = &self.atoms[atom].basis_values;
                let b = self.atoms[atom].decoder_coefficients();
                let mut align = 0.0_f64;
                for out in 0..p {
                    let mut recon = 0.0_f64;
                    for col in 0..m {
                        recon += phi[[row, col]] * b[[col, out]];
                    }
                    align += recon * target[[row, out]];
                }
                if align > best_align {
                    best_align = align;
                    best = atom;
                }
            }
            owner[row] = best;
        }
        let bias = self.assignment.mode.temperature().max(f64::MIN_POSITIVE);
        for row in 0..n {
            for atom in 0..k {
                let delta = if atom == owner[row] { bias } else { -bias };
                self.assignment.logits[[row, atom]] += delta;
            }
        }
        if matches!(self.assignment.mode, AssignmentMode::Softmax { .. }) {
            canonicalize_softmax_logits(&mut self.assignment.logits);
        }
        Ok(())
    }

    /// #2082 — STRUCTURAL coherence collapse detector. The median/EV co-collapse
    /// arms catch a dictionary whose decoders have VANISHED (`‖B_k‖ → 0`). They are
    /// blind to the "HIGH EV, NO STRUCTURE" mode the #2027 two-width test exposes:
    /// two atoms carry full decoder norm yet decode ~the SAME output subspace, so the
    /// reconstruction EV looks healthy while the dictionary really has one atom's worth
    /// of structure. Detect it from the max inter-atom output-frame coherence
    /// `μ̂_{jk} = σ_max(Q_jᵀ Q_k)` — the largest principal-angle COSINE between the
    /// atoms' orthonormal decoder output frames `Q_k` (`certificate_output_frame`) —
    /// fired against a DERIVED random-subspace null (no magic constant).
    ///
    /// Null bar: two INDEPENDENT Haar-random subspaces of dims `r_j, r_k` in `Rᵖ` have
    /// their largest canonical correlation concentrate at the Wachter / MANOVA bulk
    /// edge `μ_null = √(a(1−b)) + √(b(1−a))` with `a = r_j/p, b = r_k/p` (→ 0 as `p`
    /// grows: random atoms are incoherent). A pair is STRUCTURALLY collapsed when its
    /// coherence has moved from that null floor to (near) the degenerate ceiling
    /// `μ = 1` (identical subspaces): fire when `μ̂_{jk}` exceeds the MIDPOINT
    /// `½(μ_null + 1)` — halfway between "as incoherent as random" and "identical". The
    /// only inputs are the derived `μ_null` and the hard degeneracy ceiling 1, so there
    /// is no free threshold. Returns the worst offending pair `(j, k, μ̂)`, or `None`
    /// when every pair sits below its derived bar (`K < 2`, a rank-0 atom, or a genuine
    /// well-separated dictionary all return `None`).
    pub(crate) fn structural_coherence_collapse_detected(
        &self,
    ) -> Result<Option<(usize, usize, f64)>, String> {
        Ok(self
            .structural_coherence_collapsed_pairs()?
            .into_iter()
            .max_by(|a, b| a.2.partial_cmp(&b.2).unwrap_or(std::cmp::Ordering::Equal))
            .map(|(j, kk, coherence, _bar)| (j, kk, coherence)))
    }

    fn structural_coherence_collapsed_pairs(
        &self,
    ) -> Result<Vec<(usize, usize, f64, f64)>, String> {
        let k = self.k_atoms();
        let p = self.output_dim();
        if k < 2 || p == 0 {
            return Ok(Vec::new());
        }
        let frames = (0..k)
            .map(|atom| crate::manifold::certificate::certificate_output_frame(self, atom))
            .collect::<Result<Vec<_>, String>>()?;
        // OVERCOMPLETE GATE (#2132 #2b — the union-frame-rank gate). Let
        // `R = dim(⋃_k col Q_k)` be the effective output rank spanned by the atoms'
        // orthonormal decoder output frames. When `K > R`, pigeonhole FORCES
        // output-frame sharing: `K` curved atoms cannot each claim a private output
        // direction inside an `R < K`-dim space, so every co-firing pair MUST overlap
        // in output subspace even when encoding DISTINCT charts/phases — the PASS-1
        // frame-coherence prune is therefore UNINFORMATIVE overcomplete (it admits
        // everything) and false-fired the old frame-only detector (`ordered_beta_bernoulli_default_alpha`:
        // 8 curved atoms in a ~6-dim output, every frame-coherent pair EV≈0.99 with
        // contribution cosine at the independence null).
        //
        // The old code turned that off by returning NO collapsed pairs whenever
        // `K > R` — but that also DISABLED the PASS-2 contribution-cosine verdict, the
        // one measure that stays valid overcomplete and is exactly what separates a
        // true duplicate (same gated rows ⇒ collinear contributions) from benign
        // pigeonhole sharing (distinct phases ⇒ contribution cosine at the null). So a
        // genuine overcomplete duplicate — the regime where duplicates are MOST likely
        // — went undetected. The gate now only DROPS THE FRAME PRUNE (admitting every
        // pair as a candidate so PASS 2 can adjudicate it), never the verdict. `R` is
        // READ from the frames at hand (numeric rank of the stacked orthonormal
        // frames), never a config knob.
        let effective_output_rank = union_output_frame_rank(&frames, p);
        let overcomplete = k > effective_output_rank;
        // PASS 1 — output-SUBSPACE overlap CANDIDATES. A pair enters the guard only
        // when its decoder output frames overlap beyond the random-frame null
        // `½(μ_null+1)` — a cheap prune, NOT the verdict. Orthogonal-output atoms have
        // coherence≈0 and never become candidates (their contributions are also
        // uncorrelated), so nothing functionally-redundant is pruned here. Overcomplete
        // (`K > R`), frame overlap is pigeonhole-forced and thus useless as a prune, so
        // every pair is admitted and PASS 2 decides.
        let mut candidates: Vec<(usize, usize)> = Vec::new();
        for j in 0..k {
            for kk in (j + 1)..k {
                let rj = frames[j].ncols();
                let rk = frames[kk].ncols();
                if rj == 0 || rk == 0 {
                    continue;
                }
                if overcomplete {
                    candidates.push((j, kk));
                    continue;
                }
                let overlap = fast_atb(&frames[j], &frames[kk]);
                let (_u, s, _vt) = overlap.svd(false, false).map_err(|e| {
                    format!("structural_coherence_collapse_detected: SVD failed ({j},{kk}): {e}")
                })?;
                let coherence = s.iter().copied().fold(0.0_f64, f64::max);
                let a = rj as f64 / p as f64;
                let b = rk as f64 / p as f64;
                let mu_null = (a * (1.0 - b)).max(0.0).sqrt() + (b * (1.0 - a)).max(0.0).sqrt();
                let frame_bar = 0.5 * (mu_null.min(1.0) + 1.0);
                if coherence > frame_bar {
                    candidates.push((j, kk));
                }
            }
        }
        if candidates.is_empty() {
            return Ok(Vec::new());
        }
        // PASS 2 — FUNCTIONAL-REDUNDANCY verdict (#2132/#1893). A frame-coherent pair
        // is genuine high-EV co-collapse only when the two atoms are the SAME
        // FUNCTION — their gated per-row contributions `Y_k = diag(a_·k)·Φ_k·B_k`
        // (n×p) are collinear over the rows — NOT merely when they share an output
        // subspace. Two curved atoms sharing a decoder frame at DIFFERENT charts
        // (phases) reconstruct DIFFERENT rows, so `Y_j ≠ Y_k`: benign, healthy,
        // must not be reseeded (measured on `ordered_beta_bernoulli_default_alpha`: every frame-coherent
        // pair reconstructs EV≈0.99 with contribution cosine ≤0.27, right at the
        // independence null, while the frame coherence reads ≈1). Confirm each
        // candidate on the Frobenius cosine of its contributions against a bar
        // RE-DERIVED for THIS statistic (the frame-coherence bar `½(μ_null+1)` is the
        // WRONG null here). Matched null: same frames, INDEPENDENT phases ⇒ the two
        // contributions are independent random vectors whose shared structure spans
        // `D = M_k·r_k` dimensions (`M` chart basis functions × `r` frame rank), so
        // `E_null|cos| = √(2/(πD))`; the bar is its ½-envelope to full alignment,
        // `contribution_bar = ½(√(2/(πD)) + 1)`, with `D = min(M_j r_j, M_k r_k)` (the
        // smaller intrinsic dimension bounds the null correlation). No inherited
        // constant. A true duplicate (`Y_j ∝ Y_k`, cos→1) clears it and still fires;
        // the benign overcomplete pair (cos≈E_null) does not.
        // Gated per-row contributions `Y_k` for every atom appearing in a candidate
        // (computed once each). `None` = no gated design available for that atom.
        let gates = self.assignment.assignments();
        let n = gates.nrows();
        let mut in_candidate = vec![false; k];
        for &(j, kk) in &candidates {
            in_candidate[j] = true;
            in_candidate[kk] = true;
        }
        let mut contribution: Vec<Option<Array2<f64>>> = vec![None; k];
        for atom in 0..k {
            if !in_candidate[atom] {
                continue;
            }
            let phi = &self.atoms[atom].basis_values;
            if phi.nrows() != n || n == 0 {
                continue;
            }
            // Per-atom decode `Φ_k · B_k` (N×M · M×p). This runs inside the
            // per-accepted-iterate structural-coherence guard, so route the
            // matrix-matrix product through the faer GEMM (small shapes fall
            // back to `ndarray::dot` inside `fast_ab`; the reduction order may
            // differ, acceptable per the crate convention).
            let mut y = fast_ab(phi, self.atoms[atom].decoder_coefficients());
            for row in 0..n {
                let g = gates[[row, atom]];
                for col in 0..y.ncols() {
                    y[[row, col]] *= g;
                }
            }
            contribution[atom] = Some(y);
        }
        let mut collapsed = Vec::with_capacity(candidates.len());
        for (j, kk) in candidates {
            let d_eff = (self.atoms[j].basis_size().max(1) * frames[j].ncols().max(1))
                .min(self.atoms[kk].basis_size().max(1) * frames[kk].ncols().max(1))
                as f64;
            let e_null = (2.0 / (std::f64::consts::PI * d_eff)).sqrt();
            let contribution_bar = 0.5 * (e_null.min(1.0) + 1.0);
            let contribution_cos = match (&contribution[j], &contribution[kk]) {
                (Some(yj), Some(yk)) => {
                    let mut dot = 0.0_f64;
                    let mut nj = 0.0_f64;
                    let mut nk = 0.0_f64;
                    for (a, b) in yj.iter().zip(yk.iter()) {
                        dot += a * b;
                        nj += a * a;
                        nk += b * b;
                    }
                    let denom = (nj * nk).sqrt();
                    if denom > 0.0 {
                        (dot / denom).abs()
                    } else {
                        0.0
                    }
                }
                // Contribution unavailable (decoder-only detector call before any
                // gated design). For a `K ≤ R` candidate the frame-coherence prune
                // already established output-subspace overlap, so keep that verdict
                // (1.0); an OVERCOMPLETE candidate was admitted WITHOUT any frame
                // check, so with no contribution there is no evidence at all — do not
                // flag it (0.0).
                _ => {
                    if overcomplete {
                        0.0
                    } else {
                        1.0
                    }
                }
            };
            if contribution_cos > contribution_bar {
                collapsed.push((j, kk, contribution_cos, contribution_bar));
            }
        }
        Ok(collapsed)
    }

    /// High-EV structural co-collapse guard. Decoder-norm and EV guards catch atoms
    /// that vanish; this one catches atoms that keep norm and EV while occupying the
    /// same output frame. Those states must not be treated as healthy reconstruction
    /// incumbents, and a bounded residual-PC reseed gives the fit a separated basin to
    /// descend from instead of cycling through restore -> duplicate -> restore.
    pub(crate) fn enforce_structural_coherence_guard(
        &mut self,
        target: ArrayView2<'_, f64>,
        iteration: usize,
        rho: &SaeManifoldRho,
    ) -> Result<(), String> {
        if !self.guards_enabled || self.k_atoms() < 2 {
            return Ok(());
        }
        let mut pairs = self.structural_coherence_collapsed_pairs()?;
        if pairs.is_empty() {
            return Ok(());
        }
        pairs.sort_by(|a, b| b.2.partial_cmp(&a.2).unwrap_or(std::cmp::Ordering::Equal));
        let k = self.k_atoms();
        let decoder_norms: Vec<f64> = self
            .atoms
            .iter()
            .map(|atom| {
                atom.decoder_coefficients()
                    .iter()
                    .map(|value| value * value)
                    .sum::<f64>()
                    .sqrt()
            })
            .collect();
        let mut selected = vec![false; k];
        let mut floor_by_atom = vec![0.0_f64; k];
        let mut coherence_by_atom = vec![0.0_f64; k];
        for &(j, kk, coherence, bar) in &pairs {
            let atom = if selected[j] && selected[kk] {
                continue;
            } else if selected[j] {
                kk
            } else if selected[kk] {
                j
            } else if decoder_norms[j] < decoder_norms[kk] {
                j
            } else if decoder_norms[kk] < decoder_norms[j] {
                kk
            } else {
                kk
            };
            selected[atom] = true;
            floor_by_atom[atom] = bar;
            coherence_by_atom[atom] = coherence;
        }
        // #2132 — reseed only onto UNCOVERED structure. The residual is what the
        // whole dictionary leaves unexplained; if it is at the measured noise floor
        // the collapsed atoms are genuinely REDUNDANT and reseeding would just
        // re-plant a duplicate onto noise (the reseed-duplication spiral). In that
        // case demote them (terminal) instead — killing the duplicate before it is
        // re-created rather than detecting it after (where duplication is
        // indistinguishable from benign tiling). Measured once per guard call.
        let residual_uncovered = self.residual_has_uncovered_signal(target, rho)?;
        let mut to_reseed = Vec::new();
        for atom in 0..k {
            if !selected[atom] {
                continue;
            }
            let reseeds_used = self
                .collapse_events
                .iter()
                .filter(|event| event.atom == atom && event.action == CollapseAction::Reseeded)
                .count();
            if residual_uncovered
                && reseeds_used < SAE_ATOM_COLLAPSE_RESEED_BUDGET
                && self.structural_cocollapse_reseeds < SAE_DICTIONARY_COCOLLAPSE_RESEED_BUDGET
            {
                to_reseed.push(atom);
                self.collapse_events.push(CollapseEvent {
                    iteration,
                    atom,
                    max_active_mass: coherence_by_atom[atom],
                    floor: floor_by_atom[atom],
                    action: CollapseAction::Reseeded,
                });
            } else {
                let already_terminal = self
                    .collapse_events
                    .iter()
                    .any(|event| event.atom == atom && event.action == CollapseAction::Terminal);
                if !already_terminal {
                    self.collapse_events.push(CollapseEvent {
                        iteration,
                        atom,
                        max_active_mass: coherence_by_atom[atom],
                        floor: floor_by_atom[atom],
                        action: CollapseAction::Terminal,
                    });
                }
            }
        }
        if to_reseed.is_empty() {
            return Ok(());
        }
        self.structural_cocollapse_reseeds += 1;
        log::warn!(
            "SaeManifoldTerm: structural coherence collapse — reseeding {} duplicate-output \
             atom(s) onto residual PCs (structural multi-start \
             {}/{SAE_DICTIONARY_COCOLLAPSE_RESEED_BUDGET})",
            to_reseed.len(),
            self.structural_cocollapse_reseeds
        );
        let pc_pair_offset = self.structural_cocollapse_reseeds.saturating_sub(1);
        // #2132 — CURVED reborn atoms take DISJOINT chunks of the uncovered
        // residual by SEQUENTIAL deflation (peel between atoms): a co-collapsed
        // dictionary leaves one low-rank structure, so a simultaneous seed re-reads
        // it for every atom and they re-collide. FLAT atoms keep the simultaneous
        // PC-offset / data-row seed — their euclidean score-projection charts no
        // manifold and needs no residual deflation to stay disjoint.
        let (curved, flat): (Vec<usize>, Vec<usize>) =
            to_reseed.iter().copied().partition(|&atom| {
                !matches!(
                    self.atoms[atom].basis_kind(),
                    SaeAtomBasisKind::EuclideanPatch | SaeAtomBasisKind::Linear
                )
            });
        if !curved.is_empty() {
            self.reseed_curved_atoms_sequential_deflation(&curved, target, rho)?;
        }
        if !flat.is_empty() {
            self.reseed_atoms_onto_distinct_residual_pcs(&flat, target, rho, pc_pair_offset)?;
        }
        for &atom in &to_reseed {
            self.reseed_collapsed_atom_logits(atom);
        }
        self.refit_decoder_sequential_deflation(target)?;
        self.anchor_logits_to_residual_ownership(target)?;
        self.refit_decoder_sequential_deflation(target)?;
        Ok(())
    }

    /// #2027 cold-start SEQUENTIAL CHART deflation — seed each atom's CHART *and*
    /// decoder onto DISJOINT structure so a K≥2 fit recovers every planted factor,
    /// not just the dominant one.
    ///
    /// [`Self::refit_decoder_sequential_deflation`] places disjoint DECODERS but
    /// leaves every atom's COORDINATES at the shared PCA seed. When two atoms' seed
    /// charts read the SAME dominant structure (empirically the whitened two-circle
    /// case: both atoms' PCA-pair seeds land on the higher-variance circle) they
    /// both fit that one factor and the weaker planted factor is never recovered —
    /// a HIGH EV with NO structure separation (both decoders on the same output
    /// channels). The decoder is only as expressive as the chart it rides.
    ///
    /// This re-seeds each atom's coordinates from the CURRENT residual's LEADING
    /// structure before fitting its decoder and deflating: atom 0 takes the dominant
    /// planted factor, atom 1 the dominant factor of what atom 0 left behind, and so
    /// on — the block-nursery sequential-composition principle applied to the charts
    /// themselves at cold-start entry. Each atom's chart is therefore aligned with a
    /// DISTINCT factor, so its deflation decoder lands on that factor's channels and
    /// the atoms separate. Uses only the production seeding primitive
    /// (`sae_pca_seed_initial_coords`, one atom at a time on the residual) and the
    /// same gated design as the joint refit.
    pub(crate) fn seed_cold_start_disjoint_charts(
        &mut self,
        target: ArrayView2<'_, f64>,
    ) -> Result<(), String> {
        self.seed_disjoint_charts(target)
    }

    /// #2080 reactive-domain chart placement.
    ///
    /// The chart/decoder separation is identical to
    /// [`Self::seed_cold_start_disjoint_charts`], but this is a move inside the
    /// objective whose rho upper face was already derived from each atom's
    /// native `smooth_penalty`. Preserve that operator instead of refreshing it
    /// from the placed decoder, so the later fixed-face decoder solve and joint
    /// corrector optimize exactly the advertised objective.
    pub(crate) fn place_reactive_entry_disjoint_charts(
        &mut self,
        target: ArrayView2<'_, f64>,
    ) -> Result<(), String> {
        self.seed_disjoint_charts(target)
    }

    fn seed_disjoint_charts(&mut self, target: ArrayView2<'_, f64>) -> Result<(), String> {
        let n = self.n_obs();
        let p = self.output_dim();
        let k = self.k_atoms();
        if n == 0 || k == 0 {
            return Ok(());
        }
        // #2080/#2023 — JOINT (independence) chart separation for entangled factors.
        // The per-atom PCA-residual seed below separates by VARIANCE, so an
        // entangled product-of-circles (equal-variance factors on overlapping
        // frames) has every atom read the SAME dominant mixed direction → shared
        // decoder subspace → μ̂ = 1.0 co-collapse (EV-invisible). Capture the signal
        // span ONCE and run the joint Jacobi ISA split to separate up to K circle
        // planes SIMULTANEOUSLY by kurtosis contrast (statistical independence),
        // not variance. Each certified plane already carries its per-row
        // `phases_turns` in the exact `[0, 1)` chart-seed format the Periodic PCA
        // seed emits (see `certify_plane`), so only the chart SOURCE changes; the
        // decoder LS and residual deflation below are unchanged. When the span
        // carries fewer than K κ-certified circle planes
        // (non-circle atom, or too little independent structure) the remaining
        // atoms fall back to the PCA peel, so peelable/disjoint fixtures are
        // untouched — the κ certificate itself is the gate, never a tuned knob.
        let joint_planes: Vec<super::isa_seed::IsaPlaneCandidate> =
            match super::isa_seed::capture_signal_span(target, k)? {
                Some(parts) => super::isa_seed::isa_extract_certified_planes(
                    target,
                    &parts,
                    k,
                    &super::isa_seed::IsaSeedConfig::default(),
                ),
                None => Vec::new(),
            };
        let mut next_isa_plane = joint_planes.into_iter();

        let mut residual = target.to_owned();
        for atom in 0..k {
            // 1. Seed THIS atom's chart. Prefer a jointly-separated ISA circle
            //    plane (independence contrast); otherwise re-seed from the current
            //    residual's leading structure (one-atom PCA seed on the residual
            //    left by prior atoms).
            let dim = self.atoms[atom].latent_dim();
            let is_periodic = matches!(self.atoms[atom].basis_kind(), SaeAtomBasisKind::Periodic);
            let isa_plane = if dim > 0 && is_periodic {
                next_isa_plane.next()
            } else {
                None
            };
            self.seed_atom_chart_coords(atom, n, residual.view(), isa_plane)?;
            // 2. Fit this atom's decoder to the residual on its fresh chart (gated
            //    design `diag(a_·k)·Φ_k`), then deflate the residual by its fit.
            let m = self.atoms[atom].basis_size();
            let mut d = Array2::<f64>::zeros((n, m));
            for row in 0..n {
                let assignments = self.assignment.try_assignments_row(row)?;
                let w = assignments[atom];
                for col in 0..m {
                    d[[row, col]] = w * self.atoms[atom].basis_values[[row, col]];
                }
            }
            let beta = solve_design_least_squares(d.view(), residual.view())?;
            if beta.dim() != (m, p) {
                return Err(format!(
                    "SaeManifoldTerm::seed_cold_start_disjoint_charts: atom {atom} beta shape {:?} != ({m}, {p})",
                    beta.dim()
                ));
            }
            let fit = d.dot(&beta);
            residual = &residual - &fit;
            for col in 0..m {
                for out in 0..p {
                    self.atoms[atom].decoder_coefficients_mut()[[col, out]] = beta[[col, out]];
                }
            }
        }
        Ok(())
    }

    /// Refit the already-separated reactive-entry decoders against the exact
    /// per-atom smoothness strengths on the advertised rho face.
    ///
    /// Chart placement deliberately uses an unpenalized residual peel because
    /// that is what identifies distinct factors. Carrying those coefficients
    /// directly into a heavy-smoothing waypoint, however, leaves a large
    /// `lambda_k S_k B_k` score that the bounded joint corrector must first
    /// unwind. This second peel keeps the placed charts fixed and solves
    ///
    /// `(D_k' W D_k + lambda_k sym(S_k)) B_k = D_k' W R_k`
    ///
    /// before deflating `R_k`, where `D_k = diag(a_k) Phi_k` and `W` is the
    /// objective's design-honesty row weight. The native `S_k` is the preserved
    /// reactive-objective operator; it is not refreshed from the new decoder.
    /// This is an entry placement, not an evidence certificate: the subsequent
    /// joint corrector still owns cross-atom, chart, routing, row-metric, and
    /// analytic-registry terms and must pass the unchanged strict KKT gate.
    pub(crate) fn refit_reactive_entry_decoders_at_smooth_face(
        &mut self,
        target: ArrayView2<'_, f64>,
        rho: &SaeManifoldRho,
    ) -> Result<(), String> {
        self.assignment.validate_rho_domain(rho)?;
        let n = self.n_obs();
        let p = self.output_dim();
        let k = self.k_atoms();
        if target.dim() != (n, p) {
            return Err(format!(
                "SaeManifoldTerm::refit_reactive_entry_decoders_at_smooth_face: target shape {:?} != ({n}, {p})",
                target.dim()
            ));
        }
        if rho.log_lambda_smooth.len() != k {
            return Err(format!(
                "SaeManifoldTerm::refit_reactive_entry_decoders_at_smooth_face: rho smoothness length {} != K {k}",
                rho.log_lambda_smooth.len()
            ));
        }
        if n == 0 || k == 0 {
            return Ok(());
        }

        let mut residual = target.to_owned();
        for atom in 0..k {
            let m = self.atoms[atom].basis_size();
            if self.atoms[atom].smooth_penalty().dim() != (m, m) {
                return Err(format!(
                    "SaeManifoldTerm::refit_reactive_entry_decoders_at_smooth_face: atom {atom} smooth penalty shape {:?} != ({m}, {m})",
                    self.atoms[atom].smooth_penalty().dim()
                ));
            }

            let mut weighted_design = Array2::<f64>::zeros((n, m));
            let mut weighted_residual = residual.clone();
            for row in 0..n {
                let assignments = self.assignment.try_assignments_row(row)?;
                let honesty_weight = self
                    .row_loss_weights
                    .as_ref()
                    .map_or(1.0, |weights| weights[row]);
                if !(honesty_weight.is_finite() && honesty_weight >= 0.0) {
                    return Err(format!(
                        "SaeManifoldTerm::refit_reactive_entry_decoders_at_smooth_face: row {row} has invalid design-honesty weight {honesty_weight}"
                    ));
                }
                let root_weight = honesty_weight.sqrt();
                let gate = assignments[atom];
                for basis_col in 0..m {
                    weighted_design[[row, basis_col]] =
                        root_weight * gate * self.atoms[atom].basis_values[[row, basis_col]];
                }
                for output in 0..p {
                    weighted_residual[[row, output]] *= root_weight;
                }
            }

            let mut normal = fast_atb(&weighted_design, &weighted_design);
            let lambda = rho.lambda_smooth_for(atom)?;
            for left in 0..m {
                for right in 0..m {
                    let smooth = 0.5
                        * (self.atoms[atom].smooth_penalty()[[left, right]]
                            + self.atoms[atom].smooth_penalty()[[right, left]]);
                    normal[[left, right]] += lambda * smooth;
                }
            }
            let rhs = fast_atb(&weighted_design, &weighted_residual);
            let factor = normal.cholesky(Side::Lower).map_err(|error| {
                format!(
                    "SaeManifoldTerm::refit_reactive_entry_decoders_at_smooth_face: atom {atom} penalized normal equation is not positive definite at lambda={lambda:.6e}: {error}"
                )
            })?;
            let beta = factor.solve_mat(&rhs);
            if beta.dim() != (m, p) || !beta.iter().all(|value| value.is_finite()) {
                return Err(format!(
                    "SaeManifoldTerm::refit_reactive_entry_decoders_at_smooth_face: atom {atom} solve produced invalid beta shape {:?}",
                    beta.dim()
                ));
            }

            // Deflate in the physical reconstruction geometry. The honesty
            // weights choose the coefficients but do not rescale the model's
            // emitted contribution.
            let mut design = weighted_design;
            for row in 0..n {
                let honesty_weight = self
                    .row_loss_weights
                    .as_ref()
                    .map_or(1.0, |weights| weights[row]);
                let root_weight = honesty_weight.sqrt();
                if root_weight > 0.0 {
                    for basis_col in 0..m {
                        design[[row, basis_col]] /= root_weight;
                    }
                } else {
                    let assignments = self.assignment.try_assignments_row(row)?;
                    for basis_col in 0..m {
                        design[[row, basis_col]] =
                            assignments[atom] * self.atoms[atom].basis_values[[row, basis_col]];
                    }
                }
            }
            let fit = design.dot(&beta);
            residual = &residual - &fit;
            self.atoms[atom].decoder_coefficients_mut().assign(&beta);
        }
        Ok(())
    }

    /// Seed atom `atom`'s chart coordinates from the current residual: write the
    /// certified ISA circle phase when a jointly-separated plane is supplied,
    /// otherwise the one-atom Periodic/Euclidean PCA seed on the residual, then
    /// refresh the atom's basis at the seeded coordinates.
    fn seed_atom_chart_coords(
        &mut self,
        atom: usize,
        n: usize,
        residual: ArrayView2<'_, f64>,
        isa_plane: Option<super::isa_seed::IsaPlaneCandidate>,
    ) -> Result<(), String> {
        let kind = self.atoms[atom].basis_kind().clone();
        let dim = self.atoms[atom].latent_dim();
        let mut flat = Array1::<f64>::zeros(n * dim);
        if let Some(plane) = isa_plane {
            // The certified per-row phase (turns, `[0, 1)`) IS the circle chart
            // seed on axis 0; higher axes stay zero, matching the Periodic PCA
            // seed which only writes axis 0.
            for row in 0..n {
                flat[row * dim] = plane.phases_turns[[row, 0]];
            }
        } else {
            let seeded = sae_pca_seed_initial_coords(
                residual,
                std::slice::from_ref(&kind),
                std::slice::from_ref(&dim),
            )?;
            for row in 0..n {
                for axis in 0..dim {
                    flat[row * dim + axis] = seeded[[0, row, axis]];
                }
            }
        }
        self.assignment.coords[atom].set_flat(flat.view());
        let coords = self.assignment.coords[atom].as_matrix();
        self.atoms[atom].refresh_basis(coords.view())?;
        Ok(())
    }

    pub(crate) fn apply_newton_step_impl(
        &mut self,
        delta_ext_coord: ArrayView1<'_, f64>,
        delta_beta: ArrayView1<'_, f64>,
        step_size: f64,
        refresh_basis: bool,
    ) -> Result<(), String> {
        self.apply_newton_step_impl_with_parallelism(
            delta_ext_coord,
            delta_beta,
            step_size,
            refresh_basis,
            None,
        )
    }

    /// Implementation shared by the production auto-policy and the
    /// parallelism-invariance regression. `forced_parallelism == None` selects
    /// the production policy; tests force the serial and indexed-parallel paths
    /// inside local Rayon pools without mutating global process state.
    pub(crate) fn apply_newton_step_impl_with_parallelism(
        &mut self,
        delta_ext_coord: ArrayView1<'_, f64>,
        delta_beta: ArrayView1<'_, f64>,
        step_size: f64,
        refresh_basis: bool,
        forced_parallelism: Option<bool>,
    ) -> Result<(), String> {
        if !(step_size.is_finite() && step_size > 0.0) {
            return Err(format!(
                "SaeManifoldTerm::apply_newton_step: step_size must be finite and positive; got {step_size}"
            ));
        }
        let n = self.n_obs();
        let q = self.assignment.row_block_dim();
        let k_atoms = self.k_atoms();
        let assignment_dim = self.assignment.assignment_coord_dim();
        let at_top_level = rayon::current_thread_index().is_none();
        let parallel_rows =
            forced_parallelism.unwrap_or(n >= SAE_LOSS_PARALLEL_ROW_MIN && at_top_level);
        let parallel_atoms = forced_parallelism
            .unwrap_or(n >= SAE_LOSS_PARALLEL_ROW_MIN && k_atoms > 1 && at_top_level);
        let softmax = matches!(self.assignment.mode, AssignmentMode::Softmax { .. });
        // #972 / #977 T1: when the most recent assembly built the factored
        // β-tier, `delta_beta` is a factored ΔC (length `factored_border_dim`)
        // that must be LIFTED through each active frame (`ΔB_k = ΔC_k U_kᵀ`)
        // before being applied to the p-wide decoder. Otherwise it is a plain
        // ΔB of length `beta_dim`. The expected length and the application path
        // both branch on `last_frames_active`.
        let expected_delta_len = if self.last_frames_active {
            self.factored_border_dim()
        } else {
            self.beta_dim()
        };
        if delta_beta.len() != expected_delta_len {
            return Err(format!(
                "SaeManifoldTerm::apply_newton_step: delta_beta length {} != expected {}",
                delta_beta.len(),
                expected_delta_len
            ));
        }

        // When last_row_layout is set (compact hard-TopK support), delta_ext_coord uses a
        // variable-stride layout where row i occupies
        // [compact_offset_i .. compact_offset_i + q_active_i].
        // We expand each row back to full-q before applying.
        if let Some(ref layout) = self.last_row_layout.clone() {
            let row_dims: Vec<usize> = (0..n).map(|row| layout.row_q_active(row)).collect();
            let mut compact_offsets = Vec::with_capacity(n + 1);
            compact_offsets.push(0usize);
            let mut compact_total = 0usize;
            for &row_dim in &row_dims {
                compact_total += row_dim;
                compact_offsets.push(compact_total);
            }
            let total_len = compact_offsets[n];
            if delta_ext_coord.len() != total_len {
                return Err(format!(
                    "SaeManifoldTerm::apply_newton_step: compact delta_ext_coord length {} != expected {}",
                    delta_ext_coord.len(),
                    total_len
                ));
            }
            // Expand compact rows independently into disjoint full-q slices.
            let mut full_delta = vec![0.0_f64; n * q];
            if parallel_rows && q > 0 {
                use rayon::prelude::*;
                full_delta
                    .par_chunks_mut(q)
                    .enumerate()
                    .for_each(|(row, full_row)| {
                        let compact_row: Vec<f64> = delta_ext_coord
                            .slice(ndarray::s![compact_offsets[row]..compact_offsets[row + 1]])
                            .iter()
                            .copied()
                            .collect();
                        layout.expand_row(row, &compact_row, full_row);
                    });
            } else {
                for row in 0..n {
                    let compact_row: Vec<f64> = delta_ext_coord
                        .slice(ndarray::s![compact_offsets[row]..compact_offsets[row + 1]])
                        .iter()
                        .copied()
                        .collect();
                    layout.expand_row(row, &compact_row, &mut full_delta[row * q..(row + 1) * q]);
                }
            }
            // Apply logits from expanded buffer, clamped to the #976 gate-scale
            // step cap, then canonicalize each softmax row in the same worker.
            let logit_step_cap =
                SAE_ASSIGNMENT_LOGIT_STEP_CAP_TAUS * self.assignment.mode.temperature();
            if parallel_rows {
                use rayon::prelude::*;
                self.assignment
                    .logits
                    .axis_iter_mut(ndarray::Axis(0))
                    .into_par_iter()
                    .enumerate()
                    .for_each(|(row, mut logits)| {
                        let row_base = row * q;
                        for atom_idx in 0..assignment_dim {
                            logits[atom_idx] += (step_size * full_delta[row_base + atom_idx])
                                .clamp(-logit_step_cap, logit_step_cap);
                        }
                        if softmax {
                            canonicalize_softmax_logit_row(
                                logits.as_slice_mut().expect("contiguous logit row"),
                            );
                        }
                    });
            } else {
                for row in 0..n {
                    let row_base = row * q;
                    let mut logits = self.assignment.logits.row_mut(row);
                    for atom_idx in 0..assignment_dim {
                        logits[atom_idx] += (step_size * full_delta[row_base + atom_idx])
                            .clamp(-logit_step_cap, logit_step_cap);
                    }
                    if softmax {
                        canonicalize_softmax_logit_row(
                            logits.as_slice_mut().expect("contiguous logit row"),
                        );
                    }
                }
            }
            // Coordinate blocks and basis caches are independent across atoms.
            let coord_offsets = self.assignment.coord_offsets();
            self.apply_coordinate_step_from_rows(
                n,
                q,
                &coord_offsets,
                step_size,
                |_, flat_idx| full_delta[flat_idx],
                refresh_basis,
                parallel_atoms,
            )?;
        } else {
            // Dense layout: uniform q per row.
            if delta_ext_coord.len() != n * q {
                return Err(format!(
                    "SaeManifoldTerm::apply_newton_step: delta_ext_coord length {} != expected {}",
                    delta_ext_coord.len(),
                    n * q
                ));
            }
            let coord_offsets = self.assignment.coord_offsets();
            // #976 gate-scale step cap, as in the compact branch above.
            let logit_step_cap =
                SAE_ASSIGNMENT_LOGIT_STEP_CAP_TAUS * self.assignment.mode.temperature();
            if parallel_rows {
                use rayon::prelude::*;
                self.assignment
                    .logits
                    .axis_iter_mut(ndarray::Axis(0))
                    .into_par_iter()
                    .enumerate()
                    .for_each(|(row, mut logits)| {
                        let row_base = row * q;
                        for atom_idx in 0..assignment_dim {
                            logits[atom_idx] += (step_size * delta_ext_coord[row_base + atom_idx])
                                .clamp(-logit_step_cap, logit_step_cap);
                        }
                        if softmax {
                            canonicalize_softmax_logit_row(
                                logits.as_slice_mut().expect("contiguous logit row"),
                            );
                        }
                    });
            } else {
                for row in 0..n {
                    let row_base = row * q;
                    let mut logits = self.assignment.logits.row_mut(row);
                    for atom_idx in 0..assignment_dim {
                        logits[atom_idx] += (step_size * delta_ext_coord[row_base + atom_idx])
                            .clamp(-logit_step_cap, logit_step_cap);
                    }
                    if softmax {
                        canonicalize_softmax_logit_row(
                            logits.as_slice_mut().expect("contiguous logit row"),
                        );
                    }
                }
            }
            self.apply_coordinate_step_from_rows(
                n,
                q,
                &coord_offsets,
                step_size,
                |_, flat_idx| delta_ext_coord[flat_idx],
                refresh_basis,
                parallel_atoms,
            )?;
        }

        if self.last_frames_active {
            // Factored ΔC → lift to a p-wide ΔB and add `step·ΔB`. For atom `k`,
            // basis row `m`, output channel `i`:
            //   ΔB_k[m,i] = Σ_j ΔC[off_C[k] + m·r_k + j] · U_k[i,j].
            // Un-framed atoms (`U_k = I_p`, `r_k = p`) lift by identity, so a
            // mixed dictionary is handled uniformly. The resulting p-wide step
            // is applied directly to each authoritative decoder block; active
            // frames are re-synced from those decoders by the polar refresh in
            // the joint-fit driver.
            let delta_b = FrameProjection::new(self).lift_border_vec(delta_beta);
            self.apply_decoder_step_from_flat(delta_b.view(), step_size, parallel_atoms)?;
        } else {
            self.apply_decoder_step_from_flat(delta_beta, step_size, parallel_atoms)?;
        }
        Ok(())
    }

    pub(crate) fn solve_fixed_decoder_row_step(
        h: ArrayView2<'_, f64>,
        g: ArrayView1<'_, f64>,
        base_ridge: f64,
    ) -> Result<Array1<f64>, String> {
        let d = h.nrows();
        if h.ncols() != d || g.len() != d {
            return Err(format!(
                "SaeManifoldTerm::solve_fixed_decoder_row_step: shape mismatch H={:?}, g={}",
                h.dim(),
                g.len()
            ));
        }
        if d == 0 {
            return Ok(Array1::<f64>::zeros(0));
        }
        let mut last_err = String::new();
        escalate_ridge(
            RidgeSchedule {
                initial: base_ridge.max(SAE_MANIFOLD_ROW_RIDGE_FLOOR),
                growth: SAE_MANIFOLD_ROW_RIDGE_GROWTH,
                max_escalations: SAE_MANIFOLD_ROW_RIDGE_MAX_ATTEMPTS,
            },
            |ridge| {
                let mut a = h.to_owned();
                for axis in 0..d {
                    a[[axis, axis]] += ridge;
                }
                match sae_cholesky_solve_neg_gradient(a.view(), g) {
                    Ok(delta) => Some(delta),
                    Err(err) => {
                        last_err = err;
                        None
                    }
                }
            },
        )
        .map(|success| success.value)
        .map_err(|_| {
            format!(
                "SaeManifoldTerm::solve_fixed_decoder_row_step: row Hessian did not factor after LM escalation; last error: {last_err}"
            )
        })
    }

    pub(crate) fn fixed_decoder_step_from_rows(
        sys: &ArrowSchurSystem,
        ridge_ext_coord: f64,
    ) -> Result<Array1<f64>, String> {
        let total = sys.row_offsets[sys.rows.len()];
        let mut delta = Array1::<f64>::zeros(total);
        for (row_idx, row) in sys.rows.iter().enumerate() {
            let row_delta =
                Self::solve_fixed_decoder_row_step(row.htt.view(), row.gt.view(), ridge_ext_coord)?;
            let start = sys.row_offsets[row_idx];
            let end = sys.row_offsets[row_idx + 1];
            if row_delta.len() != end - start {
                return Err(format!(
                    "SaeManifoldTerm::fixed_decoder_step_from_rows: row {row_idx} delta len {} != row span {}",
                    row_delta.len(),
                    end - start
                ));
            }
            delta.slice_mut(s![start..end]).assign(&row_delta);
        }
        Ok(delta)
    }

    /// Row visitation order for the discovery/seeding pass, drawn from the
    /// per-row Fisher-mass enrichment measure (#980, role (c)).
    ///
    /// Builds [`RowSamplingMeasure::from_metric`](gam_solve::row_sampling_measure::RowSamplingMeasure::from_metric)
    /// from the term's installed [`RowMetric`] (Euclidean fallback when none is
    /// installed), draws a length-`n` systematic-resampling
    /// [`enrichment_order`](gam_solve::row_sampling_measure::RowSamplingMeasure::enrichment_order),
    /// and reduces it to a first-seen unique permutation. Behaviorally-live rows
    /// (high Fisher mass) appear earliest; any row the measure never named is
    /// appended in index order so **every** row is still visited exactly once.
    ///
    /// Under a Euclidean / no-harvest metric the measure is exactly uniform, the
    /// systematic-resampling draw is an even round-robin, and the first-seen
    /// reduction is the plain `0..n` index order — bit-for-bit today's behavior.
    ///
    /// Pure attention: the order is consumed only to decide *which row is looked
    /// at first*; each visited row runs the identical unmodified per-row
    /// objective, so this touches no loss / criterion / penalty.
    pub(crate) fn enrichment_visit_order(&self) -> Vec<usize> {
        let n = self.n_obs();
        // No installed metric ⇒ the measure is exactly uniform and the
        // systematic draw reduces to plain index order (documented below), so
        // skip building the Euclidean metric object entirely — this runs in
        // the seeding hot path, per seed-candidate evaluation.
        if self.row_metric.is_none() {
            return (0..n).collect();
        }
        let metric = match self.diagnostic_metric() {
            Ok(m) => m,
            // A metric build failure cannot occur for the term's own validated
            // shape, but degrade to the plain index sweep rather than propagate:
            // the order is attention-only and must never gate the seed.
            Err(_) => return (0..n).collect(),
        };
        let measure = gam_solve::row_sampling_measure::RowSamplingMeasure::from_metric(&metric);
        // Seed the deterministic systematic-resampling draw from the row count so
        // the ordering is reproducible across runs (no clock randomness).
        let drawn = measure.enrichment_order(n, n as u64);
        let mut order = Vec::with_capacity(n);
        let mut seen = vec![false; n];
        for row in drawn {
            if row < n && !seen[row] {
                seen[row] = true;
                order.push(row);
            }
        }
        // Append any row the enrichment draw never named so every row is seeded.
        for (row, &was_seen) in seen.iter().enumerate() {
            if !was_seen {
                order.push(row);
            }
        }
        order
    }

    /// Globally seed every atom's per-row latent coordinate by projecting each
    /// target row onto that atom's **frozen** decoder image manifold.
    ///
    /// For a fixed decoder the exact out-of-sample encoding of row `i` against
    /// atom `k` is the projection
    /// `t*_{ik} = argmin_t ‖x_i − Φ_k(t)·B_k‖²`. For a periodic curve this is a
    /// trigonometric polynomial: every stationary coordinate is enumerated by
    /// the shared companion-root solver and compared globally. This exact
    /// enumeration is available only for the rank-1 Fourier charts (periodic /
    /// torus with `latent_dim == 1`).
    ///
    /// Every other atom — coupled multivariate compact charts (sphere,
    /// cylinder, Möbius, multivariate periodic/torus) and the unbounded or
    /// basis-linear latents (Duchon, Euclidean patch, Poincaré, linear, finite
    /// set) — **retains its incoming coordinates**. It is fed here already
    /// carrying the natural-chart seed [`sae_pca_seed_initial_coords`] /
    /// `topology_curved_seed_initial_coords` placed on it, and we do not
    /// overwrite that with a dishonest fixed-lattice projection: a finite
    /// multistart support cannot certify it found every stationary component of
    /// a compact multivariate chart, and this crate does not yet expose the
    /// interval extensions or polynomial-system solver needed to make that
    /// completeness claim. Skipping refinement for those atoms is honest (no
    /// completeness is asserted) and non-fatal (the natural-chart seed survives
    /// into the joint solve), so a default fit whose topology race selects a
    /// sphere / Möbius / swiss-sheet atom completes instead of aborting.
    ///
    /// The decoder, assignment logits, smoothness penalties and rho are
    /// untouched; only exact rank-1 Fourier coordinates and their basis caches
    /// move.
    pub fn seed_coords_by_decoder_projection(
        &mut self,
        target: ArrayView2<'_, f64>,
    ) -> Result<(), String> {
        let n = self.n_obs();
        let p = self.output_dim();
        if target.dim() != (n, p) {
            return Err(format!(
                "SaeManifoldTerm::seed_coords_by_decoder_projection: target shape {:?} != ({n}, {p})",
                target.dim()
            ));
        }
        // Atoms whose complete stationary set the rank-1 Fourier companion
        // solver cannot enumerate (compact multivariate charts, and every
        // unbounded / basis-linear latent) are SKIPPED below, retaining the
        // natural-chart seed they arrived with. We deliberately do not perform a
        // fixed-lattice projection for them: a finite multistart cannot certify
        // completeness for a compact multivariate chart, so refining them here
        // would assert a guarantee this engine does not carry. Skipping is
        // honest and lets a default fit whose topology race selects a sphere /
        // Möbius / swiss-sheet atom complete rather than abort.
        // ENRICHMENT (#980, role (c)): the order in which this discovery/seeding
        // pass *visits* rows is drawn from the per-row Fisher-mass sampling
        // measure when an output-Fisher harvest is present, so behaviorally-live
        // rows get attention FIRST. This is attention-only: every visited row
        // runs the identical, unmodified per-row argmin projection objective
        // below — the measure reweights *which row is looked at first*, never the
        // loss. Under a Euclidean / no-harvest metric the measure is exactly
        // uniform, so the order degrades to the plain `0..n` index sweep and the
        // result is bit-for-bit today's behavior. Because each row's seed is
        // computed independently and written exactly once, the visitation order
        // cannot change any seed value — confirming the attention-only invariant.
        let visit_order = self.enrichment_visit_order();
        for atom_idx in 0..self.k_atoms() {
            let d = self.atoms[atom_idx].latent_dim();
            if matches!(
                self.atoms[atom_idx].basis_kind(),
                SaeAtomBasisKind::Periodic | SaeAtomBasisKind::Torus
            ) && d == 1
            {
                let mut seeded = self.assignment.coords[atom_idx].as_matrix();
                let mut decoder = self.atoms[atom_idx].full_width_decoder();
                let eta = self.atoms[atom_idx].homotopy_eta;
                if eta != 1.0 {
                    // The harmonic homotopy keeps `[1, sin θ, cos θ]` fixed and
                    // scales harmonics h >= 2.  Folding eta into the physical
                    // decoder preserves the standard Fourier basis required by
                    // the companion solver.
                    for basis in 3..decoder.nrows() {
                        for output in 0..decoder.ncols() {
                            decoder[[basis, output]] *= eta;
                        }
                    }
                }
                let gram = decoder.dot(&decoder.t());
                let extrema = PeriodicCurveExtrema::from_gram(gram.view()).map_err(|error| {
                    format!(
                        "SaeManifoldTerm::seed_coords_by_decoder_projection: atom {atom_idx}: {error}"
                    )
                })?;
                for &row in &visit_order {
                    let linear = decoder.dot(&target.row(row));
                    let coefficients = linear.as_slice().ok_or_else(|| {
                        "SaeManifoldTerm::seed_coords_by_decoder_projection: Fourier coefficients are not contiguous".to_string()
                    })?;
                    seeded[[row, 0]] = extrema
                        .minimize_squared_distance(coefficients)
                        .map_err(|error| {
                            format!(
                                "SaeManifoldTerm::seed_coords_by_decoder_projection: row {row}, atom {atom_idx}: {error}"
                            )
                        })?
                        .coordinate;
                }
                let flat = Array1::from_iter(seeded.iter().copied());
                self.assignment.coords[atom_idx].set_flat(flat.view());
                let coords = self.assignment.coords[atom_idx].as_matrix();
                self.atoms[atom_idx].refresh_basis(coords.view())?;
            }
        }
        Ok(())
    }

    pub fn run_fixed_decoder_arrow_schur(
        &mut self,
        target: ArrayView2<'_, f64>,
        rho: &mut SaeManifoldRho,
        analytic_penalties: Option<&AnalyticPenaltyRegistry>,
        max_iter: usize,
        step_size: f64,
        ridge_ext_coord: f64,
    ) -> Result<SaeManifoldLoss, String> {
        *rho = rho.clone().for_assignment(self.assignment.mode);
        self.assignment.validate_rho_domain(rho)?;
        if !(step_size.is_finite() && step_size > 0.0) {
            return Err(format!(
                "SaeManifoldTerm::run_fixed_decoder_arrow_schur: step_size must be finite and positive; got {step_size}"
            ));
        }
        // #2267 — the backtracking search only ever CONTRACTS from its first
        // trial, so pinning that trial to the caller's `step_size` caps the
        // per-iteration contraction at `1 - step_size` regardless of how good
        // the direction is. Clean acceptances ratchet the trial toward the unit
        // Newton step instead; the Armijo bound is unchanged.
        let warm_growth = 1.0 / BacktrackConfig::default().contraction;
        let unit_step_ceiling = step_size.max(1.0);
        let mut warm_step = step_size;
        if max_iter < 1 {
            return Err(
                "SaeManifoldTerm::run_fixed_decoder_arrow_schur: max_iter must be positive".into(),
            );
        }
        let beta_zero = Array1::<f64>::zeros(self.beta_dim());
        let mut last_loss = self.loss(target, rho)?;
        for _ in 0..max_iter {
            self.advance_temperature_schedule()?;
            let pre_step_loss = self.loss(target, rho)?;
            // #1407: assemble ONLY the per-row htt/gt block-diagonal — the frozen
            // decoder makes the entire β tier (G/gb/htbeta/hbb/β-penalties) dead
            // work. `fixed_decoder_step_from_rows` below reads only htt/gt.
            self.fixed_decoder_assembly = true;
            let sys_result = self.assemble_arrow_schur(target, rho, analytic_penalties);
            self.fixed_decoder_assembly = false;
            let sys = sys_result
                .map_err(|err| format!("SaeManifoldTerm::run_fixed_decoder_arrow_schur: {err}"))?;
            let pre_step_total =
                self.penalized_objective_total(target, rho, analytic_penalties, 1.0)?;
            let delta_ext_coord = Self::fixed_decoder_step_from_rows(&sys, ridge_ext_coord)?;
            let directional_decrease = sae_manifold_newton_directional_decrease(
                &sys,
                delta_ext_coord.view(),
                beta_zero.view(),
            );
            let grad_norm_sq: f64 = sys
                .rows
                .iter()
                .flat_map(|row| row.gt.iter())
                .map(|&v| v * v)
                .sum();
            let step_norm_sq: f64 = delta_ext_coord.iter().map(|&v| v * v).sum();
            let directional_decrease_floor = SAE_MANIFOLD_DIRECTIONAL_DECREASE_REL_FLOOR
                * grad_norm_sq.sqrt()
                * step_norm_sq.sqrt();
            let snapshot = self.snapshot_mutable_state();
            if !(pre_step_total.is_finite()
                && directional_decrease.is_finite()
                && directional_decrease > 0.0
                && directional_decrease > directional_decrease_floor)
            {
                self.restore_mutable_state(&snapshot)?;
                last_loss = pre_step_loss;
                break;
            }

            // Each trial re-applies the Newton step from the pre-step
            // `snapshot` (reset-before-reapply on every trial after the
            // first). A trial whose step application or objective evaluation
            // errors is INVALID (`Ok(None)`): halve without consulting the
            // Armijo test. On acceptance the mutable state already holds the
            // accepted trial, so the loss is read after the search returns.
            let mut first_trial = true;
            let accepted = backtracking_line_search::<_, String>(
                BacktrackConfig {
                    initial_step: warm_step,
                    max_steps: SAE_MANIFOLD_MAX_LINESEARCH_HALVINGS + 1,
                    ..BacktrackConfig::default()
                },
                |trial_step_size| {
                    if !std::mem::take(&mut first_trial) {
                        self.restore_mutable_state(&snapshot)?;
                    }
                    Ok(self
                        .apply_newton_step(
                            delta_ext_coord.view(),
                            beta_zero.view(),
                            trial_step_size,
                        )
                        .and_then(|()| {
                            self.penalized_objective_total(target, rho, analytic_penalties, 1.0)
                        })
                        .ok()
                        .map(|post_step_total| (post_step_total, ())))
                },
                |trial_step_size, post_step_total| {
                    let armijo_bound = pre_step_total
                        - SAE_MANIFOLD_ARMIJO_C1 * trial_step_size * directional_decrease;
                    post_step_total.is_finite() && post_step_total <= armijo_bound
                },
            )?;
            match accepted {
                Some(step) => {
                    // Same ratchet as the joint driver (#2267): this is a Newton
                    // step too, so its natural length is one, and the caller's
                    // `step_size` is the conservative first trial, not a ceiling
                    // the accepted step may never exceed.
                    warm_step = (if step.step >= warm_step {
                        warm_step * warm_growth
                    } else {
                        step.step * warm_growth
                    })
                    .min(unit_step_ceiling);
                    last_loss = self.loss(target, rho)?;
                }
                None => {
                    self.restore_mutable_state(&snapshot)?;
                    last_loss = pre_step_loss;
                    break;
                }
            }
        }
        Ok(last_loss)
    }

    /// Rank-revealing adaptive basis depth for rank-deficient decoder designs
    /// (#1117 root-cause fix; supersedes the prior data-null projector deflation
    /// + post-fit range projection and the #1051 LM ridge for this case).
    ///
    /// On a near-degenerate input manifold (e.g. the OLMo L25 PCA-32 circle, or
    /// the `stage1-step0` checkpoint with post-PCA std ≈ 0.04) the fitted latent
    /// coordinate `t` plus the assignment weights fail to excite the full
    /// fixed-width periodic basis `[1, sin 2πt, cos 2πt, sin 4πt, cos 4πt]`: the
    /// bare data Gram `G_k = D_kᵀ D_k` is rank-deficient (`rank 3/5`, the
    /// `[SAE-AUDIT]` signal). WHICH `r_k`-d subspace the data DOES support is
    /// data-dependent — it is whatever combination of the fixed columns the data
    /// excites — so we discover it from the Gram rather than truncating a fixed
    /// set of columns.
    ///
    /// We symmetrise each `G_k`, eigendecompose it, and keep the eigenvectors
    /// ABOVE the relative spectral cutoff as the orthonormal data-supported
    /// column map `Q_k` (`M_k × r_k`, `r_k = rank(G_k)`). For any rank-deficient
    /// atom (`r_k < M_k`) we REPARAMETRIZE its basis onto `Q_k`
    /// ([`SaeManifoldAtom::reduce_basis_to_subspace`]): the design `Φ̃ = Φ Q_k`
    /// becomes full-rank by construction, the decoder is the rank-`r_k` oracle
    /// `B̃ = Q_kᵀ B`, the roughness Gram is `Q_kᵀ S Q_k`, and the evaluator is
    /// wrapped so the reduction survives every basis refresh. The inner solve no
    /// longer descends a flat valley and the outer penalized quasi-Laplace log-det is well-posed —
    /// no step-time deflation, ridge floor, or post-fit projection needed for
    /// the deficiency. The depth decision is made ONCE here, before the outer
    /// loop, so it is held fixed across the inner Newton walk.
    ///
    /// A full-rank atom (`base`/`step_2300`, `r_k == M_k`) is SKIPPED entirely —
    /// its basis, decoder, penalty, and evaluator are left byte-for-byte the
    /// historical full-`B` path, so the well-conditioned fit is unchanged.
    pub(crate) fn reduce_atoms_to_data_supported_rank(&mut self) -> Result<(), String> {
        let p = self.output_dim();
        if p == 0 || self.beta_dim() == 0 {
            return Ok(());
        }
        let mut grams = self.empty_decoder_gram_accumulator();
        self.accumulate_decoder_gram(&mut grams)?;
        // Phase 1 (parallel, READ-ONLY): each atom's rank-revealing eigendecomp
        // depends ONLY on its own data Gram + its own (immutable) atom state, so
        // the per-atom column-map plan `Q_k` is computed independently and
        // collected in atom order. The eigendecomp is deterministic and the plan
        // per atom is a pure function of read-only inputs, so the parallel result
        // is bit-identical to the serial sweep (ordered collect). #1557 — pin the
        // faer eigendecomp GEMM to `Par::Seq` inside each atom worker.
        let plans: Vec<Option<Array2<f64>>> =
            {
                let atoms = &self.atoms;
                let compute_plan =
                    |atom_idx: usize| -> Option<Array2<f64>> {
                        let m = atoms[atom_idx].basis_size();
                        if m == 0 || grams[atom_idx].dim() != (m, m) {
                            return None;
                        }
                        // Symmetrise the bare data Gram `G_k` before the eigendecomposition.
                        let mut data_gram = grams[atom_idx].clone();
                        for i in 0..m {
                            for j in 0..i {
                                let sym = 0.5 * (data_gram[[i, j]] + data_gram[[j, i]]);
                                data_gram[[i, j]] = sym;
                                data_gram[[j, i]] = sym;
                            }
                        }
                        let (evals, evecs) = match data_gram.eigh(Side::Lower) {
                            Ok(pair) => pair,
                            Err(_) => return None,
                        };
                        let max_eig = evals.iter().fold(0.0_f64, |acc, &v| {
                            if v.is_finite() { acc.max(v) } else { acc }
                        });
                        if !(max_eig > 0.0) {
                            // An all-zero data Gram (no assignment mass) is handled by the
                            // fatal pre-fit audit, not by a basis reduction here.
                            return None;
                        }
                        let cutoff = SAE_MANIFOLD_SPECTRAL_RANK_CUTOFF * max_eig;
                        // Eigenvectors whose eigenvalue clears the relative cutoff span the
                        // data-supported subspace `Q_k` (the retained columns).
                        let kept: Vec<usize> = (0..evals.len())
                            .filter(|&idx| {
                                let lambda = evals[idx];
                                lambda.is_finite() && lambda > cutoff
                            })
                            .collect();
                        let r = kept.len();
                        // Full rank (`r == m`) → the well-conditioned path; leave it
                        // byte-for-byte unchanged. `r == 0` is a degenerate all-null Gram
                        // that the fatal pre-fit audit already rejects; do not reduce to a
                        // zero-width basis here.
                        if r == m || r == 0 {
                            return None;
                        }
                        // Build the orthonormal column map `Q_k` (M × r) from the retained
                        // eigenvectors. The reduction needs an analytic second-jet evaluator
                        // to compose the reduced jets; atoms without one (caller-managed,
                        // e.g. an out-of-band design) keep the historical projector-free
                        // full-`B` path and rely on the LM ridge — the periodic/torus/
                        // sphere/Duchon production atoms all carry a second jet.
                        if atoms[atom_idx].basis_second_jet.is_none() {
                            return None;
                        }
                        let mut q = Array2::<f64>::zeros((m, r));
                        for (col, &eig_idx) in kept.iter().enumerate() {
                            for row in 0..m {
                                q[[row, col]] = evecs[[row, eig_idx]];
                            }
                        }
                        Some(q)
                    };
                let n_atoms = atoms.len();
                let parallel =
                    n_atoms >= SAE_LOSS_PARALLEL_ROW_MIN && rayon::current_thread_index().is_none();
                if parallel {
                    use rayon::prelude::*;
                    (0..n_atoms)
                        .into_par_iter()
                        .map(|atom_idx| with_nested_parallel(|| compute_plan(atom_idx)))
                        .collect()
                } else {
                    (0..n_atoms).map(compute_plan).collect()
                }
            };
        // Phase 2 (serial): apply the reparametrization to each atom in atom order.
        // Each mutation touches ONLY its own atom, but keep it serial so a failure
        // surfaces the deterministic (lowest-index) error.
        for (atom_idx, plan) in plans.into_iter().enumerate() {
            let Some(q) = plan else { continue };
            self.atoms[atom_idx]
                .reduce_basis_to_subspace(&q)
                .map_err(|err| {
                    format!(
                        "SaeManifoldTerm::reduce_atoms_to_data_supported_rank: atom {atom_idx}: {err}"
                    )
                })?;
        }
        Ok(())
    }

    pub fn run_joint_fit_arrow_schur(
        &mut self,
        target: ArrayView2<'_, f64>,
        rho: &mut SaeManifoldRho,
        analytic_penalties: Option<&AnalyticPenaltyRegistry>,
        max_iter: usize,
        step_size: f64,
        ridge_ext_coord: f64,
        ridge_beta: f64,
    ) -> Result<SaeManifoldLoss, String> {
        self.run_joint_fit_arrow_schur_with_termination_policy(
            target,
            rho,
            analytic_penalties,
            max_iter,
            step_size,
            ridge_ext_coord,
            ridge_beta,
            true,
        )
        .map(|outcome| outcome.loss)
    }

    /// Evidence-gradient inner polish. The ordinary fit accepts the documented
    /// coarse KKT band immediately; a Laplace value paired with an implicit
    /// derivative cannot do that, because the resulting warm-start map is flat
    /// inside the band while the analytic adjoint differentiates the exact root.
    /// Keep the same KKT tolerance as an admission certificate, but bypass both
    /// its loop-top early exit and the approximate objective-stall shortcut. The
    /// latter deliberately stops ordinary fits after a few sufficiently small
    /// but still STRICT decreases; re-entering from that state continues moving,
    /// so it is not an idempotent root and cannot define the state response used
    /// by an implicit evidence derivative. Evidence therefore retains only the
    /// actual no-descent / proximal-no-strict-decrease termination routes before
    /// the undamped cache is formed (#2253).
    pub(crate) fn run_joint_fit_arrow_schur_for_quasi_laplace(
        &mut self,
        target: ArrayView2<'_, f64>,
        rho: &mut SaeManifoldRho,
        analytic_penalties: Option<&AnalyticPenaltyRegistry>,
        max_iter: usize,
        step_size: f64,
        ridge_ext_coord: f64,
        ridge_beta: f64,
    ) -> Result<EvidenceJointFitOutcome, String> {
        // Entry preparation is part of the evidence map too: rank reduction,
        // frame activation, collapse guards, and cold-start placement all run
        // before the Newton loop's explicit `state_moved` tracking begins. Keep
        // an exact snapshot here so none of those model transitions can be
        // mistaken for an idempotent re-entry. The snapshot is differential
        // (large basis caches are deterministic and omitted), so this does not
        // copy the dominant N x M storage.
        let entry_state = self.snapshot_mutable_state();
        let entry_temperature = self.assignment.mode.temperature();
        let outcome = self.run_joint_fit_arrow_schur_with_termination_policy(
            target,
            rho,
            analytic_penalties,
            max_iter,
            step_size,
            ridge_ext_coord,
            ridge_beta,
            false,
        )?;
        if matches!(outcome.termination, JointFitTermination::Heuristic) {
            return Err(
                "SaeManifoldTerm::run_joint_fit_arrow_schur_for_quasi_laplace: heuristic \
                 termination escaped the evidence policy"
                    .to_string(),
            );
        }
        let entry_state_recurred = self.matches_mutable_state(&entry_state)
            && self.assignment.mode.temperature().to_bits() == entry_temperature.to_bits();
        // `GumbelTemperatureSchedule::step` advances its counter even when the
        // emitted temperature equals the currently installed value (notably its
        // first `tau_start` step). Such a call has not reached an idempotent
        // evidence map if the NEXT re-entry will anneal to a different objective.
        // At the temperature floor `current_tau(iter_count)` stays bit-identical,
        // so a genuinely settled schedule remains certifiable.
        let temperature_stable_on_reentry =
            self.temperature_schedule.as_ref().is_none_or(|schedule| {
                schedule.current_tau(schedule.iter_count).to_bits()
                    == self.assignment.mode.temperature().to_bits()
            });
        // Evaluate the conjunction clause by clause so the first false one can be
        // named. The order is the causal one: a pass that never reached a settled
        // root explains a state move, which explains a non-recurrence.
        let settled_root = matches!(
            outcome.termination,
            JointFitTermination::Frozen | JointFitTermination::NoStrictDecrease
        );
        let gap = if !settled_root {
            EvidenceFixedPointGap::NotASettledRoot
        } else if outcome.state_moved {
            // Name the site: `termination` is a fact about the Newton loop while
            // `state_moved` is an OR over the whole call, so a settled-root
            // termination paired with a move is only readable once you know
            // WHICH of the four out-of-loop sites fired.
            EvidenceFixedPointGap::StateMoved(
                outcome
                    .moved_at
                    .unwrap_or(StateMoveSite::AcceptedNewtonStep),
            )
        } else if !entry_state_recurred {
            EvidenceFixedPointGap::StateNotRecurred
        } else if !temperature_stable_on_reentry {
            EvidenceFixedPointGap::TemperatureStillAnnealing
        } else {
            EvidenceFixedPointGap::None
        };
        Ok(EvidenceJointFitOutcome {
            loss: outcome.loss,
            fixed_point: gap == EvidenceFixedPointGap::None,
        })
    }

    pub(crate) fn run_joint_fit_arrow_schur_with_termination_policy(
        &mut self,
        target: ArrayView2<'_, f64>,
        rho: &mut SaeManifoldRho,
        analytic_penalties: Option<&AnalyticPenaltyRegistry>,
        max_iter: usize,
        step_size: f64,
        ridge_ext_coord: f64,
        ridge_beta: f64,
        allow_heuristic_termination: bool,
    ) -> Result<JointFitOutcome, String> {
        *rho = rho.clone().for_assignment(self.assignment.mode);
        self.assignment.validate_rho_domain(rho)?;
        if !(step_size.is_finite() && step_size > 0.0) {
            return Err(format!(
                "SaeManifoldTerm::run_joint_fit_arrow_schur: step_size must be finite and positive; got {step_size}"
            ));
        }
        // The inner Newton fit fans the per-row assembly, factorization, and
        // reduced-Schur reduction across the global Rayon pool (`into_par_iter`
        // over the `n` rows). Every faer HIGH-LEVEL solver reached from inside
        // those workers — per-row Cholesky / self-adjoint eigendecomposition, the
        // border factorization — reads `faer::get_global_parallelism()` directly.
        // `with_nested_parallel` pins only gam's OWN `matmul` wrapper to
        // `Par::Seq`; it CANNOT reach those faer solvers (they take no parallelism
        // argument). Under faer's default `Par::rayon(0)` each per-row solver
        // therefore re-fans faer's `spindle` barrier pool INTO the already
        // saturated outer Rayon fan-out. Profiling the real behavior fit
        // (n=4000, p=256, K=8) on an H100 showed ~34% of all cycles spinning in
        // `spindle::Barrier::wait_and_clear_while` and a further ~16% in the
        // futex/spinlock slow path, both pure oversubscription overhead. Pinning
        // faer's process-global parallelism to `Par::Seq` for the duration of the
        // inner fit collapses that nested pool: the coarse per-row Rayon
        // parallelism is untouched (it is where the actual parallel speedup
        // lives), and faer's reductions are parallelism-invariant — `Par::Seq`
        // and `Par::rayon` are bit-for-bit identical (`tests_parallelism_invariance_1557`)
        // — so this removes only wasted synchronization, changing no fitted value.
        //
        // Held in a named binding and consumed by the explicit `drop(...)` at the
        // tail return (mirroring `finalize_cap_guard` in run_plan.rs), rather than
        // `let _guard`: the workspace ban-scanner forbids every underscore-leading
        // `let`, and a plain unused `let guard` trips `unused_variables` under
        // `warnings = "deny"`. The guard's Drop still restores the prior
        // parallelism on every early `?`/`return` path via RAII.
        let faer_sequential_inner_fit = gam_linalg::faer_ndarray::FaerSequentialScope::enter();
        self.refresh_basis_from_current_coords()
            .map_err(|err| format!("SaeManifoldTerm::run_joint_fit_arrow_schur: {err}"))?;
        // #850 / gam#577 / gam#579 — `max_iter == 0` is a genuine FREEZE of the
        // warm-started inner `(t, β)` state, a verbatim reuse and NOT a
        // convergence request. The caller (`penalized_quasi_laplace_criterion_with_cache_refine_policy`
        // / `penalized_quasi_laplace_criterion_streaming_exact`) runs this with `max_iter == 0`
        // precisely to hold β at the seed, then factors once at that frozen
        // iterate (`converge_inner_for_undamped_logdet`'s `inner_max_iter == 0`
        // branch). Everything below — the rank-reduction reparametrization, the
        // decoder-frame activation, the #1003/#976 active-mass / decoder-norm
        // re-seed guards, and especially the #1026 post-loop decoder-LSQ polish —
        // can MOVE β off the seed: the polish refits the decoder to the
        // unpenalised least-squares argmin and commits it whenever the warm-start
        // arrives off that argmin (i.e. for any genuine continuation seed). That
        // silently broke the warm-start reuse the continuation walk depends on
        // (the regression test `seed_inner_state_installs_and_reuses_matching_beta`
        // published a refined hint instead of the seed). So at a zero-iteration
        // freeze we run ONLY the β-neutral basis refresh above and return the loss
        // at the untouched warm-start state. The state is already structurally
        // prepared by the full solve that produced it: any rank reduction
        // (`SubspaceReducedEvaluator`) and decoder frames it needs are persistent
        // on the atoms, so re-running those entry stages here would at best be a
        // no-op and at worst reparametrize the frozen β — neither is wanted under
        // the freeze contract.
        if max_iter == 0 {
            return self.loss(target, rho).map(|loss| JointFitOutcome {
                loss,
                termination: JointFitTermination::Frozen,
                state_moved: false,
                moved_at: None,
            });
        }
        // #1117 root-cause fix — rank-revealing adaptive basis depth, applied
        // FIRST (before frame activation, the identifiability audit, and the
        // outer loop) so every downstream stage sees a full-rank design. A
        // fixed-width decoder basis (e.g. the periodic circle's
        // `[1, sin2πt, cos2πt, sin4πt, cos4πt]`) emits `M_k` columns whether or
        // not the fitted `t`/assignment excite them; on a near-degenerate
        // checkpoint (OLMo `stage1-step0` PCA-32: data Gram rank `3/5`) the
        // unexcited columns make the decoder design rank-deficient BY
        // CONSTRUCTION, flattening the outer penalized quasi-Laplace surface so BFGS stalls. We
        // discover the data-supported subspace `Q_k = range(G_k)` ONCE here from
        // the bare data Gram and, for any rank-deficient atom, REPARAMETRIZE its
        // basis onto that subspace (`Φ̃ = Φ Q_k`, `B̃ = Q_kᵀ B`, `S̃ = Q_kᵀ S Q_k`,
        // and a `SubspaceReducedEvaluator` so the reduction survives every
        // refresh). The reduced design is full-rank, so the identifiability audit
        // passes, the frame profiles the reduced block, the inner solve needs no
        // step-time deflation, and the outer penalized quasi-Laplace log-det is well-conditioned —
        // this SUPERSEDES the prior data-null projector deflation + post-fit
        // range projection for the rank-deficiency case. The depth decision is
        // made once here and held FIXED across the inner Newton walk. A full-rank
        // atom (`base`/`step_2300`, `r_k == M_k`) is left untouched, so its
        // design, decoder, and penalized quasi-Laplace criterion are byte-for-byte the historical
        // full-`B` path.
        self.reduce_atoms_to_data_supported_rank()?;
        // #972 / #977 T1 — magic-by-default decoder-frame activation. Before the
        // outer loop, auto-derive and install the low-rank Grassmann frames
        // (each atom independently, only when the factorization materially
        // shrinks its border and leaves a positive Grassmann dimension). No
        // flag: small-`p` / full-rank atoms stay on the bit-for-bit full-`B`
        // path, so the small-model fits are unchanged; large-ambient-`p`,
        // low-decoder-rank atoms collapse their border `M_k·p → M_k·r_k` and the
        // joint solve runs in the factored coordinate space.
        self.ensure_decoder_frames_active_for_current_decoder()
            .map_err(|err| format!("SaeManifoldTerm::run_joint_fit_arrow_schur: {err}"))?;
        // #976 Layer-1 guard ledger is per joint fit for ORDINARY fits: each
        // standalone inner solve gets a fresh re-seed budget and reports only
        // its own breaches. EVIDENCE lanes (`allow_heuristic_termination ==
        // false`) are different: `converge_inner_for_undamped_logdet` re-enters
        // this driver once per refine round (16–64 rounds per criterion
        // evaluation), and clearing here handed every round a fresh per-atom
        // reseed budget — so an atom sitting near its collapse threshold was
        // reseeded roughly once per round, each reseed an unguarded state jump
        // that spikes ‖g‖ at an objective-good iterate (the measured 2.887e8
        // gradient spike in `tests_inner_budget_trajectory_2015`), breaking
        // `refine_round_made_progress`'s monotone-decrease requirement and
        // collapsing the 64× progress budget back to base. The evidence ledger
        // is therefore PER CRITERION EVALUATION: cleared once at the
        // `penalized_quasi_laplace_criterion*` entry, persistent across refine re-entries, so the
        // per-atom budget (`SAE_ATOM_COLLAPSE_RESEED_BUDGET`) genuinely bounds
        // reseeds over the whole converge-to-KKT drive.
        if allow_heuristic_termination {
            self.collapse_events.clear();
        }
        // #1003 — run the active-mass guard at ENTRY (iteration 0), before the
        // pre-fit identifiability audit. A cold seed can hand the fit an atom
        // whose gates are vacuous on every row (the outer seed cascade sweeps
        // ρ states the seeding heuristics never saw); without this call the
        // audit below reports that atom as a fatal rank-0 weighted design and
        // the whole seed dies, even though the #976 guard exists precisely to
        // answer a support collapse with one observable re-seed. The guard's
        // shared per-fit budget applies unchanged: an atom re-seeded here that
        // collapses again mid-fit goes Terminal, which is the structure
        // search's signal, not the inner loop's. Genuinely degenerate bases
        // (zero rows regardless of gates) still fail the audit — correctly.
        self.enforce_active_mass_guard(0, Some(rho))?;
        // #976 decoder arm at entry: if a warm-started decoder arrives already
        // collapsed (e.g. a ρ-sweep state seeded from a prior degenerate fit),
        // reseed it before the audit. An all-zero cold seed has a zero median
        // decoder norm, so the guard returns early and the cold-start path is
        // untouched.
        self.enforce_decoder_norm_guard(target, 0, rho, None)?;
        // ── Pre-fit decoder identifiability audit ──────────────────────────
        //
        // Each decoder atom `k` contributes `η_i += a_ik · Φ_k(t_ik) · B_k`,
        // with `B_k ∈ ℝ^{M_k × p}`. The decoder Hessian for atom `k` is
        // `H_data = G_k ⊗ I_p` where `G_k = (diag(a_·k)·Φ_k)ᵀ (diag(a_·k)·Φ_k)`
        // (the diagonal `(atom_k, atom_k)` block of the sparse data Gram `G`
        // assembled in `assemble_arrow_schur`); the
        // `p` output channels share the identical `M_k × M_k` Gram, so decoder
        // identifiability is fully determined by the per-atom `(n, M_k)` design
        // `D_k = diag(a_·k)·Φ_k`. The `p`-fold output replication carries no
        // extra structural information and must NOT be materialised — doing so
        // (the former `(n·p, M_k·p)` channel-block route through the
        // cross-block flat audit) broadcast an `(n·p)`-row Jacobian into the
        // `n`-row placeholder design and panicked inside ndarray.
        //
        // We therefore run the rank check directly on each `D_k`. A
        // rank-deficient `D_k` means atom `k`'s decoder block Hessian is
        // singular (its Cholesky will fail or produce garbage steps), which is
        // surfaced as an immediate fatal error. Near-rank-deficient columns are
        // logged as INFO so callers can see which atoms are weakly identified.
        //
        // The check is performed chunk-aware through the per-atom Gram
        // accumulator: the full-batch path is the single-chunk special case.
        // `D_k`'s singular spectrum equals `√spec(G_k)` with
        // `G_k = D_kᵀ D_k`, so accumulating `G_k` over the whole design and
        // taking its eigenvalues reproduces the former pivoted-QR rank exactly
        // while never retaining an `(N × M_k)` design.
        {
            let mut grams = self.empty_decoder_gram_accumulator();
            self.accumulate_decoder_gram(&mut grams)?;
            self.finalize_decoder_identifiability_audit(&grams, self.n_obs())?;
        }
        // #2027 — COLD-START disjoint decoder placement. The joint Newton solve
        // below relies on its first step to place decoder mass from the seed, but an
        // all-≈0 cold decoder is a DEGENERATE stationary start: with every `B_k = 0`
        // the reconstruction is the zero map, the inner gradient can already sit under
        // the relative convergence tolerance, and the loop "converges" and BREAKS at
        // iteration 0 without ever placing a decoder — the fit returns the null
        // reconstruction (EV ≈ 0) and the in-loop co-collapse guard (which the loop
        // body reaches only AFTER an accepted step) never runs. This is the whitened
        // K≥2 co-collapse fingerprint: EV = −0.0, `cocollapse_reseeds = 0`. Give the
        // solve a NON-DEGENERATE start whenever the dictionary decoder has co-vanished
        // at entry: place an initial DISJOINT-subspace decoder by greedy deflation —
        // each atom claims a distinct chunk of the target (the same refit the
        // co-collapse reseed arm uses), so the atoms start on separate structure and
        // the Newton walk has a real coordinate gradient to descend. Gated strictly on
        // a co-vanished decoder (`max_k ‖B_k‖ == 0`, the cold seed): any warm-started
        // or already-placed decoder is left byte-for-byte untouched, so every existing
        // non-cold fit — and the `max_iter == 0` freeze handled above — is unchanged.
        let max_decoder_norm = self
            .atoms
            .iter()
            .map(|atom| atom.decoder_coefficients().iter().map(|v| v * v).sum::<f64>())
            .fold(0.0_f64, f64::max)
            .sqrt();
        if !(max_decoder_norm > 0.0) {
            // Sequential CHART deflation (not just decoder deflation): re-seed each
            // atom's coordinates from the residual left by prior atoms so the atoms
            // align with DISTINCT planted factors and separate, rather than both
            // fitting the dominant factor (high EV, no structure recovery).
            self.seed_cold_start_disjoint_charts(target)?;
        }
        // #1026/#2230 — keep the best state found inside this bounded inner
        // solve, keyed on the PENALIZED OBJECTIVE (`prefer_candidate_state`):
        // the same scalar the Armijo lane descends and the outer penalized quasi-Laplace score
        // consumes. The incumbent exists to undo damage from the NON-monotone
        // boundary hooks (collapse reseeds, gauge retraction/pin, frame
        // refresh) — the Armijo walk itself is objective-monotone, so under
        // this key the end-of-loop restore never vetoes legitimate descent.
        // The former EV key did: a walk that traded EV for penalty (the
        // objective's own preference at this ρ) was "restored" back to the
        // high-EV incumbent after EVERY probe, so the outer criterion was
        // priced at ≈ the same ρ-independent state each evaluation and the ρ
        // search flattened into the #2230/#2134 restore-churn grind. EV and
        // coordinate uniformity remain as the tie-break at near-equal
        // objective (#2081), and as telemetry. This is not a PCA shortcut:
        // the incumbent is the normal SAE dictionary state (coords, logits,
        // decoder blocks) produced by the existing seed/reseed + LSQ machinery.
        let mut best_reconstruction_ev = self
            .dictionary_reconstruction_ev(target, rho)
            .unwrap_or(f64::NEG_INFINITY);
        let mut best_reconstruction_obj = self
            .penalized_objective_total(target, rho, analytic_penalties, 1.0)
            .unwrap_or(f64::INFINITY);
        let initial_reconstruction_is_structurally_healthy = best_reconstruction_ev.is_finite()
            && best_reconstruction_obj.is_finite()
            && self.structural_coherence_collapse_detected()?.is_none();
        // #2081 — the incumbent carries its coordinate-uniformity score alongside
        // EV so the keep-best can break (near-)equal-objective ties on coordinate
        // fidelity.
        let mut best_reconstruction_uniformity = if initial_reconstruction_is_structurally_healthy {
            self.coordinate_uniformity_aggregate()
        } else {
            None
        };
        let mut best_reconstruction_state = if initial_reconstruction_is_structurally_healthy {
            Some(self.snapshot_mutable_state())
        } else {
            best_reconstruction_ev = f64::NEG_INFINITY;
            best_reconstruction_obj = f64::INFINITY;
            None
        };
        // EXIT-BOUNDARY OBJECTIVE WARRANTY bank (#2228 divergence class). The
        // EV-keyed incumbent above is deliberately CONDITIONAL (structural-
        // coherence/EV-gated basin preference), which leaves a gap: on a
        // trajectory where the coherence gate fires from the start, NOTHING is
        // ever banked, the end-of-loop restore has nothing to restore, and a
        // non-monotone boundary mover (a collapse reseed thrown at the budget
        // edge, a gauge hook, a post-loop sweep whose exact block solves
        // themselves fail on the blown state) leaks an amplified iterate to
        // the caller. Chaotic ulp-level trajectory sensitivity made that leak
        // intermittent (fd_2015: the same binary/host/thread-count returned
        // ‖g‖ ≈ 2e-3 or ≈ 3.8e30 run to run before the deterministic-reduction
        // stack pinned the trajectory). This bank is UNCONDITIONAL and keyed
        // on the penalized objective alone — the one scalar the walk descends
        // — so the engine can always honor the contract "never return a state
        // materially worse than the best state it held". Basin preference
        // (EV/uniformity/coherence) is untouched: it still owns WHICH
        // near-equal-objective state is kept; the warranty only forbids
        // returning an objectively degraded one.
        let mut warranty_obj = self
            .penalized_objective_total(target, rho, analytic_penalties, 1.0)
            .unwrap_or(f64::INFINITY);
        let mut warranty_state = if warranty_obj.is_finite() {
            Some(self.snapshot_mutable_state())
        } else {
            None
        };
        // #2100/#1117 — objective-stagnation convergence for the JOINT outer loop,
        // the exact analogue of the #1051 stall gate already guarding
        // `converge_inner_for_undamped_logdet`. On a co-collapsed K≥2 basin (two
        // atoms decode a SHARED output subspace, μ̂≈1 — the inter-atom
        // coefficient-rotation gauge orbit), the joint Newton wanders that flat
        // direction: each Armijo-accepted step lowers the penalised objective by a
        // sub-√εmach amount while ‖g‖ and the quotient step stay above their
        // relative tolerances (the near-singular Schur amplifies the weakly-identified
        // decoder direction), so the grad/step gates never clear and the loop grinds
        // the full (refine-escalated, ≥1024) `max_iter` at ~1 s/iterate — the
        // BLOCKER-1 hours-long K=2 planted-circle hang. The grad/quotient-step gates
        // quotient the SINGLE-atom chart gauge and the decoder-β-null but NOT this
        // inter-atom shared-subspace gauge, so the objective itself is the honest
        // stationarity witness here: an iterate whose penalised objective has stopped
        // decreasing to within √εmach of its scale IS the numerical inner optimum on
        // whatever quotient the flat direction spans, and ranking the Laplace
        // criterion there is correct. Break after
        // `SAE_MANIFOLD_INNER_OBJECTIVE_STALL_MIN_ROUNDS` CONSECUTIVE stalled
        // iterations (a single flat step can be a benign saddle crossing; a run of
        // them is sufficient for the ordinary bounded-fit shortcut). Evidence
        // disables this heuristic because a still-strict decrease is not an
        // idempotent root. `previous_full_iterate_objective` is the
        // loop-top objective, which already reflects the PRIOR iteration's step,
        // guards, retraction and canonicalization, so the measured decrease is the
        // TOTAL per-iteration progress. Reuses the existing derived stall constants
        // (no new magic number). A healthy fit clears the grad gate long before its
        // relative decrease falls below 1e-8, so this never truncates real descent.
        let mut previous_full_iterate_objective = f64::INFINITY;
        let mut consecutive_objective_stalls = 0usize;
        // #976 hot-path: the decoder-norm co-collapse guard centers its EV and
        // output-energy signals on the TARGET, an invariant of the whole joint
        // fit. Reduce its per-column means and total centered sum-of-squares ONCE
        // here and hand them to every iteration's guard call, rather than
        // re-reducing the full n×p target on each accepted step (the O(n·p)
        // column pass that dominated the single-threaded inner-loop profile).
        // Bit-identical to the historical per-call reduction (see
        // `TargetCenteredColStats`).
        let target_col_stats = TargetCenteredColStats::compute(target);
        // #2015 line-search step-length warm start (the ‖g‖ crawl mitigation).
        // The Armijo backtracking only CONTRACTS from `initial_step`; carry the
        // previous accepted step forward so the search does not re-discover the
        // same tiny step from `step_size` each iterate. A CLEAN acceptance resets
        // to the full `step_size` (no overshoot evidence), so a hard early iterate
        // never throttles later easy iterates; only a BACKTRACKED acceptance warms
        // forward by one contraction step (`accepted / contraction`). Pure
        // globalization — KKT convergence and typed exhaustion (#2235/#2241)
        // unchanged.
        let warm_growth = 1.0 / BacktrackConfig::default().contraction;
        // #2267/#2762 — resume the WHOLE globalization state the previous
        // re-entry established. The Armijo step length and the two LM ridges
        // describe one optimizer trajectory; resuming only the step length
        // while restoring the ridges to their caller floors made every evidence
        // refinement window spend its first iterations rediscovering the same
        // trust region. The caller values remain hard floors, so a continuation
        // never resumes less damping or a shorter first trial than a cold solve.
        let mut globalization = InnerGlobalizationHint::resume(
            self.inner_globalization_hint,
            step_size,
            ridge_ext_coord,
            ridge_beta,
        );
        // #2015 Levenberg–Marquardt ridge, adapted across iterates. The primary
        // solve (`solve_with_lm_escalation_inner`) escalates the ridge only when
        // the factorization FAILS, so on a well-conditioned-but-nonlinear system
        // it returns the undamped Gauss–Newton step — whose 1-D minimum along the
        // step is a tiny fraction of the full step on a high-residual / ill-posed
        // shape (the GN Hessian mismodels curvature because the dropped
        // residual·∇²r term is large), so Armijo backtracks to ~0.05 every iterate
        // and the KKT residual crawls. Carry an LM ridge that GROWS when the step
        // overshoots (the line search had to backtrack — the observed gain-ratio
        // signal: backtracking depth = ⌈log₂ overshoot⌉) and SHRINKS back toward
        // Gauss–Newton on a clean full-step acceptance. Growing the ridge bends
        // the step from GN toward gradient descent (shorter, better-scaled) so the
        // full step is accepted and real progress resumes; shrinking recovers GN's
        // quadratic convergence as the fit enters its local quadratic basin. Uses
        // ONLY the existing ridge parameters and `SAE_MANIFOLD_ROW_RIDGE_GROWTH`
        // (no new tuning knob), floored at the caller's ridges, and reset to them
        // on a proximal-correction fallback (which runs its own escalation).
        // Armijo still refereed the true objective, so descent — and the
        // #2235/#2241 certified-termination / typed-exhaustion contract — is
        // unchanged; only the trajectory to the same certified optimum is.
        let mut termination = JointFitTermination::IterationGrantExhausted;
        // #2762 — whether the gauge-orbit block descent is armed for the NEXT
        // objective-stall plateau in the ORDINARY lane. Same arm/disarm doctrine
        // as `terminal_newton_polish_armed` in the evidence refine loop:
        // consulting the block disarms it, and only a materially-descending
        // Newton or proximal step re-arms, so a long fit that alternates real
        // descent with plateaus gets one block consultation per plateau rather
        // than an unbounded alternation.
        let mut gauge_block_armed = true;
        let mut state_moved = false;
        // FIRST site to move state — `termination` is set only inside the Newton
        // loop, so without this the out-of-loop sites are unattributable.
        let mut moved_at: Option<StateMoveSite> = None;
        // FIRST-PRINCIPLES ENGINE ORDER (#2228 stage 4, increment 1) — run the
        // deterministic alternating block sweeps BEFORE the joint Newton walk,
        // not only as a post-loop rescue. At fixed gates the problem is
        // structurally easy in blocks: the decoder given coordinates is an
        // EXACTLY solvable penalized linear LS, and the coordinates given the
        // decoder decouple per row with globally enumerable solutions (the
        // companion-matrix projector). Each sweep is objective-monotone by
        // construction (same strict-decrease gate as the historical post-loop
        // polish), deterministic given the seed, and does in O(1) exact block
        // solves what the majorized joint Newton does in O(10²–10³) linear-rate
        // iterations. The Newton walk below then starts inside the sweep fixed
        // point's basin and serves as the joint certifier (logits + cross-block
        // coupling + KKT gate) instead of as the bulk workhorse. The
        // max_iter == 0 freeze already returned above.
        //
        // BOTH LANES sweep at entry, with LANE-DEPENDENT commit floors (see
        // `sweep_blocks_to_objective_fixed_point`): the measured A/B pair
        // proved the entry sweep is BOTH the wide-p divergence kill (a blown
        // or cold entry state's decoder-LSQ decrease is O(objective); removing
        // the entry sweep restored the ‖g‖≈3e27 baseline blow-up bit-for-bit)
        // AND, at the fine floor, the #2253 idempotence breaker on evidence
        // re-entries (per-assembly gate-freeze drift lets each re-entry
        // harvest a fresh ε-decrease ⇒ refused as non-idempotent at 512). The
        // evidence lane therefore commits only MATERIAL decreases
        // (STALL_FRACTION of scale): the rescue passes, the harvest cannot.
        if self.sweep_blocks_to_objective_fixed_point(
            target,
            rho,
            analytic_penalties,
            allow_heuristic_termination,
        )? {
            state_moved = true;
            moved_at.get_or_insert(StateMoveSite::EntryBlockSweep);
        }
        for outer_iteration in 0..max_iter {
            let temperature_before = self.assignment.mode.temperature();
            if self
                .advance_temperature_schedule()?
                .is_some_and(|temperature| temperature.to_bits() != temperature_before.to_bits())
            {
                state_moved = true;
                moved_at.get_or_insert(StateMoveSite::TemperatureSchedule);
            }
            // ρ (including the ARD precisions) is owned by the outer engine
            // (`SaeManifoldOuterObjective`) and held FIXED across this inner
            // (t, β) Newton solve. The inner loop solves the joint manifold +
            // decoder system at the engine's current ρ; the engine alone
            // moves ρ by minimising the penalised quasi-Laplace score
            // score (see `SaeManifoldTerm::penalized_quasi_laplace_criterion`; #1421: NOT a
            // true normalized-prior REML — the improper softmax/ThresholdGate
            // assignment priors have no finite normalizer). The former in-loop
            // `update_ard_reml` rule (α = n / ‖t‖²) dropped the logdet /
            // effective-dof term and collapsed α on near-degenerate axes; it
            // has been removed in favour of the criterion-driven update.
            let mut sys = self
                .assemble_arrow_schur(target, rho, analytic_penalties)
                .map_err(|err| format!("SaeManifoldTerm::run_joint_fit_arrow_schur: {err}"))?;
            let plan = self
                .streaming_plan()
                .map_err(|err| format!("SaeManifoldTerm::run_joint_fit_arrow_schur: {err}"))?
                .admitted_or_error(self.n_obs(), self.output_dim(), self.k_atoms())
                .map_err(|err| format!("SaeManifoldTerm::run_joint_fit_arrow_schur: {err}"))?;
            let mut solve_options = plan
                .solve_options_for_border_dim(sys.k)
                .with_gpu_policy(self.gpu_policy);
            // #2228 — gauge-fix the inner Newton STEP on the reduced β border.
            //
            // The closed-form chart gauge (circle/torus phase, patch
            // translation+scale) is an exact reconstruction symmetry whose β
            // component is a null direction of the reduced β-Schur `S_β`. Left
            // un-deflated, the dense Direct/SqrtBA step solves an exactly-singular
            // `S_β`, so the orbit component of Δβ is arbitrary: it drifts the state
            // along the orbit (walking `t` off the circle over the outer ρ-walk,
            // fit_drivers.rs' second-root note) and starves the identifiable
            // descent, so the fit crawls at ~0.997 contraction and eventually
            // reports a non-stationary plateau (#2228 repro A / #2253). Installing
            // the closed-form gauge as an [`ArrowBetaGaugeQuotient`] makes the dense
            // step solve the Faddeev–Popov quotient `P S_β P + Q Qᵀ`, projecting Δβ
            // onto the identifiable complement. The criterion evaluation and the
            // outer-ρ gradient assemble their own systems and are untouched, and
            // the loss/criterion are gauge-invariant, so this only changes the
            // convergence path, converging to a gauge-fixed representative.
            //
            // Installed on the dense Direct/SqrtBA modes AND the wide-`p`
            // InexactPCG lane: the matrix-free reduced-Schur matvec applies the
            // same Faddeev–Popov pin `P S_β P + Q Qᵀ` (`ReducedSchurOperator`), and
            // the CPU `steihaug_pcg_auto` lane projects the RHS onto the
            // identifiable complement. The device `solve_sae_matrix_free_pcg`
            // kernel does NOT yet apply the pin, so it is gated off to the CPU path
            // whenever a quotient is present (a follow-up will project in-kernel).
            if sys.k > 0
                && matches!(
                    solve_options.mode,
                    ArrowSolverMode::Direct | ArrowSolverMode::SqrtBA | ArrowSolverMode::InexactPCG
                )
            {
                match self.closed_form_beta_gauge_directions() {
                    Ok(dirs) if !dirs.is_empty() => {
                        let quotient = ArrowBetaGaugeQuotient::new(dirs).map_err(|err| {
                            format!(
                                "SaeManifoldTerm::run_joint_fit_arrow_schur: invalid closed-form \
                                 beta-gauge quotient: {err}"
                            )
                        })?;
                        sys.set_beta_gauge_quotient(quotient).map_err(|err| {
                            format!(
                                "SaeManifoldTerm::run_joint_fit_arrow_schur: closed-form \
                                 beta-gauge quotient does not match the assembled border: {err}"
                            )
                        })?;
                    }
                    Ok(_) => {}
                    Err(err) => {
                        return Err(format!(
                            "SaeManifoldTerm::run_joint_fit_arrow_schur: closed-form gauge \
                             directions: {err}"
                        ));
                    }
                }
            }
            // #1017 allocation residency across ACCEPTED nonlinear iterates.
            // The retained handle owns device allocations only; `prepare_*`
            // overwrites every ridge-independent operand from this freshly
            // assembled `sys` (or rebuilds on shape drift). The LM ladder then
            // recomputes `ainv` for each ridge trial as before. No factor or
            // numerical block crosses the accepted-iterate boundary.
            let existing_resident_frame = self.arrow_assembly_workspace.resident_frame.take();
            let resident_frame = prepare_sae_resident_frame(
                &sys,
                &solve_options,
                existing_resident_frame,
            )
            .map_err(|error| {
                format!(
                    "SaeManifoldTerm::run_joint_fit_arrow_schur: resident GPU frame preparation failed: {error}"
                )
            })?;
            solve_options.sae_resident_frame = resident_frame;
            self.arrow_assembly_workspace.resident_frame = solve_options.sae_resident_frame.clone();
            // Inner Newton step with principled LM-style ridge escalation. The
            // PCA-seed starting state on a small batch (e.g. `predict` on a
            // strict subset of the training set) can produce a per-row
            // `H_tt + ridge_t·I` whose Cholesky has a negative pivot, or a
            // near-singular Schur complement, at the caller's nominal ridges.
            // Rather than abort, mirror the proximal-correction outer wrapper
            // and grow both ridges geometrically until the linear system
            // factors. This is the same LM-trust-region damping the convergent
            // proximal_correction path applies; we route it through the same
            // factor-failure error variants so legitimate, non-recoverable
            // errors (PCG divergence with no factor failure, adaptive-step
            // exhaustion, …) still surface immediately.
            let (mut delta_ext_coord, mut delta_beta, _diag) =
                solve_with_lm_escalation_inner(
                    &sys,
                    globalization.lm_ridge_t,
                    globalization.lm_ridge_b,
                    &solve_options,
                )
                .map_err(|err| format!("SaeManifoldTerm::run_joint_fit_arrow_schur: {err}"))?;
            // #1095/#2228 (second root) — per-row STEP gauge fixing. On a chart
            // over-parametrized for its intrinsic data dimension (d=2 chart on an
            // intrinsically 1-D circle) every per-row `H_tt` carries a rank-1
            // radial null whose direction ROTATES per row (the null is the radial
            // unit vector `(cosθ_i, sinθ_i)`, distinct for every row — NOT a chart
            // axis, so no global/per-atom axis reduction can capture it). The
            // undamped acceptance factorizations in `penalized_quasi_laplace_criterion` already deflate
            // that null to UNIT stiffness (`log 1 = 0`, ρ-independent) so the
            // criterion log-det is finite — but the coordinate SOLVE here does not:
            // `solve_with_lm_escalation_inner` LM-ridge-damps the near-null block,
            // leaving a small-but-nonzero step along the radial null (the data is
            // radially FLAT, not absent, so `g_null ≠ 0` at finite noise). Those
            // sub-floor steps ACCUMULATE across the cumulative outer ρ-walk, walking
            // `t` off the unit circle → the decoder loses angular resolution
            // (reconstruction collapses) and the inner optimum — hence the REML
            // criterion — becomes warm-start dependent rather than a function of ρ.
            //
            // True gauge fixing is a projection: subtract each row's sub-floor null
            // direction from that row's coordinate step so there is ZERO motion along
            // a deflated direction, period, while the identifiable (angular)
            // complement keeps the exact LM/Newton step. `row_sub_floor_null_directions`
            // uses the IDENTICAL spectral floor + hysteresis the criterion deflation
            // uses, so the step freezes exactly what the log-det deflated. It returns
            // EMPTY for a genuinely full-rank row (a well-conditioned block, or a
            // merely-ill-conditioned NON-null K>1 block whose weak but data-supported
            // direction must stay with the LM damping, not be frozen) and for
            // radius-curved circle data (the radial eigenvalue lifts above the floor)
            // — so healthy fits are bit-for-bit unchanged and the fix is auto-undone
            // wherever the chart is not over-parametrized. Projecting the coordinate
            // block alone is sufficient: the null's cross-coupling to β flows through
            // `H_tβ = ∂²/∂t∂β`, built from the SAME decoded derivative that vanishes
            // in the radial direction, so it is second-order small; the dominant
            // drift is the direct `Δt` null component removed here, and any residual
            // β coupling is re-solved next iterate from the on-circle state.
            // Each row projects its own sub-floor null directions out of ONLY its
            // own `[off..off+di]` coordinate segment (disjoint segments keyed by
            // `row_offsets`), so the rows are independent. Fan out over the SAE row
            // count, handing each row-chunk its own contiguous output slice via
            // `split_at_mut` keyed on `row_offsets` (the same disjoint-segment idiom
            // `back_substitute_delta_t` uses). Disjoint writes ⇒ no reduction, no
            // run-to-run drift — bit-identical to the serial sweep.
            let n_rows = sys.rows.len();
            let parallel =
                n_rows >= SAE_LOSS_PARALLEL_ROW_MIN && rayon::current_thread_index().is_none();
            if parallel {
                use rayon::prelude::*;
                const CHUNK: usize = 64;
                let row_offsets = &sys.row_offsets;
                let dt_slice = delta_ext_coord
                    .as_slice_mut()
                    .expect("delta_ext_coord contiguous");
                let n_chunks = n_rows.div_ceil(CHUNK);
                let mut remaining = dt_slice;
                let mut segments: Vec<(usize, &mut [f64])> = Vec::with_capacity(n_chunks);
                let mut prev_end = 0usize;
                for chunk in 0..n_chunks {
                    let start = chunk * CHUNK;
                    let end = (start + CHUNK).min(n_rows);
                    let seg_len = row_offsets[end] - row_offsets[start];
                    assert!(
                        prev_end == row_offsets[start],
                        "sae gauge-fix: non-contiguous row segment at chunk start {start} \
                         (prev_end={prev_end}, row_offset={})",
                        row_offsets[start]
                    );
                    let (seg, rest) = remaining.split_at_mut(seg_len);
                    remaining = rest;
                    segments.push((start, seg));
                    prev_end = row_offsets[end];
                }
                segments.into_par_iter().for_each(|(start, seg)| {
                    let end = (start + CHUNK).min(n_rows);
                    let mut local = 0usize;
                    for row_idx in start..end {
                        let di = sys.row_dims[row_idx];
                        // #1557 — the null-direction eigendecomp (`sym.eigh`) issues a
                        // faer GEMM; pin it to `Par::Seq` inside this row worker so it
                        // does not re-fan the outer pool (bit-identical result).
                        let dirs = with_nested_parallel(|| {
                            row_sub_floor_null_directions(sys.rows[row_idx].htt.view())
                        });
                        for dir in dirs {
                            if dir.len() != di {
                                continue;
                            }
                            let mut dot = 0.0;
                            for a in 0..di {
                                dot += dir[a] * seg[local + a];
                            }
                            for a in 0..di {
                                seg[local + a] -= dot * dir[a];
                            }
                        }
                        local += di;
                    }
                });
            } else {
                for row_idx in 0..n_rows {
                    let off = sys.row_offsets[row_idx];
                    let di = sys.row_dims[row_idx];
                    for dir in row_sub_floor_null_directions(sys.rows[row_idx].htt.view()) {
                        if dir.len() != di {
                            continue;
                        }
                        let mut dot = 0.0;
                        for a in 0..di {
                            dot += dir[a] * delta_ext_coord[off + a];
                        }
                        for a in 0..di {
                            delta_ext_coord[off + a] -= dot * dir[a];
                        }
                    }
                }
            }
            // Relative-scale floor on the directional decrease. When the
            // gradient is nearly orthogonal to the Newton step (ill-conditioned
            // near-convergence), `directional_decrease` collapses to O(machine
            // epsilon · ‖g‖ · ‖Δ‖). At that scale the Armijo bound
            // `pre_step_total − c1·step·directional_decrease` is numerically
            // indistinguishable from `pre_step_total`, so the line search would
            // "accept" on rounding noise. Treat that as converged and stop. The
            // norms are the natural scale of the inner product; the relative
            // constant keeps the reduction term distinguishable from rounding at
            // full step size given SAE_MANIFOLD_ARMIJO_C1 = 1e-4.
            let mut grad_norm_sq = 0.0;
            for (row_idx, row) in sys.rows.iter().enumerate() {
                let di = sys.row_dims[row_idx];
                for axis in 0..di {
                    grad_norm_sq += row.gt[axis] * row.gt[axis];
                }
            }
            for idx in 0..sys.k {
                grad_norm_sq += sys.gb[idx] * sys.gb[idx];
            }
            let grad_norm = grad_norm_sq.sqrt();
            let iterate_scale = self.inner_iterate_scale();
            let grad_tolerance = SAE_MANIFOLD_INNER_GRAD_REL_TOL * iterate_scale;
            let step_tolerance = SAE_MANIFOLD_INNER_STEP_REL_TOL * iterate_scale;
            let lambda_smooth = rho.lambda_smooth_vec()?;
            let quotient_grad_norm =
                self.quotient_gradient_norm_from_system(&sys, grad_norm_sq, &lambda_smooth);
            // Stop only on stationarity in the raw chart or on the identified
            // quotient. A tiny quotient Newton step is a globalization diagnostic,
            // not a KKT certificate: on K=1 near-isotropic clouds it can be tiny
            // along the chart gauge while the outer residual remains large.
            if allow_heuristic_termination
                && (grad_norm <= grad_tolerance || quotient_grad_norm <= grad_tolerance)
            {
                termination = JointFitTermination::Heuristic;
                self.reclaim_arrow_assembly_workspace(&mut sys);
                break;
            }
            let mut step_norm_sq = 0.0;
            for &v in delta_ext_coord.iter() {
                step_norm_sq += v * v;
            }
            for &v in delta_beta.iter() {
                step_norm_sq += v * v;
            }
            let mut quotient_step_norm = step_norm_sq.sqrt();
            if delta_ext_coord.len() == self.n_obs() * self.assignment.row_block_dim()
                && delta_beta.len() == self.factored_border_dim()
            {
                let quotient_step_norm_sq = self.quotient_newton_step_norm_sq(
                    delta_ext_coord.view(),
                    delta_beta.view(),
                    step_norm_sq,
                    &lambda_smooth,
                )?;
                quotient_step_norm = quotient_step_norm_sq.sqrt();
                // #2267 — the trust region the unit step needs.
                //
                // Lifting the step ceiling lets the line search reach `α = 1`, which
                // is what buys the superlinear tail — but a Newton step is only
                // credible over the region where its LOCAL MODEL is, and Armijo
                // alone does not bound that: a monotone objective decrease is
                // compatible with a single long step crossing into a different
                // basin (measured: a K=2 fixture whose decoders walk to
                // ‖B‖ ≈ 0.2 and trip the co-collapse guard). Step length and
                // model credibility are two different controls and the code had
                // only been using one of them, with `step_size` accidentally
                // standing in for both.
                //
                // The scale-free statement of "where the model is credible" is the
                // state's own magnitude: one iterate may not move the iterate
                // further than the iterate itself. That is `inner_iterate_scale`,
                // already the scale the KKT tolerance is measured against, so no
                // new constant enters. Near convergence the Newton step is far
                // inside this region and `α = 1` is untouched — exactly where it
                // matters — while a wild early step is clipped instead of taken.
                // Any caller-supplied radius still applies on top.
                let trust_radius = solve_options.trust_region.radius.min(iterate_scale);
                if quotient_step_norm > trust_radius
                    && trust_radius.is_finite()
                    && trust_radius > 0.0
                {
                    let scale = trust_radius / quotient_step_norm;
                    delta_ext_coord.mapv_inplace(|v| v * scale);
                    delta_beta.mapv_inplace(|v| v * scale);
                    step_norm_sq *= scale * scale;
                    quotient_step_norm = trust_radius;
                }
            }
            if quotient_step_norm <= step_tolerance {
                log::debug!(
                    "SAE inner quotient step {:.3e} <= tol {:.3e} with non-stationary gradient \
                     raw={:.3e}, quotient={:.3e}; continuing after quotient trust-region gate",
                    quotient_step_norm,
                    step_tolerance,
                    grad_norm,
                    quotient_grad_norm
                );
            }
            let directional_decrease = sae_manifold_newton_directional_decrease(
                &sys,
                delta_ext_coord.view(),
                delta_beta.view(),
            );
            let directional_decrease_floor = SAE_MANIFOLD_DIRECTIONAL_DECREASE_REL_FLOOR
                * grad_norm_sq.sqrt()
                * step_norm_sq.sqrt();
            // Capture the exact state whose assembled gradient/Hessian produced
            // `sys`, then evaluate the Armijo baseline from that same state.
            // Assembly installs compact active-set layout in `last_row_layout`;
            // computing the baseline after that mutation prevents comparing a
            // trial at one represented state against a bound from another.
            //
            // Each rejected trial restores from this snapshot in place; the
            // static atom metadata, smoothness penalties and basis-evaluator
            // `Arc`s are never re-cloned. This replaces the per-halving full
            // `self.clone()`, whose dominant cost was copying the
            // `O(N·M·d)` `basis_jacobian` and `O(N·M)` `basis_values` on every
            // backtrack.
            let snapshot = self.snapshot_mutable_state();
            let pre_step_total =
                self.penalized_objective_total(target, rho, analytic_penalties, 1.0)?;
            if !pre_step_total.is_finite() {
                // Pre-step state is unperturbed here; restore is a no-op but
                // keeps the invariant explicit.
                self.restore_mutable_state(&snapshot)?;
                self.reclaim_arrow_assembly_workspace(&mut sys);
                if !allow_heuristic_termination {
                    return Err(
                        "SaeManifoldTerm::run_joint_fit_arrow_schur: evidence polish \
                         encountered a non-finite pre-step objective"
                            .to_string(),
                    );
                }
                termination = JointFitTermination::Heuristic;
                break;
            }
            // #2100/#1117 ordinary-fit objective-stagnation shortcut (see the
            // locals above). The
            // loop-top `pre_step_total` already carries the full effect of the
            // previous iteration, so a relative decrease below the derived stall
            // tolerance means that whole iteration (Newton step + guards +
            // retraction + canonicalization) failed to move the penalised objective
            // to within √εmach of its scale. On the gauge-orbit crawl this fires
            // immediately (constant EV ⇒ vanishing objective decrease); on a healthy
            // fit the grad gate above breaks first. Counting CONSECUTIVE stalls
            // tolerates a lone flat step; `MIN_ROUNDS` in a row is the fixed point.
            if allow_heuristic_termination && previous_full_iterate_objective.is_finite() {
                let round_improvement = (previous_full_iterate_objective - pre_step_total).max(0.0);
                let objective_scale = previous_full_iterate_objective
                    .abs()
                    .max(pre_step_total.abs())
                    + 1.0;
                let relative_decrease = round_improvement / objective_scale;
                if relative_decrease < SAE_MANIFOLD_INNER_OBJECTIVE_STALL_REL_TOL {
                    consecutive_objective_stalls += 1;
                    if consecutive_objective_stalls >= SAE_MANIFOLD_INNER_OBJECTIVE_STALL_MIN_ROUNDS
                    {
                        // #2762 — THE SAME BLOCK, AT THE OTHER FIXED-POINT CLAIM.
                        //
                        // This comment used to say the shortcut fires "on the
                        // gauge-orbit crawl ... immediately (constant EV ⇒
                        // vanishing objective decrease)" — naming the exact
                        // mechanism and then treating it as a reason to STOP.
                        // The objective stops moving here because the movers can
                        // only shorten a step and the remaining decrease lives in
                        // a near-null block that needs a long one; measured on the
                        // seeded two-circle fixture, this exit left `7.66e-2` of
                        // penalized objective — relative `2.3e-3`, five orders
                        // above the `1e-8` resolution this very branch calls "no
                        // meaningful change" — recoverable in the removed span.
                        //
                        // A stall is only a fixed point if it is a fixed point of
                        // BOTH blocks, so ask the other one before concluding.
                        //
                        // ARMED ONCE PER PLATEAU, on the same doctrine this file
                        // already uses for the terminal Newton polish: consulting
                        // the block disarms it, and only a materially-descending
                        // NEWTON or proximal step re-arms. Without that, the
                        // block's own decrease breaks the stall streak that
                        // summoned it, the streak re-forms, and the ordinary
                        // lane's cheap approximation becomes a budget-limited
                        // grind — measured on the seeded two-circle fixture as
                        // `IterationGrantExhausted` at 256 iterations where the
                        // shipped exit is a bounded heuristic. One consultation
                        // per plateau is what makes the exit state gauge-
                        // minimized without changing what the exit MEANS.
                        let orbit = if gauge_block_armed {
                            gauge_block_armed = false;
                            self.descend_gauge_orbit(
                                target,
                                rho,
                                analytic_penalties,
                                &rho.lambda_smooth_vec()?,
                                max_iter.saturating_sub(outer_iteration).max(1),
                            )?
                        } else {
                            GaugeOrbitDescent::default()
                        };
                        if orbit.moved() {
                            state_moved = true;
                            moved_at.get_or_insert(StateMoveSite::GaugeOrbitDescent);
                            consecutive_objective_stalls = 0;
                            previous_full_iterate_objective = f64::NAN;
                            log::debug!(
                                "run_joint_fit_arrow_schur: gauge-orbit descent recovered \
                                 {:.6e} over {} round(s) at the objective-stall shortcut, \
                                 iteration {outer_iteration} (span dim {}, \
                                 maxᵢ|gᵀvᵢ|={:.6e}, {} objective evaluations)",
                                orbit.objective_decrease,
                                orbit.rounds,
                                orbit.dimension,
                                orbit.max_directional_derivative,
                                orbit.evaluations,
                            );
                            self.reclaim_arrow_assembly_workspace(&mut sys);
                            continue;
                        }
                        // The ordinary bounded fit has reached its documented
                        // objective-stall approximation, now in both blocks. The
                        // pre-step state is unperturbed (the snapshot was taken
                        // from it, and a descent that commits nothing restores
                        // it), so no restore is needed.
                        termination = JointFitTermination::Heuristic;
                        self.reclaim_arrow_assembly_workspace(&mut sys);
                        break;
                    }
                } else {
                    consecutive_objective_stalls = 0;
                }
            }
            previous_full_iterate_objective = pre_step_total;
            // A non-descent Newton direction (gᵀΔ ≤ 0 or below the rounding
            // floor) is only a STOPPING criterion when the iterate is actually
            // stationary: the floor exists for benign ill-conditioned
            // near-convergence, where `gᵀΔ` collapses to rounding noise while
            // ‖g‖ is already tiny. In degenerate multi-atom geometry (gate
            // tug-of-war, rank-deficient duchon columns) the LM solve factors
            // with a near-zero pivot, the step is dominated by that near-null
            // direction, and `gᵀΔ/(‖g‖·‖Δ‖)` collapses while ‖g‖ is HUGE —
            // breaking there silently froze the iterate and let the
            // `penalized_quasi_laplace_criterion` refine loop re-measure the same point until its
            // budget died (the constant-‖g‖=1e12 signature). Gate the break on
            // genuine KKT stationarity — the SAME iterate-scaled tolerance
            // `penalized_quasi_laplace_criterion` uses — and otherwise fall through to the
            // proximal-correction ridge escalation below: heavier LM damping
            // bends the step toward steepest descent, which is always a
            // descent direction for a consistent gradient.
            let descent_direction_ok = directional_decrease.is_finite()
                && directional_decrease > 0.0
                && directional_decrease > directional_decrease_floor;
            // No Armijo bound is meaningful along a non-descent direction, so
            // the whole line search is gated on `descent_direction_ok` and a
            // non-descent delta routes straight to the proximal correction.
            // The ordinary-fit coarse KKT gate above already breaks on a small
            // gradient; evidence polish intentionally bypasses that gate, so
            // the non-descent route is also its numerical fixed-point route:
            // try the existing proximal correction once, then stop below when
            // even that correction cannot produce a strict objective decrease.
            // Each trial re-applies the Newton step from the pre-step
            // `snapshot` (reset-before-reapply after the first trial); a trial
            // whose step application or objective evaluation errors is INVALID
            // (`Ok(None)`), halving without consulting the Armijo test.
            let mut first_trial = true;
            let accepted_step = if descent_direction_ok {
                backtracking_line_search::<_, String>(
                    BacktrackConfig {
                        initial_step: globalization.warm_step,
                        max_steps: SAE_MANIFOLD_MAX_LINESEARCH_HALVINGS + 1,
                        ..BacktrackConfig::default()
                    },
                    |trial_step_size| {
                        if !std::mem::take(&mut first_trial) {
                            self.restore_mutable_state(&snapshot)?;
                        }
                        Ok(self
                            .apply_newton_step(
                                delta_ext_coord.view(),
                                delta_beta.view(),
                                trial_step_size,
                            )
                            .and_then(|()| {
                                self.penalized_objective_total(target, rho, analytic_penalties, 1.0)
                            })
                            .ok()
                            .map(|post_step_total| (post_step_total, ())))
                    },
                    |trial_step_size, post_step_total| {
                        let armijo_bound = pre_step_total
                            - SAE_MANIFOLD_ARMIJO_C1 * trial_step_size * directional_decrease;
                        // #2253 idempotence — EVIDENCE lanes additionally require
                        // the decrease to clear the stall detector's own
                        // resolution: a sub-resolution "strict" decrease (the
                        // ε-harvest of per-assembly gate-freeze drift at a
                        // KKT-band iterate) is not measurable progress, but each
                        // such accept was a fresh state move that kept the inner
                        // map non-idempotent forever (tier-0 K=2 fixtures:
                        // refused at 512 granted iterations with ‖g‖ 300× inside
                        // the band). Rejecting it routes to the proximal path
                        // and then to the NoStrictDecrease termination — exactly
                        // the recurrence the certificate needs. Discovery lanes
                        // (floor 0) are byte-identical to the historical gate.
                        let material_floor = if allow_heuristic_termination {
                            0.0
                        } else {
                            SAE_MANIFOLD_INNER_OBJECTIVE_STALL_REL_TOL
                                * (1.0 + pre_step_total.abs())
                        };
                        post_step_total.is_finite()
                            && post_step_total <= armijo_bound
                            && pre_step_total - post_step_total >= material_floor
                    },
                )?
            } else {
                None
            };
            let accepted = accepted_step.is_some();
            // #2267 — per-iteration STEP ACCEPTANCE trace. A crawling inner solve
            // has exactly three distinguishable causes and they are told apart
            // here, not by inference: an accepted step far below the warm start
            // (`alpha ≪ warm`) is curvature overshoot the line search is
            // absorbing; a growing `lm_ridge` is the damping ladder bending the
            // step toward steepest descent; and a rejected step routes to the
            // proximal correction. Together with `‖g‖`/`‖Δ‖`/`gᵀΔ` this is the
            // whole per-iterate state of the globalization.
            log::debug!(
                "[SAE/inner] it={outer_iteration} ‖g‖={grad_norm:.6e} \
                 ‖Π⊥g‖={quotient_grad_norm:.6e} ‖Δ‖={:.6e} gᵀΔ={directional_decrease:.6e} \
                 alpha={} warm={:.4e} ridge_t={:.3e} ridge_b={:.3e} \
                 obj={pre_step_total:.9e}",
                step_norm_sq.sqrt(),
                match accepted_step.as_ref() {
                    Some(step) => format!("{:.4e}", step.step),
                    None => "rejected".to_string(),
                },
                globalization.warm_step,
                globalization.lm_ridge_t,
                globalization.lm_ridge_b,
            );
            if let Some(step) = accepted_step {
                state_moved = true;
                moved_at.get_or_insert(StateMoveSite::AcceptedNewtonStep);
                // Genuine transverse progress: the next plateau is a new one, so
                // the gauge block is worth asking again (#2762).
                gauge_block_armed = true;
                // #2267 — A NEWTON STEP'S NATURAL LENGTH IS ONE.
                //
                // `backtracking_line_search` only ever CONTRACTS from its initial
                // step, so whatever `warm_step` holds is a hard ceiling on the
                // accepted `α`. Capping it at the caller's `step_size` — a
                // "learning rate", 0.04–0.1 on every production path — therefore
                // caps the per-iteration KKT contraction at `1 − step_size ≥ 0.90`
                // no matter how good the direction is: the superlinear tail of a
                // Newton method is UNREACHABLE by construction, and the solve is
                // pinned to a first-order rate. That is the measured ~0.997 crawl
                // and the 10³-iteration criterion evaluations behind #2267/#2080;
                // a rate that close to 1 is not a hard problem, it is an
                // arithmetic consequence of the ceiling.
                //
                // `step_size` is the caller's CONSERVATIVE STARTING damping for a
                // cold, strongly nonlinear seed, and it stays exactly that: the
                // first trial of a fresh solve, and the reset after any rejection
                // below. What changes is that a run of clean acceptances now
                // RATCHETS the trial length geometrically toward the unit step,
                // which is what buys quadratic convergence once the iterate is in
                // its local basin. Nothing is loosened: every trial still has to
                // clear the same Armijo bound against the same objective, and a
                // trial that fails simply backtracks — a longer first trial can
                // only cost extra halvings, never accept a step the old ceiling
                // would have refused.
                //
                // This is the complement of the exact-curvature solve metric
                // installed above: getting the curvature right is what makes the
                // unit step SAFE to try, and lifting the ceiling is what lets the
                // solve actually take it.
                // True Levenberg–Marquardt gain-ratio ridge adaptation (a
                // trust-region on the RIDGE, not the step length). The gain ratio
                //   ρ = actual decrease / model-predicted decrease
                // measures how well the local quadratic model predicted the step:
                // ρ ≈ 1 ⇒ the model is trustworthy ⇒ RELAX toward Gauss–Newton;
                // ρ small ⇒ the GN step overshot the nonlinear objective ⇒ GROW the
                // ridge to bend toward gradient descent. A middle HOLD band lets
                // the ridge settle at the damping the problem needs instead of
                // oscillating — the fixed-floor version un-damped on every clean
                // step and re-overshot, so it only reduced the crawl. Predicted
                // decrease along the accepted step α·Δ is α·d − ½α²·ΔᵀHΔ, with
                // d = directional_decrease (= −gᵀΔ > 0) and, for the LM step
                // (H+λI)Δ = −g, ΔᵀHΔ = d − λ‖Δ‖² (λ the β-block ridge). Standard
                // 0.25/0.75 trust-region thresholds; factor 4 the standard
                // aggressive LM step (Marquardt / Nocedal–Wright Alg. 4.1, inverted
                // for the ridge↔radius reciprocal). Floored at the caller's ridges.
                let alpha = step.step;
                let actual = pre_step_total - step.value;
                let d_th_d = (directional_decrease
                    - globalization.lm_ridge_b * step_norm_sq)
                    .max(0.0);
                let predicted =
                    (alpha * directional_decrease - 0.5 * alpha * alpha * d_th_d).max(0.0);
                let gain_ratio = if predicted > 0.0 {
                    actual / predicted
                } else {
                    1.0
                };
                globalization.record_accepted_step(
                    step.step,
                    warm_growth,
                    step_size.max(1.0),
                    gain_ratio,
                    ridge_ext_coord,
                    ridge_beta,
                );
                self.inner_globalization_hint = Some(globalization);
            }
            if !accepted {
                // The proximal LM correction below re-solves with its own ridge
                // escalation; the next line-search regime is unrelated to this
                // iterate's accepted length or ridge, so reset and carry the
                // complete globalization state atomically. A struggling fit
                // cannot resume a re-entry with any control from the regime its
                // own line search just refused (#2267/#2762).
                globalization.reset(step_size, ridge_ext_coord, ridge_beta);
                self.inner_globalization_hint = Some(globalization);
                self.restore_mutable_state(&snapshot)?;
                let correction = ArrowProximalCorrectionOptions {
                    initial_ridge: ridge_ext_coord
                        .max(ridge_beta)
                        .max(SAE_MANIFOLD_ROW_RIDGE_FLOOR),
                    armijo_c1: SAE_MANIFOLD_ARMIJO_C1,
                    ..ArrowProximalCorrectionOptions::default()
                };
                let accepted_step = match solve_arrow_newton_step_with_proximal_correction(
                    &sys,
                    ridge_ext_coord,
                    ridge_beta,
                    pre_step_total,
                    // `sys.k` is the actual border width — factored
                    // (`factored_border_dim`) when frames are active, else
                    // `beta_dim` — so the direct/PCG mode threshold keys on the
                    // dimension the solve actually runs at.
                    &solve_options,
                    &correction,
                    |trial_delta_t, trial_delta_beta| {
                        if self.restore_mutable_state(&snapshot).is_err() {
                            return f64::INFINITY;
                        }
                        self.apply_newton_step(trial_delta_t, trial_delta_beta, 1.0)
                            .and_then(|()| {
                                self.penalized_objective_total(target, rho, analytic_penalties, 1.0)
                            })
                            .unwrap_or(f64::INFINITY)
                    },
                ) {
                    Ok(step) => step,
                    Err(err) => {
                        log::debug!(
                            "run_joint_fit_arrow_schur: proximal correction errored at \
                             iteration {outer_iteration} (gᵀΔ={directional_decrease:.3e}, \
                             floor={directional_decrease_floor:.3e}, \
                             ‖g‖={:.3e}): {err}",
                            grad_norm_sq.sqrt()
                        );
                        self.restore_mutable_state(&snapshot)?;
                        self.reclaim_arrow_assembly_workspace(&mut sys);
                        if !allow_heuristic_termination {
                            return Err(format!(
                                "SaeManifoldTerm::run_joint_fit_arrow_schur: evidence \
                                 proximal correction failed before a no-descent certificate: {err}"
                            ));
                        }
                        termination = JointFitTermination::Heuristic;
                        break;
                    }
                };
                // Same #2253 evidence-lane material floor as the Armijo gate
                // above: a sub-stall-resolution proximal decrease is the same
                // ε-harvest, and accepting it here would just move the
                // non-idempotence from the line search to the fallback.
                let proximal_material_floor = if allow_heuristic_termination {
                    0.0
                } else {
                    SAE_MANIFOLD_INNER_OBJECTIVE_STALL_REL_TOL * (1.0 + pre_step_total.abs())
                };
                if !(accepted_step.trial_objective_value.is_finite()
                    && pre_step_total - accepted_step.trial_objective_value
                        > proximal_material_floor)
                {
                    log::debug!(
                        "run_joint_fit_arrow_schur: proximal correction made no decrease at \
                         iteration {outer_iteration} (trial={:.9e}, pre={pre_step_total:.9e}, \
                         ‖g‖={:.3e})",
                        accepted_step.trial_objective_value,
                        grad_norm_sq.sqrt()
                    );
                    self.restore_mutable_state(&snapshot)?;
                    self.reclaim_arrow_assembly_workspace(&mut sys);
                    // #2762 — THE BLOCK THE NEWTON MODEL CANNOT LOOK IN.
                    //
                    // Both movers have now failed to find a decrease along a
                    // Newton direction. That is a statement about the Newton
                    // model, not about the objective: the chart-gauge orbit
                    // carries no data-fit curvature at all (it is an exact
                    // symmetry of the reconstruction), so the residual there
                    // needs a LONG step, and both movers above — Armijo
                    // backtracking and the proximal ridge escalation — can only
                    // SHORTEN one. The measurement that forced this is on
                    // `descend_gauge_orbit`: at the `zz2015` refusal the best
                    // ambient step bought `1.879e-4` against a `1.949e-4` floor
                    // (correctly a stall) while the removed span bought
                    // `1.090e-1` at a 1000x longer step.
                    //
                    // So before this loop concludes there is no strict decrease
                    // left, minimize the objective over exactly the span the
                    // convergence measure removes. It commits only a decrease
                    // clearing the same material floor as the two gates above,
                    // and a state it converges on satisfies the precondition the
                    // quotient measure's removal assumes.
                    let orbit = self.descend_gauge_orbit(
                        target,
                        rho,
                        analytic_penalties,
                        &rho.lambda_smooth_vec()?,
                        // RUN THE BLOCK TO ITS OWN STATIONARITY, not one step of
                        // it. `descend_gauge_orbit` returns at the first round
                        // that cannot commit a material decrease, so this is a
                        // bound, not a schedule — and the bound is the outer
                        // loop's OWN remaining budget, so no second budget and
                        // no constant enter. Measured on `zz2015` with a
                        // one-round schedule: each round cost a full Newton
                        // solve + line search + proximal correction to
                        // rediscover that the transverse block had nothing,
                        // which is the expensive half of an iteration spent to
                        // learn something the previous round already proved.
                        max_iter.saturating_sub(outer_iteration).max(1),
                    )?;
                    if orbit.moved() {
                        state_moved = true;
                        moved_at.get_or_insert(StateMoveSite::GaugeOrbitDescent);
                        log::debug!(
                            "run_joint_fit_arrow_schur: gauge-orbit descent recovered \
                             {:.6e} over {} round(s) at iteration {outer_iteration} \
                             (span dim {}, maxᵢ|gᵀvᵢ|={:.6e}, {} objective evaluations) \
                             where both Newton movers found none",
                            orbit.objective_decrease,
                            orbit.rounds,
                            orbit.dimension,
                            orbit.max_directional_derivative,
                            orbit.evaluations,
                        );
                        continue;
                    }
                    termination = JointFitTermination::NoStrictDecrease;
                    break;
                }
                state_moved = true;
                moved_at.get_or_insert(StateMoveSite::ProximalCorrectionStep);
                gauge_block_armed = true;
            }
            // Affine gauge canonicalization is a representation change, but the
            // decoder smoothness term is part of the optimized objective — a
            // class-(c) objective-guarded transaction (kept move discarded: a
            // pure representation change is not an evidence-map transition).
            self.run_objective_guarded_hook(target, rho, analytic_penalties, 0.0, |term| {
                term.canonicalize_affine_gauge_after_accept(Some(rho))
            })?;
            // #976 Layer-1 guard 3: after an accepted step (Armijo or proximal
            // — the rejection paths `break` above), check every atom's support
            // and answer breaches with a bounded re-seed or a terminal
            // CollapseEvent. Runs post-acceptance so it never perturbs a
            // line-search trial, and any re-seed is simply the next
            // iteration's starting state.
            //
            // QUIESCENCE near stationarity — for the BASIN-SELECTION guards
            // only. The hook taxonomy has three kinds:
            //   (a) basin-selection escapes (active-mass reseed, structural-
            //       coherence reseed): escaping a degenerate basin is OPTIONAL;
            //       near a KKT root a reseed is never a rescue — it is a state
            //       jump that spikes ‖g‖ at an objective-good iterate (the
            //       measured 2.887e8 event), invalidates the #2253 idempotence
            //       certificate, and breaks the refine loop's monotone-‖g‖
            //       accounting. Basin choice at stationarity belongs to the
            //       outer / structure search, so these stand down inside the
            //       band.
            //   (b) divergence CONTAINMENT (the decoder-norm guard here, the
            //       #2015 scale re-gauge below): interruption is MANDATORY and
            //       must NEVER be quiesced — the amplitude-gauge runaway
            //       (a→0, B→∞ at fixed a·B) is gradient-invisible, i.e. it
            //       lives exactly INSIDE the KKT band, and the iterate-scaled
            //       yardstick is self-reinforcing under a norm blow-up (the
            //       band widens with ‖B‖). Containment keyed on norms, not on
            //       ‖g‖, is the only sound trigger there.
            //   (c) representation re-gauges (unit-speed, polar, affine
            //       canonicalization): objective-guarded transactions below,
            //       unaffected here.
            let kkt_quiescent = grad_norm_sq.is_finite()
                && grad_norm_sq.sqrt()
                    <= 10.0 * SAE_MANIFOLD_INNER_GRAD_REL_TOL * self.inner_iterate_scale();
            if !kkt_quiescent {
                self.enforce_active_mass_guard(outer_iteration, Some(rho))?;
            }
            // #976 Layer-1 guard 3b (decoder arm): the gate-mass guard above is
            // blind to a dictionary whose gates stay spread but whose decoders
            // have all collapsed to ≈0 (the real-data K>1 failure that drives
            // EV→0 and the `0 → K·n` evidence-deflation abort). Catch a decoder
            // that has fallen far behind its peers and reseed it onto the
            // residual; a strict no-op for K=1. CONTAINMENT class (b): always
            // live, never quiesced.
            self.enforce_decoder_norm_guard(target, outer_iteration, rho, Some(&target_col_stats))?;
            if !kkt_quiescent {
                self.enforce_structural_coherence_guard(target, outer_iteration, rho)?;
            }
            // #2089 defense-in-depth: never grind a hopeless fit (and never let a
            // CPU watchdog SIGKILL the host while it does). Once the co-collapse
            // multi-start budget is spent, re-test the exact same typed, same-state
            // predicate that armed the reseeds. A live dictionary is never refused
            // merely because its training EV is poor; EV is telemetry here.
            if self.dictionary_cocollapse_reseeds
                >= crate::assignment::SAE_DICTIONARY_COCOLLAPSE_RESEED_BUDGET
            {
                let verdict = self.dictionary_collapse_verdict(target, rho, None)?;
                if let Some(reason) = verdict.proof_unavailable_reason() {
                    return Err(format!(
                        "SaeManifoldTerm::run_joint_fit_arrow_schur: \
                         decoder-vanishing proof unavailable after co-collapse reseeds: {reason}"
                    ));
                }
                let ev_now = verdict.explained_variance;
                let atom_count = self.k_atoms();
                if verdict.degenerate(atom_count) {
                    let decoder_norms: Vec<f64> = self
                        .atoms
                        .iter()
                        .map(|atom| {
                            atom.decoder_coefficients()
                                .iter()
                                .map(|value| value * value)
                                .sum::<f64>()
                                .sqrt()
                        })
                        .collect();
                    let arm = if verdict.all_decoders_vanished(atom_count) {
                        let max_signal = verdict
                            .decoder_vanishing
                            .max_signal_upper_bound()
                            .ok_or_else(|| {
                                "certified decoder-vanishing verdict omitted signal bounds"
                                    .to_string()
                            })?;
                        let roundoff_floor = verdict
                            .decoder_vanishing
                            .residual_roundoff_floor()
                            .ok_or_else(|| {
                                "certified decoder-vanishing verdict omitted its roundoff floor"
                                    .to_string()
                            })?;
                        let residual_scale = verdict
                            .decoder_vanishing
                            .residual_scale_upper()
                            .ok_or_else(|| {
                                "certified decoder-vanishing verdict omitted its residual scale"
                                    .to_string()
                            })?;
                        let signal_boundary = verdict
                            .decoder_vanishing
                            .signal_vanish_boundary()
                            .ok_or_else(|| {
                                "certified decoder-vanishing verdict omitted its signal boundary"
                                    .to_string()
                            })?;
                        format!(
                            "every atom's actual gated decoder signal vanished \
                             [max_signal_upper_bound={max_signal:.3e}, \
                             residual_scale_upper={residual_scale:.3e}, \
                             residual_roundoff_floor={roundoff_floor:.3e}, \
                             derived_signal_boundary={signal_boundary:.3e}]"
                        )
                    } else {
                        let evidence = verdict.structural_collapse.ok_or_else(|| {
                            "degenerate dictionary verdict omitted structural evidence"
                                .to_string()
                        })?;
                        format!(
                            "the decoder union output span collapsed structurally \
                             [decoder_span_rank={}, target_reach={:.4}, \
                             rank-matched random-subspace null={:.4}]",
                            evidence.decoder_span_rank,
                            evidence.target_reach,
                            evidence.random_subspace_null
                        )
                    };
                    return Err(format!(
                        "SaeManifoldTerm::run_joint_fit_arrow_schur: dictionary {} after {} \
                         reseed multi-starts: {arm}, so no residual \
                         structure could anchor K={} distinct charts for this input \
                         [EV telemetry={ev_now:.4}, decoder_norms={decoder_norms:.4?}]. \
                         Refusing to continue the degenerate \
                         fit. Try fewer atoms (a smaller K), a different atom_topology/assignment, \
                         more observations, or a different random_state.",
                        ProbeRefusalKind::total_co_collapse_marker(),
                        crate::assignment::SAE_DICTIONARY_COCOLLAPSE_RESEED_BUDGET,
                        atom_count,
                    ));
                }
            }
            // #2022 — enforce unit-speed (arc-length) charts IN-LOOP at this
            // accepted-outer-iteration boundary (post-acceptance, OUTSIDE the line
            // search, same cadence as the guards above). Image-frozen and paired
            // with an exact reference-Gram congruence ⇒ data fit and the declared
            // function seminorm are untouched; re-gauges t so the ARD coordinate
            // prior (which pins t→±t+c) is enforced throughout the fit, not merely
            // post-fit. SEAM: this boundary overlaps seed-audit STEP2's reseed/refit
            // hooks — reconcile ordering there (retraction after guards/reseed).
            // #2230 — the unit-speed retraction and the frame re-polar below are
            // NON-monotone boundary hooks applied OUTSIDE the line search. The
            // block-coordinate frame re-polar in particular can RAISE the penalized
            // objective (it trades reconstruction residual for decoder-smoothness
            // penalty). Left unguarded, that damage is banked by the #1026
            // keep-best and then clawed back by the incumbent restore at loop exit
            // — the accept/restore ALTERNATION that grinds for hours (the #2230
            // hang). Guard the pair the way the affine-gauge canonicalization above
            // is guarded: keep the re-gauged/re-polared state only when the SAME
            // penalized scalar the line search descends does NOT increase; else
            // revert. The canonical snapshot includes the frame U and its
            // singular-value gauge, so rejection restores the complete
            // profiled state and evidence recurrence can observe a kept polar
            // update (#2253).
            // One class-(c) transaction for the whole re-gauge triple: the
            // unit-speed retraction, the #2015 decoder-scale re-gauge (kept
            // only when it is the true flat-gauge move it is designed for),
            // and the #972/#977 frame re-polar (closed-form O(p r²) thin SVD
            // per active atom, C-coordinates held fixed — skipped on the
            // full-`B` path). A kept move is a real transition of the evidence
            // map; without the bit the wrapper could report
            // `fixed_point=true` after U moved invisibly (#2253).
            if self.run_objective_guarded_hook(target, rho, analytic_penalties, 0.0, |term| {
                term.retract_unit_speed_charts_in_loop()?;
                term.fix_decoder_scale_gauge()?;
                if term.frames_active() {
                    term.refresh_active_frames_from_data(target)
                        .map_err(|err| {
                            format!("SaeManifoldTerm::run_joint_fit_arrow_schur: {err}")
                        })?;
                }
                Ok(())
            })? {
                state_moved = true;
                moved_at.get_or_insert(StateMoveSite::FrameRefresh);
            }
            // Unconditional warranty-bank update (see the bank's declaration):
            // strictly-better penalized objective ⇒ this accepted boundary is
            // the new exit-warranty fallback, independent of any EV/coherence
            // basin preference below.
            let boundary_obj = self
                .penalized_objective_total(target, rho, analytic_penalties, 1.0)
                .unwrap_or(f64::INFINITY);
            if boundary_obj.is_finite() && boundary_obj < warranty_obj {
                warranty_obj = boundary_obj;
                warranty_state = Some(self.snapshot_mutable_state());
            }
            if let Ok(ev) = self.dictionary_reconstruction_ev(target, rho) {
                // #2230 — keep the best state on the PENALIZED OBJECTIVE first
                // (the walk's own referee) and, at (near-)equal objective, on the
                // #2081 EV-then-uniformity certificate ([`prefer_candidate_state`]).
                if self.structural_coherence_collapse_detected()?.is_none() {
                    let candidate_uniformity = self.coordinate_uniformity_aggregate();
                    let candidate_obj = boundary_obj;
                    if prefer_candidate_state(
                        candidate_obj,
                        ev,
                        candidate_uniformity,
                        best_reconstruction_obj,
                        best_reconstruction_ev,
                        best_reconstruction_uniformity,
                        SAE_MANIFOLD_INNER_OBJECTIVE_STALL_REL_TOL,
                        SAE_FINAL_EV_DEGRADATION_TOL,
                    ) {
                        best_reconstruction_ev = ev;
                        best_reconstruction_obj = candidate_obj;
                        best_reconstruction_uniformity = candidate_uniformity;
                        best_reconstruction_state = Some(self.snapshot_mutable_state());
                    }
                }
            }
            self.reclaim_arrow_assembly_workspace(&mut sys);
        }
        // #1117 — the rank-`r_k` oracle is already pinned: each rank-deficient
        // atom was reparametrized onto its data-supported subspace at fit entry
        // (`reduce_atoms_to_data_supported_rank`), so its decoder lives in the
        // reduced `r_k`-wide coordinate by construction and carries no data-null
        // component to project away. No post-loop projection is needed.
        let mut inner_incumbent_restored = false;
        if let Some(best_state) = best_reconstruction_state.as_ref()
            && best_reconstruction_obj.is_finite()
        {
            // #2230 ONE-referee restore: the incumbent is restored ONLY when the
            // final iterate's PENALIZED OBJECTIVE — the exact scalar the Armijo
            // lane descended and the outer evidence will consume — is materially
            // WORSE than the banked best. The Armijo walk is objective-monotone,
            // so this fires solely when a non-monotone boundary hook (collapse
            // reseed, gauge retraction/pin, frame refresh) damaged the state; a
            // walk that legitimately traded reconstruction EV for penalty is the
            // objective's own preference at this ρ and is KEPT, so the outer ρ
            // search sees a criterion that actually varies with ρ (the former
            // EV-keyed veto restored the same ρ-independent incumbent after
            // every probe and flattened the outer objective into the
            // #2230/#2134 restore-churn grind).
            let final_obj = self
                .penalized_objective_total(target, rho, analytic_penalties, 1.0)
                .unwrap_or(f64::INFINITY);
            let obj_scale = SAE_MANIFOLD_INNER_OBJECTIVE_STALL_REL_TOL
                * (1.0 + final_obj.abs().max(best_reconstruction_obj.abs()));
            if !(final_obj <= best_reconstruction_obj + obj_scale) {
                let final_ev = self
                    .dictionary_reconstruction_ev(target, rho)
                    .unwrap_or(f64::NAN);
                log::warn!(
                    "[#1026] restoring inner-fit incumbent: final penalized objective \
                     {final_obj:.6e} degraded past banked {best_reconstruction_obj:.6e} \
                     (EV {final_ev:.4} vs banked {best_reconstruction_ev:.4}) — \
                     non-monotone boundary-hook damage, not line-search descent"
                );
                self.restore_mutable_state(best_state)?;
                inner_incumbent_restored = true;
                state_moved = true;
                moved_at.get_or_insert(StateMoveSite::InnerIncumbentRestore);
                if self.frames_active() {
                    // #2230 — the post-restore frame re-polar is a class-(c)
                    // transaction like the in-loop triple; unguarded it
                    // perturbed the very incumbent just restored for being the
                    // best objective. Same tolerance band as the restore
                    // decision.
                    self.run_objective_guarded_hook(
                        target,
                        rho,
                        analytic_penalties,
                        obj_scale,
                        |term| {
                            term.refresh_active_frames_from_data(target).map_err(|err| {
                                format!("SaeManifoldTerm::run_joint_fit_arrow_schur: {err}")
                            })?;
                            Ok(())
                        },
                    )?;
                }
            }
        }
        // #1026 — final objective-gated alternating decoder-LSQ /
        // coordinate-reprojection polish on the converged (best) basin.
        //
        // The bounded joint Newton walk above can return an UNDER-converged decoder
        // on real long-tailed activations: a modest `max_iter` (the OLMo real-recon
        // budget is `n_iter = 32` at K = 8 on a 64-dim cross-layer cloud) truncates
        // the joint (t, β) solve before the decoder β reaches the penalized argmin
        // for the converged coordinates, and the line-search / proximal LM damping
        // shortens β steps further near a flat decoder-null direction. The result is
        // the "degenerate-basin under-recovery" #1026 documents on REAL data: the
        // dictionary reconstructs planted synthetic circles cleanly but leaves EV on
        // the table on the long-tailed real spectrum because the decoder never
        // settled, not because the chart is wrong.
        //
        // The cure reuses the SAME proven primitives the curvature-homotopy arrival
        // path already trusts (`SaeManifoldOuterObjective::run_curvature_homotopy_
        // entry_at_rho`, outer_objective.rs): a closed-form least-squares decoder
        // refit at the current coordinates/gates (the exact data-optimal decoder for
        // the fixed chart), then a per-row coordinate re-projection onto that
        // refreshed decoder (an objective-guarded block-coordinate sweep that globally projects each rank-1
        // Fourier coordinate through all companion roots), then one more decoder
        // refit at the re-projected coordinates. Coupled compact charts fail this
        // optional round transactionally instead of using a lattice.
        //
        // It is applied here (every joint fit) rather than only on the homotopy
        // arrival because the standard inner solve — the path the real-data fit
        // actually takes when the curvature walk bifurcates rather than "arrives" —
        // never reached this polish before.
        //
        // CRITICAL: the gate is the PENALIZED objective total — the exact same
        // scalar the inner Armijo line search and the outer penalized quasi-Laplace score engine
        // consume (`penalized_objective_total(target, rho, analytic_penalties, 1.0)`)
        // — NOT raw reconstruction EV. The decoder refit is an UNPENALIZED data-fit
        // least squares (and the coordinate re-projection is pure data-fit too), so a
        // round can lower the reconstruction residual while RAISING the decoder
        // smoothness penalty; gating on EV would then commit a state with a worse
        // penalized objective and corrupt the evidence comparison the outer loop runs
        // on the returned loss. Gating on the penalized total instead means a round
        // is committed ONLY when it strictly lowers the SAME objective the joint
        // Newton solve descends — so the returned penalized loss is guaranteed
        // non-increasing (it preserves the inner loop's monotonicity contract) and a
        // round that trades data-fit for penalty is correctly reverted. A truncated
        // Newton leaves the penalized objective ABOVE its decoder-β argmin, so the
        // penalized refit lowers it (the rescue); a converged decoder is already at
        // that argmin, so the first refit reproduces it, the objective does not move,
        // and the polish reverts to the bit-for-bit pre-polish state (the no-op).
        //
        // Skipped when decoder frames are active: `refit_decoder_least_squares_at_
        // current_state` writes the full-`B` decoder directly, which would desync the
        // factored frames the inner solve and `apply_newton_step` rely on; the
        // homotopy-arrival polish makes the same conservative choice.
        //
        // GATE on `max_iter > 0`: `max_iter == 0` is the documented verbatim
        // warm-start FREEZE (gam#577/#579, #850 — see
        // `converge_inner_for_undamped_logdet`), where the caller hands in a
        // seeded `(t, β)` and asks for a single factor at exactly that iterate
        // WITHOUT moving it. The polish is a decoder least-squares solve, so
        // running it on a freeze would silently overwrite the warm-started β
        // with the data-optimal refit — breaking the verbatim-reuse contract of
        // cached and typed reactive waypoint state. A freeze is by definition
        // not a convergence request, so there is no under-converged decoder to
        // rescue here.
        if max_iter > 0
            && self.sweep_blocks_to_objective_fixed_point(
                target,
                rho,
                analytic_penalties,
                allow_heuristic_termination,
            )?
        {
            state_moved = true;
            moved_at.get_or_insert(StateMoveSite::ExitBlockSweep);
        }
        // EXIT-BOUNDARY OBJECTIVE WARRANTY enforcement (#2228): the LAST gate
        // before the loss is priced. Whatever combination of non-monotone
        // movers ran above — a reseed thrown at the budget edge, a gauge hook,
        // an incumbent restore that had nothing banked, a rescue sweep whose
        // exact block solves failed transactionally on a blown state — the
        // returned state's penalized objective may not be materially worse
        // than the best state this call held at any accepted boundary (entry
        // included). A warranty restore is idempotence-safe: a settled
        // re-entry never improves on its own entry objective, so the bank
        // equals the entry state and the comparison is a no-op there.
        if let Some(bank) = warranty_state.as_ref() {
            let final_obj = self
                .penalized_objective_total(target, rho, analytic_penalties, 1.0)
                .unwrap_or(f64::INFINITY);
            let warranty_tol = SAE_MANIFOLD_INNER_OBJECTIVE_STALL_REL_TOL
                * (1.0 + final_obj.abs().max(warranty_obj.abs()));
            if !(final_obj <= warranty_obj + warranty_tol) {
                log::warn!(
                    "[#2228] exit warranty: final penalized objective {final_obj:.6e} degraded \
                     past the best accepted boundary {warranty_obj:.6e}; restoring the banked \
                     state (non-monotone boundary-mover damage leaked to the exit)"
                );
                self.restore_mutable_state(bank)?;
                state_moved = true;
                moved_at.get_or_insert(StateMoveSite::ExitWarrantyRestore);
                // A warranty restore means the walk was NOT settled; any
                // cross-call incumbent streak is void.
                self.best_fit_incumbent = None;
            }
        }
        // Track an exact recurrence of the OBJECTIVE-keyed in-call restore.
        // This is convergence evidence only; it is never a cross-ρ state bank
        // and is never installed after the outer certificate. A final polish
        // that moved the state breaks the streak.
        let exact_objective_incumbent_restored = inner_incumbent_restored
            && best_reconstruction_state
                .as_ref()
                .is_some_and(|state| self.matches_mutable_state(state));
        if exact_objective_incumbent_restored {
            let consecutive_inner_restores = self
                .best_fit_incumbent
                .as_ref()
                .filter(|prior| self.matches_mutable_state(&prior.state))
                .map_or(1, |prior| {
                    prior.consecutive_inner_restores.saturating_add(1)
                });
            self.best_fit_incumbent = Some(SaeFitIncumbent {
                state: self.snapshot_mutable_state(),
                consecutive_inner_restores,
            });
        } else {
            self.best_fit_incumbent = None;
        }
        // ρ is owned by the outer engine and unchanged here; just return the
        // converged inner loss at the fixed ρ. Drop the faer-sequential guard
        // explicitly (the idiomatic "use" that satisfies `unused_variables`);
        // faer's process-global parallelism is restored to its prior policy for
        // any work the outer engine runs after this inner fit returns.
        let loss = self.loss(target, rho)?;
        drop(faer_sequential_inner_fit);
        Ok(JointFitOutcome {
            loss,
            termination,
            state_moved,
            moved_at,
        })
    }

    /// Class-(c) hook primitive — the OBJECTIVE-GUARDED TRANSACTION.
    ///
    /// Every representation re-gauge at an accepted-iterate boundary (affine
    /// canonicalization, unit-speed retraction, scale re-gauge, frame
    /// re-polar) must obey one contract: run the hook, and keep its result
    /// ONLY when the penalized objective — the single scalar the line search
    /// descends and the evidence ranks — does not increase past
    /// `allowed_increase`; otherwise restore the pre-hook state bit-for-bit.
    /// This was hand-rolled inline at three sites with drift between copies;
    /// it is now one primitive. Returns whether a KEPT hook actually moved the
    /// state (`false` when reverted or a no-op) so callers can maintain the
    /// #2253 idempotence bookkeeping.
    pub(crate) fn run_objective_guarded_hook<F>(
        &mut self,
        target: ArrayView2<'_, f64>,
        rho: &SaeManifoldRho,
        analytic_penalties: Option<&AnalyticPenaltyRegistry>,
        allowed_increase: f64,
        hook: F,
    ) -> Result<bool, String>
    where
        F: FnOnce(&mut Self) -> Result<(), String>,
    {
        let pre_obj = self.penalized_objective_total(target, rho, analytic_penalties, 1.0)?;
        let pre_state = self.snapshot_mutable_state();
        hook(self)?;
        let post_obj = self
            .penalized_objective_total(target, rho, analytic_penalties, 1.0)
            .unwrap_or(f64::INFINITY);
        if !(post_obj.is_finite() && post_obj <= pre_obj + allowed_increase) {
            self.restore_mutable_state(&pre_state)?;
            return Ok(false);
        }
        Ok(!self.matches_mutable_state(&pre_state))
    }

    /// Deterministic alternating block-sweep engine: decoder-LSQ →
    /// per-row coordinate reprojection (global companion-matrix solves) →
    /// decoder-LSQ, repeated to its penalized-objective fixed point.
    ///
    /// Each round is committed ONLY on a strict decrease of
    /// `penalized_objective_total` (the one scalar the whole inner stack
    /// prices), else the pre-round state is restored bit-for-bit and the loop
    /// stops — so the sweep map is monotone, deterministic given the seed, and
    /// can never worsen the state. FRAMES-AWARE: on a frames-active fit each
    /// decoder-LSQ is followed by the closed-form frame re-polar
    /// (`refresh_active_frames_from_data` — thin SVD + `B ← (BU)Uᵀ`
    /// re-projection, the same primitives frame activation itself uses), so
    /// the factored border stays consistent with the refreshed decoder; the
    /// whole round is one transaction, so a re-projection that loses the LSQ
    /// optimality reverts and the sweep degrades to a no-op, never worse.
    /// This closed the wide-p coverage hole: frames auto-activate at p ≥ 12,
    /// so the historical frames skip silently excluded the sweep engine from
    /// most REAL fits — including the wide-p K=4 fixture whose 640-iteration
    /// walk diverges to ‖g‖ ≈ 3e27 with no LSQ reset on the path. Callers
    /// must not invoke this under the `max_iter == 0` freeze contract (a
    /// decoder refit would overwrite the warm-started β).
    ///
    /// This is the stage-4 primary engine (#2228): at fixed gates the decoder
    /// block is an exactly solvable penalized linear LS and the coordinate
    /// block decouples per row with globally enumerable solutions, so sweeps
    /// do in O(1) exact block solves what the majorized joint Newton needs
    /// O(10²–10³) linear-rate iterations for. Returns whether any round was
    /// committed.
    /// `discovery_lane` — two lane-dependent behaviors, both consequences of
    /// the #2253 idempotence certificate (a re-entry at the converged state
    /// must recur EXACTLY on evidence lanes):
    ///
    /// 1. The logit-block ownership rounds run on discovery lanes only. The
    ///    #2082 anchor is a CONSTANT nudge, not a fixed-point iteration —
    ///    non-idempotent by design.
    /// 2. The commit floor is MATERIAL on evidence lanes
    ///    (`SAE_MANIFOLD_INNER_OBJECTIVE_STALL_FRACTION` = 1e-4 of scale)
    ///    versus fine on discovery lanes (`…_STALL_REL_TOL` = 1e-8). Measured
    ///    A/B pair behind this: a cold or blown entry state's decoder-LSQ
    ///    clears the material floor by orders of magnitude (the wide-p
    ///    ‖g‖≈3e27 divergence kill NEEDS the entry sweep — removing it
    ///    restored the baseline blow-up bit-for-bit), while the ε-level
    ///    objective drift injected per evidence re-entry by the entry hooks'
    ///    per-assembly gate freezes harvests only ~1e-8·scale decreases —
    ///    each a fresh state move that made the inner map non-idempotent
    ///    (tier-0 K=2 fixtures refused at 512 granted iterations). The
    ///    material floor admits the rescue and rejects the harvest.
    pub(crate) fn sweep_blocks_to_objective_fixed_point(
        &mut self,
        target: ArrayView2<'_, f64>,
        rho: &SaeManifoldRho,
        analytic_penalties: Option<&AnalyticPenaltyRegistry>,
        discovery_lane: bool,
    ) -> Result<bool, String> {
        let mut best_objective =
            self.penalized_objective_total(target, rho, analytic_penalties, 1.0)?;
        if !best_objective.is_finite() {
            return Ok(false);
        }
        let floor_rel = if discovery_lane {
            SAE_MANIFOLD_INNER_OBJECTIVE_STALL_REL_TOL
        } else {
            SAE_MANIFOLD_INNER_OBJECTIVE_STALL_FRACTION
        };
        let frames = self.frames_active();
        let mut moved = false;
        loop {
            let snapshot = self.snapshot_mutable_state();
            let round = self
                .refit_decoder_least_squares_at_current_state(target, Some(rho))
                .and_then(|()| {
                    if frames {
                        self.refresh_active_frames_from_data(target)
                            .map_err(|err| format!("sweep frame re-polar: {err}"))?;
                    }
                    Ok(())
                })
                .and_then(|()| self.seed_coords_by_decoder_projection(target))
                .and_then(|()| self.refit_decoder_least_squares_at_current_state(target, Some(rho)))
                .and_then(|()| {
                    if frames {
                        self.refresh_active_frames_from_data(target)
                            .map_err(|err| format!("sweep frame re-polar: {err}"))?;
                    }
                    Ok(())
                })
                .and_then(|()| {
                    self.penalized_objective_total(target, rho, analytic_penalties, 1.0)
                });
            // Commit only on a STRICT decrease of the penalized objective,
            // scaled by the objective magnitude so the test is meaningful at
            // any loss scale. Anything else (already-converged decoder, a
            // round that traded data-fit for penalty, or a refit/projection
            // failure) restores the pre-round state and stops.
            let accept_floor = floor_rel * (1.0 + best_objective.abs());
            match round {
                Ok(value) if value.is_finite() && value < best_objective - accept_floor => {
                    best_objective = value;
                    moved = true;
                }
                _ => {
                    self.restore_mutable_state(&snapshot)?;
                    break;
                }
            }
        }
        // LOGIT-BLOCK stage (the third block of the engine, #2082 primitive):
        // once the (t, B) rounds reach their fixed point, attempt a bounded
        // number of gate-ownership rounds — the soft row-ownership anchor
        // (no-op at K=1) followed by the decoder refit the anchor contract
        // requires, then a fresh (t, B) chain — each as its OWN
        // strict-decrease transaction, so a rejected gate move can never claw
        // back committed (t, B) progress. The routing update moves gates toward
        // the decoder that best explains each row, then the decoder and
        // coordinate blocks are refit. The shared-objective gate makes the
        // sweep monotone, and the bound (2) exists only because each committed
        // anchor changes the ownership pattern it would recompute — two dry
        // rounds prove the pattern is stable. Discovery lanes only (see the
        // `discovery_lane` doc): evidence re-entries must be idempotent.
        for _ in 0..(if discovery_lane { 2 } else { 0 }) {
            let snapshot = self.snapshot_mutable_state();
            let round = self
                .anchor_logits_to_residual_ownership(target)
                .and_then(|()| self.refit_decoder_least_squares_at_current_state(target, Some(rho)))
                .and_then(|()| {
                    if frames {
                        self.refresh_active_frames_from_data(target)
                            .map_err(|err| format!("sweep frame re-polar: {err}"))?;
                    }
                    Ok(())
                })
                .and_then(|()| self.seed_coords_by_decoder_projection(target))
                .and_then(|()| self.refit_decoder_least_squares_at_current_state(target, Some(rho)))
                .and_then(|()| {
                    self.penalized_objective_total(target, rho, analytic_penalties, 1.0)
                });
            let accept_floor = floor_rel * (1.0 + best_objective.abs());
            match round {
                Ok(value) if value.is_finite() && value < best_objective - accept_floor => {
                    best_objective = value;
                    moved = true;
                }
                _ => {
                    self.restore_mutable_state(&snapshot)?;
                    break;
                }
            }
        }
        Ok(moved)
    }

    /// Allocate one zero `(M_k × M_k)` Gram accumulator per atom for the
    /// chunk-aware decoder identifiability audit.
    pub(crate) fn empty_decoder_gram_accumulator(&self) -> Vec<Array2<f64>> {
        self.atoms
            .iter()
            .map(|atom| {
                let m = atom.basis_size();
                Array2::<f64>::zeros((m, m))
            })
            .collect()
    }

    /// Accumulate this term's (chunk's) contribution to the per-atom weighted
    /// design Gram `G_k += D_kᵀ D_k`, with `D_k = diag(a_·k)·Φ_k`.
    ///
    /// `grams[k]` must be `(M_k × M_k)`. Streaming callers invoke this once per
    /// chunk against the freshly materialized chunk term; the full-batch path
    /// invokes it once against `self`. The Gram is symmetric and channel-free
    /// (the `p`-fold output replication is carried by the `⊗ I_p` Kronecker
    /// structure, so it adds no rank information), so accumulating `Φ` weighted
    /// by the per-row assignment exactly reproduces the data-fit decoder block
    /// curvature `G_k` that `assemble_arrow_schur` installs.
    pub(crate) fn accumulate_decoder_gram(&self, grams: &mut [Array2<f64>]) -> Result<(), String> {
        let n = self.n_obs();
        let assignments = self.assignment.assignments();
        // Each atom's Gram `G_k = Φ_kᵀ diag(a_k²) Φ_k` is an independent
        // weighted cross-product over the N rows — the canonical `xt_diag_x`
        // shape, and independent across the per-atom axis. This feeds a
        // tolerance-based identifiability RANK decision (not a fitted quantity),
        // so the device path's accumulation order is admissible.
        //
        // Spread the atoms across EVERY device via `gpu::pool::scatter_batched`;
        // each device tile computes its atoms' Grams through the size-gated
        // `try_fast_xt_diag_x` shim. A device-free or wholly sub-threshold shape
        // uses exact CPU rank-1 accumulation; after admission, a device decline
        // or backend failure is returned to the caller.
        let weights: Vec<Array1<f64>> = (0..self.atoms.len())
            .map(|atom_idx| {
                let col = assignments.column(atom_idx);
                col.mapv(|a| a * a)
            })
            .collect();

        // CPU per-atom contribution, used for fallback and as the whole path
        // when no GPU runtime is present.
        let cpu_one = |atom_idx: usize, gram: &mut Array2<f64>| {
            let atom = &self.atoms[atom_idx];
            let m = atom.basis_size();
            let assign_col = assignments.column(atom_idx);
            let mut weighted = vec![0.0_f64; m];
            for row in 0..n {
                let a_k = assign_col[row];
                if a_k == 0.0 {
                    continue;
                }
                for col in 0..m {
                    weighted[col] = a_k * atom.basis_values[[row, col]];
                }
                for i in 0..m {
                    let wi = weighted[i];
                    if wi == 0.0 {
                        continue;
                    }
                    for j in 0..m {
                        gram[[i, j]] += wi * weighted[j];
                    }
                }
            }
        };

        // Size gate BEFORE the device probe (startup-tax ordering fix): the
        // device path runs one `XtDiagX { n, p: m_k }` per atom, and every
        // reachable dispatch policy refuses that op below
        // `MIN_CALIBRATABLE_GEMM_FLOPS` — so when even the LARGEST per-atom
        // Gram is under the floor, every device attempt would decline and the
        // scatter would reproduce the CPU path exactly. Take the CPU path
        // directly without resolving `GpuRuntime` (whose first resolution
        // creates a CUDA primary context on every GPU). Shapes with at least
        // one admissible atom probe and scatter exactly as before.
        let max_atom_gram_flops: u128 = self
            .atoms
            .iter()
            .map(|atom| {
                let m = atom.basis_size() as u128;
                2u128 * (n as u128) * m * m
            })
            .max()
            .unwrap_or(0);
        let rt = if max_atom_gram_flops < crate::gpu::GpuDispatchPolicy::MIN_CALIBRATABLE_GEMM_FLOPS
        {
            None
        } else {
            crate::gpu::device_runtime::GpuRuntime::resolve(self.gpu_policy)
                .map_err(|error| format!("decoder-Gram CUDA admission failed: {error}"))?
        };
        match rt {
            None => {
                for atom_idx in 0..self.atoms.len() {
                    if self.atoms[atom_idx].basis_size() == 0 {
                        continue;
                    }
                    cpu_one(atom_idx, &mut grams[atom_idx]);
                }
            }
            Some(rt) => {
                // Device tiles produce each owned atom's Gram into a side channel
                // keyed by atom index; splice them back into `grams` (with `+=`
                // accumulation) after the scatter. A declined atom is recorded
                // so the admitted route can fail without laundering it as CPU work.
                let mut items: Vec<usize> = (0..self.atoms.len())
                    .filter(|&i| self.atoms[i].basis_size() > 0)
                    .collect();
                let device_grams: std::sync::Mutex<Vec<(usize, Array2<f64>)>> =
                    std::sync::Mutex::new(Vec::with_capacity(items.len()));
                let declined: std::sync::Mutex<Vec<usize>> = std::sync::Mutex::new(Vec::new());
                let atoms_ref = &self.atoms;
                let weights_ref = &weights;
                let ok = crate::gpu::pool::scatter_batched(rt, &mut items, |_, slice| {
                    for &atom_idx in slice.iter() {
                        let phi = atoms_ref[atom_idx].basis_values.view();
                        let w = weights_ref[atom_idx].view();
                        match crate::gpu::linalg_dispatch::try_fast_xt_diag_x(phi, w) {
                            Some(g) => device_grams
                                .lock()
                                .expect("device_grams mutex poisoned")
                                .push((atom_idx, g)),
                            None => declined
                                .lock()
                                .expect("declined mutex poisoned")
                                .push(atom_idx),
                        }
                    }
                    Some(())
                });
                match ok {
                    Some(()) => {
                        for (atom_idx, g) in device_grams
                            .into_inner()
                            .expect("device_grams mutex poisoned")
                        {
                            grams[atom_idx] += &g;
                        }
                        let declined = declined.into_inner().expect("declined mutex poisoned");
                        if !declined.is_empty() {
                            return Err(format!(
                                "decoder-Gram device path declined admitted atoms {declined:?}"
                            ));
                        }
                    }
                    None => {
                        return Err(
                            "decoder-Gram device scatter declined after CUDA admission".to_string()
                        );
                    }
                }
            }
        }
        Ok(())
    }

    /// Decide rank-deficiency of each accumulated decoder Gram and surface the
    /// same fatal / INFO contract as the former pivoted-QR audit.
    pub(crate) fn finalize_decoder_identifiability_audit(
        &self,
        grams: &[Array2<f64>],
        n_total: usize,
    ) -> Result<(), String> {
        // #1026/#1522 — in an OVER-COMPLETE dictionary (K chosen larger than the
        // number of real features, the explicit 32K-atom regime) surplus atoms
        // SHOULD die: a dead atom's assignment weights all vanish, so its weighted
        // design `D_k` is rank-0 and its decoder Gram `G_k = D_kᵀD_k` is the zero
        // matrix. A rank-0 block is just the EXTREME of rank-deficiency, and the
        // exact same Arrow-Schur ridge that regularises a partially-deficient
        // block (`solve_with_lm_escalation_inner` + the reduced-Schur PD floor)
        // parks a fully-deficient one: `H_block → ridge·I` with a zero data
        // gradient, so `β_k → 0` — a cleanly dead atom contributing nothing to the
        // reconstruction. Treating a single dead atom among many as a FATAL audit
        // failure (the old policy) is exactly what made the over-complete fit
        // unfittable: the seed died, the continuation spine re-failed identically,
        // and the outer loop livelocked. So rank-0 now takes the same ridge-park
        // INFO path as any other rank deficiency. The genuine pathology — a design
        // with NO identifiable signal anywhere — is still caught: if EVERY atom is
        // rank-0 the whole dictionary is unidentifiable and we fail loudly.
        let mut any_identifiable = false;
        let mut audited_atoms = 0usize;
        for (atom_idx, atom) in self.atoms.iter().enumerate() {
            let m = atom.basis_size();
            if m == 0 {
                continue;
            }
            audited_atoms += 1;
            let rank = gam_identifiability::audit::rank_of_gram(&grams[atom_idx], n_total)
                .map_err(|e| {
                    format!(
                        "SaeManifoldTerm: pre-fit decoder audit (atom '{}'): \
                         Gram eigendecomposition failed: {e}",
                        atom.name,
                    )
                })?;
            if rank > 0 {
                any_identifiable = true;
            }
            if rank < m {
                let dropped = m - rank;
                log::info!(
                    "[SAE-AUDIT] decoder atom '{}' weighted design is rank-deficient \
                     (rank={rank}/{m}, {dropped} weakly-identified column(s), n={n_total}); the \
                     Arrow-Schur ridge will regularise the deficient directions{}",
                    atom.name,
                    if rank == 0 {
                        " (atom is fully unweighted — parked dead, β_k → 0)"
                    } else {
                        ""
                    },
                );
            }
        }
        if audited_atoms > 0 && !any_identifiable {
            return Err(format!(
                "SaeManifoldTerm: pre-fit identifiability audit: ALL {audited_atoms} decoder \
                 atoms have rank-0 weighted design (n={n_total}); the entire dictionary is \
                 unidentifiable — every atom's assignment weights vanish or every basis is \
                 degenerate, so the joint Arrow-Schur Newton system is singular with no \
                 ridge-recoverable signal"
            ));
        }
        Ok(())
    }

    /// Synthesize the monomial-patch basis evaluator for a streaming chunk when
    /// the atom was built from a precomputed design matrix and therefore carries
    /// no `basis_evaluator` (issue #1801).
    ///
    /// The flat monomial-patch families — [`SaeAtomBasisKind::EuclideanPatch`],
    /// [`SaeAtomBasisKind::Linear`], and [`SaeAtomBasisKind::Poincare`] — all
    /// share the deterministic [`crate::basis::EuclideanPatchEvaluator`] design:
    /// `Φ(t)` is the set of monomials of total degree ≤ `max_degree` in the
    /// atom's `latent_dim` coordinates (the Poincaré patch differs only in its
    /// intrinsic penalty, not in `Φ`). We recover `max_degree` by searching
    /// upward for the degree whose monomial count equals the atom's
    /// `basis_size()`; the count is strictly increasing in the degree, so the
    /// match is unique. Returns `None` when the basis kind has no well-defined
    /// monomial evaluator (e.g. `Duchon`, which needs its kernel centers) or when
    /// no degree reproduces the atom's width, so the caller keeps the original
    /// "no basis evaluator" error rather than guessing.
    fn synthesize_monomial_patch_evaluator(
        atom: &SaeManifoldAtom,
    ) -> Option<Arc<dyn SaeBasisEvaluator>> {
        match atom.basis_kind() {
            SaeAtomBasisKind::EuclideanPatch
            | SaeAtomBasisKind::Linear
            | SaeAtomBasisKind::Poincare => {}
            _ => return None,
        }
        let latent_dim = atom.latent_dim();
        let target = atom.basis_size();
        for degree in 0..=target {
            if gam_terms::basis::monomial_exponents(latent_dim, degree).len() == target {
                return crate::basis::EuclideanPatchEvaluator::new(latent_dim, degree)
                    .ok()
                    .map(|ev| Arc::new(ev) as Arc<dyn SaeBasisEvaluator>);
            }
        }
        None
    }

    /// Materialize a row-chunk `[start, end)` of this term as a standalone
    /// `SaeManifoldTerm`, recomputing `(basis_values, basis_jacobian)` on demand
    /// from the persisted decoder + atom geometry and the caller-supplied
    /// per-chunk `(logits, coords)`.
    ///
    /// The streaming joint fit NEVER persists the `(N × M)` basis or `(N × K)`
    /// logit buffers. Instead, for each chunk the caller re-seeds the chunk's
    /// latent state (the SAE PCA seed restricted to the chunk's `Z` rows for the
    /// coordinates, and the chunk's gating logits) and this constructor rebuilds
    /// a small `n_chunk`-row term whose atoms share the global decoder
    /// coefficients (`B_k`), smoothness penalties, and basis evaluators with
    /// `self`. Each atom's basis is re-evaluated at the chunk coordinates via
    /// its `basis_evaluator`, so the chunk term is exactly the restriction of
    /// the global model to those rows.
    ///
    /// Errors if any atom lacks a basis evaluator (a streaming fit must be able
    /// to re-evaluate `Φ(t)` at the per-chunk coordinates) or if the supplied
    /// shapes disagree with the term's atom layout.
    /// The resident term's frozen routing (#1033) restricted to the contiguous
    /// row range `[start, end)`, or `None` when routing is not frozen. Passed to
    /// [`Self::materialize_chunk`] so a chunk's gates read the same frozen logits
    /// as the dense path instead of thawing back to the free logits.
    pub(crate) fn chunk_frozen_logits(&self, start: usize, end: usize) -> Option<Array2<f64>> {
        self.assignment
            .frozen_logits
            .as_ref()
            .map(|f| f.slice(ndarray::s![start..end, ..]).to_owned())
    }

    pub fn materialize_chunk(
        &self,
        chunk_logits: Array2<f64>,
        chunk_coords: Vec<Array2<f64>>,
        chunk_frozen_logits: Option<Array2<f64>>,
    ) -> Result<SaeManifoldTerm, String> {
        let k_atoms = self.k_atoms();
        if chunk_logits.ncols() != k_atoms {
            return Err(format!(
                "SaeManifoldTerm::materialize_chunk: chunk_logits has {} cols but K={k_atoms}",
                chunk_logits.ncols()
            ));
        }
        if chunk_coords.len() != k_atoms {
            return Err(format!(
                "SaeManifoldTerm::materialize_chunk: chunk_coords has {} atoms but K={k_atoms}",
                chunk_coords.len()
            ));
        }
        let n_chunk = chunk_logits.nrows();
        let mut atoms = Vec::with_capacity(k_atoms);
        for (atom_idx, atom) in self.atoms.iter().enumerate() {
            let coords = &chunk_coords[atom_idx];
            if coords.nrows() != n_chunk || coords.ncols() != atom.latent_dim() {
                return Err(format!(
                    "SaeManifoldTerm::materialize_chunk: atom {atom_idx} coords shape {:?} != ({n_chunk}, {})",
                    coords.dim(),
                    atom.latent_dim()
                ));
            }
            // A streaming fit must re-evaluate Φ(t) at each chunk's coordinates.
            // Atoms carried from precomputed design matrices via
            // `SaeManifoldAtom::new` hold `basis_evaluator = None`; for the flat
            // monomial-patch families we synthesize the deterministic evaluator
            // from the atom geometry (issue #1801) instead of aborting the fit.
            let synthesized_evaluator = match atom.basis_evaluator.as_ref() {
                Some(_) => None,
                None => Self::synthesize_monomial_patch_evaluator(atom),
            };
            let evaluator = match atom
                .basis_evaluator
                .as_ref()
                .or(synthesized_evaluator.as_ref())
            {
                Some(evaluator) => evaluator,
                None => {
                    return Err(format!(
                        "SaeManifoldTerm::materialize_chunk: atom '{}' has no basis evaluator; a \
                         streaming fit must re-evaluate Φ(t) at each chunk's coordinates",
                        atom.name
                    ));
                }
            };
            let (phi, jet) = evaluator.evaluate(coords.view())?;
            let m = atom.basis_size();
            if phi.dim() != (n_chunk, m) {
                return Err(format!(
                    "SaeManifoldTerm::materialize_chunk: atom '{}' evaluator returned Φ {:?}, expected ({n_chunk}, {m})",
                    atom.name,
                    phi.dim()
                ));
            }
            if jet.dim() != (n_chunk, m, atom.latent_dim()) {
                return Err(format!(
                    "SaeManifoldTerm::materialize_chunk: atom '{}' evaluator returned jet {:?}, expected ({n_chunk}, {m}, {})",
                    atom.name,
                    jet.dim(),
                    atom.latent_dim()
                ));
            }
            // Every chunk uses the identical frozen reference-function Gram as
            // the full objective. Re-estimating a chunk-specific metric would
            // change both the quadratic and its Laplace normalizer.
            let mut chunk_atom = SaeManifoldAtom::new_with_provided_function_gram(
                atom.name.clone(),
                atom.basis_kind().clone(),
                atom.latent_dim(),
                phi,
                jet,
                atom.decoder_coefficients().clone(),
                atom.smooth_penalty().clone(),
            )?;
            // Carry the atom's own evaluator when it has one; otherwise seed the
            // chunk with the synthesized monomial-patch evaluator (#1801) so the
            // downstream streaming assembly re-evaluates Φ(t) exactly as the
            // non-precomputed path does.
            chunk_atom.basis_evaluator = atom
                .basis_evaluator
                .clone()
                .or_else(|| synthesized_evaluator.clone());
            chunk_atom.basis_second_jet = atom.basis_second_jet.clone();
            // #972 / #977 T1: carry the active Grassmann frame onto the chunk
            // atom so the streaming per-chunk assembly uses the SAME factored
            // border layout as the dense path. Without this the chunk would
            // default to the full-`B` path and the streaming REML log-det would
            // be taken over a different (larger) β block than the dense one,
            // breaking the streaming↔dense log-det agreement (#847). The
            // decoder is unchanged, so the frame stays consistent with `B_k`.
            chunk_atom.decoder_frame = atom.decoder_frame.clone();
            atoms.push(chunk_atom);
        }
        // Rebuild the assignment from the chunk's logits + coords, preserving
        // each atom's latent manifold and the global assignment mode.
        let coord_values: Vec<LatentCoordValues> = chunk_coords
            .iter()
            .zip(self.assignment.coords.iter())
            .map(|(c, src)| {
                LatentCoordValues::from_matrix_with_manifold(
                    c.view(),
                    LatentIdMode::None,
                    src.manifold().clone(),
                )
            })
            .collect();
        let mut assignment =
            SaeAssignment::with_mode(chunk_logits, coord_values, self.assignment.mode)?;
        // Carry the assignment-defining metadata that `with_mode` resets to
        // defaults, so the chunk computes the SAME model as the resident term.
        // Without this the streaming/chunked path silently diverges from the dense
        // path: ungated atoms revert to their raw-logit gate instead of the fixed
        // unit gate (#1026), frozen routing thaws back to the free logits (#1033),
        // and the per-fit truncated-ordered Beta--Bernoulli α override is dropped (#1777). All three
        // change the forward gate map, hence the loss, gradient, and log-det.
        //   * `ungated` is per-atom (length K) — row-independent.
        //   * `ordered_beta_bernoulli_alpha_override` is scalar — row-independent.
        //   * frozen routing is per-row (n×K) — the caller slices it to the chunk's
        //     rows and passes it as `chunk_frozen_logits`.
        assignment.ungated = self.assignment.ungated.clone();
        assignment.ordered_beta_bernoulli_alpha_override =
            self.assignment.ordered_beta_bernoulli_alpha_override;
        if let Some(frozen) = chunk_frozen_logits {
            if frozen.dim() != (n_chunk, k_atoms) {
                return Err(format!(
                    "SaeManifoldTerm::materialize_chunk: chunk_frozen_logits shape {:?} != ({n_chunk}, {k_atoms})",
                    frozen.dim()
                ));
            }
            assignment.frozen_logits = Some(frozen);
        }
        let mut term = SaeManifoldTerm::new(atoms, assignment)?;
        // #2532 — the chunk plans against the SAME environment reading as the fit
        // it belongs to. `new` samples afresh, which would let a chunk choose a
        // different evidence operator than its parent purely because the box got
        // busy between materializations.
        term.host_available_bytes = self.host_available_bytes;
        // The temperature schedule is global outer state; the chunk term is
        // assembled at the schedule's current temperature, which the caller
        // already baked into `self.assignment.mode` before materializing.
        term.temperature_schedule = self.temperature_schedule.clone();
        // #1801 — when a streaming fit has frozen the collapse-prevention gates
        // GLOBALLY (from the full resident routing), carry them onto the chunk and
        // mark it so its assembly SKIPS the per-chunk gate refresh. This is the
        // gate analogue of the decoder-frame carry above: the gates' per-pair
        // strength `μ_jk` inverts near-singular small-minibatch design Grams, so a
        // per-chunk refresh would make the fit `chunk_size`-dependent.
        if self.streaming_gates_frozen {
            term.decoder_repulsion_gate = self.decoder_repulsion_gate.clone();
            term.barrier_coactivation_gate = self.barrier_coactivation_gate.clone();
            // #2343 — the amplitude barrier's frozen turn-on radius `ε²` is a global
            // dictionary property (a function of the SHARED decoders `B_k`, not the
            // chunk routing), so carrying it onto the chunk keeps its assembly from
            // needing a per-chunk refresh, exactly like the gates above.
            term.amplitude_barrier_gate = self.amplitude_barrier_gate;
            term.streaming_gates_frozen = true;
        }
        Ok(term)
    }

}

/// Effective output rank `R = dim(⋃_k col(Q_k))` — the dimension actually spanned by
/// the atoms' orthonormal decoder output frames `Q_k` (`certificate_output_frame`),
/// as the numeric rank of the HORIZONTALLY-STACKED frames at the shared frame-rank
/// cutoff [`crate::frames::SAE_FRAME_RANK_CUTOFF`]. Caps the structural-coherence
/// overcomplete gate: a dictionary with `K > R` atoms cannot give each atom a private
/// output direction, so output-frame sharing there is FORCED (benign over-completeness)
/// rather than evidence of a redundant atom. `p` is the output dimension (every frame
/// is `p × r_k`); an SVD failure degrades to `p` (the maximal meaningful rank) so a
/// numerical hiccup never spuriously DISABLES the guard.
/// #2132 — does the LEADING residual direction carry signal above the measured
/// noise floor? `energies` are the residual output-Gram eigenvalues (per-direction
/// residual energies, unordered). The robust noise level is their MEDIAN (real
/// uncovered directions are sparse spikes that do not move it); the leading
/// direction carries signal when its energy exceeds `median · log2(#dirs)` — the
/// Bonferroni expected-one-false-alarm bound over the `#dirs` directions (the
/// energy of the largest of `#dirs` noise directions in units of the median grows
/// only logarithmically), guarded below by a numerical-zero fraction of the peak.
/// This is the same measured-floor shape as the #2243 spectral bandwidth. The test
/// errs toward RESEED (a false "signal present" only wastes a budget-bounded
/// reseed; a false "noise" would wrongly demote a real atom), so the log2 factor is
/// deliberately conservative rather than an MP-exact edge.
fn leading_direction_above_noise_floor(energies: &[f64]) -> bool {
    if energies.is_empty() {
        return false;
    }
    let mut sorted: Vec<f64> = energies.to_vec();
    sorted.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
    let Some(&peak) = sorted.last() else {
        return false;
    };
    if !(peak > 0.0) {
        return false;
    }
    let m = sorted.len();
    // Robust noise-scale estimate for the Bonferroni floor. The MEDIAN reads the
    // noise level only while FEWER than half the directions carry signal (its 50%
    // breakdown point); a co-collapsed dictionary leaves a residual whose real
    // structure can span up to HALF the — often very few — output directions. Two
    // unequal circles uncovered in p=4 channels give a residual Gram spectrum
    // ≈[7.7, 7.7, 48, 48]: the median (27.8) is pulled onto circle A's own energy
    // and `median·log2(4)=55.7` swallows the peak (48), so the gate reads genuine
    // two-circle signal as pure noise and NOTHING reseeds (#2132). Estimate the
    // noise subspace from the LOWER QUARTILE instead: it tolerates signal in up to
    // ~3/4 of the directions, yet — unlike the raw minimum — stays robust to a lone
    // spuriously-small (rank-deficient) eigenvalue. Under pure noise the quartile
    // still tracks the flat bulk, so the `·log2(#dirs)` Bonferroni multiple keeps a
    // spike-free spectrum below the floor exactly as before.
    let noise_scale = sorted[(((m - 1) as f64) * 0.25).round() as usize];
    let floor = (peak * 1e-12).max(noise_scale * (m as f64).max(2.0).log2());
    peak > floor
}

/// Numerical rank of the union of the per-atom decoder output frames inside the
/// `p`-dimensional output space. `pub(crate)` since #2756 so a witness can state
/// the saturation `R_dec == p` that makes the structural-collapse comparison
/// vacuous, instead of inferring it from the verdict it is testing.
pub(crate) fn union_output_frame_rank(frames: &[Array2<f64>], p: usize) -> usize {
    let total_cols: usize = frames.iter().map(|q| q.ncols()).sum();
    if p == 0 || total_cols == 0 {
        return 0;
    }
    let mut stacked = Array2::<f64>::zeros((p, total_cols));
    let mut col = 0usize;
    for q in frames {
        let m = q.ncols();
        if m == 0 {
            continue;
        }
        // Frames are `p × r_k`; guard a stray row-count mismatch rather than panic.
        if q.nrows() != p {
            return p;
        }
        for qc in 0..m {
            for row in 0..p {
                stacked[[row, col + qc]] = q[[row, qc]];
            }
        }
        col += m;
    }
    let sv = match stacked.svd(false, false) {
        Ok((_, sv, _)) => sv,
        Err(_) => return p,
    };
    let max_sv = sv.iter().copied().fold(0.0_f64, f64::max);
    if !(max_sv > 0.0) {
        return 0;
    }
    let tol = crate::frames::SAE_FRAME_RANK_CUTOFF * max_sv;
    sv.iter().filter(|&&v| v > tol).count().min(p)
}

/// #2362 Face B — orthonormal basis `Q` (`p x R_dec`) of the union decoder output
/// span: the column-space companion to [`union_output_frame_rank`]. Same stacked
/// decoder output frames and the same RELATIVE singular-value cutoff, but returns
/// the retained LEFT singular vectors so a caller can PROJECT the target onto the
/// realized output subspace (the amplitude-free reach ceiling), not merely count
/// its dimension. Returns a `p x 0` matrix when the dictionary has no usable output
/// frame (the caller then reads no structural collapse).
fn union_output_frame_basis(frames: &[Array2<f64>], p: usize) -> Array2<f64> {
    let total_cols: usize = frames.iter().map(|q| q.ncols()).sum();
    if p == 0 || total_cols == 0 {
        return Array2::<f64>::zeros((p, 0));
    }
    let mut stacked = Array2::<f64>::zeros((p, total_cols));
    let mut col = 0usize;
    for q in frames {
        let m = q.ncols();
        if m == 0 {
            continue;
        }
        if q.nrows() != p {
            return Array2::<f64>::zeros((p, 0));
        }
        for qc in 0..m {
            for row in 0..p {
                stacked[[row, col + qc]] = q[[row, qc]];
            }
        }
        col += m;
    }
    let (u_opt, sv, _) = match stacked.svd(true, false) {
        Ok(factors) => factors,
        Err(_) => return Array2::<f64>::zeros((p, 0)),
    };
    let Some(u) = u_opt else {
        return Array2::<f64>::zeros((p, 0));
    };
    let max_sv = sv.iter().copied().fold(0.0_f64, f64::max);
    if !(max_sv > 0.0) {
        return Array2::<f64>::zeros((p, 0));
    }
    let tol = crate::frames::SAE_FRAME_RANK_CUTOFF * max_sv;
    let rank = sv
        .iter()
        .filter(|&&v| v > tol)
        .count()
        .min(p)
        .min(u.ncols());
    let mut basis = Array2::<f64>::zeros((p, rank));
    for c in 0..rank {
        for row in 0..p {
            basis[[row, c]] = u[[row, c]];
        }
    }
    basis
}

#[cfg(test)]
mod projection_policy_tests {
    use super::*;
    use crate::basis::{AmbientSphereHarmonicEvaluator, SaeBasisEvaluator};
    use ndarray::array;
    use std::sync::Arc;

    #[test]
    fn multivariate_compact_projection_skips_without_mutation() {
        // A compact multivariate chart (sphere) has no complete rank-1 Fourier
        // stationary enumeration, so the decoder-projection coordinate update must SKIP it
        // — leaving its incoming natural-chart coordinates untouched — and
        // return Ok, rather than aborting the whole fit. (A fixed-lattice
        // projection is still never performed: honesty is preserved by not
        // moving the atom, not by erroring.)
        let coordinates = array![[0.36, 0.48, 0.8]];
        let evaluator = Arc::new(AmbientSphereHarmonicEvaluator::new(2).unwrap());
        let (phi, jet) = evaluator.evaluate(coordinates.view()).unwrap();
        let atom = SaeManifoldAtom::new_with_provided_function_gram(
            "sphere",
            SaeAtomBasisKind::Sphere,
            3,
            phi,
            jet,
            Array2::<f64>::zeros((9, 3)),
            Array2::<f64>::eye(9),
        )
        .unwrap()
        .with_basis_evaluator(evaluator);
        let assignment = SaeAssignment::from_blocks_with_mode_and_manifolds(
            Array2::<f64>::zeros((1, 1)),
            vec![coordinates.clone()],
            vec![SaeAtomBasisKind::Sphere.latent_manifold(2)],
            AssignmentMode::softmax(1.0),
        )
        .unwrap();
        let mut term = SaeManifoldTerm::new(vec![atom], assignment).unwrap();

        let before = term.assignment.coords[0].as_matrix();
        term.seed_coords_by_decoder_projection(Array2::<f64>::zeros((1, 2)).view())
            .expect("compact multivariate chart is skipped, not an error");
        assert_eq!(term.assignment.coords[0].as_matrix(), before);
    }

    /// #2132 — the measured-noise-floor "uncovered signal" test that gates a
    /// co-collapse reseed against re-planting a duplicate onto noise: a flat
    /// (pure-noise) residual spectrum reads as NO uncovered signal (demote the
    /// redundant atom), while a spectrum with a dominant direction reads as signal
    /// (reseed onto it is legitimate).
    #[test]
    fn leading_direction_above_noise_floor_separates_signal_from_noise_2132() {
        // Pure noise: comparable per-direction energies, no spike ⇒ the leading
        // direction does NOT clear the lower-quartile·log2 floor.
        let noise: Vec<f64> = (0..20)
            .map(|i| 1.0 + 0.15 * ((i % 5) as f64 - 2.0))
            .collect();
        assert!(
            !leading_direction_above_noise_floor(&noise),
            "a flat (pure-noise) residual spectrum must read as NO uncovered signal"
        );
        // One dominant uncovered direction rises far above the noise quantile ⇒ signal.
        let mut signal = noise.clone();
        signal[7] = 100.0;
        assert!(
            leading_direction_above_noise_floor(&signal),
            "a residual spectrum with a dominant direction must read as uncovered signal"
        );
        // #2132 root-cause pin — signal spanning HALF the (few) directions must NOT
        // be swallowed. Two unequal circles uncovered in p=4 output channels give a
        // residual Gram spectrum ≈[7.7, 7.7, 48, 48]; a median noise estimate (27.8)
        // is pulled onto circle A's own energy and `median·log2(4)=55.7` buries the
        // peak (48), so a median floor reads real two-circle signal as pure noise
        // and reseeds NOTHING. The lower-quartile floor must read it as signal.
        assert!(
            leading_direction_above_noise_floor(&[7.68, 7.68, 48.0, 48.0]),
            "two circles filling all p=4 directions must read as uncovered signal, not noise"
        );
        // And the peeled remainder (circle A subtracted) — circle B alone, a rank-2
        // structure in p=4 with two near-zero directions — must still read as signal
        // so the sequential-deflation reseed lands the second atom.
        assert!(
            leading_direction_above_noise_floor(&[1.0e-9, 1.0e-9, 7.68, 7.68]),
            "the weaker uncovered circle must still clear the floor after the dominant peel"
        );
        // Degenerate inputs carry no signal to reseed onto.
        assert!(!leading_direction_above_noise_floor(&[]));
        assert!(!leading_direction_above_noise_floor(&[0.0, 0.0, 0.0]));
    }
}