Skip to main content

cgp/analysis/
contracts.rs

1//! Performance contract verification (CI/CD gate).
2//! Extends provable-contracts framework to performance bounds.
3//! See spec section 3.4 and 7.1.
4
5use anyhow::{Context, Result};
6use serde::{Deserialize, Serialize};
7use std::path::Path;
8
9/// A performance contract loaded from YAML.
10#[derive(Debug, Clone, Serialize, Deserialize)]
11pub struct PerformanceContract {
12    pub kind: String,
13    pub name: String,
14    pub version: String,
15    #[serde(default)]
16    pub kernel: String,
17    #[serde(default)]
18    pub hardware: HardwareSpec,
19    #[serde(default)]
20    pub bounds: Vec<PerformanceBound>,
21    #[serde(default)]
22    pub metrics: std::collections::HashMap<String, MetricBound>,
23    #[serde(default)]
24    pub falsification: Vec<FalsificationCheck>,
25    /// Absorb any extra fields from domain-specific contract schemas
26    #[serde(flatten, default)]
27    pub extra: std::collections::HashMap<String, ExtraValue>,
28}
29
30#[derive(Debug, Clone, Default, Serialize, Deserialize)]
31pub struct HardwareSpec {
32    pub gpu: Option<String>,
33    pub cpu: Option<String>,
34    pub compute_capability: Option<String>,
35}
36
37#[derive(Debug, Clone, Serialize, Deserialize)]
38pub struct PerformanceBound {
39    #[serde(default, deserialize_with = "deserialize_size")]
40    pub size: Vec<u32>,
41    #[serde(default)]
42    pub max_time_us: Option<f64>,
43    #[serde(default)]
44    pub min_tflops: Option<f64>,
45    #[serde(default)]
46    pub max_regression_pct: Option<f64>,
47    #[serde(default)]
48    pub min_bandwidth_gbps: Option<f64>,
49    /// Absorb domain-specific bound fields (operation, competitor, etc.)
50    #[serde(flatten, default)]
51    pub extra: std::collections::HashMap<String, ExtraValue>,
52}
53
54/// One absorbed `extra` field value. serde_yaml_ng accepted any YAML node here, but
55/// serde_json::Value refuses a non-string mapping key and has no .inf/.nan. This reads any
56/// node: scalar keys become strings and a non-finite float keeps its YAML spelling.
57#[derive(Debug, Clone, PartialEq, Serialize)]
58#[serde(transparent)]
59pub struct ExtraValue(pub serde_json::Value);
60
61impl<'de> Deserialize<'de> for ExtraValue {
62    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
63        d.deserialize_any(ExtraVisitor).map(ExtraValue)
64    }
65}
66
67struct ExtraVisitor;
68
69impl<'de> serde::de::Visitor<'de> for ExtraVisitor {
70    type Value = serde_json::Value;
71    fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
72        f.write_str("any YAML node")
73    }
74    fn visit_bool<E>(self, v: bool) -> Result<Self::Value, E> {
75        Ok(v.into())
76    }
77    fn visit_i64<E>(self, v: i64) -> Result<Self::Value, E> {
78        Ok(v.into())
79    }
80    fn visit_u64<E>(self, v: u64) -> Result<Self::Value, E> {
81        Ok(v.into())
82    }
83    fn visit_f64<E>(self, v: f64) -> Result<Self::Value, E> {
84        Ok(serde_json::Number::from_f64(v).map_or_else(
85            || serde_json::Value::String(yaml_non_finite(v).to_string()),
86            serde_json::Value::Number,
87        ))
88    }
89    fn visit_str<E>(self, v: &str) -> Result<Self::Value, E> {
90        Ok(v.into())
91    }
92    fn visit_unit<E>(self) -> Result<Self::Value, E> {
93        Ok(serde_json::Value::Null)
94    }
95    fn visit_none<E>(self) -> Result<Self::Value, E> {
96        Ok(serde_json::Value::Null)
97    }
98    fn visit_some<D: serde::Deserializer<'de>>(self, d: D) -> Result<Self::Value, D::Error> {
99        d.deserialize_any(ExtraVisitor)
100    }
101    fn visit_seq<A: serde::de::SeqAccess<'de>>(self, mut s: A) -> Result<Self::Value, A::Error> {
102        let mut items = Vec::new();
103        while let Some(ExtraValue(v)) = s.next_element()? {
104            items.push(v);
105        }
106        Ok(serde_json::Value::Array(items))
107    }
108    fn visit_map<A: serde::de::MapAccess<'de>>(self, mut m: A) -> Result<Self::Value, A::Error> {
109        let mut map = serde_json::Map::new();
110        while let Some((ExtraKey(k), ExtraValue(v))) = m.next_entry()? {
111            map.insert(k, v);
112        }
113        Ok(serde_json::Value::Object(map))
114    }
115}
116
117/// The YAML spelling of a non-finite float.
118fn yaml_non_finite(v: f64) -> &'static str {
119    if v.is_nan() {
120        ".nan"
121    } else if v > 0.0 {
122        ".inf"
123    } else {
124        "-.inf"
125    }
126}
127
128/// A mapping key inside an `extra` value: any scalar, as a string.
129struct ExtraKey(String);
130
131impl<'de> Deserialize<'de> for ExtraKey {
132    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
133        match d.deserialize_any(ExtraVisitor)? {
134            serde_json::Value::String(s) => Ok(ExtraKey(s)),
135            serde_json::Value::Null => Ok(ExtraKey("~".to_string())),
136            v @ (serde_json::Value::Bool(_) | serde_json::Value::Number(_)) => {
137                Ok(ExtraKey(v.to_string()))
138            }
139            _ => Err(serde::de::Error::custom("a mapping key must be a scalar")),
140        }
141    }
142}
143
144/// Accept both `size: 1024` (single int) and `size: [1024, 1024, 1024]` (sequence).
145fn deserialize_size<'de, D>(deserializer: D) -> Result<Vec<u32>, D::Error>
146where
147    D: serde::Deserializer<'de>,
148{
149    use serde::de;
150
151    struct SizeVisitor;
152    impl<'de> de::Visitor<'de> for SizeVisitor {
153        type Value = Vec<u32>;
154        fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
155            f.write_str("an integer or sequence of integers")
156        }
157        fn visit_u64<E: de::Error>(self, v: u64) -> Result<Vec<u32>, E> {
158            Ok(vec![v as u32])
159        }
160        fn visit_i64<E: de::Error>(self, v: i64) -> Result<Vec<u32>, E> {
161            Ok(vec![v as u32])
162        }
163        fn visit_seq<A: de::SeqAccess<'de>>(self, mut seq: A) -> Result<Vec<u32>, A::Error> {
164            let mut v = Vec::new();
165            while let Some(elem) = seq.next_element::<u32>()? {
166                v.push(elem);
167            }
168            Ok(v)
169        }
170        fn visit_none<E: de::Error>(self) -> Result<Vec<u32>, E> {
171            Ok(Vec::new())
172        }
173        fn visit_unit<E: de::Error>(self) -> Result<Vec<u32>, E> {
174            Ok(Vec::new())
175        }
176    }
177    deserializer.deserialize_any(SizeVisitor)
178}
179
180#[derive(Debug, Clone, Serialize, Deserialize)]
181pub struct MetricBound {
182    pub min: Option<f64>,
183    pub max: Option<f64>,
184}
185
186#[derive(Debug, Clone, Serialize, Deserialize)]
187pub struct FalsificationCheck {
188    pub name: String,
189    #[serde(default)]
190    pub description: String,
191    #[serde(default)]
192    pub check: String,
193    #[serde(flatten, default)]
194    pub extra: std::collections::HashMap<String, ExtraValue>,
195}
196
197/// Result of verifying a single contract.
198#[derive(Debug)]
199pub struct ContractVerification {
200    pub contract_name: String,
201    pub passed: Vec<String>,
202    pub failed: Vec<String>,
203    pub skipped: Vec<String>,
204}
205
206impl ContractVerification {
207    pub fn is_pass(&self) -> bool {
208        self.failed.is_empty()
209    }
210}
211
212/// Load a performance contract from a YAML file.
213pub fn load_contract(path: &Path) -> Result<PerformanceContract> {
214    let content = std::fs::read_to_string(path)
215        .with_context(|| format!("Failed to read contract: {}", path.display()))?;
216    let contract: PerformanceContract = serde_saphyr::from_str_with_options(&content, serde_saphyr::options! { strict_booleans: true, merge_keys: serde_saphyr::MergeKeyPolicy::AsOrdinary, emit_comments: false, reject_non_finite_typeless_float: false })
217        .with_context(|| format!("Failed to parse contract: {}", path.display()))?;
218    Ok(contract)
219}
220
221/// Load all contracts from a directory.
222pub fn load_contracts_dir(dir: &Path) -> Result<Vec<PerformanceContract>> {
223    let mut contracts = Vec::new();
224    if dir.is_dir() {
225        for entry in std::fs::read_dir(dir)? {
226            let entry = entry?;
227            let path = entry.path();
228            if path.extension().is_some_and(|e| e == "yaml" || e == "yml") {
229                match load_contract(&path) {
230                    Ok(c) => contracts.push(c),
231                    Err(e) => eprintln!("Warning: skipping {}: {e}", path.display()),
232                }
233            }
234        }
235    }
236    Ok(contracts)
237}
238
239/// Verify a contract against measured values.
240/// Loads saved profiles from /tmp/cgp-{kernel}-{size}.json if available,
241/// and checks performance bounds + falsification expressions.
242pub fn verify_contract(contract: &PerformanceContract) -> ContractVerification {
243    let mut result = ContractVerification {
244        contract_name: contract.name.clone(),
245        passed: Vec::new(),
246        failed: Vec::new(),
247        skipped: Vec::new(),
248    };
249    validate_contract_metadata(contract, &mut result);
250    for (i, bound) in contract.bounds.iter().enumerate() {
251        verify_single_bound(contract, bound, i, &mut result);
252    }
253    for check in &contract.falsification {
254        verify_single_falsification(contract, check, &mut result);
255    }
256    result
257}
258
259/// Check the contract has the required `kind` field and record `kernel` if present.
260fn validate_contract_metadata(contract: &PerformanceContract, result: &mut ContractVerification) {
261    if contract.kind.is_empty() {
262        result
263            .failed
264            .push("Contract missing 'kind' field".to_string());
265    } else {
266        result.passed.push(format!("kind: {}", contract.kind));
267    }
268    if contract.kernel.is_empty() {
269        result
270            .skipped
271            .push("No kernel field — domain-specific contract".to_string());
272    } else {
273        result.passed.push(format!("kernel: {}", contract.kernel));
274    }
275}
276
277/// Verify one `PerformanceBound`: structural pass if no size, else compare to profile data.
278fn verify_single_bound(
279    contract: &PerformanceContract,
280    bound: &PerformanceBound,
281    i: usize,
282    result: &mut ContractVerification,
283) {
284    if bound.size.is_empty() {
285        result
286            .passed
287            .push(format!("Bound {i}: structural (no size)"));
288        return;
289    }
290    let size = bound.size[0];
291    match load_kernel_profile(&contract.kernel, size) {
292        Some(p) => check_bound_thresholds(bound, i, &p, result),
293        None => check_bound_structural(bound, i, result),
294    }
295}
296
297/// Load `/tmp/cgp-{kernel}-{size}.json` profile if present and parseable.
298fn load_kernel_profile(kernel: &str, size: u32) -> Option<crate::metrics::catalog::FullProfile> {
299    let profile_path = format!("/tmp/cgp-{kernel}-{size}.json");
300    let path = std::path::Path::new(&profile_path);
301    if !path.exists() {
302        return None;
303    }
304    crate::metrics::export::load_json(path).ok()
305}
306
307/// Run each individual threshold check present on the bound.
308fn check_bound_thresholds(
309    bound: &PerformanceBound,
310    i: usize,
311    p: &crate::metrics::catalog::FullProfile,
312    result: &mut ContractVerification,
313) {
314    check_max_time(bound, i, p, result);
315    check_min_tflops(bound, i, p, result);
316    check_min_bandwidth(bound, i, p, result);
317}
318
319/// Compare `wall_clock_time_us` to `bound.max_time_us` (lower is better).
320fn check_max_time(
321    bound: &PerformanceBound,
322    i: usize,
323    p: &crate::metrics::catalog::FullProfile,
324    result: &mut ContractVerification,
325) {
326    let Some(max_time) = bound.max_time_us else {
327        return;
328    };
329    let actual = p.timing.wall_clock_time_us;
330    if actual <= max_time {
331        result
332            .passed
333            .push(format!("Bound {i}: time {actual:.1}us <= {max_time:.1}us"));
334    } else {
335        result.failed.push(format!(
336            "Bound {i}: time {actual:.1}us > {max_time:.1}us EXCEEDED"
337        ));
338    }
339}
340
341/// Compare measured TFLOP/s to `bound.min_tflops` (higher is better).
342fn check_min_tflops(
343    bound: &PerformanceBound,
344    i: usize,
345    p: &crate::metrics::catalog::FullProfile,
346    result: &mut ContractVerification,
347) {
348    let Some(min_tflops) = bound.min_tflops else {
349        return;
350    };
351    let actual = p.throughput.tflops;
352    if actual >= min_tflops {
353        result
354            .passed
355            .push(format!("Bound {i}: {actual:.1} TFLOP/s >= {min_tflops:.1}"));
356    } else {
357        result.failed.push(format!(
358            "Bound {i}: {actual:.1} TFLOP/s < {min_tflops:.1} BELOW MINIMUM"
359        ));
360    }
361}
362
363/// Compare measured GB/s to `bound.min_bandwidth_gbps` (higher is better).
364fn check_min_bandwidth(
365    bound: &PerformanceBound,
366    i: usize,
367    p: &crate::metrics::catalog::FullProfile,
368    result: &mut ContractVerification,
369) {
370    let Some(min_bw) = bound.min_bandwidth_gbps else {
371        return;
372    };
373    let actual = p.throughput.bandwidth_gbps;
374    if actual >= min_bw {
375        result
376            .passed
377            .push(format!("Bound {i}: {actual:.1} GB/s >= {min_bw:.1}"));
378    } else {
379        result.failed.push(format!(
380            "Bound {i}: {actual:.1} GB/s < {min_bw:.1} BELOW MINIMUM"
381        ));
382    }
383}
384
385/// No profile found: record the bound structurally and flag empty-criteria bounds.
386fn check_bound_structural(bound: &PerformanceBound, i: usize, result: &mut ContractVerification) {
387    result
388        .passed
389        .push(format!("Bound {i}: size {:?}", bound.size));
390    if bound.max_time_us.is_none()
391        && bound.min_tflops.is_none()
392        && bound.min_bandwidth_gbps.is_none()
393    {
394        result
395            .skipped
396            .push(format!("Bound {i}: no criteria specified"));
397    }
398}
399
400/// Verify one falsification clause: validate fields, then evaluate against a profile.
401fn verify_single_falsification(
402    contract: &PerformanceContract,
403    check: &FalsificationCheck,
404    result: &mut ContractVerification,
405) {
406    if check.name.is_empty() || check.check.is_empty() {
407        result.failed.push(format!(
408            "Falsification '{}': missing name or check",
409            check.name
410        ));
411        return;
412    }
413    let size = contract
414        .bounds
415        .first()
416        .and_then(|b| b.size.first())
417        .copied()
418        .unwrap_or(512);
419    let profile_path = format!("/tmp/cgp-{}-{size}.json", contract.kernel);
420    match load_kernel_profile(&contract.kernel, size) {
421        Some(p) => {
422            if evaluate_check(&check.check, &p) {
423                result.passed.push(format!("FALSIFY {}: PASS", check.name));
424            } else {
425                result.failed.push(format!(
426                    "FALSIFY {}: FAIL ({})",
427                    check.name, check.description
428                ));
429            }
430        }
431        None => {
432            result.skipped.push(format!(
433                "FALSIFY {}: {} (no profile at {profile_path})",
434                check.name, check.description
435            ));
436        }
437    }
438}
439
440/// Evaluate a simple check expression against a profile.
441/// Supports: "field > value", "field < value", "field >= value", "field == value"
442fn evaluate_check(expr: &str, profile: &crate::metrics::catalog::FullProfile) -> bool {
443    let parts: Vec<&str> = expr.split_whitespace().collect();
444    if parts.len() != 3 {
445        return false;
446    }
447    let field = parts[0];
448    let op = parts[1];
449    let threshold: f64 = match parts[2].parse() {
450        Ok(v) => v,
451        Err(_) => return false,
452    };
453
454    let value = match field {
455        "tflops" => profile.throughput.tflops,
456        "wall_clock_time_us" => profile.timing.wall_clock_time_us,
457        "bandwidth_gbps" => profile.throughput.bandwidth_gbps,
458        "arithmetic_intensity" => profile.throughput.arithmetic_intensity,
459        "warp_execution_efficiency" => profile
460            .gpu_compute
461            .as_ref()
462            .map_or(0.0, |g| g.warp_execution_efficiency_pct),
463        "achieved_occupancy" => profile
464            .gpu_compute
465            .as_ref()
466            .map_or(0.0, |g| g.achieved_occupancy_pct),
467        "global_load_efficiency" => profile
468            .gpu_memory
469            .as_ref()
470            .map_or(0.0, |g| g.global_load_efficiency_pct),
471        _ => return false,
472    };
473
474    match op {
475        ">" => value > threshold,
476        "<" => value < threshold,
477        ">=" => value >= threshold,
478        "<=" => value <= threshold,
479        "==" => (value - threshold).abs() < 0.001,
480        _ => false,
481    }
482}
483
484/// Run contract verification for a directory of contracts.
485pub fn run_verify(
486    contracts_dir: Option<&str>,
487    contract_file: Option<&str>,
488    self_verify: bool,
489    fail_on_regression: bool,
490) -> Result<()> {
491    let Some(contracts) = resolve_contracts_input(contracts_dir, contract_file, self_verify)?
492    else {
493        return Ok(());
494    };
495
496    println!("\n=== cgp Contract Verification ===\n");
497    let totals = run_verify_all(&contracts);
498    println!(
499        "\n  Total: {} pass, {} fail, {} skip",
500        totals.pass, totals.fail, totals.skip
501    );
502    if totals.fail > 0 && fail_on_regression {
503        anyhow::bail!("{} contract verification(s) failed", totals.fail);
504    }
505    println!();
506    Ok(())
507}
508
509/// Resolve the set of contracts to verify from CLI flags. Returns `None` when the
510/// self-verify directory is absent (early-exit signal for `run_verify`).
511fn resolve_contracts_input(
512    contracts_dir: Option<&str>,
513    contract_file: Option<&str>,
514    self_verify: bool,
515) -> Result<Option<Vec<PerformanceContract>>> {
516    if let Some(dir) = contracts_dir {
517        return Ok(Some(load_contracts_dir(Path::new(dir))?));
518    }
519    if let Some(file) = contract_file {
520        return Ok(Some(vec![load_contract(Path::new(file))?]));
521    }
522    if self_verify {
523        let dir = Path::new("contracts/cgp");
524        if !dir.exists() {
525            println!("No contracts found at contracts/cgp/");
526            return Ok(None);
527        }
528        return Ok(Some(load_contracts_dir(dir)?));
529    }
530    anyhow::bail!("Specify --contracts-dir, --contract, or --self");
531}
532
533#[derive(Default)]
534struct VerifyTotals {
535    pass: usize,
536    fail: usize,
537    skip: usize,
538}
539
540/// Verify every contract and print per-contract status; return aggregate counts.
541fn run_verify_all(contracts: &[PerformanceContract]) -> VerifyTotals {
542    let mut totals = VerifyTotals::default();
543    for c in contracts {
544        let result = verify_contract(c);
545        print_contract_status(c, &result);
546        totals.pass += result.passed.len();
547        totals.fail += result.failed.len();
548        totals.skip += result.skipped.len();
549    }
550    totals
551}
552
553fn print_contract_status(c: &PerformanceContract, result: &ContractVerification) {
554    let status = if result.is_pass() {
555        "\x1b[32mPASS\x1b[0m"
556    } else {
557        "\x1b[31mFAIL\x1b[0m"
558    };
559    println!(
560        "  {} {} ({} pass, {} fail, {} skip)",
561        status,
562        c.name,
563        result.passed.len(),
564        result.failed.len(),
565        result.skipped.len()
566    );
567}
568
569/// Generate a performance contract YAML from a profile or estimated values.
570pub fn run_generate(kernel: &str, size: u32, tolerance: f64) -> Result<()> {
571    // Try to load a saved profile for this kernel
572    let profile_path = format!("/tmp/cgp-{kernel}-{size}.json");
573    let profile = if std::path::Path::new(&profile_path).exists() {
574        Some(crate::metrics::export::load_json(std::path::Path::new(
575            &profile_path,
576        ))?)
577    } else {
578        None
579    };
580
581    let (time_us, tflops) = match &profile {
582        Some(p) => (p.timing.wall_clock_time_us, p.throughput.tflops),
583        None => {
584            // Estimate for GEMM
585            let flops = 2.0 * (size as f64).powi(3);
586            let est_time = 23.2 * (size as f64 / 512.0).powi(3); // Scale from 512 baseline
587            let est_tflops = flops / (est_time * 1e-6) / 1e12;
588            (est_time, est_tflops)
589        }
590    };
591
592    let max_time = time_us * (1.0 + tolerance / 100.0);
593    let min_tflops = tflops * (1.0 - tolerance / 100.0);
594
595    // Detect GPU
596    let gpu_name = std::process::Command::new("nvidia-smi")
597        .args(["--query-gpu=name", "--format=csv,noheader"])
598        .output()
599        .ok()
600        .filter(|o| o.status.success())
601        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
602        .unwrap_or_else(|| "Unknown GPU".to_string());
603
604    let contract_yaml = format!(
605        r#"# Generated by cgp contract generate
606# Kernel: {kernel} at size {size}x{size}x{size}
607# Tolerance: {tolerance}%
608kind: PerformanceContract
609name: {kernel}-{size}
610version: "1.0.0"
611kernel: {kernel}
612hardware:
613  gpu: "{gpu_name}"
614  compute_capability: "8.9"
615
616bounds:
617  - size: [{size}, {size}, {size}]
618    max_time_us: {max_time:.1}
619    min_tflops: {min_tflops:.1}
620    max_regression_pct: {tolerance}
621
622metrics:
623  warp_execution_efficiency:
624    min: 95.0
625  achieved_occupancy:
626    min: 25.0
627
628falsification:
629  - name: FALSIFY-{kernel_upper}-001
630    description: "{kernel} must achieve >{min_tflops:.1} TFLOP/s at {size}x{size}"
631    check: "tflops > {min_tflops:.1}"
632  - name: FALSIFY-{kernel_upper}-002
633    description: "{kernel} must complete in <{max_time:.1}us at {size}x{size}"
634    check: "wall_clock_time_us < {max_time:.1}"
635"#,
636        kernel = kernel,
637        size = size,
638        tolerance = tolerance,
639        gpu_name = gpu_name,
640        max_time = max_time,
641        min_tflops = min_tflops,
642        kernel_upper = kernel.to_uppercase().replace('-', "_"),
643    );
644
645    // Write to contracts directory
646    let contracts_dir = std::path::Path::new("contracts/cgp");
647    std::fs::create_dir_all(contracts_dir)?;
648    let contract_path = contracts_dir.join(format!("{kernel}-{size}-v1.yaml"));
649    std::fs::write(&contract_path, &contract_yaml)?;
650
651    println!("Generated contract: {}", contract_path.display());
652    println!();
653    print!("{contract_yaml}");
654
655    Ok(())
656}
657
658#[cfg(test)]
659mod tests {
660    use super::*;
661
662    fn sample_contract() -> PerformanceContract {
663        PerformanceContract {
664            kind: "PerformanceContract".to_string(),
665            name: "test-gemm-contract".to_string(),
666            version: "1.0.0".to_string(),
667            kernel: "gemm_cta_wmma_fp16".to_string(),
668            hardware: HardwareSpec {
669                gpu: Some("NVIDIA GeForce RTX 4090".to_string()),
670                cpu: None,
671                compute_capability: Some("8.9".to_string()),
672            },
673            bounds: vec![PerformanceBound {
674                size: vec![512, 512, 512],
675                max_time_us: Some(30.0),
676                min_tflops: Some(9.0),
677                max_regression_pct: Some(10.0),
678                min_bandwidth_gbps: None,
679                extra: Default::default(),
680            }],
681            metrics: {
682                let mut m = std::collections::HashMap::new();
683                m.insert(
684                    "warp_execution_efficiency".to_string(),
685                    MetricBound {
686                        min: Some(95.0),
687                        max: None,
688                    },
689                );
690                m
691            },
692            falsification: vec![FalsificationCheck {
693                name: "FALSIFY-TEST-001".to_string(),
694                description: "CTA WMMA must achieve >9 TFLOP/s".to_string(),
695                check: "tflops > 9.0".to_string(),
696                extra: Default::default(),
697            }],
698            extra: Default::default(),
699        }
700    }
701
702    #[test]
703    fn test_verify_valid_contract() {
704        let contract = sample_contract();
705        let result = verify_contract(&contract);
706        assert!(result.is_pass());
707        assert!(!result.passed.is_empty());
708    }
709
710    #[test]
711    fn test_verify_missing_kernel_is_skipped() {
712        let mut contract = sample_contract();
713        contract.kernel = String::new();
714        let result = verify_contract(&contract);
715        // Domain-specific contracts without kernel are allowed (skipped, not failed)
716        assert!(result.is_pass());
717        assert!(!result.skipped.is_empty());
718    }
719
720    /// Haiku C314 Q1 (#5326): the three flatten `extra` maps are serde_json::Value now.
721    /// A contract carrying .inf/.nan, a tagged node or a non-string key in an extra field
722    /// must still load, as it did under serde_yaml_ng.
723    /// A tagged value keeps its tag as a one-key map.
724    #[test]
725    fn test_extra_fields_keep_loading_yaml_only_values() {
726        let yaml = r#"
727kind: PerformanceContract
728name: hazards
729version: "1.0.0"
730kernel: k
731ceiling: .inf
732floor: -.inf
733undefined: .nan
734tagged: !custom value
735by_id:
736  1: one
737  2.5: two
738  true: three
739bounds:
740  - size: 512
741    max_time_us: 30.0
742    headroom: .inf
743    note: !tag text
744    table: {7: seven}
745falsification:
746  - name: FALSIFY-HAZ-001
747    limit: .nan
748    marker: !m x
749    keyed: {3: three}
750"#;
751        let dir = tempfile::tempdir().expect("tempdir");
752        let path = dir.path().join("hazards.yaml");
753        std::fs::write(&path, yaml).expect("write");
754        let c = load_contract(&path).expect("a contract with YAML-only extras still loads");
755        let s = |m: &std::collections::HashMap<String, ExtraValue>, k: &str| m[k].0.clone();
756        assert_eq!(s(&c.extra, "ceiling"), ".inf");
757        assert_eq!(s(&c.extra, "floor"), "-.inf");
758        assert_eq!(s(&c.extra, "undefined"), ".nan");
759        assert_eq!(s(&c.extra, "tagged")["custom"], "value");
760        let by_id = s(&c.extra, "by_id");
761        assert_eq!(by_id["1"], "one");
762        assert_eq!(by_id["2.5"], "two");
763        assert_eq!(by_id["true"], "three");
764        let b = &c.bounds[0].extra;
765        assert_eq!(s(b, "headroom"), ".inf");
766        assert_eq!(s(b, "note")["tag"], "text");
767        assert_eq!(s(b, "table")["7"], "seven");
768        let f = &c.falsification[0].extra;
769        assert_eq!(s(f, "limit"), ".nan");
770        assert_eq!(s(f, "marker")["m"], "x");
771        assert_eq!(s(f, "keyed")["3"], "three");
772    }
773
774    #[test]
775    fn test_contract_yaml_roundtrip() {
776        let contract = sample_contract();
777        let yaml = serde_saphyr::to_string(&contract).unwrap();
778        let parsed: PerformanceContract = serde_saphyr::from_str_with_options(&yaml, serde_saphyr::options! { strict_booleans: true, merge_keys: serde_saphyr::MergeKeyPolicy::AsOrdinary, emit_comments: false, reject_non_finite_typeless_float: false }).unwrap();
779        assert_eq!(parsed.name, contract.name);
780        assert_eq!(parsed.kernel, contract.kernel);
781        assert_eq!(parsed.bounds.len(), 1);
782        assert_eq!(parsed.bounds[0].size, vec![512, 512, 512]);
783    }
784
785    #[test]
786    fn test_contract_falsification_checks() {
787        let contract = sample_contract();
788        let result = verify_contract(&contract);
789        // Falsification checks are skipped (need runtime data), not failed
790        assert!(result.is_pass());
791        assert!(!result.skipped.is_empty());
792    }
793}