gam_solve/inference/

certificate_impls.rs

//! `Certificate` implementations and margin-resolved `Verdict` mappings for
//! the gam-solve-tier certificate zoo (task #16; descended #1521).
//!
//! Two concerns live here, both gam-solve-tier: (a) the `impl Certificate for …`
//! blocks for the gam-solve-owned certificate types (`OuterCriterionCertificate`,
//! [`CoresetCertificate`](crate::row_sampling_measure::CoresetCertificate),
//! `LogdetEnclosure`, [`CollapseEvent`](crate::structure_search::CollapseEvent)),
//! and (b) the two pure margin-resolution helpers, whose only inputs are
//! gam-solve-tier types (`LogdetEnclosure`/`MarginVerdict` and
//! [`CoresetMarginVerdict`](crate::row_sampling_measure::CoresetMarginVerdict))
//! plus the contracted-down `Verdict` ladder. Both were relocated out of the
//! monolith root (`gam::inference::certificate_impls`) to satisfy the coherence
//! orphan rule: the `Certificate` trait now lives in the neutral `gam-problem`
//! crate and these types are owned here in `gam-solve`, so the impls must be
//! defined in the type's home crate. The bodies are byte-identical to the
//! monolith originals, so there remains exactly one decision rule per verdict.
//! (The gam-sae-owned certificate types — `EncodeResult`, `ResidualGaugeReport`,
//! `CertificateInputs` — carry their own impls in `gam_sae::certificate_impls`.)

use crate::logdet_bounds::LogdetEnclosure;
use crate::model_types::OuterCriterionCertificate;
use crate::row_sampling_measure::CoresetCertificate;
use crate::structure_search::{CollapseAction, CollapseEvent};
use gam_problem::topology_certificates::{Certificate, Claim, Evidence, Verdict};
use crate::row_sampling_measure::CoresetMarginVerdict;
use crate::logdet_bounds::MarginVerdict;

/// Helper: insert a scalar only when finite, else record it as text "n/a" so the
/// evidence is explicit about a missing quantity (never a silent 0.0).
fn put_finite(evidence: &mut Evidence, key: &'static str, value: f64) {
    if value.is_finite() {
        evidence.insert(key, value.into());
    } else {
        evidence.insert(key, "n/a".into());
    }
}

// ── 1. Outer-optimum first-order self-audit (#931/#934) ──────────────────────

impl Certificate for OuterCriterionCertificate {
    fn claim(&self) -> Claim {
        Claim::new(
            "outer-optimality",
            concat!(
                "the returned outer optimum is analytically KKT-stationary and ",
                "its available exact curvature is not indefinite",
            ),
        )
    }

    fn evidence(&self) -> Evidence {
        let mut e = Evidence::new();
        put_finite(
            &mut e,
            "stationarity_raw_norm",
            self.stationarity.raw_norm(),
        );
        put_finite(
            &mut e,
            "stationarity_projected_norm",
            self.stationarity.projected_norm(),
        );
        put_finite(&mut e, "stationarity_bound", self.stationarity.bound());
        // The bound never appears without the standard that produced it: across
        // this subsystem the bound alone spans nine orders and names nothing
        // (#2458/#2530).
        let rung = self.stationarity.rung();
        e.insert("stationarity_rung", rung.label.clone().into());
        e.insert("stationarity_rung_derived", rung.derived_standard.into());
        // `kind_label` rather than `is_fixed_point()` + else: the old two-way
        // test reported an AsymptoteRail certificate as "analytic_gradient" —
        // a route wearing another route's name, in the map a reader consults
        // precisely to find out which route ran.
        e.insert("stationarity_kind", self.stationarity.kind_label().into());
        e.insert(
            "hessian_psd",
            match self.hessian_psd() {
                Some(psd) => psd.into(),
                None => "n/a".into(),
            },
        );
        // The floor's verdict rides BESIDE the raw measurement, never over it,
        // so a reader can see both which question was asked and how much
        // negative curvature the floor was able to absorb.
        if let Some(clearance) = self.curvature_floor {
            e.insert("curvature_floor_cleared", clearance.cleared.into());
            put_finite(
                &mut e,
                "curvature_interior_min_eigenvalue",
                clearance.interior_min_eigenvalue,
            );
            put_finite(&mut e, "curvature_gradient_floor", clearance.gradient_floor);
        }
        e.insert("lambdas_railed_count", self.lambdas_railed.len().into());
        e.insert("stationary", self.is_stationary().into());
        // Both, deliberately (#2578): the boolean is the published contract and
        // stays byte-compatible, and the verdict beside it says WHICH of the
        // three states produced it — so a reader can tell "measured and
        // admissible" from "nothing was measured", which the boolean alone
        // cannot express.
        e.insert("curvature_admissible", self.curvature_not_refused().into());
        e.insert(
            "curvature_verdict",
            self.curvature_verdict().to_string().into(),
        );
        e.insert("summary", self.summary().into());
        e
    }

    fn verdict(&self) -> Verdict {
        if self.certifies() {
            Verdict::Certified
        } else {
            Verdict::Insufficient
        }
    }
}

// ── 2. Sensitivity-coreset error budget ──────────────────────────────────────

impl Certificate for CoresetCertificate {
    fn claim(&self) -> Claim {
        Claim::new(
            "coreset-budget",
            "the selected row coreset reproduces the full-corpus evidence within \
             a certified spectral + likelihood error budget; a race decision \
             inherits the full-corpus verdict only when its margin clears this \
             budget",
        )
    }

    fn evidence(&self) -> Evidence {
        let mut e = Evidence::new();
        put_finite(&mut e, "eps_spectral", self.eps_spectral);
        put_finite(&mut e, "eps_likelihood", self.eps_likelihood);
        e.insert("dim_effective", self.dim_effective.into());
        e.insert("n_selected", self.n_selected.into());
        put_finite(&mut e, "logdet_error_bound", self.logdet_error_bound());
        put_finite(&mut e, "race_transfer_margin", self.race_transfer_margin());
        e
    }

    fn verdict(&self) -> Verdict {
        // A coreset certificate is a transfer BUDGET, not a standalone decision:
        // it certifies a race verdict only once a consumer supplies a decision
        // margin that clears `race_transfer_margin`. With no consumer margin in
        // hand, the conservative standalone verdict is `Insufficient` (the
        // budget is present, but nothing has been decided by it yet) when the
        // budget is finite, and `Unavailable` when it is not.
        if self.race_transfer_margin().is_finite() {
            Verdict::Insufficient
        } else {
            Verdict::Unavailable
        }
    }
}

/// Map a coreset race outcome (the certificate's own
/// `CoresetCertificate::certify_margin`
/// rule, evaluated against a consumer's
/// `decision_margin`) onto the shared [`Verdict`] ladder. This is the
/// margin-resolved entry point a race consumer uses to obtain a unified verdict
/// without re-deriving the mapping.
pub fn coreset_race_verdict(verdict: CoresetMarginVerdict) -> Verdict {
    match verdict {
        CoresetMarginVerdict::Certified { .. } => Verdict::Certified,
        CoresetMarginVerdict::InsufficientMargin { .. } => Verdict::Insufficient,
    }
}

/// Verdict for an enclosure resolved against a concrete consumer
/// `decision_margin`, reusing [`LogdetEnclosure::decide_within_margin`].
pub fn enclosure_margin_verdict(enclosure: &LogdetEnclosure, decision_margin: f64) -> Verdict {
    match enclosure.decide_within_margin(decision_margin) {
        MarginVerdict::Decided { .. } => Verdict::Certified,
        MarginVerdict::InsufficientMargin { .. } => Verdict::Insufficient,
    }
}

// ── 3. Log-det enclosure ─────────────────────────────────────────────────────

impl Certificate for LogdetEnclosure {
    fn claim(&self) -> Claim {
        Claim::new(
            "logdet-enclosure",
            "the log-determinant is enclosed in a certified [lower, upper] \
             interval whose midpoint is interchangeable with the exact value for \
             any decision whose margin exceeds the enclosure gap",
        )
    }

    fn evidence(&self) -> Evidence {
        let mut e = Evidence::new();
        put_finite(&mut e, "block_diag_logdet", self.block_diag_logdet);
        put_finite(&mut e, "lower", self.lower);
        put_finite(&mut e, "upper", self.upper);
        put_finite(&mut e, "gap", self.gap());
        put_finite(&mut e, "rho", self.rho);
        put_finite(&mut e, "p2", self.p2);
        match self.p3 {
            Some(p3) => put_finite(&mut e, "p3", p3),
            None => {
                e.insert("p3", "n/a".into());
            }
        }
        e
    }

    fn verdict(&self) -> Verdict {
        // An enclosure on its own does not certify a decision — only a consumer
        // margin does (via `decide_within_margin`). The standalone verdict is
        // `Insufficient` when the enclosure is finite (evidence present, no
        // decision yet) and `Unavailable` when the bounds are non-finite.
        if self.lower.is_finite() && self.upper.is_finite() && self.gap().is_finite() {
            Verdict::Insufficient
        } else {
            Verdict::Unavailable
        }
    }
}

// ── 7. Structure-search collapse event ───────────────────────────────────────

impl Certificate for CollapseEvent {
    fn claim(&self) -> Claim {
        Claim::new(
            "structure-collapse",
            "an atom's active mass fell below the collapse floor during the joint \
             fit; the guard either reseeded it from a fresh basin or, once the \
             reseed budget was exhausted, recorded the collapse as the objective's \
             terminal verdict",
        )
    }

    fn evidence(&self) -> Evidence {
        let mut e = Evidence::new();
        e.insert("iteration", self.iteration.into());
        e.insert("atom", self.atom.into());
        put_finite(&mut e, "max_active_mass", self.max_active_mass);
        put_finite(&mut e, "floor", self.floor);
        e.insert(
            "action",
            match self.action {
                CollapseAction::Reseeded => "reseeded",
                CollapseAction::Terminal => "terminal",
            }
            .into(),
        );
        e
    }

    fn verdict(&self) -> Verdict {
        // A collapse event is, by definition, a guard FIRING — it never certifies
        // health. A `Reseeded` event is a recovered breach (`Insufficient`: the
        // breach happened but the fit continued); a `Terminal` event is the
        // objective's verdict that the collapse stands (`Unavailable`: the claim
        // of a healthy non-collapsed dictionary cannot be made at all).
        match self.action {
            CollapseAction::Reseeded => Verdict::Insufficient,
            CollapseAction::Terminal => Verdict::Unavailable,
        }
    }
}

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

    #[test]
    fn criterion_stationarity_and_curvature_control_verdict() {
        let clean = OuterCriterionCertificate {
            stationarity: crate::model_types::OuterStationarityCertificate::AnalyticGradient {
                grad_norm: 1e-8,
                projected_grad_norm: 1e-8,
                bound: 1e-6,
                rung: gam_problem::StationarityRung {
                    label: "solver-band",
                    derived_standard: false,
                }
                .into(),
            },
            curvature: crate::model_types::CurvatureEvidence::Measured { psd: true },
            lambdas_railed: Vec::new(),
            railed_facts: Vec::new(),
            curvature_floor: None,
        };
        assert_eq!(clean.verdict(), Verdict::Certified);
        assert!(clean.verdict().is_certified());

        let nonstationary = OuterCriterionCertificate {
            stationarity: crate::model_types::OuterStationarityCertificate::AnalyticGradient {
                grad_norm: 1e-2,
                projected_grad_norm: 1e-2,
                bound: 1e-6,
                rung: gam_problem::StationarityRung {
                    label: "solver-band",
                    derived_standard: false,
                }
                .into(),
            },
            ..clean
        };
        assert_eq!(nonstationary.verdict(), Verdict::Insufficient);
        assert!(!nonstationary.verdict().is_certified());
        // The claim id is stable and the summary rides the evidence.
        assert_eq!(nonstationary.claim().id, "outer-optimality");
        assert!(nonstationary.evidence().contains_key("summary"));
    }

    #[test]
    fn enclosure_certifies_only_when_margin_clears_gap() {
        let enc = LogdetEnclosure {
            block_diag_logdet: 10.0,
            lower: 9.9,
            upper: 10.1,
            rho: 0.3,
            p2: 0.01,
            p3: None,
        };
        assert_eq!(enc.verdict(), Verdict::Insufficient);
        // gap = 0.2; a margin of 0.5 > gap certifies; 0.1 < gap does not.
        assert_eq!(enclosure_margin_verdict(&enc, 0.5), Verdict::Certified);
        assert_eq!(enclosure_margin_verdict(&enc, 0.1), Verdict::Insufficient);
    }

    #[test]
    fn collapse_terminal_is_unavailable_reseeded_is_insufficient() {
        let reseeded = CollapseEvent {
            iteration: 3,
            atom: 1,
            max_active_mass: 1e-4,
            floor: 1e-3,
            action: CollapseAction::Reseeded,
        };
        assert_eq!(reseeded.verdict(), Verdict::Insufficient);
        let terminal = CollapseEvent {
            action: CollapseAction::Terminal,
            ..reseeded
        };
        assert_eq!(terminal.verdict(), Verdict::Unavailable);
    }

}