Skip to main content

qualia_core_db/platform/
hardware_passport.rs

1//! STELLAR §A AH-track H1(a) cache — the **hardware passport** (decision D26).
2//!
3//! Probing the host (H0 topology + H1(a) cross-circuit benchmark) costs real time; doing it every
4//! boot burns TTFT (A7). The passport caches the discovered topology + capability matrix to a small
5//! **CBOR** blob keyed by the host's **adapter identifiers** (vendor:device handles — identifiers,
6//! not an "identity"). On later boots, if the current adapter set matches the cached key, the probe
7//! is skipped; a topology change invalidates the cache and forces a re-probe (D26/D28).
8//!
9//! CBOR (via `ciborium`, serde-compatible) is used rather than JSON: it round-trips IEEE-754 floats
10//! natively — including the `f64::INFINITY` that marks an in-pool (no-transfer) circuit — and a
11//! compact binary blob fits the project's `.q42` binary-first ethos. **Cache only (no signing):** the
12//! human-key *signing* of the passport (H1(b)) is gated on the identity remediation and lives
13//! elsewhere; this module never claims trust, only fast-boot.
14//!
15//! Native only.
16//! CPU/GPU measurements are cached here; NPU discovery is fresh and independent.
17#![cfg(not(target_arch = "wasm32"))]
18
19use serde::{Deserialize, Serialize};
20use std::io::Read;
21use std::path::PathBuf;
22
23use crate::device_benchmark::{benchmark_devices, CapabilityMatrix, CircuitKind};
24use crate::host_topology::{probe_host_topology, HostTopology};
25use std::path::Path;
26
27/// Bump when the passport layout changes (older blobs are then ignored → re-probe).
28/// v2: optional `decode_proxy_tok_s` per circuit + ranking by real decode when measured.
29pub const PASSPORT_VERSION: u32 = 2;
30
31/// Default representative GEMV side length for the cached benchmark.
32pub const PASSPORT_GEMV_N: usize = 2048;
33const MAX_PASSPORT_BYTES: usize = 4 * 1024 * 1024;
34
35/// Cached discovery: topology + measured capability matrix, keyed by adapter identifiers.
36#[derive(Debug, Clone, Serialize, Deserialize)]
37pub struct HardwarePassport {
38    pub version: u32,
39    /// Stable key from the discovered adapter identifiers (sorted `vendor:device` handles).
40    pub key: String,
41    pub topology: HostTopology,
42    pub matrix: CapabilityMatrix,
43    /// Best GPU backend token for inference (`dx12` / `vulkan` / `metal` / `gl`), if any.
44    /// Derived from the measured matrix; used when `QUALIA_WGPU_BACKEND` is unset.
45    #[serde(default)]
46    pub preferred_inference_backend: Option<String>,
47    /// GEMV n used for the matrix (for operator honesty).
48    #[serde(default)]
49    pub probe_gemv_n: usize,
50    /// Model path used for decode-proxy ranking (if any).
51    #[serde(default, skip_serializing_if = "Option::is_none")]
52    pub decode_proxy_model: Option<String>,
53    /// Decode tokens used for the proxy (0 = none).
54    #[serde(default)]
55    pub decode_proxy_tokens: u32,
56}
57
58/// Stable key from the discovered adapter identifiers (sorted `vendor:device`). Identifiers (handles),
59/// never an identity — this is referential integrity for "is this the same hardware set", nothing more.
60pub fn topology_key(topo: &HostTopology) -> String {
61    let mut ids: Vec<String> = topo
62        .adapters
63        .iter()
64        .map(|a| format!("{:04x}:{:04x}", a.vendor, a.device))
65        .collect();
66    ids.sort();
67    ids.join(",")
68}
69
70/// Default cache location (OS temp dir). Callers may pass any path (e.g. a per-user data dir).
71pub fn default_cache_path() -> PathBuf {
72    std::env::temp_dir().join("qualia_hardware_passport.cbor")
73}
74
75/// Serialize a passport to a CBOR blob on disk.
76pub fn write_passport(passport: &HardwarePassport, path: &Path) -> Result<(), String> {
77    if !gpu_cpu_only(passport) {
78        return Err("NPU execution claims cannot be stored in the GPU/CPU passport".into());
79    }
80    let mut buf = PassportBuffer(Vec::new());
81    ciborium::into_writer(passport, &mut buf).map_err(|e| format!("cbor encode: {e}"))?;
82    std::fs::write(path, &buf.0).map_err(|e| format!("write {}: {e}", path.display()))
83}
84
85struct PassportBuffer(Vec<u8>);
86
87impl std::io::Write for PassportBuffer {
88    fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
89        if bytes.len() > MAX_PASSPORT_BYTES.saturating_sub(self.0.len()) {
90            return Err(std::io::Error::other(
91                "hardware passport exceeds its byte budget",
92            ));
93        }
94        self.0.extend_from_slice(bytes);
95        Ok(bytes.len())
96    }
97
98    fn flush(&mut self) -> std::io::Result<()> {
99        Ok(())
100    }
101}
102
103/// Read + decode a passport (CBOR). Returns `None` on missing file, decode error, or version mismatch.
104pub fn read_passport(path: &Path) -> Option<HardwarePassport> {
105    let file = std::fs::File::open(path).ok()?;
106    if file.metadata().ok()?.len() > MAX_PASSPORT_BYTES as u64 {
107        return None;
108    }
109    let mut bytes = Vec::new();
110    file.take((MAX_PASSPORT_BYTES + 1) as u64)
111        .read_to_end(&mut bytes)
112        .ok()?;
113    if bytes.len() > MAX_PASSPORT_BYTES {
114        return None;
115    }
116    let passport: HardwarePassport = ciborium::from_reader(&bytes[..]).ok()?;
117    if passport.version != PASSPORT_VERSION || !gpu_cpu_only(&passport) {
118        return None;
119    }
120    Some(passport)
121}
122
123fn gpu_cpu_only(passport: &HardwarePassport) -> bool {
124    !passport.matrix.npu_probed
125        && !passport
126            .matrix
127            .circuits
128            .iter()
129            .any(|circuit| circuit.kind == CircuitKind::Npu)
130}
131
132/// Fast-boot entry: return the cached passport iff its adapter-identifier key matches the current
133/// host; otherwise probe (H0 + H1(a) benchmark), cache, and return. `(passport, was_cached)`.
134pub fn load_or_probe(path: &Path, gemv_n: usize) -> (HardwarePassport, bool) {
135    let topology = probe_host_topology();
136    let current_key = topology_key(&topology);
137
138    if let Some(cached) = read_passport(path) {
139        if cache_matches(&cached, &current_key, gemv_n) {
140            return (cached, true); // fast-boot: skip the probe (TTFT)
141        }
142        // key mismatch ⇒ hardware changed (D26/D28) → re-probe below.
143    }
144
145    let matrix = benchmark_devices(gemv_n);
146    let preferred = matrix
147        .best()
148        .and_then(|c| backend_env_token(&c.backend))
149        .map(str::to_string);
150    let fresh = HardwarePassport {
151        version: PASSPORT_VERSION,
152        key: current_key,
153        topology,
154        matrix,
155        preferred_inference_backend: preferred,
156        probe_gemv_n: gemv_n,
157        decode_proxy_model: None,
158        decode_proxy_tokens: 0,
159    };
160    let _ = write_passport(&fresh, path);
161    (fresh, false)
162}
163
164fn cache_matches(passport: &HardwarePassport, key: &str, gemv_n: usize) -> bool {
165    passport.key == key
166        && passport.probe_gemv_n == gemv_n
167        && passport.matrix.gemv_n == gemv_n
168        && gpu_cpu_only(passport)
169}
170
171/// Default small-model candidates for decode-proxy ranking (first existing wins).
172pub fn default_decode_proxy_model() -> Option<std::path::PathBuf> {
173    if let Ok(p) = std::env::var("QUALIA_LLM_PROFILE_MODEL") {
174        let pb = std::path::PathBuf::from(p);
175        if pb.is_file() {
176            return Some(pb);
177        }
178    }
179    const CANDIDATES: &[&str] = &[
180        r"C:\LLM_Models\P64\smollm2-360m-instruct-q8_0.f16.p64",
181        r"C:\LLM_Models\P64\smollm2-360m-instruct-q8_0.p64",
182        r"C:\LLM_Models\GGUF\smollm2-360m-instruct-q8_0.gguf",
183        r"C:\LLM_Models\GGUF\lmstudio-community\smollm2-360m-instruct-q8_0.gguf",
184    ];
185    CANDIDATES
186        .iter()
187        .map(std::path::PathBuf::from)
188        .find(|p| p.is_file())
189}
190
191/// Fixed factual probe used for coherence + throughput (same prompt as browser llmdemo gate).
192pub const DECODE_PROXY_PROBE_PROMPT: &str = "The capital of France is";
193
194/// Result of a decode-proxy measurement: speed **and** whether the completion is usable.
195#[derive(Debug, Clone)]
196pub struct DecodeProxyResult {
197    pub tok_s: f64,
198    pub text: String,
199    /// True when completion contains the expected factual anchor (e.g. "Paris").
200    pub coherence_ok: bool,
201    /// Backend that actually completed measured token forwards. This is derived
202    /// from production-path counters, never from the requested env label.
203    pub execution_path: String,
204    pub resident_hits: u64,
205    pub resident_fallbacks: u64,
206    pub cuda_mega_hits: u64,
207    pub cuda_mega_fallbacks: u64,
208}
209
210/// Greedy factual gate: completion must contain "paris" (case-insensitive).
211/// Garbage token streams fail closed — speed alone is not excellence.
212pub fn decode_proxy_coherence_ok(text: &str) -> bool {
213    text.to_ascii_lowercase().contains("paris")
214}
215
216/// Run a short resident decode on `model` under the **current** process backend.
217/// Returns tok/s + text + coherence, or `None` on hard failure.
218///
219/// Warm-up: one short decode builds pipelines / resident plan so the timed
220/// measurement is not dominated by first-token cold cost.
221///
222/// Safe from CLI (which already owns a Tokio multi-thread runtime): nested
223/// `block_on` panics, so we hop to a fresh OS thread for the measurement.
224pub fn measure_decode_proxy(model: &Path, n_tokens: u32) -> Option<DecodeProxyResult> {
225    #[cfg(feature = "wgsl-forge")]
226    crate::wgsl_forge::dispatch::ensure_cuda_runtime_path();
227    let n = n_tokens.max(8).min(128);
228    let path = model.to_path_buf();
229    // Greedy, bounded — comparable across backends.
230    crate::llm_bench::set_sampler_config(None);
231    let path_str = path.to_str()?.to_string();
232    let join = std::thread::Builder::new()
233        .name("decode-proxy".into())
234        .spawn(move || {
235            let prompt = DECODE_PROXY_PROBE_PROMPT;
236            // Warm: compile shaders + resident plan (discard rate).
237            let _ = crate::llm_bench::decode_with_metrics_blocking(&path_str, prompt, 4);
238            crate::llm_bench::reset_resident_path_counts();
239            crate::llm_bench::reset_cuda_mega_path_counts();
240            let measured = crate::llm_bench::decode_with_metrics_blocking(&path_str, prompt, n);
241            let resident = crate::llm_bench::resident_path_counts();
242            let cuda = crate::llm_bench::cuda_mega_path_counts();
243            (measured, resident, cuda)
244        })
245        .ok()?
246        .join();
247    match join {
248        Ok((Ok((text, tok_s)), resident, cuda)) if tok_s > 0.0 => {
249            let coherence_ok = decode_proxy_coherence_ok(&text);
250            let execution_path = match (resident.0 > 0, cuda.0 > 0) {
251                (true, false) => "wgpu-resident",
252                (false, true) => "cuda-c",
253                (true, true) => "mixed",
254                (false, false) => "legacy-or-unattributed",
255            }
256            .to_string();
257            Some(DecodeProxyResult {
258                tok_s,
259                text,
260                coherence_ok,
261                execution_path,
262                resident_hits: resident.0,
263                resident_fallbacks: resident.1,
264                cuda_mega_hits: cuda.0,
265                cuda_mega_fallbacks: cuda.1,
266            })
267        }
268        Ok((Ok(_), _, _)) => None,
269        Ok((Err(e), _, _)) => {
270            log::warn!("decode_proxy|fail|{e}");
271            None
272        }
273        Err(_) => {
274            log::warn!("decode_proxy|thread_panic");
275            None
276        }
277    }
278}
279
280/// Back-compat: tok/s only (callers that ignore quality still work).
281pub fn measure_decode_proxy_tok_s(model: &Path, n_tokens: u32) -> Option<f64> {
282    measure_decode_proxy(model, n_tokens).map(|r| r.tok_s)
283}
284
285/// Attach decode-proxy tok/s to GPU circuits by spawning a child process per backend
286/// (shared_gpu is process-wide OnceLock — cannot switch backends in-process).
287///
288/// `self_exe` should be the current CLI binary (`std::env::current_exe()`).
289/// Child runs: `llm decode-proxy <model> --tokens N` with `QUALIA_WGPU_BACKEND` set.
290pub fn attach_decode_proxy_via_subprocess(
291    matrix: &mut CapabilityMatrix,
292    model: &Path,
293    n_tokens: u32,
294    self_exe: &Path,
295) {
296    use std::process::Command;
297    let n = n_tokens.max(8).min(64);
298    // Measure only **discrete** GPU rows (iGPU would inherit a false tok/s if we
299    // keyed only by backend token — wgpu picks the discrete card under QUALIA_WGPU_BACKEND).
300    let mut seen_tokens = std::collections::HashSet::<String>::new();
301    for c in matrix.circuits.iter_mut() {
302        if c.kind != CircuitKind::DiscreteGpu {
303            continue;
304        }
305        let Some(token) = backend_env_token(&c.backend) else {
306            continue;
307        };
308        if !seen_tokens.insert(token.to_string()) {
309            continue;
310        }
311        let output = Command::new(self_exe)
312            .args([
313                "llm",
314                "decode-proxy",
315                &model.display().to_string(),
316                "--tokens",
317                &n.to_string(),
318            ])
319            .env("QUALIA_WGPU_BACKEND", token)
320            .env("QUALIA_P64_INTEGRITY", "metadata")
321            .env("RUST_LOG", "error")
322            .output();
323        let tok_s = match output {
324            Ok(o) if o.status.success() => {
325                let stdout = String::from_utf8_lossy(&o.stdout);
326                parse_decode_proxy_line(&stdout)
327            }
328            Ok(o) => {
329                log::warn!(
330                    "decode_proxy|child_fail|backend={token}|{}",
331                    String::from_utf8_lossy(&o.stderr)
332                );
333                None
334            }
335            Err(e) => {
336                log::warn!("decode_proxy|spawn_fail|backend={token}|{e}");
337                None
338            }
339        };
340        c.decode_proxy_tok_s = tok_s;
341        if let Some(t) = tok_s {
342            log::info!("decode_proxy|ok|backend={token}|{t:.2} tok/s");
343        }
344    }
345    // Copy to other discrete rows that share the same backend token only.
346    let mut by_token: std::collections::HashMap<String, f64> = std::collections::HashMap::new();
347    for c in &matrix.circuits {
348        if c.kind != CircuitKind::DiscreteGpu {
349            continue;
350        }
351        if let (Some(tok), Some(t)) = (backend_env_token(&c.backend), c.decode_proxy_tok_s) {
352            by_token.insert(tok.to_string(), t);
353        }
354    }
355    for c in matrix.circuits.iter_mut() {
356        if c.kind != CircuitKind::DiscreteGpu || c.decode_proxy_tok_s.is_some() {
357            continue;
358        }
359        if let Some(tok) = backend_env_token(&c.backend) {
360            if let Some(&t) = by_token.get(tok) {
361                c.decode_proxy_tok_s = Some(t);
362            }
363        }
364    }
365    matrix.apply_decode_proxy_ranking();
366}
367
368/// Parse `DECODE_PROXY tok_s=12.34 backend=dx12 coherence=1` from child stdout.
369pub fn parse_decode_proxy_line(stdout: &str) -> Option<f64> {
370    parse_decode_proxy_record(stdout).map(|r| r.tok_s)
371}
372
373/// Full parse of the machine line from `llm decode-proxy`.
374#[derive(Debug, Clone)]
375pub struct DecodeProxyLine {
376    pub tok_s: f64,
377    pub coherence_ok: Option<bool>,
378    pub execution_path: Option<String>,
379}
380
381/// Parses `decode-proxy-record`.
382pub fn parse_decode_proxy_record(stdout: &str) -> Option<DecodeProxyLine> {
383    for line in stdout.lines() {
384        let line = line.trim();
385        if let Some(rest) = line.strip_prefix("DECODE_PROXY ") {
386            let mut tok_s: Option<f64> = None;
387            let mut coherence_ok: Option<bool> = None;
388            let mut execution_path: Option<String> = None;
389            for part in rest.split_whitespace() {
390                if let Some(v) = part.strip_prefix("tok_s=") {
391                    tok_s = v.parse().ok();
392                } else if let Some(v) = part.strip_prefix("coherence=") {
393                    coherence_ok = Some(v == "1" || v.eq_ignore_ascii_case("true"));
394                } else if let Some(v) = part.strip_prefix("path=") {
395                    execution_path = Some(v.to_string());
396                }
397            }
398            if let Some(tok_s) = tok_s {
399                return Some(DecodeProxyLine {
400                    tok_s,
401                    coherence_ok,
402                    execution_path,
403                });
404            }
405        }
406    }
407    None
408}
409
410/// Convenience: fast-boot against the default cache path + GEMV size.
411pub fn load_or_probe_default() -> (HardwarePassport, bool) {
412    load_or_probe(&default_cache_path(), PASSPORT_GEMV_N)
413}
414
415/// Best measured GPU backend name from a cached passport, if any (`"Dx12"`, `"Vulkan"`, `"Metal"`…).
416/// Does **not** re-probe. Used by `gpu_context` when `QUALIA_WGPU_BACKEND` is unset so the
417/// machine's measured ranking (not a static Windows→DX12 rule alone) selects the path.
418pub fn cached_preferred_wgpu_backend() -> Option<String> {
419    let path = default_cache_path();
420    let passport = read_passport(&path)?;
421    // Prefer the stored token when present (stable across schema evolution).
422    if let Some(ref t) = passport.preferred_inference_backend {
423        return Some(t.clone());
424    }
425    let best = passport.matrix.best()?;
426    // CPU-only win → do not pin a GPU backend.
427    if matches!(best.kind, crate::device_benchmark::CircuitKind::Cpu) {
428        return None;
429    }
430    Some(best.backend.clone())
431}
432
433/// Map a passport `backend` string (`"Dx12"`, `"Vulkan"`, …) to a `QUALIA_WGPU_BACKEND` env value.
434pub fn backend_env_token(backend: &str) -> Option<&'static str> {
435    let s = backend.to_ascii_lowercase();
436    if s.contains("dx12") || s.contains("d3d12") {
437        Some("dx12")
438    } else if s.contains("vulkan") {
439        Some("vulkan")
440    } else if s.contains("metal") {
441        Some("metal")
442    } else if s.contains("gl") {
443        Some("gl")
444    } else {
445        None
446    }
447}
448
449#[cfg(test)]
450mod tests {
451    use super::*;
452    use crate::device_benchmark::{CapabilityMatrix, CircuitBench, CircuitKind};
453    use crate::host_topology::{AdapterClass, AdapterDesc, HostMemoryTopology, HostTopology};
454
455    const GB: u64 = 1024 * 1024 * 1024;
456
457    fn synthetic_passport() -> HardwarePassport {
458        let topology = HostTopology {
459            adapters: vec![
460                AdapterDesc {
461                    name: "Discrete GPU".into(),
462                    backend: "Dx12".into(),
463                    class: AdapterClass::Discrete,
464                    vendor: 0x10de,
465                    device: 0x2571,
466                    dedicated_vram_bytes: 12 * GB,
467                },
468                AdapterDesc {
469                    name: "iGPU".into(),
470                    backend: "Dx12".into(),
471                    class: AdapterClass::Integrated,
472                    vendor: 0x8086,
473                    device: 0x1912,
474                    dedicated_vram_bytes: 0,
475                },
476            ],
477            topology: HostMemoryTopology::Discrete,
478            host_ram_bytes: 64 * GB,
479            host_ram_available_bytes: 32 * GB,
480            cpu_cores: 8,
481            os_floor_bytes: 3 * GB / 2,
482            usable_model_budget_bytes: 12 * GB,
483        };
484        let matrix = CapabilityMatrix {
485            circuits: vec![
486                CircuitBench {
487                    label: "Discrete GPU".into(),
488                    kind: CircuitKind::DiscreteGpu,
489                    backend: "Dx12".into(),
490                    ms_per_gemv: 0.43,
491                    gflops: 19.5,
492                    upload_gbps: 3.3,
493                    rel_score: 1.0,
494                    decode_proxy_tok_s: Some(18.0),
495                },
496                CircuitBench {
497                    label: "CPU native".into(),
498                    kind: CircuitKind::Cpu,
499                    backend: "native".into(),
500                    ms_per_gemv: 23.0,
501                    gflops: 0.4,
502                    upload_gbps: f64::INFINITY, // in-pool — must survive the round-trip
503                    rel_score: 0.02,
504                    decode_proxy_tok_s: None,
505                },
506            ],
507            gemv_n: 2048,
508            npu_probed: false,
509        };
510        HardwarePassport {
511            version: PASSPORT_VERSION,
512            key: topology_key(&topology),
513            topology,
514            matrix,
515            preferred_inference_backend: Some("dx12".into()),
516            probe_gemv_n: 2048,
517            decode_proxy_model: None,
518            decode_proxy_tokens: 0,
519        }
520    }
521
522    #[test]
523    fn cbor_round_trip_preserves_infinity_and_key() {
524        let p = synthetic_passport();
525        let dir = tempfile::tempdir().unwrap();
526        let path = dir.path().join("passport.cbor");
527
528        write_passport(&p, &path).expect("write");
529        let back = read_passport(&path).expect("read");
530
531        assert_eq!(back.version, PASSPORT_VERSION);
532        assert_eq!(back.key, p.key);
533        assert_eq!(back.key, "10de:2571,8086:1912");
534        assert_eq!(back.topology.adapters.len(), 2);
535        // The in-pool sentinel (infinite bandwidth) must survive CBOR — the reason for CBOR over JSON.
536        let cpu = back
537            .matrix
538            .circuits
539            .iter()
540            .find(|c| c.kind == CircuitKind::Cpu)
541            .unwrap();
542        assert!(
543            cpu.upload_gbps.is_infinite(),
544            "f64::INFINITY must round-trip through CBOR"
545        );
546        assert!((back.matrix.circuits[0].ms_per_gemv - 0.43).abs() < 1e-9);
547    }
548
549    #[test]
550    fn version_mismatch_is_ignored() {
551        let mut p = synthetic_passport();
552        p.version = 999;
553        let dir = tempfile::tempdir().unwrap();
554        let path = dir.path().join("passport.cbor");
555        write_passport(&p, &path).unwrap();
556        assert!(
557            read_passport(&path).is_none(),
558            "stale version must be rejected → re-probe"
559        );
560    }
561
562    #[test]
563    fn gpu_passport_cannot_restore_npu_execution_claims() {
564        let dir = tempfile::tempdir().unwrap();
565        let path = dir.path().join("passport.cbor");
566        for has_npu_row in [false, true] {
567            let mut passport = synthetic_passport();
568            if has_npu_row {
569                passport.matrix.circuits[0].kind = CircuitKind::Npu;
570            } else {
571                passport.matrix.npu_probed = true;
572            }
573            let mut bytes = Vec::new();
574            ciborium::into_writer(&passport, &mut bytes).unwrap();
575            std::fs::write(&path, bytes).unwrap();
576            assert!(read_passport(&path).is_none());
577            assert!(write_passport(&passport, &path).is_err());
578        }
579    }
580
581    #[test]
582    fn benchmark_shape_changes_invalidate_the_gpu_cache() {
583        let mut passport = synthetic_passport();
584        assert!(cache_matches(&passport, &passport.key, 2048));
585        assert!(!cache_matches(&passport, &passport.key, 512));
586        passport.matrix.gemv_n = 512;
587        assert!(!cache_matches(&passport, &passport.key, 2048));
588    }
589
590    #[test]
591    fn oversized_passports_are_rejected_before_decoding() {
592        let dir = tempfile::tempdir().unwrap();
593        let path = dir.path().join("passport.cbor");
594        std::fs::File::create(&path)
595            .unwrap()
596            .set_len((MAX_PASSPORT_BYTES + 1) as u64)
597            .unwrap();
598        assert!(read_passport(&path).is_none());
599        let mut passport = synthetic_passport();
600        passport.key = "a".repeat(MAX_PASSPORT_BYTES);
601        assert!(write_passport(&passport, &path).is_err());
602    }
603
604    #[test]
605    fn parse_decode_proxy_line_extracts_tok_s() {
606        let s = "noise\nDECODE_PROXY tok_s=12.50 backend=dx12 coherence=1\nmore\n";
607        assert!((parse_decode_proxy_line(s).unwrap() - 12.5).abs() < 1e-9);
608        let r = parse_decode_proxy_record(s).unwrap();
609        assert_eq!(r.coherence_ok, Some(true));
610        assert_eq!(r.execution_path, None);
611
612        let attributed =
613            "DECODE_PROXY tok_s=44.25 backend=cuda path=cuda-c coherence=1 cuda_hits=16\n";
614        let attributed = parse_decode_proxy_record(attributed).unwrap();
615        assert_eq!(attributed.execution_path.as_deref(), Some("cuda-c"));
616        assert!(parse_decode_proxy_line("nope").is_none());
617        assert!(decode_proxy_coherence_ok("… Paris is lovely"));
618        assert!(!decode_proxy_coherence_ok("asdkfjhasdf"));
619    }
620
621    #[test]
622    fn decode_proxy_ranking_prefers_higher_tok_s() {
623        let mut matrix = CapabilityMatrix {
624            circuits: vec![
625                CircuitBench {
626                    label: "fast gemv slow decode".into(),
627                    kind: CircuitKind::DiscreteGpu,
628                    backend: "Vulkan".into(),
629                    ms_per_gemv: 0.1,
630                    gflops: 50.0,
631                    upload_gbps: 4.0,
632                    rel_score: 1.0,
633                    decode_proxy_tok_s: Some(5.0),
634                },
635                CircuitBench {
636                    label: "slower gemv fast decode".into(),
637                    kind: CircuitKind::DiscreteGpu,
638                    backend: "Dx12".into(),
639                    ms_per_gemv: 0.2,
640                    gflops: 25.0,
641                    upload_gbps: 4.0,
642                    rel_score: 0.5,
643                    decode_proxy_tok_s: Some(18.0),
644                },
645            ],
646            gemv_n: 512,
647            npu_probed: false,
648        };
649        matrix.apply_decode_proxy_ranking();
650        assert_eq!(matrix.best().unwrap().backend, "Dx12");
651        assert!((matrix.best().unwrap().rel_score - 1.0).abs() < 1e-9);
652    }
653
654    /// Real fast-boot path: first call probes + caches (was_cached=false); second loads (true).
655    /// Runs the benchmark once (CPU always available); GPU rows appear if an adapter is present.
656    #[test]
657    fn load_or_probe_caches_then_hits() {
658        let dir = tempfile::tempdir().unwrap();
659        let path = dir.path().join("passport.cbor");
660
661        let (first, cached1) = load_or_probe(&path, 512);
662        assert!(!cached1, "first call must probe");
663        assert!(path.exists(), "probe must write the cache");
664        assert!(!first.matrix.circuits.is_empty());
665
666        let (second, cached2) = load_or_probe(&path, 512);
667        assert!(cached2, "second call must hit the cache (fast-boot)");
668        assert_eq!(second.key, first.key);
669    }
670}