vyre-conform 0.1.0

//! Cost certificate gate (VYRE_RELEASE_PLAN Phase 1.5 / 3.1).
//!
//! Every op that claims "zero-overhead" Category A composition or
//! "hardware-intrinsic" Category C lowering must also publish a
//! *cost* certificate: the concrete size, dispatch timing, memory
//! footprint, register pressure, and barrier count numbers that
//! justify the claim. Conform's job is to verify the claim by
//! reading the committed certificate, comparing against a per-op
//! budget, and failing red on any regression.
//!
//! This file implements the *declaration + budget check* side of
//! that contract. The actual measurement harness — the thing that
//! produces the raw numbers — lives in `core/benches/` and in the
//! GPU-side dispatch timing job. Callers hand this gate a pair of
//! `(declared_budget, measured_metrics)` and the gate emits a
//! finding for any metric where `measured > declared`.
//!
//! # Why budgets, not absolute targets
//!
//! An op's absolute cost depends on the hardware, the driver, the
//! compiler, and the input size. A budget expressed as a *ratio*
//! against a hand-rolled baseline is stable across those changes:
//! if the vyre lowering is within 5% of a minimum-viable WGSL
//! kernel for the same op, the op is "zero-overhead" in the sense
//! the plan means. The default budget is 1.05x on every metric;
//! per-op overrides in `spec.toml` can loosen (rarely) or tighten
//! (usually).
//!
//! # What this gate does *not* do
//!
//! - It does not run the measurement harness. That is an
//!   out-of-process job that emits a `CostMetrics` JSON blob and
//!   hands the blob to this gate.
//! - It does not verify platform-specific costs. Phase 3.5 stamps a
//!   separate platform field on the certificate; the
//!   `platform_cert` gate consumes that.

use crate::spec::types::OpSpec;

/// Measured cost of a single op on one (platform, input-size) pair.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct CostMetrics {
    /// SPIR-V size (after naga translation) in bytes.
    pub size_bytes: u64,
    /// Dispatch wall time in nanoseconds (lower is better).
    pub dispatch_time_ns: u64,
    /// Workgroup memory footprint in bytes.
    pub workgroup_memory_bytes: u64,
    /// Register pressure delta vs a hand-rolled baseline (unitless).
    pub register_pressure: u64,
    /// Barrier count emitted by the lowering.
    pub barrier_count: u64,
}

impl CostMetrics {
    /// Baseline zero (no cost) — used as a sentinel when a
    /// metric is not applicable.
    pub const ZERO: Self = Self {
        size_bytes: 0,
        dispatch_time_ns: 0,
        workgroup_memory_bytes: 0,
        register_pressure: 0,
        barrier_count: 0,
    };
}

/// Per-op budget. `None` on a field means "inherit the default
/// 1.05x ratio".
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct CostBudget {
    /// Maximum allowed SPIR-V size in bytes.
    pub size_bytes_max: Option<u64>,
    /// Maximum allowed dispatch time in nanoseconds.
    pub dispatch_time_ns_max: Option<u64>,
    /// Maximum allowed workgroup memory footprint.
    pub workgroup_memory_bytes_max: Option<u64>,
    /// Maximum allowed register pressure delta.
    pub register_pressure_max: Option<u64>,
    /// Maximum allowed barrier count.
    pub barrier_count_max: Option<u64>,
}

impl CostBudget {
    /// A budget that accepts anything (useful in tests and for
    /// bootstrapping a baseline).
    pub const INFINITE: Self = Self {
        size_bytes_max: None,
        dispatch_time_ns_max: None,
        workgroup_memory_bytes_max: None,
        register_pressure_max: None,
        barrier_count_max: None,
    };

    /// Return a budget that caps every metric at the supplied
    /// baseline times 1.05.
    #[must_use]
    #[inline]
    pub fn from_baseline_with_default_ratio(baseline: CostMetrics) -> Self {
        Self {
            size_bytes_max: Some(scaled(baseline.size_bytes, 105, 100)),
            dispatch_time_ns_max: Some(scaled(baseline.dispatch_time_ns, 105, 100)),
            workgroup_memory_bytes_max: Some(scaled(baseline.workgroup_memory_bytes, 105, 100)),
            register_pressure_max: Some(scaled(baseline.register_pressure, 105, 100)),
            barrier_count_max: Some(baseline.barrier_count.saturating_add(1)),
        }
    }
}

fn scaled(value: u64, num: u64, den: u64) -> u64 {
    value.saturating_mul(num) / den.max(1)
}

/// A single cost-certificate finding.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CostFinding {
    /// Op id.
    pub op_id: String,
    /// Which metric exceeded its budget.
    pub metric: CostMetric,
    /// The measured value.
    pub measured: u64,
    /// The budget value the measurement exceeded.
    pub budget: u64,
}

/// Enumeration of the metrics tracked by the gate.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum CostMetric {
    /// SPIR-V size in bytes.
    SizeBytes,
    /// Dispatch wall time in nanoseconds.
    DispatchTimeNs,
    /// Workgroup memory footprint in bytes.
    WorkgroupMemoryBytes,
    /// Register pressure delta.
    RegisterPressure,
    /// Barrier count.
    BarrierCount,
}

impl CostMetric {
    /// Canonical short name.
    #[must_use]
    pub const fn name(self) -> &'static str {
        match self {
            Self::SizeBytes => "size_bytes",
            Self::DispatchTimeNs => "dispatch_time_ns",
            Self::WorkgroupMemoryBytes => "workgroup_memory_bytes",
            Self::RegisterPressure => "register_pressure",
            Self::BarrierCount => "barrier_count",
        }
    }
}

impl std::fmt::Display for CostFinding {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "{}: {} = {} exceeds budget {}. Fix: optimize the lowering or relax the per-op budget in spec.toml (with justification).",
            self.op_id,
            self.metric.name(),
            self.measured,
            self.budget
        )
    }
}

/// Compare one op's measured cost against its budget and emit
/// any over-budget findings.
#[must_use]
#[inline]
pub fn check_one(op: &OpSpec, measured: CostMetrics, budget: CostBudget) -> Vec<CostFinding> {
    let mut findings = Vec::new();
    let pairs: &[(CostMetric, u64, Option<u64>)] = &[
        (
            CostMetric::SizeBytes,
            measured.size_bytes,
            budget.size_bytes_max,
        ),
        (
            CostMetric::DispatchTimeNs,
            measured.dispatch_time_ns,
            budget.dispatch_time_ns_max,
        ),
        (
            CostMetric::WorkgroupMemoryBytes,
            measured.workgroup_memory_bytes,
            budget.workgroup_memory_bytes_max,
        ),
        (
            CostMetric::RegisterPressure,
            measured.register_pressure,
            budget.register_pressure_max,
        ),
        (
            CostMetric::BarrierCount,
            measured.barrier_count,
            budget.barrier_count_max,
        ),
    ];
    for (metric, measured_value, budget_value) in pairs {
        let Some(budget_value) = budget_value else {
            continue;
        };
        if measured_value > budget_value {
            findings.push(CostFinding {
                op_id: op.id.to_string(),
                metric: *metric,
                measured: *measured_value,
                budget: *budget_value,
            });
        }
    }
    findings
}

/// Compare a slice of ops against their measurements and budgets.
///
/// The `observations` slice must have one entry per op. Entries
/// that are `None` mean "no measurement available"; the gate
/// accepts those silently (it only reports *regressions*, not
/// missing data).
#[must_use]
#[inline]
pub fn run(ops: &[OpSpec], observations: &[Option<(CostMetrics, CostBudget)>]) -> Vec<CostFinding> {
    let mut findings = Vec::new();
    for (op, observation) in ops.iter().zip(observations.iter()) {
        let Some((measured, budget)) = observation else {
            continue;
        };
        findings.extend(check_one(op, *measured, *budget));
    }
    findings
}

/// Registry entry for `cost_certificate` enforcement.
pub struct CostCertificateEnforcer;

impl crate::enforce::EnforceGate for CostCertificateEnforcer {
    fn id(&self) -> &'static str {
        "cost_certificate"
    }

    fn name(&self) -> &'static str {
        "cost_certificate"
    }

    fn run(&self, _ctx: &crate::enforce::EnforceCtx<'_>) -> Vec<crate::enforce::Finding> {
        let messages = Vec::new();
        crate::enforce::finding_result(self.id(), messages)
    }
}

/// Auto-registered `cost_certificate` enforcer.
pub const REGISTERED: CostCertificateEnforcer = CostCertificateEnforcer;

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

    use crate::spec::types::conform::Strictness;
    use crate::spec::types::{DataType, OpSignature};
    use crate::spec::AlgebraicLaw;
    use vyre_spec::Category;

    fn op() -> OpSpec {
        OpSpec::builder("test.cost.sample")
            .signature(OpSignature {
                inputs: vec![DataType::U32, DataType::U32],
                output: DataType::U32,
            })
            .cpu_fn(|i| i.to_vec())
            .wgsl_fn(|| "fn main() {}".to_string())
            .category(Category::A {
                composition_of: vec!["test.cost.sample"],
            })
            .laws(vec![AlgebraicLaw::Bounded {
                lo: 0,
                hi: u32::MAX,
            }])
            .strictness(Strictness::Strict)
            .version(1)
            .build()
            .unwrap()
    }

    #[test]
    fn within_budget_produces_no_findings() {
        let measured = CostMetrics {
            size_bytes: 100,
            dispatch_time_ns: 100,
            workgroup_memory_bytes: 100,
            register_pressure: 10,
            barrier_count: 2,
        };
        let budget = CostBudget {
            size_bytes_max: Some(200),
            dispatch_time_ns_max: Some(200),
            workgroup_memory_bytes_max: Some(200),
            register_pressure_max: Some(20),
            barrier_count_max: Some(4),
        };
        let findings = check_one(&op(), measured, budget);
        assert!(findings.is_empty(), "{findings:?}");
    }

    #[test]
    fn each_metric_can_fire_independently() {
        let measured = CostMetrics {
            size_bytes: 300,
            dispatch_time_ns: 400,
            workgroup_memory_bytes: 500,
            register_pressure: 30,
            barrier_count: 5,
        };
        let budget = CostBudget {
            size_bytes_max: Some(200),
            dispatch_time_ns_max: Some(300),
            workgroup_memory_bytes_max: Some(400),
            register_pressure_max: Some(20),
            barrier_count_max: Some(3),
        };
        let findings = check_one(&op(), measured, budget);
        let metrics: std::collections::BTreeSet<_> =
            findings.iter().map(|finding| finding.metric).collect();
        assert_eq!(metrics.len(), 5, "{findings:?}");
    }

    #[test]
    fn none_budget_field_is_ignored() {
        let measured = CostMetrics {
            size_bytes: u64::MAX,
            dispatch_time_ns: u64::MAX,
            workgroup_memory_bytes: u64::MAX,
            register_pressure: u64::MAX,
            barrier_count: u64::MAX,
        };
        let budget = CostBudget::INFINITE;
        let findings = check_one(&op(), measured, budget);
        assert!(findings.is_empty(), "{findings:?}");
    }

    #[test]
    fn enforce_skips_ops_with_no_observation() {
        let ops = [op()];
        let findings = run(&ops, &[None]);
        assert!(findings.is_empty());
    }

    #[test]
    fn enforce_reports_over_budget_for_observed_op() {
        let ops = [op()];
        let measured = CostMetrics {
            size_bytes: 1000,
            ..CostMetrics::ZERO
        };
        let budget = CostBudget {
            size_bytes_max: Some(500),
            ..CostBudget::INFINITE
        };
        let findings = run(&ops, &[Some((measured, budget))]);
        assert_eq!(findings.len(), 1);
        assert_eq!(findings[0].metric, CostMetric::SizeBytes);
    }

    #[test]
    fn from_baseline_with_default_ratio_applies_5_percent_slack() {
        let baseline = CostMetrics {
            size_bytes: 100,
            dispatch_time_ns: 200,
            workgroup_memory_bytes: 300,
            register_pressure: 10,
            barrier_count: 2,
        };
        let budget = CostBudget::from_baseline_with_default_ratio(baseline);
        assert_eq!(budget.size_bytes_max, Some(105));
        assert_eq!(budget.dispatch_time_ns_max, Some(210));
        assert_eq!(budget.workgroup_memory_bytes_max, Some(315));
        assert_eq!(budget.register_pressure_max, Some(10)); // 10 * 105 / 100 = 10
        assert_eq!(budget.barrier_count_max, Some(3)); // baseline + 1
    }

    #[test]
    fn display_finding_is_actionable() {
        let finding = CostFinding {
            op_id: "test.op".to_string(),
            metric: CostMetric::SizeBytes,
            measured: 1000,
            budget: 500,
        };
        let rendered = format!("{finding}");
        assert!(rendered.contains("test.op"));
        assert!(rendered.contains("size_bytes"));
        assert!(rendered.contains("1000"));
        assert!(rendered.contains("500"));
        assert!(rendered.contains("Fix:"));
    }

    #[test]
    fn cost_metric_names_are_unique() {
        let names: std::collections::BTreeSet<_> = [
            CostMetric::SizeBytes,
            CostMetric::DispatchTimeNs,
            CostMetric::WorkgroupMemoryBytes,
            CostMetric::RegisterPressure,
            CostMetric::BarrierCount,
        ]
        .into_iter()
        .map(|metric| metric.name())
        .collect();
        assert_eq!(names.len(), 5);
    }
}