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| ®istration.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}