qualia_core_db/wgsl_forge/
mod.rs

1//! Deterministic WGSL generation, validation, certification, and tuning.
2//!
3//! WGSL Forge treats shader semantics and hardware scheduling as separate typed
4//! inputs. Tuning is therefore allowed to change work distribution without
5//! changing the mathematical operation being certified.
6
7pub mod audio;
8pub mod backend;
9// W10: the forge's calibration/adaptation pipeline (corpus→capture→learn→certify→package). Native-
10// only (drives the real inference stack for capture + the PPL oracle). The third produce-and-certify
11// entry point beside kernel certification and GGUF→p64 transcode.
12pub mod cache;
13#[cfg(not(target_arch = "wasm32"))]
14pub mod calibration;
15pub mod dispatch;
16pub mod emit;
17pub mod execute;
18pub mod graph_ops;
19pub mod ir;
20pub mod manifest;
21pub mod oracle;
22pub mod physics;
23pub mod roofline;
24pub mod runtime;
25pub mod schedule;
26pub mod tune;
27pub mod validate;
28
29#[cfg(test)]
30pub(crate) fn test_gpu_available() -> bool {
31    use std::sync::OnceLock;
32    static AVAILABLE: OnceLock<bool> = OnceLock::new();
33    *AVAILABLE.get_or_init(|| execute::WgpuComputeContext::new(64 * 1024).is_ok())
34}
35
36#[cfg(all(test, feature = "cuda"))]
37pub(crate) fn test_cuda_available() -> bool {
38    use std::sync::OnceLock;
39    static AVAILABLE: OnceLock<bool> = OnceLock::new();
40    *AVAILABLE.get_or_init(|| execute::CudaComputeContext::new(64 * 1024).is_ok())
41}
42
43pub use backend::resolve_execution_backend;
44pub use cache::ManifestCache;
45pub use dispatch::{
46    caps, coopmat_usable, fft_f32, gemm_cpu_f64, gemm_f32, gemm_f32_tc, gemm_f32_tc_coopmat,
47    gemm_f32_tc_reduced, gemm_f64, gemm_f64_df64, gemv_cpu_f64, gemv_f32, gemv_f64,
48    pairwise_sq_dist_cpu_f64, pairwise_sq_dist_f64, ComputeCaps, GEMM_GPU_THRESHOLD,
49};
50pub use emit::{decode_spirv_words, emit_shader, matmul_tc_wgsl, GeneratedShader, TargetBackend};
51pub use ir::{
52    BufferAccess, BufferElement, BufferSpec, BuiltinKernel, KernelSpec, Op, P64GpuWords64,
53    ScalarType, SharedLen, SharedMemorySpec,
54};
55pub use manifest::{
56    AdapterIdentity, CertificationManifest, HardwareProfile, TimingSource, TimingSummary,
57    TuningManifest, ValidationLevel,
58};
59pub use oracle::{
60    candidate_evaluation, certify_builtin, compare_f32, dft_cpu, evaluate_builtin, evaluate_ffn,
61    evaluate_fft, evaluate_matmul_tc, evaluate_p64, evaluate_topk, ffn_cpu, ffn_tensors,
62    fft_inputs, matmul_cpu, p64_project_cpu, p64_records, topk_cpu, topk_inputs, AffineParams,
63    ComparisonReport, FfnParams, FftParams, GpuEvaluation, OracleCase, OracleTolerance, TopKParams,
64};
65#[cfg(feature = "cuda")]
66pub use oracle::{evaluate_affine_cuda, evaluate_ffn_cuda, evaluate_topk_cuda};
67pub use roofline::{roofline_for, RooflineBound, RooflineEstimate};
68pub use runtime::ForgeRuntime;
69pub use schedule::{AdapterConstraints, Schedule, ScheduleSpace};
70pub use tune::{
71    tune_with, CandidateEvaluation, CandidateFailure, CandidateResult, TuningConfig, TuningResult,
72};
73pub use validate::{validate_native, validate_wgsl, ValidationReport};
74
75pub const FORGE_SCHEMA_VERSION: u32 = 2;
76pub const WGPU_API_VERSION: &str = "30.0.0";
77pub const NAGA_API_VERSION: &str = "30.0.0";
78/// `cudarc` crate API version the cross-backend (CUDA) oracle is built against.
79/// Folded into the tuning/certification cache key (plan §8) so reuse is
80/// invalidated when the CUDA toolchain surface changes.
81pub const CUDARC_API_VERSION: &str = "0.19";
82
83#[derive(Debug, Clone, PartialEq, Eq)]
84pub enum ForgeError {
85    UnknownKernel(String),
86    InvalidKernel(String),
87    InvalidSchedule(String),
88    Emission(String),
89    WgslParse(String),
90    WgslValidation(String),
91    GpuUnavailable(String),
92    GpuValidation(String),
93    /// The compute device was lost (driver reset, removal, or a fatal poll
94    /// failure). Unified across backends so callers handle one variant rather
95    /// than backend-specific panics (plan §7).
96    DeviceLost(String),
97    OracleMismatch(String),
98    Serialization(String),
99    Io(String),
100}
101
102impl core::fmt::Display for ForgeError {
103    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
104        let (kind, message) = match self {
105            Self::UnknownKernel(message) => ("unknown kernel", message),
106            Self::InvalidKernel(message) => ("invalid kernel", message),
107            Self::InvalidSchedule(message) => ("invalid schedule", message),
108            Self::Emission(message) => ("WGSL emission", message),
109            Self::WgslParse(message) => ("WGSL parse", message),
110            Self::WgslValidation(message) => ("WGSL validation", message),
111            Self::GpuUnavailable(message) => ("GPU unavailable", message),
112            Self::GpuValidation(message) => ("GPU validation", message),
113            Self::DeviceLost(message) => ("device lost", message),
114            Self::OracleMismatch(message) => ("oracle mismatch", message),
115            Self::Serialization(message) => ("serialization", message),
116            Self::Io(message) => ("I/O", message),
117        };
118        write!(f, "{kind}: {message}")
119    }
120}
121
122impl std::error::Error for ForgeError {}
123
124impl From<std::io::Error> for ForgeError {
125    fn from(value: std::io::Error) -> Self {
126        Self::Io(value.to_string())
127    }
128}
129
130impl From<serde_json::Error> for ForgeError {
131    fn from(value: serde_json::Error) -> Self {
132        Self::Serialization(value.to_string())
133    }
134}
135
136pub fn generate_builtin(
137    builtin: BuiltinKernel,
138    schedule: Schedule,
139    target: TargetBackend,
140) -> Result<GeneratedShader, ForgeError> {
141    let kernel = builtin.spec();
142    schedule.validate(&kernel, &AdapterConstraints::portable())?;
143    emit_shader(&kernel, schedule, target)
144}
qualia_core_db/wgsl_forge/mod.rs

qualia_core_db/wgsl_forge/
mod.rs
