softgpu_core/
fidelity.rs

1//! Fidelity vocabulary for SoftGPU runs, diagnostics, and reports.
2//!
3//! Every public claim must name its fidelity level. See the master prompt §5
4//! and `docs/architecture.md`.
5
6use serde::{Deserialize, Serialize};
7use std::fmt;
8
9/// Declared fidelity level for a SoftGPU result or advertisement.
10#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
11#[serde(rename_all = "kebab-case")]
12pub enum FidelityLevel {
13    /// Host process can call a declared HSA/ROCr subset with verified C ABI.
14    Abi,
15    /// Queues, signals, AQL, registration, and dispatch flow for a declared subset.
16    Protocol,
17    /// Kernels execute on a CPU-backed semantic engine; not gfx1201 ISA evidence.
18    Functional,
19    /// Supported gfx1201 instructions execute per verified architectural semantics.
20    ArchitecturalIsa,
21    /// Extra checking that may perturb scheduling/storage/timing.
22    Sanitized,
23    /// Parameterized estimates only; not cycle accuracy unless separately named.
24    AnalyticalPerformance,
25    /// Named test + toolchain + device profile + real hardware sample evidence.
26    HardwareConformant,
27}
28
29impl FidelityLevel {
30    pub fn as_str(self) -> &'static str {
31        match self {
32            Self::Abi => "abi",
33            Self::Protocol => "protocol",
34            Self::Functional => "functional",
35            Self::ArchitecturalIsa => "architectural-isa",
36            Self::Sanitized => "sanitized",
37            Self::AnalyticalPerformance => "analytical-performance",
38            Self::HardwareConformant => "hardware-conformant",
39        }
40    }
41}
42
43impl fmt::Display for FidelityLevel {
44    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
45        f.write_str(self.as_str())
46    }
47}
48
49#[cfg(test)]
50mod tests {
51    use super::*;
52
53    #[test]
54    fn serde_round_trip_uses_kebab_case() {
55        let json = serde_json::to_string(&FidelityLevel::ArchitecturalIsa).unwrap();
56        assert_eq!(json, "\"architectural-isa\"");
57        let parsed: FidelityLevel = serde_json::from_str(&json).unwrap();
58        assert_eq!(parsed, FidelityLevel::ArchitecturalIsa);
59    }
60
61    #[test]
62    fn all_named_levels_have_stable_ids() {
63        // SoftGPU requires every claim to name a fidelity level — keep the
64        // vocabulary wired end-to-end (Display == as_str == serde kebab).
65        let levels = [
66            FidelityLevel::Abi,
67            FidelityLevel::Protocol,
68            FidelityLevel::Functional,
69            FidelityLevel::ArchitecturalIsa,
70            FidelityLevel::Sanitized,
71            FidelityLevel::AnalyticalPerformance,
72            FidelityLevel::HardwareConformant,
73        ];
74        for level in levels {
75            let json = serde_json::to_string(&level).unwrap();
76            assert_eq!(json, format!("\"{}\"", level.as_str()));
77            assert_eq!(level.to_string(), level.as_str());
78            let parsed: FidelityLevel = serde_json::from_str(&json).unwrap();
79            assert_eq!(parsed, level);
80        }
81    }
82}
softgpu_core/fidelity.rs

softgpu_core/
fidelity.rs
