aprender-core 0.65.2

//! APR Format Validation Module - 100-Point QA Checklist
//!
//! Implements the Master Falsification QA Checklist from APR-SPEC-v2-draft.md Section 11.
//! Each check is testable and falsifiable.
//!
//! # Categories
//! - A. Format & Structural Integrity (25 Points)
//! - B. Tensor Physics & Statistics (25 Points)
//! - C. Tooling & Operations (25 Points)
//! - D. Conversion & Interoperability (25 Points)

use crate::error::{AprenderError, Result};
use std::collections::HashMap;

/// Validation check result
#[derive(Debug, Clone, PartialEq)]
pub enum CheckStatus {
    /// Check passed
    Pass,
    /// Check failed with reason
    Fail(String),
    /// Check produced a warning
    Warn(String),
    /// Check was skipped (not applicable)
    Skip(String),
}

impl CheckStatus {
    /// Returns true if the check passed
    #[must_use]
    pub fn is_pass(&self) -> bool {
        matches!(self, Self::Pass)
    }

    /// Returns true if the check failed
    #[must_use]
    pub fn is_fail(&self) -> bool {
        matches!(self, Self::Fail(_))
    }
}

/// Individual validation check
#[derive(Debug, Clone)]
pub struct ValidationCheck {
    /// Check ID (1-100)
    pub id: u8,
    /// Check name
    pub name: &'static str,
    /// Category (A, B, C, D)
    pub category: Category,
    /// Check result
    pub status: CheckStatus,
    /// Points awarded (0 or 1)
    pub points: u8,
}

/// Validation category
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Category {
    /// A. Format & Structural Integrity
    Structure,
    /// B. Tensor Physics & Statistics
    Physics,
    /// C. Tooling & Operations
    Tooling,
    /// D. Conversion & Interoperability
    Conversion,
}

impl Category {
    /// Get category letter
    #[must_use]
    pub fn letter(&self) -> char {
        match self {
            Self::Structure => 'A',
            Self::Physics => 'B',
            Self::Tooling => 'C',
            Self::Conversion => 'D',
        }
    }

    /// Get category name
    #[must_use]
    pub fn name(&self) -> &'static str {
        match self {
            Self::Structure => "Format & Structural Integrity",
            Self::Physics => "Tensor Physics & Statistics",
            Self::Tooling => "Tooling & Operations",
            Self::Conversion => "Conversion & Interoperability",
        }
    }
}

/// A QA score carrying the denominator it was measured against.
///
/// dogfood-0.63.0, issue #2394 finding 12: `apr validate` printed
/// `✓ VALID 3/100 points` for a healthy model. Read literally that is a 3%
/// model waved through. It is not: most of the checklist is `Skip("Not
/// implemented")` stubs that never ran — measured on
/// `qwen2.5-coder-0.5b-instruct.apr`, 4 of the 26 declared checks actually
/// ran. "100" was never the denominator anything was measured against. A
/// score is meaningless without the number of checks that produced it, so the
/// two travel together and `Display` refuses to print one without the other.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ImplementedScore {
    /// Checks that ran and passed.
    pub passed: u8,
    /// Checks that ran at all (Pass / Fail / Warn — not Skip).
    pub ran: u8,
    /// Checks declared by the checklist, run or not.
    pub declared: usize,
}

impl ImplementedScore {
    /// Checks the checklist declares but has not implemented.
    #[must_use]
    pub fn not_implemented(&self) -> usize {
        self.declared.saturating_sub(self.ran as usize)
    }

    /// Percentage of the checks that RAN which passed, or `None` when nothing
    /// ran.
    ///
    /// `None` is not zero. Zero means "we measured and you failed everything";
    /// `None` means "nothing was measured", which is not a score and must not
    /// be rendered as one (#1866).
    #[must_use]
    pub fn pct(&self) -> Option<f64> {
        if self.ran == 0 {
            return None;
        }
        Some((f64::from(self.passed) / f64::from(self.ran)) * 100.0)
    }
}

impl std::fmt::Display for ImplementedScore {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let skipped = self.not_implemented();
        write!(f, "{}/{} checks that ran", self.passed, self.ran)?;
        if skipped > 0 {
            write!(
                f,
                " ({skipped} of {} not implemented — not evidence of health)",
                self.declared
            )?;
        }
        Ok(())
    }
}

/// Complete validation report
#[derive(Debug, Clone)]
pub struct ValidationReport {
    /// All checks performed
    pub checks: Vec<ValidationCheck>,
    /// Total score (0-100)
    pub total_score: u8,
    /// Score by category
    pub category_scores: HashMap<Category, u8>,
}

impl ValidationReport {
    /// Create empty report
    #[must_use]
    pub fn new() -> Self {
        Self {
            checks: Vec::with_capacity(100),
            total_score: 0,
            category_scores: HashMap::new(),
        }
    }

    /// Add a check result
    pub fn add_check(&mut self, check: ValidationCheck) {
        let category = check.category;
        let points = check.points;
        self.checks.push(check);

        *self.category_scores.entry(category).or_insert(0) += points;
        self.total_score += points;
    }

    /// Letter grade for what the checklist ACTUALLY measured (#1866).
    ///
    /// This used to band `total_score`, a raw count of awarded points, against
    /// a fixed 100-point denominator. 22 of the 26 checks the `.apr` path
    /// declares are `Skip("Not implemented")` stubs that never run, so the
    /// ceiling was 4 and every healthy model was graded `F` — while the same
    /// report said `passed: true`, `failed: 0` and printed `✓ VALID`. A grade
    /// nobody can earn is not a grade, it is a lie with a letter on it.
    ///
    /// The grade is now a function of the checks that ran, and it is wired to
    /// the verdict rather than merely correlated with it:
    ///
    /// * nothing ran            → `"N/A"` — not a grade; nothing was measured
    /// * any check FAILED       → `"F"`
    /// * otherwise              → band of [`Self::implemented_score_pct`],
    ///   floored at `"D"` because a report with no failures is at worst
    ///   all-advisory.
    ///
    /// Invariant, proved by construction and asserted in
    /// `grade_is_f_exactly_when_a_check_failed`:
    ///
    /// ```text
    /// grade() == "F"  <=>  a check ran AND at least one check failed
    ///                 <=>  !is_valid()  (given something ran)
    /// ```
    ///
    /// so `is_valid()` (the human `VALID` badge), the JSON `passed` flag and
    /// the grade cannot disagree.
    #[must_use]
    pub fn grade(&self) -> &'static str {
        let Some(pct) = self.implemented_score_pct() else {
            return "N/A";
        };
        if !self.is_valid() {
            return "F";
        }
        // No failures ⇒ every check that ran either passed or warned ⇒ the
        // worst reachable band here is "D". "F" is unreachable without a
        // failure, which is exactly the invariant above.
        if pct >= 95.0 {
            "A+"
        } else if pct >= 90.0 {
            "A"
        } else if pct >= 85.0 {
            "B+"
        } else if pct >= 80.0 {
            "B"
        } else if pct >= 75.0 {
            "C+"
        } else if pct >= 70.0 {
            "C"
        } else {
            "D"
        }
    }

    /// True when no check that ran reported a failure.
    ///
    /// This is the single predicate behind the human `VALID` / `INVALID`
    /// badge, the JSON `verdict`, and the `"F"` grade band — so the three
    /// cannot contradict each other (#1866).
    #[must_use]
    pub fn is_valid(&self) -> bool {
        self.failed_checks().is_empty()
    }

    /// Check if validation cleared a `min_score` threshold, expressed as a
    /// percentage of the checks that RAN (#1866).
    ///
    /// It used to compare `total_score` — raw awarded points — against the
    /// threshold, so `report.passed(95)` was unreachable for any `.apr` file
    /// (ceiling 4) and `apr import` reported "completed with warnings" on
    /// every successful import.
    ///
    /// Fails closed when nothing ran: you cannot clear a threshold against a
    /// number that was never measured. That is the same rule `apr validate`
    /// applies when refusing `--min-score` on a format that computes no score.
    #[must_use]
    pub fn passed(&self, min_score: u8) -> bool {
        self.implemented_score_pct()
            .is_some_and(|pct| pct >= f64::from(min_score))
    }

    /// Get failed checks
    #[must_use]
    pub fn failed_checks(&self) -> Vec<&ValidationCheck> {
        self.checks.iter().filter(|c| c.status.is_fail()).collect()
    }

    /// Count checks that actually ran (Pass / Fail / Warn — not Skip).
    ///
    /// Contract: apr-validate-quality-threshold-v1 (#1866) — the 100-point
    /// QA checklist contains many `Skip("Not implemented")` placeholders. A
    /// pass/fail gate computed against the full 100-point denominator marks
    /// every working model as Grade F until every stub is filled in. This
    /// helper exposes the implemented denominator so callers can gate on
    /// implementation-relative percentage instead.
    #[must_use]
    pub fn implemented_max(&self) -> u8 {
        self.checks
            .iter()
            .filter(|c| !matches!(c.status, CheckStatus::Skip(_)))
            .count()
            .min(u8::MAX as usize) as u8
    }

    /// The score together with the denominator it was actually measured
    /// against — see [`ImplementedScore`].
    #[must_use]
    pub fn implemented_score(&self) -> ImplementedScore {
        let ran = self.implemented_max();
        let passed = self
            .checks
            .iter()
            .filter(|c| c.status.is_pass())
            .count()
            .min(u8::MAX as usize) as u8;
        ImplementedScore {
            passed,
            ran,
            declared: self.checks.len(),
        }
    }

    /// Percentage of *implemented* (non-Skip) checks that passed. Returns
    /// `None` when no checks have run (entire QA suite stubbed), in which
    /// case callers should treat the score as informational rather than
    /// a hard fail (#1866).
    #[must_use]
    pub fn implemented_score_pct(&self) -> Option<f64> {
        self.implemented_score().pct()
    }

    /// The same measured score, restricted to one category (#1866).
    ///
    /// The `--quality` table printed `B. Tensor Physics & Statistics 0/25` for
    /// categories in which not a single check is even declared on the `.apr`
    /// path — an empty progress bar that reads as "measured, scored nothing"
    /// when the truth is "never ran". `ran == 0` here lets the renderer say
    /// so instead of drawing a zero.
    #[must_use]
    pub fn category_score(&self, category: Category) -> ImplementedScore {
        let in_category = || self.checks.iter().filter(|c| c.category == category);
        let clamp = |n: usize| n.min(u8::MAX as usize) as u8;
        ImplementedScore {
            passed: clamp(in_category().filter(|c| c.status.is_pass()).count()),
            ran: clamp(
                in_category()
                    .filter(|c| !matches!(c.status, CheckStatus::Skip(_)))
                    .count(),
            ),
            declared: in_category().count(),
        }
    }
}

impl Default for ValidationReport {
    fn default() -> Self {
        Self::new()
    }
}

/// Tensor statistics for physics validation
#[derive(Debug, Clone)]
pub struct TensorStats {
    /// Tensor name
    pub name: String,
    /// Number of elements
    pub count: usize,
    /// Minimum value
    pub min: f32,
    /// Maximum value
    pub max: f32,
    /// Mean value
    pub mean: f32,
    /// Standard deviation
    pub std: f32,
    /// Number of NaN values
    pub nan_count: usize,
    /// Number of Inf values
    pub inf_count: usize,
    /// Number of zero values
    pub zero_count: usize,
}

impl TensorStats {
    /// Compute statistics from tensor data
    #[must_use]
    pub fn compute(name: &str, data: &[f32]) -> Self {
        let count = data.len();
        if count == 0 {
            return Self {
                name: name.to_string(),
                count: 0,
                min: 0.0,
                max: 0.0,
                mean: 0.0,
                std: 0.0,
                nan_count: 0,
                inf_count: 0,
                zero_count: 0,
            };
        }

        let mut min = f32::INFINITY;
        let mut max = f32::NEG_INFINITY;
        let mut sum = 0.0f64;
        let mut nan_count = 0;
        let mut inf_count = 0;
        let mut zero_count = 0;

        for &v in data {
            if v.is_nan() {
                nan_count += 1;
                continue;
            }
            if v.is_infinite() {
                inf_count += 1;
                continue;
            }
            if v == 0.0 {
                zero_count += 1;
            }
            if v < min {
                min = v;
            }
            if v > max {
                max = v;
            }
            sum += f64::from(v);
        }

        let valid_count = count - nan_count - inf_count;
        let mean = if valid_count > 0 {
            (sum / valid_count as f64) as f32
        } else {
            0.0
        };

        // Compute std dev
        let mut var_sum = 0.0f64;
        for &v in data {
            if !v.is_nan() && !v.is_infinite() {
                let diff = f64::from(v) - f64::from(mean);
                var_sum += diff * diff;
            }
        }
        let std = if valid_count > 1 {
            (var_sum / (valid_count - 1) as f64).sqrt() as f32
        } else {
            0.0
        };

        Self {
            name: name.to_string(),
            count,
            min: if min.is_infinite() { 0.0 } else { min },
            max: if max.is_infinite() { 0.0 } else { max },
            mean,
            std,
            nan_count,
            inf_count,
            zero_count,
        }
    }

    /// Check if tensor has no NaN values
    #[must_use]
    pub fn has_no_nan(&self) -> bool {
        self.nan_count == 0
    }

    /// Check if tensor has no Inf values
    #[must_use]
    pub fn has_no_inf(&self) -> bool {
        self.inf_count == 0
    }

    /// Check if tensor is not all zeros
    #[must_use]
    pub fn is_not_all_zeros(&self) -> bool {
        self.zero_count < self.count
    }

    /// Check if `LayerNorm` weight mean is in valid range [0.5, 3.0]
    #[must_use]
    pub fn is_valid_layernorm_weight(&self) -> bool {
        self.mean >= 0.5 && self.mean <= 3.0
    }

    /// Check if `LayerNorm` bias mean is in valid range [-0.5, 0.5]
    #[must_use]
    pub fn is_valid_layernorm_bias(&self) -> bool {
        self.mean >= -0.5 && self.mean <= 0.5
    }

    /// Check if attention/linear weight mean is approximately 0
    #[must_use]
    pub fn is_valid_linear_weight(&self) -> bool {
        self.mean.abs() < 0.1
    }
}

/// APR file header for validation
#[derive(Debug, Clone)]
pub struct AprHeader {
    /// Magic bytes (should be "APR\0" - ONE format)
    pub magic: [u8; 4],
    /// Version major
    pub version_major: u8,
    /// Version minor
    pub version_minor: u8,
    /// Feature flags
    pub flags: u32,
    /// Metadata offset
    pub metadata_offset: u32,
    /// Metadata size
    pub metadata_size: u32,
    /// Index offset
    pub index_offset: u32,
    /// Index size
    pub index_size: u32,
    /// Data offset
    pub data_offset: u32,
}

impl AprHeader {
    /// Parse header from bytes
    pub fn parse(bytes: &[u8]) -> Result<Self> {
        if bytes.len() < 32 {
            return Err(AprenderError::FormatError {
                message: "Header too small (< 32 bytes)".to_string(),
            });
        }

        let mut magic = [0u8; 4];
        magic.copy_from_slice(bytes.get(0..4).unwrap_or(&[0u8; 4]));

        Ok(Self {
            magic,
            version_major: bytes[4],
            version_minor: bytes[5],
            flags: u32::from_le_bytes([bytes[8], bytes[9], bytes[10], bytes[11]]),
            metadata_offset: u32::from_le_bytes([bytes[12], bytes[13], bytes[14], bytes[15]]),
            metadata_size: u32::from_le_bytes([bytes[16], bytes[17], bytes[18], bytes[19]]),
            index_offset: u32::from_le_bytes([bytes[20], bytes[21], bytes[22], bytes[23]]),
            index_size: u32::from_le_bytes([bytes[24], bytes[25], bytes[26], bytes[27]]),
            data_offset: u32::from_le_bytes([bytes[28], bytes[29], bytes[30], bytes[31]]),
        })
    }

    /// Check if magic is valid (APR\0 - ONE format)
    #[must_use]
    pub fn is_valid_magic(&self) -> bool {
        self.magic == *b"APR\0"
    }

    /// Check if version is supported
    #[must_use]
    pub fn is_supported_version(&self) -> bool {
        (self.version_major == 1 && self.version_minor <= 2)
            || (self.version_major == 2 && self.version_minor == 0)
    }

    /// Check if compressed flag is set
    #[must_use]
    pub fn is_compressed(&self) -> bool {
        self.flags & 0x01 != 0
    }

    /// Check if signed flag is set
    #[must_use]
    pub fn is_signed(&self) -> bool {
        self.flags & 0x20 != 0
    }

    /// Check if encrypted flag is set
    #[must_use]
    pub fn is_encrypted(&self) -> bool {
        self.flags & 0x10 != 0
    }
}

/// Validator for APR files implementing the 100-point checklist
#[derive(Debug)]
pub struct AprValidator {
    /// Validation report
    report: ValidationReport,
    /// Tensor statistics collected during validation
    tensor_stats: Vec<TensorStats>,
}

include!("validation_impl.rs");
include!("filterbank.rs");