diff --git a/crates/aprender-core/src/format/arch_coop_001_006.rs b/crates/aprender-core/src/format/arch_coop_001_006.rs new file mode 100644 index 000000000..a16856970 --- /dev/null +++ b/crates/aprender-core/src/format/arch_coop_001_006.rs @@ -0,0 +1,335 @@ +// Bundles two sister contracts in one verdict module: +// +// `arch-constraints-v1` (FALSIFY-ARCH-CONSTRAINTS-001..003) +// `cooperative-matrix-gemm-v1` (FALSIFY-COOP-001..003) +// +// ARCH-CONSTRAINTS-001: every model-family yaml constraints == this contract +// ARCH-CONSTRAINTS-002: enum exhaustiveness — no unknown enum values +// ARCH-CONSTRAINTS-003: DeepSeek eps == 1e-6 (regression guard) +// COOP-001: |coop - tiled| < 1e-3 elementwise +// COOP-002: coop GFLOPS > 2× tiled GFLOPS +// COOP-003: fallback path doesn't crash when coop unavailable + +/// ARCH-CONSTRAINTS-003: DeepSeek RmsNorm epsilon exact value. +pub const AC_ARCH_DEEPSEEK_EPS: f32 = 1e-6; +/// COOP-001: parity tolerance for cooperative-matrix vs tiled GEMM. +pub const AC_COOP_PARITY_TOLERANCE: f32 = 1e-3; +/// COOP-002: minimum GFLOPS multiplier (coop must be > 2× tiled). +pub const AC_COOP_GFLOPS_FLOOR: f32 = 2.0; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum ArchCoopVerdict { + Pass, + Fail, +} + +// ---------------------------------------------------------------- +// ARCH-CONSTRAINTS-001..003 +// ---------------------------------------------------------------- + +/// ARCH-CONSTRAINTS-001: model-family yaml consistency. +/// +/// `mismatch_count` = number of (family, field) pairs where the +/// model-family YAML doesn't match this contract. +#[must_use] +pub fn verdict_from_family_consistency(mismatch_count: u32) -> ArchCoopVerdict { + if mismatch_count == 0 { + ArchCoopVerdict::Pass + } else { + ArchCoopVerdict::Fail + } +} + +/// ARCH-CONSTRAINTS-002: enum exhaustiveness — no unknown values. +#[must_use] +pub fn verdict_from_enum_exhaustive(unknown_enum_count: u32) -> ArchCoopVerdict { + if unknown_enum_count == 0 { + ArchCoopVerdict::Pass + } else { + ArchCoopVerdict::Fail + } +} + +/// ARCH-CONSTRAINTS-003: DeepSeek eps regression guard. +/// +/// Pass iff `eps == 1e-6` exactly. +#[must_use] +pub fn verdict_from_deepseek_eps(eps: f32) -> ArchCoopVerdict { + if !eps.is_finite() { + return ArchCoopVerdict::Fail; + } + if eps == AC_ARCH_DEEPSEEK_EPS { + ArchCoopVerdict::Pass + } else { + ArchCoopVerdict::Fail + } +} + +// ---------------------------------------------------------------- +// COOP-001..003 +// ---------------------------------------------------------------- + +/// COOP-001: max|coop - tiled| < AC_COOP_PARITY_TOLERANCE elementwise. +#[must_use] +pub fn verdict_from_coop_parity(coop: &[f32], tiled: &[f32]) -> ArchCoopVerdict { + if coop.is_empty() || coop.len() != tiled.len() { + return ArchCoopVerdict::Fail; + } + for (a, b) in coop.iter().zip(tiled.iter()) { + if !a.is_finite() || !b.is_finite() { + return ArchCoopVerdict::Fail; + } + if (a - b).abs() >= AC_COOP_PARITY_TOLERANCE { + return ArchCoopVerdict::Fail; + } + } + ArchCoopVerdict::Pass +} + +/// COOP-002: coop GFLOPS > 2× tiled GFLOPS. +#[must_use] +pub fn verdict_from_coop_throughput(coop_gflops: f32, tiled_gflops: f32) -> ArchCoopVerdict { + if !coop_gflops.is_finite() || !tiled_gflops.is_finite() { + return ArchCoopVerdict::Fail; + } + if tiled_gflops <= 0.0 || coop_gflops <= 0.0 { + return ArchCoopVerdict::Fail; + } + if coop_gflops > AC_COOP_GFLOPS_FLOOR * tiled_gflops { + ArchCoopVerdict::Pass + } else { + ArchCoopVerdict::Fail + } +} + +/// COOP-003: fallback path takes effect on unsupported hardware. +/// +/// Pass iff: +/// - coop_supported == true → used_coop, no crash +/// - coop_supported == false → used_tiled fallback, no crash +#[must_use] +#[allow(clippy::fn_params_excessive_bools)] +pub fn verdict_from_coop_fallback( + coop_supported: bool, + used_coop_path: bool, + used_tiled_fallback: bool, + crashed: bool, +) -> ArchCoopVerdict { + if crashed { + return ArchCoopVerdict::Fail; + } + if coop_supported && used_coop_path && !used_tiled_fallback { + return ArchCoopVerdict::Pass; + } + if !coop_supported && !used_coop_path && used_tiled_fallback { + return ArchCoopVerdict::Pass; + } + ArchCoopVerdict::Fail +} + +#[cfg(test)] +mod tests { + use super::*; + + // ----------------------------------------------------------------- + // Section 1: Provenance pin. + // ----------------------------------------------------------------- + #[test] + fn provenance_constants() { + assert_eq!(AC_ARCH_DEEPSEEK_EPS, 1e-6); + assert_eq!(AC_COOP_PARITY_TOLERANCE, 1e-3); + assert_eq!(AC_COOP_GFLOPS_FLOOR, 2.0); + } + + // ----------------------------------------------------------------- + // Section 2: ARCH-CONSTRAINTS-001..003. + // ----------------------------------------------------------------- + #[test] + fn farch001_pass_no_mismatch() { + let v = verdict_from_family_consistency(0); + assert_eq!(v, ArchCoopVerdict::Pass); + } + + #[test] + fn farch001_fail_one_mismatch() { + let v = verdict_from_family_consistency(1); + assert_eq!(v, ArchCoopVerdict::Fail); + } + + #[test] + fn farch002_pass_no_unknown() { + let v = verdict_from_enum_exhaustive(0); + assert_eq!(v, ArchCoopVerdict::Pass); + } + + #[test] + fn farch002_fail_unknown_present() { + let v = verdict_from_enum_exhaustive(3); + assert_eq!(v, ArchCoopVerdict::Fail); + } + + #[test] + fn farch003_pass_correct_eps() { + let v = verdict_from_deepseek_eps(1e-6); + assert_eq!(v, ArchCoopVerdict::Pass); + } + + #[test] + fn farch003_fail_old_default() { + let v = verdict_from_deepseek_eps(1e-5); + assert_eq!(v, ArchCoopVerdict::Fail); + } + + #[test] + fn farch003_fail_nan() { + let v = verdict_from_deepseek_eps(f32::NAN); + assert_eq!(v, ArchCoopVerdict::Fail); + } + + // ----------------------------------------------------------------- + // Section 3: COOP-001 parity. + // ----------------------------------------------------------------- + #[test] + fn fcoop001_pass_within_tolerance() { + let coop = vec![1.0_f32, 2.0, 3.0]; + let tiled = vec![1.0001, 2.0001, 2.9999]; + let v = verdict_from_coop_parity(&coop, &tiled); + assert_eq!(v, ArchCoopVerdict::Pass); + } + + #[test] + fn fcoop001_fail_drift() { + let coop = vec![1.0_f32, 2.0]; + let tiled = vec![1.0, 2.5]; + let v = verdict_from_coop_parity(&coop, &tiled); + assert_eq!(v, ArchCoopVerdict::Fail); + } + + #[test] + fn fcoop001_fail_length_mismatch() { + let coop = vec![1.0_f32, 2.0]; + let tiled = vec![1.0_f32]; + let v = verdict_from_coop_parity(&coop, &tiled); + assert_eq!(v, ArchCoopVerdict::Fail); + } + + #[test] + fn fcoop001_fail_nan() { + let coop = vec![1.0_f32, f32::NAN]; + let tiled = vec![1.0_f32, 2.0]; + let v = verdict_from_coop_parity(&coop, &tiled); + assert_eq!(v, ArchCoopVerdict::Fail); + } + + // ----------------------------------------------------------------- + // Section 4: COOP-002 throughput. + // ----------------------------------------------------------------- + #[test] + fn fcoop002_pass_3x() { + let v = verdict_from_coop_throughput(300.0, 100.0); + assert_eq!(v, ArchCoopVerdict::Pass); + } + + #[test] + fn fcoop002_fail_at_2x() { + // strict >, not >= + let v = verdict_from_coop_throughput(200.0, 100.0); + assert_eq!(v, ArchCoopVerdict::Fail); + } + + #[test] + fn fcoop002_fail_below_2x() { + let v = verdict_from_coop_throughput(150.0, 100.0); + assert_eq!(v, ArchCoopVerdict::Fail); + } + + #[test] + fn fcoop002_fail_zero_tiled() { + let v = verdict_from_coop_throughput(300.0, 0.0); + assert_eq!(v, ArchCoopVerdict::Fail); + } + + // ----------------------------------------------------------------- + // Section 5: COOP-003 fallback. + // ----------------------------------------------------------------- + #[test] + fn fcoop003_pass_supported_used_coop() { + let v = verdict_from_coop_fallback(true, true, false, false); + assert_eq!(v, ArchCoopVerdict::Pass); + } + + #[test] + fn fcoop003_pass_unsupported_used_tiled() { + let v = verdict_from_coop_fallback(false, false, true, false); + assert_eq!(v, ArchCoopVerdict::Pass); + } + + #[test] + fn fcoop003_fail_crash() { + let v = verdict_from_coop_fallback(false, false, false, true); + assert_eq!(v, ArchCoopVerdict::Fail); + } + + #[test] + fn fcoop003_fail_supported_but_used_tiled() { + let v = verdict_from_coop_fallback(true, false, true, false); + assert_eq!(v, ArchCoopVerdict::Fail); + } + + #[test] + fn fcoop003_fail_unsupported_used_coop() { + // The exact regression — would crash on real hardware. + let v = verdict_from_coop_fallback(false, true, false, false); + assert_eq!(v, ArchCoopVerdict::Fail); + } + + // ----------------------------------------------------------------- + // Section 6: Mutation surveys. + // ----------------------------------------------------------------- + #[test] + fn mutation_survey_002_throughput_band() { + for ratio_x10 in [10_u32, 19, 20, 21, 25, 30] { + let coop = (ratio_x10 as f32 / 10.0) * 100.0; + let v = verdict_from_coop_throughput(coop, 100.0); + let want = if coop > 200.0 { + ArchCoopVerdict::Pass + } else { + ArchCoopVerdict::Fail + }; + assert_eq!(v, want, "ratio={ratio_x10}"); + } + } + + // ----------------------------------------------------------------- + // Section 7: Realistic. + // ----------------------------------------------------------------- + #[test] + fn realistic_healthy_passes_all_6() { + let v1 = verdict_from_family_consistency(0); + let v2 = verdict_from_enum_exhaustive(0); + let v3 = verdict_from_deepseek_eps(1e-6); + let coop = vec![1.0_f32, 2.0]; + let tiled = vec![1.0001, 2.0001]; + let v4 = verdict_from_coop_parity(&coop, &tiled); + let v5 = verdict_from_coop_throughput(300.0, 100.0); + let v6 = verdict_from_coop_fallback(true, true, false, false); + for v in [v1, v2, v3, v4, v5, v6] { + assert_eq!(v, ArchCoopVerdict::Pass); + } + } + + #[test] + fn realistic_pre_fix_all_6_failures() { + let v1 = verdict_from_family_consistency(7); + let v2 = verdict_from_enum_exhaustive(2); + let v3 = verdict_from_deepseek_eps(1e-5); // pre-fix value + let coop = vec![1.0_f32, 2.0]; + let tiled = vec![1.0, 2.5]; + let v4 = verdict_from_coop_parity(&coop, &tiled); + let v5 = verdict_from_coop_throughput(150.0, 100.0); // not >2× + let v6 = verdict_from_coop_fallback(false, true, false, false); // crash class + for v in [v1, v2, v3, v4, v5, v6] { + assert_eq!(v, ArchCoopVerdict::Fail); + } + } +} diff --git a/crates/aprender-core/src/format/mod.rs b/crates/aprender-core/src/format/mod.rs index c855d3592..6c4e4fdfb 100644 --- a/crates/aprender-core/src/format/mod.rs +++ b/crates/aprender-core/src/format/mod.rs @@ -550,6 +550,12 @@ pub mod gate_ship_011; // GATE-SHIP-012 — Line-coverage percentage inclusive-floor threshold (≥ 95.0). pub mod gate_ship_012; +// FALSIFY-ARCH-CONSTRAINTS-001..003 + FALSIFY-COOP-001..003 — sister +// bundle of arch-constraints-v1 (family consistency, enum exhaustive, +// DeepSeek eps regression) + cooperative-matrix-gemm-v1 (parity +// 1e-3, throughput >2×, fallback no-crash). +pub mod arch_coop_001_006; + // Re-export types (PMAT-198 - backward compatibility) pub use types::*;