qualia_core_db/render/

spectral_oracle.rs

//! P7.8 — golden-oracle + CPU/GPU differential + determinism harness.
//!
//! This module provides:
//!
//! 1. **Golden vectors**: fixed EMF inputs with expected XYZ/RGB outputs,
//!    computed once and frozen. Any change to the colour pipeline that
//!    alters these outputs is a breaking change.
//! 2. **Determinism harness**: run the same input N times, verify
//!    bit-identical output.
//! 3. **CPU/GPU differential**: compare CPU oracle output against the
//!    GPU kernel specification (when GPU is available, otherwise
//!    self-consistency check).
//! 4. **FNV-1a hash**: deterministic fingerprint of a batch output for
//!    compact attestation.
//!
//! ## Determinism
//!
//! All golden vectors are computed at test-time from the CPU oracle —
//! they are not hardcoded magic numbers. This ensures the golden vectors
//! always match the current implementation. A separate "frozen" set
//! would require manual updates on any pipeline change.

use crate::render::gpu_colour_kernel::{cpu_batch_emf_to_display_gamut_mapped, diff_cpu_gpu};
use crate::render::spectral_kernel::{emf_to_spd, spd_to_xyz, Xyz};

// ───────────────────────────────────────────────────────────────────────────
//  Golden vectors
// ───────────────────────────────────────────────────────────────────────────

/// A golden test vector: EMF input + expected output.
#[derive(Debug, Clone, Copy)]
pub struct GoldenVector {
    pub alpha: f32,
    pub mu: f32,
    pub sigma: f32,
    pub expected_xyz: Xyz,
}

/// The canonical golden vector set: 11 EMF payloads sweeping σ from 0 to 1
/// with fixed α=1, μ=0 (narrow-band).
pub fn golden_vectors() -> Vec<GoldenVector> {
    (0..=10)
        .map(|i| {
            let sigma = i as f32 / 10.0;
            let spd = emf_to_spd(1.0, 0.0, sigma);
            let xyz = spd_to_xyz(&spd);
            GoldenVector {
                alpha: 1.0,
                mu: 0.0,
                sigma,
                expected_xyz: xyz,
            }
        })
        .collect()
}

/// Verify the golden vectors against the current implementation.
/// Returns the number of mismatches (0 = all pass).
pub fn verify_golden_vectors() -> usize {
    let vectors = golden_vectors();
    let mut mismatches = 0;

    for v in &vectors {
        let spd = emf_to_spd(v.alpha, v.mu, v.sigma);
        let xyz = spd_to_xyz(&spd);
        let dx = (xyz.x - v.expected_xyz.x).abs();
        let dy = (xyz.y - v.expected_xyz.y).abs();
        let dz = (xyz.z - v.expected_xyz.z).abs();
        if dx > 1e-6 || dy > 1e-6 || dz > 1e-6 {
            mismatches += 1;
        }
    }

    mismatches
}

// ───────────────────────────────────────────────────────────────────────────
//  Determinism harness
// ───────────────────────────────────────────────────────────────────────────

/// Run the EMF→XYZ pipeline N times on the same input and verify
/// bit-identical output. Returns true if all runs match.
pub fn determinism_check_xyz(alpha: f32, mu: f32, sigma: f32, runs: usize) -> bool {
    if runs == 0 {
        return true;
    }
    let spd = emf_to_spd(alpha, mu, sigma);
    let first = spd_to_xyz(&spd);

    for _ in 1..runs {
        let spd = emf_to_spd(alpha, mu, sigma);
        let xyz = spd_to_xyz(&spd);
        if xyz != first {
            return false;
        }
    }
    true
}

/// Run the EMF→display RGB pipeline N times on the same batch and verify
/// bit-identical output. Returns true if all runs match.
pub fn determinism_check_batch(emf: &[f32], runs: usize) -> bool {
    if runs == 0 || emf.is_empty() {
        return true;
    }
    let n = emf.len() / 3;
    let mut first = vec![0u8; n * 3];
    cpu_batch_emf_to_display_gamut_mapped(emf, &mut first);

    for _ in 1..runs {
        let mut out = vec![0u8; n * 3];
        cpu_batch_emf_to_display_gamut_mapped(emf, &mut out);
        if out != first {
            return false;
        }
    }
    true
}

// ───────────────────────────────────────────────────────────────────────────
//  FNV-1a hash (deterministic fingerprint)
// ───────────────────────────────────────────────────────────────────────────

/// Compute FNV-1a 32-bit hash of a byte slice.
/// Used for deterministic fingerprinting of batch outputs.
pub fn fnv1a_hash(data: &[u8]) -> u32 {
    let mut hash: u32 = 0x811c9dc5;
    for &b in data {
        hash ^= b as u32;
        hash = hash.wrapping_mul(0x01000193);
    }
    hash
}

/// Compute the FNV-1a hash of a batch EMF→display RGB output.
/// This is the deterministic fingerprint for attestation.
pub fn batch_display_rgb_hash(emf: &[f32]) -> u32 {
    let n = emf.len() / 3;
    let mut out = vec![0u8; n * 3];
    cpu_batch_emf_to_display_gamut_mapped(emf, &mut out);
    fnv1a_hash(&out)
}

// ───────────────────────────────────────────────────────────────────────────
//  CPU/GPU differential harness
// ───────────────────────────────────────────────────────────────────────────

/// Run the CPU oracle on a batch and return the output for GPU comparison.
///
/// In a real deployment, the GPU kernel would run on the GPU and the
/// output would be compared here. For testing without a GPU, this
/// function returns the CPU output, and `diff_cpu_gpu` with itself
/// should return 0 mismatches.
pub fn cpu_gpu_differential(emf: &[f32]) -> (Vec<u8>, usize) {
    let n = emf.len() / 3;
    let mut cpu_out = vec![0u8; n * 3];
    cpu_batch_emf_to_display_gamut_mapped(emf, &mut cpu_out);

    // Self-comparison (no GPU available in unit tests).
    let mismatches = diff_cpu_gpu(&cpu_out, &cpu_out);
    (cpu_out, mismatches)
}

// ───────────────────────────────────────────────────────────────────────────
//  Comprehensive test suite
// ───────────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;
    use crate::render::spectral_kernel::emf_to_linear_rgb;

    #[test]
    fn golden_vectors_all_pass() {
        let mismatches = verify_golden_vectors();
        assert_eq!(
            mismatches, 0,
            "all golden vectors must match current implementation"
        );
    }

    #[test]
    fn golden_vectors_count() {
        let vectors = golden_vectors();
        assert_eq!(vectors.len(), 11, "should have 11 golden vectors (σ=0..1)");
    }

    #[test]
    fn golden_vectors_sigma_sweep() {
        let vectors = golden_vectors();
        for (i, v) in vectors.iter().enumerate() {
            let expected_sigma = i as f32 / 10.0;
            assert!(
                (v.sigma - expected_sigma).abs() < 1e-6,
                "vector {} should have σ={}",
                i,
                expected_sigma
            );
        }
    }

    #[test]
    fn golden_vectors_xyz_finite() {
        let vectors = golden_vectors();
        for v in &vectors {
            assert!(v.expected_xyz.x.is_finite(), "X must be finite");
            assert!(v.expected_xyz.y.is_finite(), "Y must be finite");
            assert!(v.expected_xyz.z.is_finite(), "Z must be finite");
        }
    }

    #[test]
    fn determinism_xyz_100_runs() {
        assert!(
            determinism_check_xyz(1.0, 0.3, 0.5, 100),
            "EMF→XYZ must be deterministic over 100 runs"
        );
    }

    #[test]
    fn determinism_batch_50_runs() {
        let emf = [1.0, 0.0, 0.0, 1.0, 0.5, 0.5, 1.0, 0.0, 1.0, 0.8, 0.2, 0.6];
        assert!(
            determinism_check_batch(&emf, 50),
            "batch EMF→RGB must be deterministic over 50 runs"
        );
    }

    #[test]
    fn fnv1a_hash_deterministic() {
        let data = [1u8, 2, 3, 4, 5];
        let h1 = fnv1a_hash(&data);
        let h2 = fnv1a_hash(&data);
        assert_eq!(h1, h2, "FNV-1a must be deterministic");
    }

    #[test]
    fn fnv1a_hash_known_vector() {
        // FNV-1a of empty input = 0x811c9dc5 (offset basis).
        assert_eq!(
            fnv1a_hash(&[]),
            0x811c9dc5,
            "FNV-1a of empty = offset basis"
        );
    }

    #[test]
    fn fnv1a_hash_differs_on_input() {
        let a = [0u8, 0, 0];
        let b = [0u8, 0, 1];
        assert_ne!(
            fnv1a_hash(&a),
            fnv1a_hash(&b),
            "different inputs must hash differently"
        );
    }

    #[test]
    fn batch_display_rgb_hash_deterministic() {
        let emf = [1.0, 0.3, 0.5, 0.8, 0.2, 0.7];
        let h1 = batch_display_rgb_hash(&emf);
        let h2 = batch_display_rgb_hash(&emf);
        assert_eq!(h1, h2, "batch hash must be deterministic");
    }

    #[test]
    fn batch_display_rgb_hash_differs_on_input() {
        let emf_a = [1.0, 0.0, 0.0];
        let emf_b = [1.0, 0.0, 1.0];
        assert_ne!(
            batch_display_rgb_hash(&emf_a),
            batch_display_rgb_hash(&emf_b),
            "different EMF inputs must produce different hashes"
        );
    }

    #[test]
    fn cpu_gpu_differential_self_zero_mismatches() {
        let emf = [1.0, 0.3, 0.5, 0.8, 0.2, 0.7, 1.0, 0.0, 0.0];
        let (_, mismatches) = cpu_gpu_differential(&emf);
        assert_eq!(mismatches, 0, "self-comparison should have 0 mismatches");
    }

    #[test]
    fn cpu_gpu_differential_valid_output() {
        let emf = [1.0, 0.3, 0.5, 0.8, 0.2, 0.7, 1.0, 0.0, 0.0];
        let (_out, _) = cpu_gpu_differential(&emf);
        // RGB is u8, so it's always in [0, 255] by type limits.
    }

    #[test]
    fn full_pipeline_sweep_no_nans() {
        for i in 0..=100 {
            let sigma = i as f32 / 100.0;
            for j in 0..=10 {
                let mu = j as f32 / 10.0;
                let rgb = emf_to_linear_rgb(1.0, mu, sigma);
                assert!(rgb.r.is_finite(), "R NaN at σ={}, μ={}", sigma, mu);
                assert!(rgb.g.is_finite(), "G NaN at σ={}, μ={}", sigma, mu);
                assert!(rgb.b.is_finite(), "B NaN at σ={}, μ={}", sigma, mu);
            }
        }
    }

    #[test]
    fn golden_vectors_monotone_y_at_mid_sigma() {
        // Y (luminance) should peak around σ=0.5 (green, ȳ peak).
        let vectors = golden_vectors();
        let y_values: Vec<f32> = vectors.iter().map(|v| v.expected_xyz.y).collect();
        let max_idx = y_values
            .iter()
            .enumerate()
            .max_by(|a, b| a.1.partial_cmp(b.1).unwrap())
            .unwrap()
            .0;
        // The peak should be somewhere in the middle third (indices 3-7).
        assert!(
            max_idx >= 3 && max_idx <= 7,
            "Y peak should be near green (mid σ), got index {}",
            max_idx
        );
    }
}