ccf-core 1.0.1

//! Story #152 REQ-01 / AC-1: `kappa_hat_t` is COMPUTED from the update matrices,
//! not handed in as a fixture. Before this slice the `kappa_dynamic_floor` test
//! supplied `kappa_hat_t` as magic numbers and only exercised the floor
//! classifier, so the headline "compute kappa_hat_t" requirement was never
//! tested. These tests derive `kappa_hat_t` from A_t / R_t / A_{t+1}.
//!
//! Oracle: the asserted values are reproduced by an independent scalar
//! calculation (see the #152 evidence note). The canonical-step value is the
//! mathematical zero of the gauge-kernel lemma, not a measured constant.

use ccf_core::kappa::{
    certify_update, compute_kappa_hat, quotient_distance, CertificateInputs, KappaCertificateStatus,
};
use ccf_core::qac::{qac_update_3x3, Matrix3, PositiveDiagonal3, QacInputs3};

const ALPHA: f64 = 0.3;
const ORACLE_TOL: f64 = 1.0e-9;

fn prior_a() -> Matrix3 {
    Matrix3::new([[2.0, 1.0, 1.0], [1.0, 2.0, 1.0], [1.0, 1.0, 2.0]])
}

fn reference_r() -> Matrix3 {
    Matrix3::new([[1.0, 1.0, 2.0], [2.0, 1.0, 1.0], [1.0, 2.0, 1.0]])
}

fn canonical_update() -> Matrix3 {
    qac_update_3x3(&QacInputs3 {
        prior_a_t: prior_a(),
        reference_r_t: reference_r(),
        left_l_t: PositiveDiagonal3::try_new([1.5, 0.8, 1.2]).unwrap(),
        right_c_t: PositiveDiagonal3::try_new([0.9, 1.1, 1.0]).unwrap(),
        alpha_t: ALPHA,
        epsilon_floor: 1.0e-12,
    })
    .expect("canonical 3x3 QAC update")
}

fn arithmetic_interpolation_update() -> Matrix3 {
    // (1 - alpha) A + alpha R -- arithmetic interpolation, NOT the log-geodesic.
    let (a, r) = (prior_a(), reference_r());
    let mut wrong = [[0.0_f64; 3]; 3];
    for row in 0..3 {
        for col in 0..3 {
            wrong[row][col] = (1.0 - ALPHA) * a.entries[row][col] + ALPHA * r.entries[row][col];
        }
    }
    Matrix3::new(wrong)
}

/// A true canonical QAC step certifies with kappa_hat ~ 0 (the diagonal gauge
/// is in the kernel of H), and the dynamic-floor classifier accepts it.
#[test]
fn computed_kappa_hat_is_zero_for_canonical_qac_step() {
    let (a, r) = (prior_a(), reference_r());
    let canonical = canonical_update();

    let kappa = compute_kappa_hat(&a, &r, &canonical, ALPHA).expect("kappa computable");
    assert!(
        kappa <= 1.0e-10,
        "canonical step must give kappa_hat ~ 0, got {kappa:.3e}"
    );

    let report = certify_update(&CertificateInputs {
        tick_id: 1,
        prior_a_t: a,
        reference_r_t: r,
        realized_a_next: canonical,
        alpha_t: ALPHA,
        delta_alpha_t: 0.01,
        epsilon_q: 1.0e-4,
        policy_margin: 5.0e-4,
    })
    .expect("certificate computable");
    assert!(!report.fail_closed);
    assert_eq!(
        report.certificate_status,
        KappaCertificateStatus::WithinDynamicFloor
    );
    assert!(report.kappa_hat_t <= report.threshold_t);
    eprintln!(
        "canonical computed kappa_hat={:.17e} floor_t={:.17e} E_t={:.17e}",
        report.kappa_hat_t, report.floor_t, report.e_t
    );
}

/// The old-wrong arithmetic-interpolation update yields a computed kappa_hat that
/// exceeds the dynamic floor and trips the fail-closed excursion. The kappa and
/// E_t values are oracle-traced against an independent calculation.
#[test]
fn computed_kappa_hat_excursion_for_arithmetic_interpolation() {
    let (a, r) = (prior_a(), reference_r());
    let wrong = arithmetic_interpolation_update();

    let kappa = compute_kappa_hat(&a, &r, &wrong, ALPHA).expect("kappa computable");
    let e_t = quotient_distance(&a, &r).expect("E_t computable");
    let floor = 2.0 * 3.0 * 1.0e-4 + 0.01_f64.abs() * e_t;

    assert!(
        (e_t - 1.69785690902066544).abs() < ORACLE_TOL,
        "E_t oracle mismatch: got {e_t:.17e}"
    );
    assert!(
        (kappa - 0.0714556324500290330).abs() < ORACLE_TOL,
        "kappa_wrong oracle mismatch: got {kappa:.17e}"
    );
    assert!(
        kappa > floor + 5.0e-4,
        "wrong update must exceed floor+margin: kappa={kappa:.6e} floor={floor:.6e}"
    );

    let report = certify_update(&CertificateInputs {
        tick_id: 2,
        prior_a_t: a,
        reference_r_t: r,
        realized_a_next: wrong,
        alpha_t: ALPHA,
        delta_alpha_t: 0.01,
        epsilon_q: 1.0e-4,
        policy_margin: 5.0e-4,
    })
    .expect("certificate computable");
    assert!(report.fail_closed);
    assert_eq!(
        report.certificate_status,
        KappaCertificateStatus::FailClosedExcursion
    );
    eprintln!(
        "wrong computed kappa_hat={:.17e} floor_t={:.17e} threshold_t={:.17e}",
        report.kappa_hat_t, report.floor_t, report.threshold_t
    );
}

/// Gauge invariance: re-gauging the realized update with any positive diagonal
/// L', C' leaves kappa_hat unchanged, because H annihilates the gauge. Shown on
/// a non-canonical update so the invariant holds at a nonzero value.
#[test]
fn computed_kappa_hat_is_gauge_invariant() {
    let (a, r) = (prior_a(), reference_r());
    let wrong = arithmetic_interpolation_update();
    let k_base = compute_kappa_hat(&a, &r, &wrong, ALPHA).unwrap();

    let lp = [2.0, 0.5, 1.3];
    let cp = [0.7, 1.4, 0.95];
    let mut regauged = [[0.0_f64; 3]; 3];
    for row in 0..3 {
        for col in 0..3 {
            regauged[row][col] = lp[row] * wrong.entries[row][col] * cp[col];
        }
    }
    let k_regauged = compute_kappa_hat(&a, &r, &Matrix3::new(regauged), ALPHA).unwrap();

    assert!(
        (k_base - k_regauged).abs() <= 1.0e-10,
        "kappa_hat must be gauge invariant: base={k_base:.6e} regauged={k_regauged:.6e}"
    );
    assert!(
        k_base > 1.0e-3,
        "sanity: the non-canonical kappa is nonzero ({k_base:.6e})"
    );
}