primal-barracuda 0.4.0

barraCuda — BARrier-free Rust Abstracted Cross-platform Unified Dimensional Algebra. Vendor-agnostic GPU compute via WGSL.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
// SPDX-License-Identifier: AGPL-3.0-or-later
//! GPU test coordination harness — admission gate for concurrent test execution.
//!
//! Provides [`GpuTestGate`] to limit how many test threads execute GPU work
//! simultaneously, preventing driver contention under full parallel load.
//! Also provides [`CoralProbe`] for cached coralReef availability checks
//! and [`gpu_section`] as the primary entry point for gated GPU work.
//!
//! # Architecture
//!
//! The device-level [`DispatchSemaphore`](super::wgpu_device::dispatch) limits
//! concurrent *operations* on a single device. This module limits concurrent
//! *tests* — a coarser gate that prevents the driver oversubscription that
//! causes device-lost errors under full `cargo test` parallelism.
//!
//! Budget is derived from device type (matching dispatch semaphore tiers)
//! or the `BARRACUDA_TEST_GPU_BUDGET` environment variable.

use std::sync::{Arc, OnceLock};

const GPU_TEST_BUDGET_CPU: u32 = 2;
const GPU_TEST_BUDGET_IGPU: u32 = 4;
const GPU_TEST_BUDGET_DGPU: u32 = 8;
const GPU_TEST_BUDGET_ENV: &str = "BARRACUDA_TEST_GPU_BUDGET";

static GPU_GATE: OnceLock<GpuTestGate> = OnceLock::new();
static CORAL_AVAILABLE: OnceLock<bool> = OnceLock::new();

/// Process-wide admission gate for GPU test execution.
///
/// Wraps an [`Arc<tokio::sync::Semaphore>`] with a budget derived from device type.
/// Acquire a permit via [`gpu_section`] or [`acquire_owned`] before executing
/// GPU work in tests.
pub struct GpuTestGate {
    semaphore: Arc<tokio::sync::Semaphore>,
    budget: u32,
}

impl GpuTestGate {
    fn new(budget: u32) -> Self {
        Self {
            semaphore: Arc::new(tokio::sync::Semaphore::new(budget as usize)),
            budget,
        }
    }

    /// Acquire a test-level GPU permit. Waits until capacity is available.
    ///
    /// # Panics
    /// Panics if the semaphore has been closed (should never happen — the
    /// gate lives for the process lifetime).
    pub async fn acquire(&self) -> tokio::sync::SemaphorePermit<'_> {
        self.semaphore
            .acquire()
            .await
            .expect("GPU test gate semaphore closed unexpectedly")
    }

    /// Acquire an owned permit for thread-local storage in the test pool.
    ///
    /// # Panics
    /// Panics if the semaphore has been closed.
    pub async fn acquire_owned(&self) -> tokio::sync::OwnedSemaphorePermit {
        Arc::clone(&self.semaphore)
            .acquire_owned()
            .await
            .expect("GPU test gate semaphore closed unexpectedly")
    }

    /// Blocking acquire of an owned permit (for sync test helpers).
    ///
    /// # Panics
    /// Panics if the semaphore has been closed or the runtime cannot block.
    pub fn acquire_owned_blocking(&self) -> tokio::sync::OwnedSemaphorePermit {
        Arc::clone(&self.semaphore)
            .try_acquire_owned()
            .unwrap_or_else(|_| crate::runtime::tokio_block_on(self.acquire_owned()))
    }

    /// The configured budget for this gate.
    #[must_use]
    pub fn budget(&self) -> u32 {
        self.budget
    }
}

impl std::fmt::Debug for GpuTestGate {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("GpuTestGate")
            .field("budget", &self.budget)
            .field("available", &self.semaphore.available_permits())
            .finish()
    }
}

/// Resolve the GPU test budget from env or device type heuristic.
fn resolve_budget() -> u32 {
    if let Ok(val) = std::env::var(GPU_TEST_BUDGET_ENV)
        && let Ok(n) = val.parse::<u32>()
        && n > 0
    {
        return n;
    }

    let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
        backends: wgpu::Backends::all(),
        ..Default::default()
    });
    let adapters =
        crate::runtime::tokio_block_on(instance.enumerate_adapters(wgpu::Backends::all()));
    if let Some(adapter) = adapters.first() {
        let info = adapter.get_info();
        match info.device_type {
            wgpu::DeviceType::DiscreteGpu => GPU_TEST_BUDGET_DGPU,
            wgpu::DeviceType::IntegratedGpu => GPU_TEST_BUDGET_IGPU,
            wgpu::DeviceType::Cpu => GPU_TEST_BUDGET_CPU,
            _ => GPU_TEST_BUDGET_IGPU,
        }
    } else {
        GPU_TEST_BUDGET_CPU
    }
}

/// Get or initialize the global GPU test gate.
pub fn global_gate() -> &'static GpuTestGate {
    GPU_GATE.get_or_init(|| {
        let budget = resolve_budget();
        tracing::debug!(budget, "GPU test gate initialized");
        GpuTestGate::new(budget)
    })
}

/// Execute a closure under the GPU test admission gate.
///
/// Acquires a test-level GPU permit before running `f`, releasing it
/// when the future completes. This is the primary entry point for
/// coordinated GPU test execution.
///
/// ```rust,ignore
/// gpu_section(|| async {
///     let device = get_test_device().await;
///     let result = my_gpu_op(&device).await?;
///     Ok(())
/// }).await;
/// ```
pub async fn gpu_section<F, Fut, T>(f: F) -> T
where
    F: FnOnce() -> Fut,
    Fut: std::future::Future<Output = T>,
{
    let _permit = global_gate().acquire().await;
    f().await
}

/// Check whether coralReef is reachable (cached after first probe).
///
/// Uses the global [`CoralCompiler`](super::coral_compiler::CoralCompiler)
/// singleton. The result is cached process-wide so 3000+ tests don't each
/// make an IPC call.
pub async fn coral_available() -> bool {
    if let Some(&cached) = CORAL_AVAILABLE.get() {
        return cached;
    }
    let available = super::coral_compiler::probe_health().await;
    *CORAL_AVAILABLE.get_or_init(|| available)
}

/// Execute a closure only if coralReef is available.
///
/// Returns `Some(result)` if coralReef is reachable and the closure succeeds,
/// `None` if coralReef is unavailable (test should skip the coralReef path).
pub async fn with_coral<F, Fut, T>(f: F) -> Option<T>
where
    F: FnOnce() -> Fut,
    Fut: std::future::Future<Output = T>,
{
    if coral_available().await {
        Some(f().await)
    } else {
        None
    }
}

// ============================================================================
// Sovereign shader validation — layered backend selection
// ============================================================================

static CORAL_CPU_AVAILABLE: OnceLock<bool> = OnceLock::new();
static CORAL_VALIDATE_AVAILABLE: OnceLock<bool> = OnceLock::new();

/// Backend used for CPU-side shader math validation.
///
/// Tests don't choose the backend directly — [`shader_validation_backend`]
/// probes the environment once and caches the result. The fallback chain:
///
/// 1. **coralReef** (sovereign CPU execution via `shader.execute.cpu`)
/// 2. **llvmpipe** (software Vulkan via `wgpu`)
///
/// Phase 2 will insert a naga interpreter between coralReef and llvmpipe.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ShaderValidationBackend {
    /// coralReef `shader.execute.cpu` — sovereign compiled CPU execution.
    CoralReef,
    /// llvmpipe / software Vulkan via wgpu — always available on CI.
    Llvmpipe,
}

/// Probe which shader validation backend is available (cached).
///
/// Checks once per process whether coralReef supports CPU execution.
/// Falls back to llvmpipe if coralReef is unavailable or doesn't
/// advertise `shader.execute.cpu`.
pub async fn shader_validation_backend() -> ShaderValidationBackend {
    let coral_cpu = if let Some(&cached) = CORAL_CPU_AVAILABLE.get() {
        cached
    } else {
        let available = coral_available().await
            && super::coral_compiler::global_coral()
                .supports_cpu_execution()
                .await;
        *CORAL_CPU_AVAILABLE.get_or_init(|| available)
    };

    if coral_cpu {
        ShaderValidationBackend::CoralReef
    } else {
        ShaderValidationBackend::Llvmpipe
    }
}

/// Check whether coralReef supports `shader.validate` (cached).
pub async fn coral_validation_available() -> bool {
    if let Some(&cached) = CORAL_VALIDATE_AVAILABLE.get() {
        return cached;
    }
    let available = coral_available().await
        && super::coral_compiler::global_coral()
            .supports_validation()
            .await;
    *CORAL_VALIDATE_AVAILABLE.get_or_init(|| available)
}

/// Validate that a WGSL shader parses and validates through naga.
///
/// Used by cross-spring validation to verify absorbed shaders compile
/// without requiring GPU hardware. Returns the shader module info on
/// success, or an error description on failure.
///
/// # Errors
///
/// Returns `Err` with a description if naga parsing or validation fails.
#[cfg(feature = "gpu")]
pub fn validate_wgsl_shader(wgsl_source: &str) -> crate::error::Result<()> {
    use crate::error::BarracudaError;
    let module = naga::front::wgsl::parse_str(wgsl_source)
        .map_err(|e| BarracudaError::shader_compilation(format!("parse: {e}")))?;

    let mut validator = naga::valid::Validator::new(
        naga::valid::ValidationFlags::all(),
        naga::valid::Capabilities::all(),
    );
    validator
        .validate(&module)
        .map_err(|e| BarracudaError::shader_compilation(format!("validate: {e}")))?;

    Ok(())
}

/// Validate a shader with DF64 preamble injection.
///
/// Prepends `df64_core.wgsl` + `df64_transcendentals.wgsl` before validation,
/// matching the runtime DF64 compilation path used by hotSpring lattice QCD
/// and neuralSpring coralForge attention shaders.
///
/// # Errors
///
/// Returns `Err` if preamble concatenation produces invalid WGSL.
#[cfg(feature = "gpu")]
pub fn validate_df64_shader(shader_body: &str) -> crate::error::Result<()> {
    let df64_core = include_str!("../shaders/math/df64_core.wgsl");
    let df64_trans = include_str!("../shaders/math/df64_transcendentals.wgsl");
    let full_source = format!("{df64_core}\n{df64_trans}\n{shader_body}");
    validate_wgsl_shader(&full_source)
}

/// Run a cross-spring shader validation suite.
///
/// Validates a batch of shader sources and returns a summary of results.
/// Intended for integration tests that verify all absorbed shaders from
/// a specific spring domain still compile.
#[cfg(feature = "gpu")]
#[must_use]
pub fn validate_shader_batch<'a>(
    shaders: &'a [(&'a str, &'a str)],
) -> Vec<(&'a str, crate::error::Result<()>)> {
    shaders
        .iter()
        .map(|(name, source)| (*name, validate_wgsl_shader(source)))
        .collect()
}

/// Check whether the device's fused f64 reduction ops produce valid results.
///
/// Runs a minimal variance computation (`[1.0, 2.0, 3.0, 4.0, 5.0]`) and
/// verifies the result is finite and positive. Returns `false` on Hybrid
/// devices where shared-memory f64 accumulators return zeros, or when the
/// GPU is otherwise unable to produce correct fused-reduction results.
///
/// Springs use this as a canary to gate test suites that depend on fused
/// reductions (`VarianceF64`, `CorrelationF64`, `HmmBatchForwardF64`).
#[cfg(feature = "gpu")]
#[must_use]
pub fn fused_ops_healthy(device: &std::sync::Arc<super::WgpuDevice>) -> bool {
    let data = [1.0_f64, 2.0, 3.0, 4.0, 5.0];
    match crate::ops::variance_f64_wgsl::VarianceF64::new(std::sync::Arc::clone(device)) {
        Ok(var_op) => match var_op.variance(&data) {
            Ok(v) => v.is_finite() && v > 0.1,
            Err(_) => false,
        },
        Err(_) => false,
    }
}

/// Check whether the adapter is a software rasterizer (llvmpipe, lavapipe, swiftshader).
///
/// Springs use this to skip hardware-specific tests or relax tolerances.
#[cfg(feature = "gpu")]
#[must_use]
pub fn is_software_adapter(device: &super::WgpuDevice) -> bool {
    let info = device.adapter_info();
    info.device_type == wgpu::DeviceType::Cpu
        || info.driver.to_lowercase().contains("llvmpipe")
        || info.driver.to_lowercase().contains("lavapipe")
        || info.name.to_lowercase().contains("swiftshader")
}

/// Resolve a path relative to the calling crate's manifest directory.
///
/// Wraps the common `CARGO_MANIFEST_DIR` pattern so springs don't have to
/// replicate it. Returns `None` if the env var is missing (e.g. running
/// outside `cargo test`).
#[must_use]
pub fn baseline_path(relative: &str) -> Option<std::path::PathBuf> {
    std::env::var("CARGO_MANIFEST_DIR")
        .ok()
        .map(|dir| std::path::PathBuf::from(dir).join(relative))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn budget_resolves_positive() {
        let budget = resolve_budget();
        assert!(budget > 0, "budget should be positive: {budget}");
        assert!(budget <= 128, "budget should be bounded: {budget}");
    }

    #[test]
    fn global_gate_is_consistent() {
        let gate1 = global_gate();
        let gate2 = global_gate();
        assert_eq!(gate1.budget(), gate2.budget());
    }

    #[tokio::test]
    async fn gpu_section_executes_closure() {
        let result = gpu_section(|| async { 42 }).await;
        assert_eq!(result, 42);
    }

    #[tokio::test]
    async fn gpu_section_concurrent_bounded() {
        let gate = global_gate();
        let budget = gate.budget() as usize;

        let barrier = std::sync::Arc::new(tokio::sync::Barrier::new(budget));
        let mut handles = Vec::with_capacity(budget);

        for _ in 0..budget {
            let b = barrier.clone();
            handles.push(tokio::spawn(gpu_section(move || async move {
                b.wait().await;
                true
            })));
        }

        for h in handles {
            assert!(h.await.unwrap());
        }
    }

    #[tokio::test]
    async fn coral_probe_is_cached() {
        let a = coral_available().await;
        let b = coral_available().await;
        assert_eq!(a, b, "coral probe should return cached result");
    }

    #[cfg(feature = "gpu")]
    #[test]
    fn validate_wgsl_shader_accepts_valid() {
        let wgsl = "@compute @workgroup_size(64) fn main() {}";
        assert!(validate_wgsl_shader(wgsl).is_ok());
    }

    #[cfg(feature = "gpu")]
    #[test]
    fn validate_wgsl_shader_rejects_invalid() {
        let bad = "fn main() { let x = ; }";
        assert!(validate_wgsl_shader(bad).is_err());
    }

    #[cfg(feature = "gpu")]
    #[test]
    fn validate_shader_batch_mixed() {
        let shaders = vec![
            ("valid", "@compute @workgroup_size(64) fn main() {}"),
            ("invalid", "fn main() { let x = ; }"),
        ];
        let results = validate_shader_batch(&shaders);
        assert!(results[0].1.is_ok());
        assert!(results[1].1.is_err());
    }
}