Skip to main content

vyre_harness/
lib.rs

1#![forbid(unsafe_code)]
2//! Universal Cat-A op harness registry + Region builder.
3//!
4//! **Registry Layering**: This file defines the `OpEntry` registry for Tier-3 Cat-A compositions.
5//! It operates in parallel with the Tier-2.5 primitives registry (`vyre-primitives::harness::OpEntry`) and the Tier-2 hardware intrinsics registry (`vyre-intrinsics::harness::OpEntry`).
6//! For an architectural overview of this three-registry split, see `vyre-harness/README.md`.
7//!
8//! Every Cat-A composition that participates in automated harness
9//! checks registers one `OpEntry` through `inventory::submit!`. The
10//! conform integration test at `tests/universal_harness.rs` discovers
11//! every entry and validates: program validity, wire round-trip, CSE
12//! stability, and (when available) CPU-oracle parity.
13//!
14//! The crate also re-exports the Region builder used by every Cat-A
15//! library to wrap its produced `Vec<Node>` so optimizer passes treat
16//! the library call as an opaque unit by default. See
17//! [`region`](self::region) for `wrap`, `wrap_anonymous`, `wrap_child`,
18//! `tag_program`.
19
20pub mod fp_contract;
21pub mod region;
22
23pub use region::{reparent_program_children, tag_program, wrap, wrap_anonymous, wrap_child};
24
25/// Re-exported so the [`vyre_op!`] macro can call into `inventory`
26/// without callers needing to add it as a direct dependency.
27#[doc(hidden)]
28pub use inventory;
29
30use vyre::ir::Program;
31
32/// Canonical operation tier used by harness, catalog, and matrix gates.
33#[derive(Clone, Copy, Debug, Eq, PartialEq)]
34pub enum OpTier {
35    /// Foundation-level IR rewrite or built-in IR operation.
36    FoundationIr,
37    /// Tier-2 hardware intrinsic.
38    Intrinsic,
39    /// Tier-2.5 reusable primitive.
40    Primitive,
41    /// Tier-3 library composition.
42    Libs,
43    /// Runtime or driver-owned operation.
44    Runtime,
45    /// External consumer registered into the shared harness.
46    External,
47    /// Identifier does not match any accepted registry namespace.
48    Unknown,
49}
50
51impl OpTier {
52    /// Return the stable `OP_MATRIX.toml` tier spelling.
53    #[must_use]
54    pub const fn matrix_value(self) -> &'static str {
55        match self {
56            Self::FoundationIr => "foundation_ir",
57            Self::Intrinsic => "intrinsic",
58            Self::Primitive => "primitive",
59            Self::Libs => "libs",
60            Self::Runtime => "runtime",
61            Self::External => "external",
62            Self::Unknown => "unknown",
63        }
64    }
65}
66
67/// Classify an operation id by the canonical namespace contract.
68#[must_use]
69pub fn classify_op_id(id: &str) -> OpTier {
70    if id.starts_with("vyre-intrinsics::hardware::") {
71        OpTier::Intrinsic
72    } else if id.starts_with("vyre-primitives::") {
73        OpTier::Primitive
74    } else if id.starts_with("vyre-libs::") {
75        OpTier::Libs
76    } else if id.starts_with("core.") || id.starts_with("io.") || id.starts_with("mem.") {
77        OpTier::Runtime
78    } else if is_external_crate_namespace(id) {
79        OpTier::External
80    } else {
81        OpTier::Unknown
82    }
83}
84
85fn is_external_crate_namespace(id: &str) -> bool {
86    let Some((crate_name, _)) = id.split_once("::") else {
87        return false;
88    };
89    !crate_name.is_empty() && !crate_name.starts_with("vyre-")
90}
91
92/// Deterministic fixture input cases.
93pub type InputsFn = fn() -> Vec<Vec<Vec<u8>>>;
94/// Deterministic expected-output fixtures.
95pub type ExpectedFn = fn() -> Vec<Vec<Vec<u8>>>;
96
97/// Shared migration-compatible fixture descriptor for registered Cat-A programs.
98///
99/// At migration time, new entries may still rely on the
100/// [`OpEntry::expected_output`] field while legacy entries that only
101/// set `expected_output` and omit an oracle are skipped from oracle
102/// comparison. Once all entries migrate, `expected_output` is
103/// deprecated but kept for back-compat until that migration completes.
104//
105// The struct is intentionally NOT `#[non_exhaustive]` so the dozens of
106// in-tree vyre-libs registrations (graph/, parsing/, security/, …) can
107// continue to use struct-literal syntax. External consumers should still
108// prefer `OpEntry::new(...)` to keep their code resilient to future
109// fields, but every cross-crate field addition will be accompanied by
110// either a bump or a defaulted helper.
111pub struct OpEntry {
112    /// Stable operation identifier.
113    pub id: &'static str,
114
115    /// Construct the [`Program`] under test.
116    pub build: fn() -> Program,
117
118    /// Deterministic fixture input bytes in declaration order.
119    ///
120    /// The harness passes this into both `vyre_reference::reference_eval` and the
121    /// legacy `expected_output` oracle when they are both provided.
122    pub test_inputs: Option<InputsFn>,
123
124    /// Legacy fixture oracle output bytes.
125    ///
126    /// Kept during migration so existing registrations in
127    /// `src/{math,nn,crypto,matching}` remain buildable without edits.
128    pub expected_output: Option<ExpectedFn>,
129
130    /// Coarse-grained taxonomy tag (T028 / SEPARATION_AUDIT S2 prep).
131    /// Examples: `"math"`, `"nn"`, `"crypto"`, `"scan"`, `"parsing"`,
132    /// `"graph"`, `"security"`, `"dataflow"`, `"compiler"`. `None`
133    /// means uncategorised  -  equivalent to the pre-T028 behaviour.
134    pub category: Option<&'static str>,
135}
136
137impl OpEntry {
138    /// Construct an `OpEntry` with all required fields set. Exists so
139    /// community Cat-A crates can `inventory::submit!(OpEntry::new(...))`
140    /// despite the struct being `#[non_exhaustive]` (V7-EXT-004).
141    /// `category` initialises to `None`; chain `with_category` if a
142    /// category is required at submission time.
143    #[must_use]
144    pub const fn new(
145        id: &'static str,
146        build: fn() -> Program,
147        test_inputs: Option<InputsFn>,
148        expected_output: Option<ExpectedFn>,
149    ) -> Self {
150        Self {
151            id,
152            build,
153            test_inputs,
154            expected_output,
155            category: None,
156        }
157    }
158
159    /// Set the category and return `self`. `const`-friendly so callers
160    /// can write `OpEntry::new(...).with_category("math")` inside
161    /// `inventory::submit!`.
162    #[must_use]
163    pub const fn with_category(mut self, category: &'static str) -> Self {
164        self.category = Some(category);
165        self
166    }
167
168    /// Return the registered coarse-grained taxonomy tag, if any.
169    #[must_use]
170    pub const fn category(&self) -> Option<&'static str> {
171        self.category
172    }
173
174    /// Allowed output drift in ULPs for f32-producing backends.
175    ///
176    /// `0` means byte identity is required. Non-zero tolerances are used only
177    /// for operations whose numerical contract permits the declared drift.
178    #[must_use]
179    pub fn tolerance(&self) -> u32 {
180        Self::tolerance_for_id(self.id)
181    }
182
183    /// Resolve the ULP tolerance for a registered operation id.
184    #[must_use]
185    pub fn tolerance_for_id(id: &str) -> u32 {
186        explicit_tolerance_for_id(id)
187    }
188}
189
190fn explicit_tolerance_for_id(id: &str) -> u32 {
191    match id {
192        "vyre-libs::nn::softmax" => 1,
193        "vyre-libs::nn::attention" => 4,
194        "vyre-libs::nn::gqa_attention" => 4,
195        "vyre-libs::nn::layer_norm" => 1,
196        "vyre-libs::nn::silu" => 1,
197        // Observed 2-ULP drift on a 5090 lane (CPU 0x415dd0f4 vs
198        // GPU 0x415dd0f6) under FMA fusion in cat_a_gpu_differential.
199        "vyre-libs::nn::logit_softcap" => 2,
200        "vyre-libs::nn::rms_norm" => 2,
201        "vyre-libs::nn::rms_norm_linear" => 2,
202        "vyre-libs::math::fft::fft_convolve_circular_complex" => 4,
203        // Strassen's seven-product reconstruction contains cancellation-heavy
204        // add/sub chains. Composing fractional upstream values exposed 24 ULP
205        // of WGSL FMA drift on the fourth output lane.
206        "vyre-libs::math::linalg::matmul_strassen_2x2" => 32,
207        "vyre-libs::optim::newton_schulz_5step" => 64,
208        // `decay*ema + (1-decay)*theta`  -  straight mul+add chain,
209        // one lane drifts 1 ULP from CPU's serial mul+add+add to
210        // GPU's fused mul-add (WGSL-spec-allowed).
211        "vyre-libs::optim::ema_apply" => 1,
212        // MuonEq-R computes momentum and Nesterov update through
213        // adjacent f32 mul+add chains. Random-input WGPU parity observed
214        // 6-ULP drift on an RTX backend under allowed FMA contraction.
215        "vyre-libs::optim::muoneq_r" => 8,
216        // Newton-Schulz Cat-A primitive: the polynomial has nested
217        // mul+add steps that fuse to FMA on GPU. Random-input parity
218        // observed 24-ULP drift across catalog wrappers.
219        "vyre-primitives::math::newton_schulz_poly5_f32" => 32,
220        _ => 0,
221    }
222}
223
224inventory::collect!(OpEntry);
225
226/// Return all registered operation entries.
227pub fn all_entries() -> impl Iterator<Item = &'static OpEntry> {
228    inventory::iter::<OpEntry>()
229}
230
231/// Fixpoint contract for dataflow ops whose GPU body performs one
232/// iteration per dispatch.
233///
234/// Submitting a `FixpointRegistration` alongside an `OpEntry` tells the
235/// conform harness to call `backend.dispatch` in a loop until the
236/// `converged_flag_buffer` reads zero before comparing against the CPU
237/// reference. Without this registration such ops would always diverge
238/// in a single-dispatch byte-identity test even though their lowering
239/// is correct.
240#[derive(Clone, Debug)]
241pub struct FixpointContract {
242    /// Name of the RW buffer whose bytes-interpreted-as-`u32` must
243    /// equal zero for the fixpoint loop to terminate. Semantics: the
244    /// GPU body writes `1` whenever any lane updated shared state;
245    /// the driver clears it between iterations.
246    pub converged_flag_buffer: &'static str,
247    /// Hard cap on driver iterations before the loop bails out. Every
248    /// fixpoint op MUST reach its answer in a known-bounded number of
249    /// steps so the harness cannot hang.
250    pub max_iterations: u32,
251}
252
253/// Link-time registration binding a fixpoint contract to an op id.
254pub struct FixpointRegistration {
255    /// Stable op id (`OpEntry::id`) this contract applies to.
256    pub op_id: &'static str,
257    /// Fixpoint contract parameters.
258    pub contract: FixpointContract,
259}
260
261inventory::collect!(FixpointRegistration);
262
263/// Look up the fixpoint contract registered for `op_id`, if any.
264#[must_use]
265pub fn fixpoint_contract(op_id: &str) -> Option<&'static FixpointContract> {
266    inventory::iter::<FixpointRegistration>()
267        .find(|registration| registration.op_id == op_id)
268        .map(|registration| &registration.contract)
269}
270
271/// Convergence contract for ops whose GPU body performs one
272/// iteration per dispatch and needs an external driver loop to
273/// reach fixpoint before byte-identity comparison.
274///
275/// Submitting a `ConvergenceContract` alongside an `OpEntry` tells
276/// the conform harness to dispatch the backend in a loop (transfer
277/// step + `bitset_fixpoint` convergence check) until the changed
278/// flag clears or the iteration budget is exhausted.
279#[derive(Clone, Debug)]
280pub struct ConvergenceContract {
281    /// Stable op id (`OpEntry::id`) this contract applies to.
282    pub op_id: &'static str,
283    /// Hard cap on driver iterations before the loop bails out.
284    pub max_iterations: u32,
285}
286
287inventory::collect!(ConvergenceContract);
288
289/// Look up the convergence contract registered for `op_id`, if any.
290#[must_use]
291pub fn convergence_contract(op_id: &str) -> Option<&'static ConvergenceContract> {
292    inventory::iter::<ConvergenceContract>().find(|contract| contract.op_id == op_id)
293}
294
295// Tolerance metadata and capability requirements are encoded in
296// [`OpEntry::tolerance`] and checked by the conform lenses directly.
297// There is no global exemption registry; every registered op must
298// provide runnable `test_inputs` / `expected_output` fixtures or fail
299// loudly with a diagnostic.
300
301/// Declarative op registration shorthand (ROADMAP S8 generator half).
302///
303/// One source declares a Cat-A op; the macro expands to the matching
304/// `inventory::submit!{ OpEntry { .. } }` so writers can't accidentally
305/// drift from the canonical `OpEntry` shape.
306///
307/// ## Forms
308///
309/// ```ignore
310/// // Minimal: just id + builder.
311/// vyre_harness::vyre_op! {
312///     id: "vyre-libs::math::matmul",
313///     build: || matmul("a", "b", "out", 2, 2, 2),
314/// }
315///
316/// // Full: explicit fixtures.
317/// vyre_harness::vyre_op! {
318///     id: "vyre-libs::math::matmul",
319///     build: || matmul("a", "b", "out", 2, 2, 2),
320///     test_inputs: || vec![vec![input_bytes(), output_zeros()]],
321///     expected_output: || vec![vec![expected_bytes()]],
322/// }
323/// ```
324///
325/// `test_inputs` / `expected_output` default to `None` when omitted.
326/// Every form expands to exactly one `inventory::submit!` of an
327/// `OpEntry`, keeping the registration shape locked to the struct
328/// definition above.
329///
330/// Future `OpEntry` field additions extend this macro with defaulted
331/// arms so existing call sites stay green.
332#[macro_export]
333macro_rules! vyre_op {
334    (
335        id: $id:expr,
336        build: $build:expr $(,)?
337    ) => {
338        $crate::vyre_op! {
339            id: $id,
340            build: $build,
341            test_inputs: ::core::option::Option::None,
342            expected_output: ::core::option::Option::None,
343        }
344    };
345    (
346        id: $id:expr,
347        build: $build:expr,
348        test_inputs: $inputs:expr,
349        expected_output: $output:expr $(,)?
350    ) => {
351        $crate::inventory::submit! {
352            $crate::OpEntry {
353                id: $id,
354                build: $build,
355                test_inputs: $inputs,
356                expected_output: $output,
357                category: None,
358            }
359        }
360    };
361}
362
363#[cfg(test)]
364mod tests {
365    use super::OpEntry;
366
367    #[test]
368    fn tolerance_defaults_to_zero_byte_identity() {
369        // Adversarial: an unknown op id (not catalog-shaped, no
370        // explicit tolerance row) must default to byte identity.
371        assert_eq!(
372            OpEntry::tolerance_for_id("vyre-libs::foo::bar::baz_unknown_op_id"),
373            0
374        );
375    }
376
377    #[test]
378    fn muoneq_r_random_stress_tolerance_covers_fma_contraction() {
379        assert_eq!(OpEntry::tolerance_for_id("vyre-libs::optim::muoneq_r"), 8);
380    }
381
382    /// Fractional upstream values must retain enough budget for Strassen's
383    /// cancellation-heavy seven-product reconstruction.
384    #[test]
385    fn strassen_composition_tolerance_covers_fma_cancellation() {
386        assert_eq!(
387            OpEntry::tolerance_for_id("vyre-libs::math::linalg::matmul_strassen_2x2"),
388            32
389        );
390    }
391
392    #[test]
393    fn newton_schulz_random_stress_tolerance_covers_nested_fma_drift() {
394        assert_eq!(
395            OpEntry::tolerance_for_id("vyre-primitives::math::newton_schulz_poly5_f32"),
396            32
397        );
398        assert_eq!(
399            OpEntry::tolerance_for_id("vyre-libs::optim::newton_schulz_5step"),
400            64
401        );
402    }
403
404    // ---------------- vyre_op! macro (S8 generator) ----------------
405
406    fn _trivial_program() -> vyre_foundation::ir::Program {
407        use vyre_foundation::ir::{BufferDecl, DataType, Expr, Node, Program};
408        Program::wrapped(
409            vec![BufferDecl::output("out", 0, DataType::U32).with_count(1)],
410            [1, 1, 1],
411            vec![Node::store("out", Expr::u32(0), Expr::u32(7))],
412        )
413    }
414
415    // Minimal-form invocation; expansion succeeds at compile time.
416    crate::vyre_op! {
417        id: "vyre-harness::test::trivial_minimal",
418        build: _trivial_program,
419    }
420
421    // Full-form invocation with explicit fixtures.
422    crate::vyre_op! {
423        id: "vyre-harness::test::trivial_full",
424        build: _trivial_program,
425        test_inputs: ::core::option::Option::Some(|| vec![vec![vec![0u8; 4]]]),
426        expected_output: ::core::option::Option::Some(|| vec![vec![vec![7u8, 0, 0, 0]]]),
427    }
428
429    #[test]
430    fn vyre_op_macro_minimal_form_registers_entry() {
431        let entry = crate::all_entries()
432            .find(|e| e.id == "vyre-harness::test::trivial_minimal")
433            .expect("Fix: vyre_op! minimal form must register an OpEntry");
434        assert!(entry.test_inputs.is_none());
435        assert!(entry.expected_output.is_none());
436    }
437
438    #[test]
439    fn vyre_op_macro_full_form_registers_entry_with_fixtures() {
440        let entry = crate::all_entries()
441            .find(|e| e.id == "vyre-harness::test::trivial_full")
442            .expect("Fix: vyre_op! full form must register an OpEntry");
443        assert!(entry.test_inputs.is_some());
444        assert!(entry.expected_output.is_some());
445    }
446
447    #[test]
448    fn vyre_op_macro_build_fn_produces_program() {
449        let entry = crate::all_entries()
450            .find(|e| e.id == "vyre-harness::test::trivial_minimal")
451            .expect("Fix: entry must exist");
452        let program = (entry.build)();
453        assert_ne!(program.entry().len(), 0);
454    }
455}