Skip to main content

qualia_core_db/
gpu_context.rs

1//! Shared GPU context and VRAM ledger for LLM + tensor + render coexistence.
2//!
3//! **Compute universes** (Track B2): logical partitions on one physical adapter —
4//! pinned ledger slots and queue lanes, not multiple `GPUDevice` instances.
5//!
6//! Qualia-native bindings (graph–tensor SOA, Phase-8 SPSC, Sentinel, ledger pins)
7//! live in `compute_universe.rs` — this module owns VRAM accounting and `shared_gpu()`.
8//!
9//! Operational modes: **Full**, **Eco**, **Reserve** (no heap in hot-path accounting).
10
11use std::sync::atomic::{AtomicU32, AtomicU64, Ordering};
12
13#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
14use std::sync::OnceLock;
15
16#[cfg(test)]
17mod migration_contract_tests;
18mod reservation;
19pub use reservation::{GraphicsReservationError, VramReservation, VramResourceClass};
20
21// `caps` reports wgpu adapter capabilities, so it only compiles when `gpu-runtime`
22// pulls in the wgpu crate. `portal` / `wasm-llm` already enable `gpu-runtime`;
23// qdnf-only does not, and must not `use wgpu` here.
24#[cfg(feature = "gpu-runtime")]
25mod caps;
26#[cfg(all(
27    not(target_arch = "wasm32"),
28    feature = "gpu-runtime",
29    feature = "wgsl-forge"
30))]
31pub(crate) use caps::experimental_features_allowed;
32#[cfg(feature = "gpu-runtime")]
33pub(crate) use caps::requested_native_llm_features;
34#[cfg(all(feature = "gpu-runtime", not(target_arch = "wasm32")))]
35pub use caps::{
36    GpuAdapterCaps, GpuFeatureCaps, GpuLimitCaps, qualia_backend_override,
37    recommend_inference_backend,
38};
39#[cfg(all(feature = "gpu-runtime", target_arch = "wasm32"))]
40pub use caps::{GpuAdapterCaps, GpuFeatureCaps, GpuLimitCaps, recommend_inference_backend};
41
42#[cfg(feature = "gpu-runtime")]
43pub use etalon_agent::{
44    AccessRights as EtalonAccessRights, AccessRights, AllocationId as EtalonAllocationId,
45    AllocationId, BufferRegion as EtalonBufferRegion, BufferRegion,
46    CapabilityState as EtalonCapabilityState, CapabilityState,
47    HalComputeLane as EtalonHalComputeLane, HalComputeLane, MemoryTopology as EtalonMemoryTopology,
48    MemoryTopology, QualiaSlabAllocator as EtalonSlabAllocator, QualiaSlabAllocator,
49    QueueId as EtalonQueueId, QueueId, SiliconCapability as EtalonSiliconCapability,
50    SiliconCapability, SubmissionLease as EtalonSubmissionLease, SubmissionLease,
51    SubmissionToken as EtalonSubmissionToken, SubmissionToken,
52};
53
54/// Device-per-circuit registry — obtain a `etalon::Device` for a SPECIFIC adapter/circuit
55/// (e.g. the integrated GPU), not just the single process-wide primary (STELLAR H3 foundation).
56/// Native only; mirrors `try_shared_gpu` — never panics on a missing/failed device.
57#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
58pub mod device_registry;
59
60/// Desktop / portal operational mode (thermal + VRAM driven).
61#[repr(u8)]
62#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
63pub enum OperationalMode {
64    #[default]
65    Full = 0,
66    Eco = 1,
67    /// Engine-only: inference + queries; viewport particles/bloom off.
68    Reserve = 2,
69}
70
71impl OperationalMode {
72    /// Mode from VRAM pressure ∈ [0, ~1.25]: `Reserve` ≥ 0.92,
73    /// `Eco` ≥ 0.72, else `Full`.
74    #[inline]
75    pub fn from_pressure(pressure: f32) -> Self {
76        if pressure >= 0.92 {
77            Self::Reserve
78        } else if pressure >= 0.72 {
79            Self::Eco
80        } else {
81            Self::Full
82        }
83    }
84
85    /// Ambient-particle draw cap per mode (50k Full / 8k Eco / 0 Reserve).
86    #[inline]
87    pub fn max_particles(self) -> u32 {
88        match self {
89            Self::Full => 50_000,
90            Self::Eco => 8_000,
91            Self::Reserve => 0,
92        }
93    }
94
95    /// Whether the bloom post-process is enabled — `Full` only.
96    #[inline]
97    pub fn bloom_enabled(self) -> bool {
98        matches!(self, Self::Full)
99    }
100
101    /// Whether this tier can render the full 3D scene. Only [`Self::Full`] does; `Eco`
102    /// (VRAM-conservation) and `Reserve` (engine-only) degrade 3D → 2D — the affordability rail.
103    /// Single source of the Phase-5 budget rule, shared by `render::authoring` and the portal.
104    #[inline]
105    pub fn supports_3d(self) -> bool {
106        matches!(self, Self::Full)
107    }
108}
109
110/// Parallel compute plane on shared silicon (maps to 10D **q** / **w** semantics).
111#[repr(u8)]
112#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
113pub enum ComputeUniverse {
114    /// U0 — LLM forward pass, KV cache, weight staging.
115    LlmInference = 0,
116    /// U1 — baked 10D tensor SOA, kNN / spatial filters.
117    Tensor10D = 1,
118    /// U2 — projector, ambient, bloom.
119    Viewport = 2,
120    /// U3 — AcousticPlane; read-only pin on U1 SOA + sonic token SPSC (no extra ledger slice yet).
121    AcousticPlane = 3,
122}
123
124impl ComputeUniverse {
125    pub const ALL: [Self; 4] = [
126        Self::LlmInference,
127        Self::Tensor10D,
128        Self::Viewport,
129        Self::AcousticPlane,
130    ];
131
132    /// Physical ledger partition index (U3 aliases U1 until acoustic sidecar pins land).
133    #[inline]
134    pub fn partition_index(self) -> usize {
135        match self {
136            Self::AcousticPlane => Self::Tensor10D as usize,
137            u => u as usize,
138        }
139    }
140
141    /// Short display label (`"U0 LLM"`, …) for telemetry/receipts.
142    #[inline]
143    pub fn label(self) -> &'static str {
144        match self {
145            Self::LlmInference => "U0 LLM",
146            Self::Tensor10D => "U1 Tensor10D",
147            Self::Viewport => "U2 Viewport",
148            Self::AcousticPlane => "U3 AcousticPlane",
149        }
150    }
151
152    /// Preferred queue lane for this universe's work.
153    #[inline]
154    pub fn default_queue_lane(self) -> QueueLane {
155        match self {
156            Self::LlmInference => QueueLane::LlmCompute,
157            Self::Tensor10D => QueueLane::TensorCompute,
158            Self::Viewport | Self::AcousticPlane => QueueLane::ViewportRender,
159        }
160    }
161
162    /// The `VramLedgerSlot`s whose bytes count toward this universe.
163    #[inline]
164    pub fn ledger_slots(self) -> &'static [VramLedgerSlot] {
165        match self {
166            Self::LlmInference => &[VramLedgerSlot::LlmKvCache, VramLedgerSlot::LlmWeightStaging],
167            Self::Tensor10D | Self::AcousticPlane => &[VramLedgerSlot::Tensor10D],
168            Self::Viewport => &[VramLedgerSlot::Viewport],
169        }
170    }
171}
172
173/// Pinned VRAM accounting bucket (zero-copy crossover between universes reads, not writes).
174#[repr(u8)]
175#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
176pub enum VramLedgerSlot {
177    LlmKvCache = 0,
178    LlmWeightStaging = 1,
179    Tensor10D = 2,
180    Viewport = 3,
181}
182
183/// Preferred async queue on the single `etalon::Device` (spatial concurrency, not MIG).
184#[repr(u8)]
185#[derive(Debug, Clone, Copy, PartialEq, Eq)]
186pub enum QueueLane {
187    LlmCompute = 0,
188    TensorCompute = 1,
189    ViewportRender = 2,
190}
191
192/// Immutable consecutive byte range in the logical VRAM ledger (no overlap between universes).
193#[derive(Debug, Clone, Copy, PartialEq, Eq)]
194pub struct VramByteRange {
195    pub offset: u64,
196    pub size: u64,
197}
198
199impl VramByteRange {
200    /// Zero-size range at offset 0.
201    #[inline]
202    pub const fn empty() -> Self {
203        Self { offset: 0, size: 0 }
204    }
205
206    /// Exclusive end offset (`offset + size`, saturating).
207    #[inline]
208    pub fn end(&self) -> u64 {
209        self.offset.saturating_add(self.size)
210    }
211
212    /// True when `[offset, offset+size)` lies entirely inside this partition pin.
213    #[inline]
214    pub fn contains(&self, alloc_offset: u64, alloc_size: u64) -> bool {
215        alloc_size == 0
216            || alloc_offset >= self.offset && alloc_offset.saturating_add(alloc_size) <= self.end()
217    }
218}
219
220/// Hermetic partition: universe ↔ ledger bounds ↔ queue preference.
221#[derive(Debug, Clone, Copy)]
222pub struct UniversePartition {
223    pub universe: ComputeUniverse,
224    pub mode: OperationalMode,
225    /// Hard cap for this universe (sum of its ledger slots).
226    pub vram_budget_bytes: u64,
227    /// Pinned consecutive ledger slice — U2 cannot grow into U0's range.
228    pub ledger_range: VramByteRange,
229    pub queue_lane: QueueLane,
230}
231
232/// Orchestrator enforces pinned boundaries on one adapter (Full / Eco / Reserve degrade per universe).
233#[derive(Debug, Clone)]
234pub struct UniverseOrchestrator {
235    pub active_mode: OperationalMode,
236    pub partitions: [UniversePartition; 3],
237}
238
239impl UniverseOrchestrator {
240    /// VRAM split for the active operational mode (consecutive pins, no thrashing).
241    #[inline]
242    pub fn budget_triplet(total_bytes: u64, mode: OperationalMode) -> (u64, u64, u64) {
243        match mode {
244            OperationalMode::Reserve => {
245                let u2 = total_bytes / 10;
246                let rem = total_bytes.saturating_sub(u2);
247                let u0 = rem / 2;
248                let u1 = rem.saturating_sub(u0);
249                (u0, u1, u2)
250            }
251            OperationalMode::Eco => {
252                let u2 = total_bytes / 4;
253                let rem = total_bytes.saturating_sub(u2);
254                let u0 = rem.saturating_mul(6) / 10;
255                let u1 = rem.saturating_sub(u0);
256                (u0, u1, u2)
257            }
258            OperationalMode::Full => {
259                let u0 = total_bytes.saturating_mul(55) / 100;
260                let u1 = total_bytes.saturating_mul(25) / 100;
261                let u2 = total_bytes.saturating_mul(15) / 100;
262                (u0, u1, u2)
263            }
264        }
265    }
266
267    /// Build one partition for `universe` spanning
268    /// `[offset, offset+size)` of the ledger under `mode`.
269    fn partition_at_offset(
270        universe: ComputeUniverse,
271        mode: OperationalMode,
272        offset: u64,
273        size: u64,
274    ) -> UniversePartition {
275        UniversePartition {
276            universe,
277            mode,
278            vram_budget_bytes: size,
279            ledger_range: VramByteRange { offset, size },
280            queue_lane: universe.default_queue_lane(),
281        }
282    }
283
284    /// Mode-aware ledger partition (Track B2.2).
285    pub fn from_total_budget(total_bytes: u64, mode: OperationalMode) -> Self {
286        let (u0, u1, u2) = Self::budget_triplet(total_bytes, mode);
287        Self {
288            active_mode: mode,
289            partitions: [
290                Self::partition_at_offset(ComputeUniverse::LlmInference, mode, 0, u0),
291                Self::partition_at_offset(ComputeUniverse::Tensor10D, mode, u0, u1),
292                Self::partition_at_offset(
293                    ComputeUniverse::Viewport,
294                    mode,
295                    u0.saturating_add(u1),
296                    u2,
297                ),
298            ],
299        }
300    }
301
302    /// Default split at **Full** fidelity: 55% U0 / 25% U1 / 15% U2 (~5% headroom implicit).
303    #[inline]
304    pub fn from_total_budget_full(total_bytes: u64) -> Self {
305        Self::from_total_budget(total_bytes, OperationalMode::Full)
306    }
307
308    /// The pinned partition for `universe` (U3 resolves to the U1
309    /// partition via `partition_index`).
310    #[inline]
311    pub fn partition(&self, universe: ComputeUniverse) -> &UniversePartition {
312        &self.partitions[universe.partition_index()]
313    }
314
315    /// Global mode mapped per universe — LLM (U0) wins under pressure.
316    #[inline]
317    pub fn effective_mode(
318        &self,
319        universe: ComputeUniverse,
320        global: OperationalMode,
321    ) -> OperationalMode {
322        match global {
323            OperationalMode::Full => OperationalMode::Full,
324            OperationalMode::Eco => match universe {
325                ComputeUniverse::Viewport | ComputeUniverse::AcousticPlane => OperationalMode::Eco,
326                _ => OperationalMode::Eco,
327            },
328            OperationalMode::Reserve => match universe {
329                ComputeUniverse::LlmInference => OperationalMode::Full,
330                ComputeUniverse::Tensor10D => OperationalMode::Eco,
331                ComputeUniverse::Viewport | ComputeUniverse::AcousticPlane => {
332                    OperationalMode::Reserve
333                }
334            },
335        }
336    }
337
338    /// Particle cap for `universe` under `global` pressure (via
339    /// `effective_mode`).
340    #[inline]
341    pub fn max_particles(&self, universe: ComputeUniverse, global: OperationalMode) -> u32 {
342        self.effective_mode(universe, global).max_particles()
343    }
344
345    /// Whether bloom runs in `universe` under `global` pressure —
346    /// Viewport only, and only at effective `Full`.
347    #[inline]
348    pub fn bloom_enabled(&self, universe: ComputeUniverse, global: OperationalMode) -> bool {
349        universe == ComputeUniverse::Viewport
350            && self.effective_mode(universe, global).bloom_enabled()
351    }
352}
353
354/// Universe map derived from adapter budget + live operational mode (recomputed; 3 partitions).
355#[inline]
356pub fn universe_orchestrator() -> UniverseOrchestrator {
357    let ledger = global_vram_ledger();
358    UniverseOrchestrator::from_total_budget(ledger.budget().max(1), ledger.mode())
359}
360
361/// Alias retained for orchestration call sites.
362#[inline]
363pub fn global_universe_orchestrator() -> UniverseOrchestrator {
364    universe_orchestrator()
365}
366
367/// U2-effective operational mode from live `VramLedger` pressure.
368#[inline]
369pub fn viewport_operational_mode() -> OperationalMode {
370    let ledger = global_vram_ledger();
371    universe_orchestrator().effective_mode(ComputeUniverse::Viewport, ledger.mode())
372}
373
374/// Zero-heap ambient draw throttle — static SSBO, dynamic `instance_count` (instant step-down).
375#[inline]
376pub fn ambient_draw_instances_for_mode(resident: u32, global: OperationalMode) -> u32 {
377    let cap = universe_orchestrator()
378        .effective_mode(ComputeUniverse::Viewport, global)
379        .max_particles();
380    resident.min(cap)
381}
382
383/// Live ledger hook for per-frame draw throttling (no buffer resize).
384#[inline]
385pub fn ambient_draw_instances(resident: u32) -> u32 {
386    ambient_draw_instances_for_mode(resident, global_vram_ledger().mode())
387}
388
389/// Zero-heap VRAM budget tracker (bytes, atomics).
390#[derive(Debug, Default)]
391pub struct VramLedger {
392    budget_bytes: AtomicU64,
393    tensor_bytes: AtomicU64,
394    kv_cache_bytes: AtomicU64,
395    render_bytes: AtomicU64,
396    llm_weight_staging_bytes: AtomicU64,
397    /// Live, owned allocations admitted through `try_reserve_graphics`.
398    graphics_reservations: etalon_resources::reservation::ReservationPool<6>,
399    mode: AtomicU32,
400}
401
402impl VramLedger {
403    /// Hard cap on tracked KV-cache bytes (448 MiB).
404    pub const KV_CACHE_CAP_BYTES: u64 = 448 * 1024 * 1024;
405
406    /// Bytes currently recorded in `slot` (relaxed read).
407    #[inline]
408    fn load_slot(&self, slot: VramLedgerSlot) -> u64 {
409        match slot {
410            VramLedgerSlot::LlmKvCache => self.kv_cache_bytes.load(Ordering::Relaxed),
411            VramLedgerSlot::LlmWeightStaging => {
412                self.llm_weight_staging_bytes.load(Ordering::Relaxed)
413            }
414            VramLedgerSlot::Tensor10D => self.tensor_bytes.load(Ordering::Relaxed),
415            VramLedgerSlot::Viewport => self.render_bytes.load(Ordering::Relaxed),
416        }
417    }
418
419    /// Write `bytes` into `slot` (KV cache clamped to
420    /// `KV_CACHE_CAP_BYTES`) and refresh the operational mode.
421    #[inline]
422    fn store_slot(&self, slot: VramLedgerSlot, bytes: u64) {
423        let bytes = match slot {
424            VramLedgerSlot::LlmKvCache => bytes.min(Self::KV_CACHE_CAP_BYTES),
425            _ => bytes,
426        };
427        match slot {
428            VramLedgerSlot::LlmKvCache => self.kv_cache_bytes.store(bytes, Ordering::Relaxed),
429            VramLedgerSlot::LlmWeightStaging => self
430                .llm_weight_staging_bytes
431                .store(bytes, Ordering::Relaxed),
432            VramLedgerSlot::Tensor10D => self.tensor_bytes.store(bytes, Ordering::Relaxed),
433            VramLedgerSlot::Viewport => self.render_bytes.store(bytes, Ordering::Relaxed),
434        }
435        self.refresh_mode();
436    }
437
438    /// Configured total budget in bytes.
439    #[inline]
440    pub fn budget(&self) -> u64 {
441        self.budget_bytes.load(Ordering::Relaxed)
442    }
443
444    /// Bytes currently recorded in `slot`.
445    #[inline]
446    pub fn used_in_slot(&self, slot: VramLedgerSlot) -> u64 {
447        self.load_slot(slot)
448    }
449
450    /// Record `bytes` as the new usage of `slot` (clamped for KV cache;
451    /// refreshes mode).
452    #[inline]
453    pub fn record_slot(&self, slot: VramLedgerSlot, bytes: u64) {
454        self.store_slot(slot, bytes);
455    }
456
457    /// Total recorded bytes across `universe`'s slots; the Viewport
458    /// universe additionally includes live `try_reserve_graphics`
459    /// reservations.
460    #[inline]
461    pub fn universe_used_bytes(&self, universe: ComputeUniverse) -> u64 {
462        let recorded = universe
463            .ledger_slots()
464            .iter()
465            .map(|s| self.load_slot(*s))
466            .fold(0u64, u64::saturating_add);
467        if universe == ComputeUniverse::Viewport {
468            recorded.saturating_add(self.graphics_reservations.total_bytes())
469        } else {
470            recorded
471        }
472    }
473
474    /// `universe` used-bytes ÷ its partition budget, clamped to
475    /// [0, 1.25] (0 when the partition has no budget).
476    #[inline]
477    pub fn universe_pressure(
478        &self,
479        orchestrator: &UniverseOrchestrator,
480        universe: ComputeUniverse,
481    ) -> f32 {
482        let cap = orchestrator.partition(universe).vram_budget_bytes;
483        if cap == 0 {
484            return 0.0;
485        }
486        (self.universe_used_bytes(universe) as f32 / cap as f32).clamp(0.0, 1.25)
487    }
488
489    /// Whether `extra_bytes` fits both inside `universe`'s partition
490    /// range (at the current usage offset) and the global budget.
491    #[inline]
492    pub fn can_allocate_in_universe(
493        &self,
494        orchestrator: &UniverseOrchestrator,
495        universe: ComputeUniverse,
496        extra_bytes: u64,
497    ) -> bool {
498        let part = orchestrator.partition(universe);
499        let used = self.universe_used_bytes(universe);
500        if used.saturating_add(extra_bytes) > part.vram_budget_bytes {
501            return false;
502        }
503        part.ledger_range
504            .contains(part.ledger_range.offset.saturating_add(used), extra_bytes)
505            && self.can_allocate(extra_bytes)
506    }
507
508    /// Map a ledger slot to its pinned byte offset inside the adapter ledger.
509    #[inline]
510    pub fn slot_byte_offset(orchestrator: &UniverseOrchestrator, slot: VramLedgerSlot) -> u64 {
511        let universe = match slot {
512            VramLedgerSlot::LlmKvCache | VramLedgerSlot::LlmWeightStaging => {
513                ComputeUniverse::LlmInference
514            }
515            VramLedgerSlot::Tensor10D => ComputeUniverse::Tensor10D,
516            VramLedgerSlot::Viewport => ComputeUniverse::Viewport,
517        };
518        let used_before = match slot {
519            VramLedgerSlot::LlmWeightStaging => {
520                orchestrator
521                    .partition(ComputeUniverse::LlmInference)
522                    .ledger_range
523                    .offset
524                    + global_vram_ledger().used_in_slot(VramLedgerSlot::LlmKvCache)
525            }
526            _ => orchestrator.partition(universe).ledger_range.offset,
527        };
528        used_before
529    }
530
531    /// Record `bytes` into `slot`, asserting it belongs to `universe`.
532    #[inline]
533    pub fn record_universe(&self, universe: ComputeUniverse, slot: VramLedgerSlot, bytes: u64) {
534        debug_assert!(universe.ledger_slots().contains(&slot));
535        self.store_slot(slot, bytes);
536    }
537
538    /// Ledger with `budget_bytes` total and zeroed usage counters.
539    #[inline]
540    pub fn new(budget_bytes: u64) -> Self {
541        Self {
542            budget_bytes: AtomicU64::new(budget_bytes),
543            ..Default::default()
544        }
545    }
546
547    /// Overwrite the total budget (does not refresh mode).
548    #[inline]
549    pub fn set_budget(&self, bytes: u64) {
550        self.budget_bytes.store(bytes, Ordering::Relaxed);
551    }
552
553    /// Record Tensor10D (U1) usage bytes.
554    #[inline]
555    pub fn record_tensor(&self, bytes: u64) {
556        self.record_universe(ComputeUniverse::Tensor10D, VramLedgerSlot::Tensor10D, bytes);
557    }
558
559    /// Record LLM KV-cache usage bytes (clamped to `KV_CACHE_CAP_BYTES`).
560    #[inline]
561    pub fn record_kv_cache(&self, bytes: u64) {
562        self.record_universe(
563            ComputeUniverse::LlmInference,
564            VramLedgerSlot::LlmKvCache,
565            bytes,
566        );
567    }
568
569    /// Record Viewport (U2) render usage bytes.
570    #[inline]
571    pub fn record_render(&self, bytes: u64) {
572        self.record_universe(ComputeUniverse::Viewport, VramLedgerSlot::Viewport, bytes);
573    }
574
575    /// Record LLM weight-staging usage bytes.
576    #[inline]
577    pub fn record_llm_staging(&self, bytes: u64) {
578        self.record_universe(
579            ComputeUniverse::LlmInference,
580            VramLedgerSlot::LlmWeightStaging,
581            bytes,
582        );
583    }
584
585    /// Total used bytes — recorded slots plus live graphics
586    /// reservations.
587    #[inline]
588    pub fn used_bytes(&self) -> u64 {
589        self.recorded_used_bytes()
590            .saturating_add(self.graphics_reservations.total_bytes())
591    }
592
593    /// Sum of the four recorded slot counters (excludes graphics
594    /// reservations).
595    #[inline]
596    fn recorded_used_bytes(&self) -> u64 {
597        self.tensor_bytes
598            .load(Ordering::Relaxed)
599            .saturating_add(self.kv_cache_bytes.load(Ordering::Relaxed))
600            .saturating_add(self.render_bytes.load(Ordering::Relaxed))
601            .saturating_add(self.llm_weight_staging_bytes.load(Ordering::Relaxed))
602    }
603
604    /// Global pressure = used ÷ budget, clamped to [0, 1.25] (0 with
605    /// no budget configured).
606    #[inline]
607    pub fn pressure(&self) -> f32 {
608        let budget = self.budget_bytes.load(Ordering::Relaxed);
609        if budget == 0 {
610            return 0.0;
611        }
612        (self.used_bytes() as f32 / budget as f32).clamp(0.0, 1.25)
613    }
614
615    /// Current operational mode (last `refresh_mode` result; `Full`
616    /// before any write).
617    #[inline]
618    pub fn mode(&self) -> OperationalMode {
619        match self.mode.load(Ordering::Relaxed) {
620            1 => OperationalMode::Eco,
621            2 => OperationalMode::Reserve,
622            _ => OperationalMode::Full,
623        }
624    }
625
626    /// Recompute the operational mode from live pressure and store it.
627    #[inline]
628    pub fn refresh_mode(&self) {
629        let m = OperationalMode::from_pressure(self.pressure());
630        self.mode.store(m as u32, Ordering::Relaxed);
631    }
632
633    /// Whether `extra_bytes` fits inside the global budget
634    /// (overflow-safe comparison).
635    #[inline]
636    pub fn can_allocate(&self, extra_bytes: u64) -> bool {
637        let budget = self.budget_bytes.load(Ordering::Relaxed);
638        self.used_bytes()
639            .checked_add(extra_bytes)
640            .is_some_and(|required| required <= budget)
641    }
642}
643
644/// Process-wide ledger (lazy static).
645static LEDGER: std::sync::OnceLock<VramLedger> = std::sync::OnceLock::new();
646
647/// Process-wide VRAM ledger (lazy static, 6 GiB default budget).
648#[inline]
649pub fn global_vram_ledger() -> &'static VramLedger {
650    LEDGER.get_or_init(|| VramLedger::new(6 * 1024 * 1024 * 1024))
651}
652
653// ── Ambient telemetry pulses (atomics, zero-heap) ─────────────────────────────
654
655static LLM_HEAT_MILLI: AtomicU32 = AtomicU32::new(0);
656static LOGIC_FLASH_MILLI: AtomicU32 = AtomicU32::new(0);
657static BAKE_PULSE_MILLI: AtomicU32 = AtomicU32::new(0);
658static NETWORK_RIPPLE_MILLI: AtomicU32 = AtomicU32::new(0);
659static PRODUCER_CYCLE_MILLI: AtomicU32 = AtomicU32::new(0);
660static CONTEXT_RING_DROP_MILLI: AtomicU32 = AtomicU32::new(0);
661static DRAFT_ACCEPT_MILLI: AtomicU32 = AtomicU32::new(0);
662static DRAFT_LEN_CUR: AtomicU32 = AtomicU32::new(0);
663
664/// Raise `atom` to at least `strength_milli` (monotonic-max pulse).
665#[inline]
666fn pulse(atom: &AtomicU32, strength_milli: u32) {
667    let cur = atom.load(Ordering::Relaxed);
668    atom.store(cur.max(strength_milli), Ordering::Relaxed);
669}
670
671/// Read `atom` as a [0,1] fraction, then subtract `decay`
672/// (saturating) — per-frame ambient telemetry decay.
673#[inline]
674fn sample_decay(atom: &AtomicU32, decay: u32) -> f32 {
675    let v = atom.load(Ordering::Relaxed);
676    atom.store(v.saturating_sub(decay), Ordering::Relaxed);
677    (v as f32 / 1000.0).clamp(0.0, 1.0)
678}
679
680/// Called once per autoregressive decode step (gguf_bridge hot loop).
681#[inline]
682pub fn record_llm_decode_step() {
683    pulse(&LLM_HEAT_MILLI, 1000);
684}
685
686/// SPARQL / GeoSPARQL / rule resolution flash.
687#[inline]
688pub fn record_logic_flash() {
689    pulse(&LOGIC_FLASH_MILLI, 900);
690}
691
692/// Tensor / Quin bake or encode event.
693#[inline]
694pub fn record_bake_pulse() {
695    pulse(&BAKE_PULSE_MILLI, 850);
696    global_vram_ledger().refresh_mode();
697}
698
699/// Mesh / network I/O ripple (daemon fetch, torrent, etc.).
700#[inline]
701pub fn record_network_ripple() {
702    pulse(&NETWORK_RIPPLE_MILLI, 700);
703}
704
705/// U1 background producer completed a kNN inject cycle (B3.3).
706#[inline]
707pub fn record_producer_cycle(pushed_tokens: u32) {
708    let strength = (500 + pushed_tokens.min(16) * 25).min(1000);
709    pulse(&PRODUCER_CYCLE_MILLI, strength);
710}
711
712/// Context inject ring full — lossy drop rather than stalling U0.
713#[inline]
714pub fn record_context_ring_drop() {
715    pulse(&CONTEXT_RING_DROP_MILLI, 800);
716}
717
718/// Topological speculative decode: accepted draft tokens this step (B3.1e).
719#[inline]
720pub fn record_draft_acceptance(accepted: u32, draft_len: u32) {
721    if draft_len > 0 {
722        let rate = ((accepted as u64) * 1000 / draft_len as u64).min(1000) as u32;
723        DRAFT_LEN_CUR.store(draft_len, Ordering::Relaxed);
724        pulse(&DRAFT_ACCEPT_MILLI, rate);
725    }
726}
727
728/// Portal + desktop ambient field sampling (48 B contract subset).
729#[inline]
730pub fn sample_ambient_telemetry() -> [f32; 11] {
731    let ledger = global_vram_ledger();
732    [
733        ledger.pressure(),
734        sample_decay(&NETWORK_RIPPLE_MILLI, 25),
735        sample_decay(&BAKE_PULSE_MILLI, 20),
736        sample_decay(&LOGIC_FLASH_MILLI, 35),
737        sample_decay(&LLM_HEAT_MILLI, 30),
738        sample_decay(&PRODUCER_CYCLE_MILLI, 18),
739        sample_decay(&CONTEXT_RING_DROP_MILLI, 22),
740        0.08,
741        0.25,
742        ledger.pressure() * 0.5,
743        ledger.mode() as u32 as f32,
744    ]
745}
746
747// ── Shared wgpu device (native: one device per process) ───────────────────────
748
749#[cfg(feature = "gpu-runtime")]
750pub struct SharedGpuContext {
751    pub provider_lease: etalon_agent::device_lease::DeviceLease,
752    pub device: etalon::Device,
753    pub queue: etalon::Queue,
754    /// The wgpu instance — needed to create surfaces (must be same instance as adapter).
755    pub instance: etalon::Instance,
756    /// The wgpu adapter — needed to create surfaces and query capabilities.
757    pub adapter: etalon::Adapter,
758    /// Immutable adapter capability snapshot for diagnostics and feature negotiation.
759    pub adapter_caps: GpuAdapterCaps,
760    /// Feature subset actually requested on the process-wide device.
761    pub enabled_features: GpuFeatureCaps,
762    /// Whether `TIMESTAMP_QUERY` was negotiated on this device (adapter-dependent).
763    /// When false, the LLM GPU profiler degrades to a no-op (CPU wall-clock only).
764    pub timestamps_supported: bool,
765    /// Nanoseconds per timestamp tick (`Queue::get_timestamp_period`); 0.0 when unsupported.
766    pub timestamp_period_ns: f32,
767}
768
769#[cfg(feature = "gpu-runtime")]
770impl SharedGpuContext {
771    /// Logical queue lane for universe-tagged dispatch (B2.3).
772    /// Single physical `etalon::Queue` today; lane tags preserve driver scheduling intent.
773    #[inline]
774    pub fn queue_for_lane(&self, lane: QueueLane) -> &etalon::Queue {
775        let _ = lane;
776        &self.queue
777    }
778
779    /// Queue for `universe`'s default lane — same physical queue;
780    /// universe tagging is intent metadata today.
781    #[inline]
782    pub fn queue_for_universe(&self, universe: ComputeUniverse) -> &etalon::Queue {
783        self.queue_for_lane(universe.default_queue_lane())
784    }
785
786    /// Create an Etalon HAL compute lane borrowing this device and queue.
787    pub fn create_etalon_hal_lane(&self) -> etalon_agent::HalComputeLane {
788        etalon_agent::HalComputeLane::new(
789            std::sync::Arc::new(self.device.clone()),
790            std::sync::Arc::new(self.queue.clone()),
791            etalon_agent::QueueId(0),
792        )
793    }
794
795    /// Create an Etalon ring-slab allocator with the requested capacity.
796    pub fn create_etalon_slab_allocator(
797        &self,
798        capacity_bytes: u64,
799        label: &str,
800    ) -> etalon_agent::QualiaSlabAllocator {
801        let _ = (&self.device, label);
802        etalon_agent::QualiaSlabAllocator::new(
803            capacity_bytes as usize,
804            etalon_agent::slab::DEFAULT_BINDING_ALIGNMENT,
805        )
806    }
807}
808
809#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
810static SHARED_GPU: OnceLock<Option<SharedGpuContext>> = OnceLock::new();
811
812// WebGPU Device is !Send/!Sync (Rc internals). The browser is single-threaded,
813// so the shared context lives in a thread-local leaked slot rather than a Sync OnceLock.
814#[cfg(all(target_arch = "wasm32", feature = "gpu-runtime"))]
815std::thread_local! {
816    static WASM_SHARED_GPU: std::cell::Cell<Option<&'static SharedGpuContext>> =
817        const { std::cell::Cell::new(None) };
818}
819
820/// Choose the DX12 shader compiler. DX12's legacy FXC compiler cannot compile our flash-attention
821/// shader (`fused_attention.wgsl`, X4026) — DXC (the modern compiler) can. Resolution order:
822///   1. `QUALIA_DXC_PATH` → `DynamicDxc` at that explicit `dxcompiler.dll` (bespoke override).
823///   2. `dxcompiler.dll` beside the current executable (where `build.rs` copies the vendored
824///      `vendor/dxc/` DLLs) → `DynamicDxc` at that path (turnkey — no env var needed).
825///   3. Otherwise `Auto` (static-DXC → PATH-DXC → FXC) — graceful fallback (Vulkan stays default).
826///
827/// Resolution order documented above; returns the chosen compiler.
828#[cfg(all(
829    not(target_arch = "wasm32"),
830    feature = "gpu-runtime",
831    feature = "gpu-native-dx12"
832))]
833fn resolve_dx12_compiler() -> etalon::Dx12Compiler {
834    if let Ok(p) = std::env::var("QUALIA_DXC_PATH") {
835        if !p.trim().is_empty() {
836            log::info!("shared_gpu|dx12_compiler|DynamicDxc(env)={p}");
837            return etalon::Dx12Compiler::DynamicDxc { dxc_path: p };
838        }
839    }
840    if let Ok(exe) = std::env::current_exe() {
841        if let Some(dir) = exe.parent() {
842            let dll = dir.join("dxcompiler.dll");
843            if dll.exists() {
844                log::info!(
845                    "shared_gpu|dx12_compiler|DynamicDxc(vendored)={}",
846                    dll.display()
847                );
848                return etalon::Dx12Compiler::DynamicDxc {
849                    dxc_path: dll.to_string_lossy().into_owned(),
850                };
851            }
852        }
853    }
854    etalon::Dx12Compiler::Auto
855}
856
857/// Native init: request a high-performance adapter (falling back to
858/// the default), then build the `SharedGpuContext` for it.
859#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
860async fn init_shared_gpu_async() -> Result<SharedGpuContext, String> {
861    // Inference-pipeline (GPU backend) selection. Default = wgpu's own pick; `QUALIA_WGPU_BACKEND`
862    // pins it (e.g. =vulkan for the vendor-neutral path). The capability checker then reports what
863    // was actually selected + the recommendation, so "which pipeline is this machine on" is visible.
864    // DX12 shader compiler: the legacy FXC (D3DCompile) compiler CANNOT compile our flash-attention
865    // shader (`fused_attention.wgsl` — barriers after a per-thread varying-length SDPA loop; FXC
866    // error X4026), which is what the long-mislabelled "DX12 decode deadlock" actually was. DXC (the
867    // modern DirectX Shader Compiler) compiles it correctly. wgpu's own default is `Auto`
868    // (static-DXC → DXC-on-PATH → FXC), so DX12 silently falls back to FXC unless `dxcompiler.dll`
869    // is discoverable. `QUALIA_DXC_PATH` points wgpu straight at a `dxcompiler.dll` (with `dxil.dll`
870    // alongside it, for DXIL signing) so DX12 uses DXC without needing it on PATH. Absent the var we
871    // keep `Auto` (Vulkan stays the working default backend regardless).
872    let mut desc = etalon::InstanceDescriptor::new_without_display_handle();
873    #[cfg(feature = "gpu-native-dx12")]
874    {
875        let dx12_compiler = resolve_dx12_compiler();
876        desc.backend_options.dx12.shader_compiler = dx12_compiler;
877    }
878    if let Some(backends) = caps::qualia_backend_override() {
879        log::info!("shared_gpu|backend_override|QUALIA_WGPU_BACKEND={backends:?}");
880        desc.backends = backends;
881    } else if cfg!(target_os = "windows") {
882        #[cfg(feature = "gpu-native-dx12")]
883        {
884            // Windows default = DX12. It is the verified-reliable native path: the DXC compiler fix
885            // builds the fused-attention shader, and DX12 decodes Q4_K_M / large models (e.g.
886            // llama-3.2-3b) that the Vulkan/SPIR-V path currently HANGS on (tracked bug). Vulkan is
887            // still the default off-Windows and remains selectable anywhere via QUALIA_WGPU_BACKEND=vulkan.
888            desc.backends = etalon::Backends::DX12;
889            log::info!(
890                "shared_gpu|backend_default|windows->dx12 (override with QUALIA_WGPU_BACKEND=vulkan)"
891            );
892        }
893        #[cfg(not(feature = "gpu-native-dx12"))]
894        {
895            // Portable builds are intended for browser/viewport use. Keep the
896            // shared inference device on GLES rather than silently selecting
897            // the Vulkan path with its tracked native inference hang.
898            desc.backends = etalon::Backends::GL;
899            log::info!("shared_gpu|backend_default|windows->gles_portable_build");
900        }
901    }
902    let instance = etalon::Instance::new(desc);
903    let adapter = instance
904        .request_adapter(&etalon::RequestAdapterOptions {
905            power_preference: etalon::PowerPreference::HighPerformance,
906            ..Default::default()
907        })
908        .await
909        .map_err(|e| format!("Failed to find wgpu adapter: {e}"))?;
910
911    // Primary circuit only: size the process-wide VRAM ledger from the best adapter's dedicated
912    // memory (Windows/DXGI). The global ledger models the PRIMARY LLM device's budget, so the
913    // per-circuit `device_registry` path (auxiliary GPUs) deliberately does NOT touch it.
914    #[cfg(target_os = "windows")]
915    if let Ok(memory) = crate::directml_bridge::probe_best_adapter_memory() {
916        let total_local = memory
917            .local_budget_bytes
918            .max(memory.dedicated_vram_bytes)
919            .max(memory.available_local_bytes());
920        if total_local > 0 {
921            global_vram_ledger().set_budget(total_local);
922        }
923    }
924
925    init_shared_gpu_for_adapter(instance, adapter).await
926}
927
928#[cfg(all(target_arch = "wasm32", feature = "gpu-runtime"))]
929pub(crate) use etalon_resources::device_caps::webgpu_minimum_limits;
930
931/// Build a [`SharedGpuContext`] from a GIVEN instance + adapter — the reusable core shared by the
932/// process-wide primary device ([`init_shared_gpu_async`], which requests its own HighPerformance
933/// adapter then delegates here) and the per-circuit [`device_registry`]. Requests only
934/// adapter-advertised features, raises buffer-size limits to the adapter maximum, and negotiates
935/// timestamps. Never panics; returns `Err` on device-request failure so callers can fall back.
936#[cfg(feature = "gpu-runtime")]
937pub(crate) async fn init_shared_gpu_for_adapter(
938    instance: etalon::Instance,
939    adapter: etalon::Adapter,
940) -> Result<SharedGpuContext, String> {
941    let adapter_caps = GpuAdapterCaps::from_adapter(&adapter);
942    log::info!(
943        "shared_gpu|adapter|{}|{}",
944        adapter_caps.summary_line(),
945        adapter_caps.llm_feature_line()
946    );
947    log::info!(
948        "shared_gpu|inference_backend|{}|recommend: {}",
949        adapter_caps.backend_label(),
950        caps::recommend_inference_backend(&adapter_caps)
951    );
952    if adapter_caps.is_integrated_gpu()
953        && std::env::var("QUALIA_LLM_ALLOW_IGPU").ok().as_deref() != Some("1")
954    {
955        log::warn!(
956            "shared_gpu|adapter|integrated_gpu_selected|set QUALIA_LLM_ALLOW_IGPU=1 to acknowledge this for native LLM runs"
957        );
958    }
959
960    // Request only features the adapter advertises, and keep the selector in the caps module so
961    // native feature policy stays visible. Today only timestamps are used by default; f16,
962    // subgroup, pipeline-cache/statistics, and cooperative matrix are enabled for the optimized
963    // native shader variants that follow.
964    let required_features = requested_native_llm_features(adapter.features());
965    let enabled_features = GpuFeatureCaps::from_features(required_features);
966    log::info!(
967        "shared_gpu|enabled_features|{}",
968        enabled_features.compact_flags()
969    );
970    if adapter_caps.features.cooperative_matrix && !enabled_features.cooperative_matrix {
971        log::info!(
972            "shared_gpu|cooperative_matrix_supported_but_disabled|set QUALIA_WGPU_EXPERIMENTAL_FEATURES=1 to request it"
973        );
974    }
975    let _ts_supported = enabled_features.timestamp_query;
976    // Modern weight tensors blow past the wgpu DEFAULTS (max_buffer_size = 256 MiB,
977    // max_storage_buffer_binding_size = 128 MiB): the all-F16 Llama-3.2-3B tied lm_head
978    // (token_embd, 3072×128256×2 = 751 MiB) is a single resident buffer that the defaults reject
979    // ("Buffer size 788004864 > maximum buffer size 268435456"). Raise both caps to the adapter's
980    // reported maximum — always valid for request_device, so this never fails on weaker GPUs (they
981    // simply get their own, smaller, max). Vendor-neutral: pure wgpu limits, no CUDA / no extra
982    // device feature. Other limits stay at the conservative defaults.
983    let adapter_limits = {
984        #[cfg(target_arch = "wasm32")]
985        {
986            let _ = &adapter;
987            webgpu_minimum_limits()
988        }
989        #[cfg(not(target_arch = "wasm32"))]
990        {
991            adapter.limits()
992        }
993    };
994    let required_limits = etalon::Limits {
995        max_buffer_size: adapter_limits.max_buffer_size,
996        max_storage_buffer_binding_size: adapter_limits.max_storage_buffer_binding_size,
997        ..etalon::Limits::default()
998    };
999    let experimental_features = if required_features.intersects(
1000        etalon::Features::EXPERIMENTAL_COOPERATIVE_MATRIX | etalon::Features::EXPERIMENTAL_RAY_QUERY,
1001    ) {
1002        // Safety: experimental capabilities are requested only after intersecting
1003        // with the selected adapter's advertised feature set. Callers must also
1004        // explicitly opt in through QUALIA_WGPU_EXPERIMENTAL_FEATURES.
1005        unsafe { etalon::ExperimentalFeatures::enabled() }
1006    } else {
1007        etalon::ExperimentalFeatures::disabled()
1008    };
1009    let context = etalon_agent::shared_device::DeviceContext::request(
1010        instance,
1011        adapter,
1012        &etalon::DeviceDescriptor {
1013            required_features,
1014            required_limits,
1015            experimental_features,
1016            ..Default::default()
1017        },
1018    )
1019    .await?;
1020    Ok(SharedGpuContext {
1021        provider_lease: context.lease,
1022        device: context.device,
1023        queue: context.queue,
1024        instance: context.instance,
1025        adapter: context.adapter,
1026        adapter_caps: context.adapter_caps,
1027        enabled_features: context.enabled_features,
1028        timestamps_supported: context.timestamps_supported,
1029        timestamp_period_ns: context.timestamp_period_ns,
1030    })
1031}
1032
1033/// Process-wide wgpu device + queue, or `None` when no usable GPU adapter exists
1034/// (headless / integrated-only / GPU-less machine, or the tokio runtime can't start).
1035///
1036/// Callers that can degrade to CPU MUST use this and fall back on `None`, rather than
1037/// `shared_gpu()` which aborts the process. The `None` result is cached, so a GPU-less
1038/// machine probes once. (Init is lazy and reused by QTensorEngine + render.)
1039#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
1040pub fn try_shared_gpu() -> Option<&'static SharedGpuContext> {
1041    #[cfg(all(not(target_arch = "wasm32"), feature = "wgsl-forge"))]
1042    crate::wgsl_forge::install_device_policy();
1043    SHARED_GPU
1044        .get_or_init(|| {
1045            let handle = match tokio::runtime::Handle::try_current() {
1046                Ok(h) => h,
1047                Err(_) => match tokio::runtime::Runtime::new() {
1048                    Ok(rt) => Box::leak(Box::new(rt)).handle().clone(),
1049                    Err(_) => return None,
1050                },
1051            };
1052            tokio::task::block_in_place(|| handle.block_on(init_shared_gpu_async()).ok())
1053        })
1054        .as_ref()
1055}
1056
1057/// Fail-closed probe when `gpu-runtime` is off (qdnf-only / ontology lite).
1058/// Returns `None` so CPU floors stay live. Never panics. Does not name wgpu.
1059#[cfg(not(feature = "gpu-runtime"))]
1060pub fn try_shared_gpu() -> Option<&'static ()> {
1061    None
1062}
1063
1064/// Install the process-wide WebGPU device (browser). Idempotent.
1065/// Graph accel, the volumetric renderer, and LLM decode all reuse this device.
1066#[cfg(all(target_arch = "wasm32", feature = "gpu-runtime"))]
1067pub async fn ensure_shared_gpu() -> Result<(), String> {
1068    if WASM_SHARED_GPU.with(|c| c.get().is_some()) {
1069        return Ok(());
1070    }
1071    etalon_wasm::readback::recover_browser_worker()
1072        .map_err(|error| format!("Browser device recovery: {error:?}"))?;
1073    let ctx = init_shared_gpu_wasm().await?;
1074    // Another initializer may have installed the shared device while we awaited the adapter.
1075    if WASM_SHARED_GPU.with(|c| c.get().is_some()) {
1076        return Ok(());
1077    }
1078    let leaked: &'static SharedGpuContext = Box::leak(Box::new(ctx));
1079    WASM_SHARED_GPU.with(|c| c.set(Some(leaked)));
1080    let owner_identity = leaked as *const SharedGpuContext as usize;
1081    let worker = etalon_wasm::readback::browser_worker();
1082    leaked.device.set_device_lost_callback(move |reason, message| {
1083        let retired = WASM_SHARED_GPU.with(|slot| {
1084            if slot.get().is_some_and(|current| current as *const SharedGpuContext as usize == owner_identity) {
1085                slot.set(None);
1086                true
1087            } else {
1088                false
1089            }
1090        });
1091        if retired {
1092            worker.lock().unwrap().notify_device_lost();
1093            crate::gguf_bridge::WASM_ENGINE_INSTANCE.with(|slot| {
1094                *slot.borrow_mut() = None;
1095            });
1096            log::warn!("shared_gpu|browser_device_lost|{reason:?}|{message}");
1097        }
1098    });
1099    Ok(())
1100}
1101
1102/// WASM init: request a BROWSER_WEBGPU adapter (high-performance,
1103/// falling back to default), then build the `SharedGpuContext` for it.
1104#[cfg(all(target_arch = "wasm32", feature = "gpu-runtime"))]
1105async fn init_shared_gpu_wasm() -> Result<SharedGpuContext, String> {
1106    let mut desc = etalon::InstanceDescriptor::new_without_display_handle();
1107    desc.backends = etalon::Backends::BROWSER_WEBGPU;
1108    let instance = etalon::Instance::new(desc);
1109    let adapter = match instance
1110        .request_adapter(&etalon::RequestAdapterOptions {
1111            power_preference: etalon::PowerPreference::HighPerformance,
1112            ..Default::default()
1113        })
1114        .await
1115    {
1116        Ok(a) => a,
1117        Err(high_err) => instance
1118            .request_adapter(&etalon::RequestAdapterOptions::default())
1119            .await
1120            .map_err(|e| {
1121                format!(
1122                    "Failed to find WebGPU adapter (high-performance: {high_err}; default: {e})"
1123                )
1124            })?,
1125    };
1126    init_shared_gpu_for_adapter(instance, adapter).await
1127}
1128
1129/// The thread-local shared GPU context, `None` until
1130/// `ensure_shared_gpu` succeeds (WASM: per-thread slot since `Device`
1131/// is `!Send`/`!Sync`).
1132#[cfg(all(target_arch = "wasm32", feature = "gpu-runtime"))]
1133pub fn try_shared_gpu() -> Option<&'static SharedGpuContext> {
1134    WASM_SHARED_GPU.with(|c| c.get())
1135}
1136
1137/// Shared GPU context — **panics** if init hasn't run; prefer
1138/// [`try_shared_gpu`] on fallible paths.
1139#[cfg(all(target_arch = "wasm32", feature = "gpu-runtime"))]
1140pub fn shared_gpu() -> &'static SharedGpuContext {
1141    try_shared_gpu().expect("shared wgpu init failed — call ensure_shared_gpu() first")
1142}
1143
1144/// Process-wide wgpu device + queue (lazy init). **Panics** if no GPU is available —
1145/// use only where a device is genuinely mandatory. Prefer [`try_shared_gpu`] on any
1146/// path that can fall back to CPU.
1147#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
1148pub fn shared_gpu() -> &'static SharedGpuContext {
1149    try_shared_gpu().expect("shared wgpu init failed")
1150}
1151
1152/// Convenience helper to obtain an Etalon HAL compute lane from the shared GPU context,
1153/// or `None` if GPU runtime is unavailable or failed to initialize.
1154#[cfg(feature = "gpu-runtime")]
1155pub fn try_shared_etalon_hal_lane() -> Option<etalon_agent::HalComputeLane> {
1156    try_shared_gpu().map(|g| g.create_etalon_hal_lane())
1157}
1158
1159#[cfg(all(test, not(target_arch = "wasm32"), feature = "gpu-runtime"))]
1160mod shared_gpu_robustness_tests {
1161    use super::*;
1162
1163    #[test]
1164    fn try_shared_gpu_never_panics_and_is_idempotent() {
1165        // The point of the fix: probing for a GPU must NOT abort the process on a
1166        // GPU-less / headless machine, and the None/Some result is cached so repeated
1167        // calls agree (a GPU-less box probes exactly once).
1168        let first = try_shared_gpu().is_some();
1169        let second = try_shared_gpu().is_some();
1170        assert_eq!(first, second, "try_shared_gpu must be cached + consistent");
1171    }
1172}
1173
1174#[cfg(all(test, not(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))))]
1175mod try_shared_gpu_fail_closed_tests {
1176    use super::*;
1177
1178    #[test]
1179    fn try_shared_gpu_is_none_without_gpu_runtime() {
1180        assert!(try_shared_gpu().is_none());
1181    }
1182}
1183
1184#[cfg(test)]
1185mod tests {
1186    use super::*;
1187
1188    /// Reports which GPU backend the engine's shared device actually selected for inference on this
1189    /// machine (default, or pinned by `QUALIA_WGPU_BACKEND`). Run default vs `QUALIA_WGPU_BACKEND=vulkan`
1190    /// in separate processes to confirm the override drives the real device.
1191    #[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
1192    #[test]
1193    #[serial_test::serial(gpu)]
1194    fn report_inference_backend() {
1195        if !crate::wgsl_forge::test_gpu_available() {
1196            return;
1197        }
1198        let g = shared_gpu();
1199        eprintln!(
1200            "[inference-backend] selected = {} | recommend: {}",
1201            g.adapter_caps.backend_label(),
1202            recommend_inference_backend(&g.adapter_caps),
1203        );
1204        eprintln!("[inference-backend] {}", g.adapter_caps.summary_line());
1205        // The device must really exist (a backend was selected and an adapter acquired).
1206        assert!(!g.adapter_caps.backend_label().is_empty());
1207    }
1208
1209    #[test]
1210    fn pressure_triggers_eco_and_reserve() {
1211        let ledger = VramLedger::new(1000);
1212        ledger.record_tensor(500);
1213        assert_eq!(ledger.mode(), OperationalMode::Full);
1214        ledger.record_kv_cache(300);
1215        assert_eq!(ledger.mode(), OperationalMode::Eco);
1216        ledger.record_render(200);
1217        assert_eq!(ledger.mode(), OperationalMode::Reserve);
1218    }
1219
1220    #[test]
1221    fn universe_partitions_sum_below_total() {
1222        let orch = UniverseOrchestrator::from_total_budget_full(10_000);
1223        let sum: u64 = orch.partitions.iter().map(|p| p.vram_budget_bytes).sum();
1224        assert!(sum <= 10_000);
1225        assert_eq!(
1226            orch.partition(ComputeUniverse::LlmInference)
1227                .vram_budget_bytes,
1228            5500
1229        );
1230    }
1231
1232    #[test]
1233    fn reserve_mode_caps_u2_at_ten_percent() {
1234        let orch = UniverseOrchestrator::from_total_budget(10_000, OperationalMode::Reserve);
1235        assert_eq!(
1236            orch.partition(ComputeUniverse::Viewport).vram_budget_bytes,
1237            1_000
1238        );
1239        assert_eq!(
1240            orch.partition(ComputeUniverse::LlmInference)
1241                .vram_budget_bytes,
1242            4_500
1243        );
1244        assert_eq!(orch.active_mode, OperationalMode::Reserve);
1245    }
1246
1247    #[test]
1248    fn ledger_ranges_are_consecutive_non_overlapping() {
1249        let orch = UniverseOrchestrator::from_total_budget(10_000, OperationalMode::Eco);
1250        let u0 = orch.partition(ComputeUniverse::LlmInference).ledger_range;
1251        let u1 = orch.partition(ComputeUniverse::Tensor10D).ledger_range;
1252        let u2 = orch.partition(ComputeUniverse::Viewport).ledger_range;
1253        assert_eq!(u0.offset, 0);
1254        assert_eq!(u1.offset, u0.end());
1255        assert_eq!(u2.offset, u1.end());
1256        assert!(u2.end() <= 10_000);
1257    }
1258
1259    #[test]
1260    fn u2_cannot_evict_u0_kv_under_reserve() {
1261        let orch = UniverseOrchestrator::from_total_budget_full(10_000);
1262        assert_eq!(
1263            orch.effective_mode(ComputeUniverse::LlmInference, OperationalMode::Reserve),
1264            OperationalMode::Full
1265        );
1266        assert_eq!(
1267            orch.effective_mode(ComputeUniverse::Viewport, OperationalMode::Reserve),
1268            OperationalMode::Reserve
1269        );
1270    }
1271
1272    #[test]
1273    fn universe_budget_isolated() {
1274        let ledger = VramLedger::new(10_000);
1275        let orch = UniverseOrchestrator::from_total_budget_full(10_000);
1276        ledger.record_render(2000);
1277        assert!(ledger.can_allocate_in_universe(&orch, ComputeUniverse::LlmInference, 5000));
1278        assert!(!ledger.can_allocate_in_universe(&orch, ComputeUniverse::Viewport, 2000));
1279    }
1280
1281    #[test]
1282    fn ambient_draw_instant_step_by_mode() {
1283        let orch =
1284            UniverseOrchestrator::from_total_budget(6 * 1024 * 1024 * 1024, OperationalMode::Full);
1285        assert_eq!(
1286            orch.max_particles(ComputeUniverse::Viewport, OperationalMode::Full),
1287            50_000
1288        );
1289        assert_eq!(
1290            orch.max_particles(ComputeUniverse::Viewport, OperationalMode::Eco),
1291            8_000
1292        );
1293        assert_eq!(
1294            orch.max_particles(ComputeUniverse::Viewport, OperationalMode::Reserve),
1295            0
1296        );
1297
1298        let resident = 50_000_u32;
1299        assert_eq!(
1300            ambient_draw_instances_for_mode(resident, OperationalMode::Full),
1301            50_000
1302        );
1303        assert_eq!(
1304            ambient_draw_instances_for_mode(resident, OperationalMode::Eco),
1305            8_000
1306        );
1307        assert_eq!(
1308            ambient_draw_instances_for_mode(resident, OperationalMode::Reserve),
1309            0
1310        );
1311        assert_eq!(
1312            ambient_draw_instances_for_mode(3_000, OperationalMode::Eco),
1313            3_000
1314        );
1315    }
1316}