Skip to main content

qualia_core_db/q42/
execution_profile.rs

1//! P64 / Q42 **execution profile** — attested how to run a **native package at excellence**.
2//!
3//! QualiaDB is a human-centric multi-capability system. Inference packages are one toolchain
4//! lane. The profile exists so autonomous campaigns optimise **speed and sense** (and later
5//! grounding/rights), not so agents ship half-working “skeleton” products.
6//!
7//! ## On disk
8//! Sibling of a winner `.p64`: `{stem}.execution-profile.json`
9
10use serde::{Deserialize, Serialize};
11use std::path::{Path, PathBuf};
12
13/// Schema version for campaign tooling (bump when fields change meaning).
14pub const EXECUTION_PROFILE_VERSION: u32 = 1;
15
16/// File suffix: `model.f16.p64` → `model.f16.execution-profile.json` (stem-preserving).
17pub const EXECUTION_PROFILE_SUFFIX: &str = "execution-profile.json";
18
19/// Exactness class of an execution lane (`ADR 0003` / Q42 v4 §6.2.3).
20#[repr(C)]
21#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
22pub enum ExactnessProfile {
23    /// Exact integer, rational, symbolic, or bitwise-deterministic evaluation (`mismatches == 0`).
24    Exact,
25    /// Bounded numerical evaluation with explicit non-negative finite error bounds.
26    DeterministicApproximate { abs_bound: f64, rel_bound: f64 },
27    /// Heuristic, stochastic, or fast-math GPU preview lane; never admissible as a policy/rights oracle.
28    InteractiveApproximate,
29}
30
31/// Epistemic solver verification outcome distinguishing witness verification, bounded domain exhaustion,
32/// incomplete budget exhaustion, and global mathematical impossibility (`Q42-08` / §6.2.3).
33#[repr(C)]
34#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
35pub enum SolverVerificationOutcome {
36    /// Concrete witness verified via exact integer/symbolic arithmetic.
37    WitnessChecked,
38    /// Exhaustively proved unsatisfiable within the declared bounded search domain.
39    UnsatisfiableWithinDomain,
40    /// Search/QPU/heuristic budget exhausted without a verified witness or impossibility proof.
41    UnknownWithinBudget,
42    /// Global algebraic/modular obstruction proved (e.g., `k ≡ 4, 5 (mod 9)` for `x^3 + y^3 + z^3 = k`).
43    GlobalImpossibilityProved,
44}
45
46/// Gate function enforcing `ADR 0003`: policy, deontic, and identity decisions require exact
47/// verification (`Exact` or zero-error `DeterministicApproximate`) and hard-reject `InteractiveApproximate`.
48pub fn admit_for_policy_decision(profile: &ExactnessProfile) -> Result<(), &'static str> {
49    match profile {
50        ExactnessProfile::Exact => Ok(()),
51        ExactnessProfile::DeterministicApproximate {
52            abs_bound,
53            rel_bound,
54        } if abs_bound.is_finite()
55            && rel_bound.is_finite()
56            && *abs_bound == 0.0
57            && *rel_bound == 0.0 =>
58        {
59            Ok(())
60        }
61        ExactnessProfile::DeterministicApproximate { .. } => Err(
62            "DeterministicApproximate with non-zero error bounds cannot be admitted for policy/rights decisions without an exact CPU/symbolic oracle check",
63        ),
64        ExactnessProfile::InteractiveApproximate => Err(
65            "InteractiveApproximate results are forbidden for policy, deontic, or identity decisions (ADR 0003)",
66        ),
67    }
68}
69
70/// Attested run recipe for a converted native weight package.
71#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
72pub struct ExecutionProfile {
73    pub version: u32,
74    /// ISO-ish stamp (unix ms) when this profile was written.
75    pub written_unix_ms: u64,
76    /// Source import path if known (GGUF/Safetensors); empty if measured from P64 only.
77    pub source_import: String,
78    /// Absolute or operator-local path to the winning `.p64`.
79    pub p64_path: String,
80    /// Optional `.q42` model-helper path.
81    #[serde(default)]
82    pub q42_helper_path: String,
83    /// Convert layout: `verbatim` | `f16` | `soa` | …
84    pub layout: String,
85    /// `portable` | `cuda` | `quant-graph` | `fast-verify`
86    pub inference_mode: String,
87    /// wgpu backend hint (`auto` | `vulkan` | `dx12` | …).
88    pub backend: String,
89    /// Runtime toggles applied or recommended for this package.
90    pub toggles: ExecutionToggles,
91    /// Measured evidence (honest; may be partial).
92    pub metrics: ExecutionMetrics,
93    /// Representation levers available or used (not all active at once).
94    pub representation: RepresentationNotes,
95    /// Human/agent notes — failures, next steps, human decisions needed.
96    #[serde(default)]
97    pub notes: Vec<String>,
98    /// Multi-objective scores (optional; fill as gates land).
99    #[serde(default)]
100    pub objectives: ObjectiveScores,
101}
102
103/// Runtime knobs that compose with InferenceMode (env-applied at load).
104#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
105pub struct ExecutionToggles {
106    /// W5a int8 KV cache (native; ~3.8× less KV BW when on).
107    pub kv_int8: bool,
108    /// Resident mega-pass decode when available.
109    pub resident_decode: bool,
110    /// Cooperative GEMV.
111    pub coop_gemv: bool,
112    /// FFN fusion in resident path.
113    pub ffn_fusion: bool,
114    /// Promote FFN weights to f16 in VRAM when measuring.
115    pub ffn_f16: bool,
116    /// Ternary (BitNet-class ~1.58b / ≈1.6 bit/weight) FFN path when container has it.
117    pub ternary_ffn: bool,
118}
119
120/// Measured numbers — never invent.
121#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
122pub struct ExecutionMetrics {
123    /// Decode-proxy tokens/s when measured.
124    pub decode_proxy_tok_s: Option<f64>,
125    /// Token budget used for that measurement.
126    pub decode_proxy_tokens: u32,
127    /// Package size on disk (bytes).
128    pub p64_bytes: u64,
129    /// Optional coherence flag from a later gate (null until implemented).
130    pub coherence_ok: Option<bool>,
131    /// Optional ΔPPL vs reference (null until calibrated).
132    pub delta_ppl: Option<f64>,
133}
134
135/// Documents which representation levers exist in the ecosystem (matrix, not a single format).
136#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
137pub struct RepresentationNotes {
138    /// Weight quant / layout family used for this package.
139    pub weight_path: String,
140    /// KV cache class recommended: `int8` | `f32` | `dict`.
141    pub kv_class: String,
142    /// BitNet ternary ~1.58b (code type 1158); FFN-only when present.
143    pub ternary_158_available: bool,
144    /// f16 expand layout was candidate or winner.
145    pub f16_layout: bool,
146    /// Q4_K SoA layout was candidate or winner.
147    pub soa_layout: bool,
148}
149
150/// Multi-objective matrix (incremental fill). Missing = not yet measured.
151#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
152pub struct ObjectiveScores {
153    /// A — throughput (tok/s class).
154    pub throughput: Option<f64>,
155    /// B — format/layout fitness (operator 0..1 or free note in metrics).
156    pub format_fitness: Option<f64>,
157    /// C — text/coherence / ΔPPL gate.
158    pub correctness: Option<f64>,
159    /// D — grounding / tools / graph (later).
160    pub grounding: Option<f64>,
161    /// E — rights / governance path exercised.
162    pub governance: Option<f64>,
163    /// F — resource (inverse memory pressure; later).
164    pub resource: Option<f64>,
165}
166
167impl ExecutionProfile {
168    /// `ExecutionProfile::path_for_p64`.
169    pub fn path_for_p64(p64_path: &Path) -> PathBuf {
170        let parent = p64_path.parent().unwrap_or_else(|| Path::new("."));
171        let stem = p64_path
172            .file_stem()
173            .and_then(|s| s.to_str())
174            .unwrap_or("model");
175        parent.join(format!("{stem}.{EXECUTION_PROFILE_SUFFIX}"))
176    }
177
178    /// Current time in ms.
179    pub fn now_ms() -> u64 {
180        std::time::SystemTime::now()
181            .duration_since(std::time::UNIX_EPOCH)
182            .map(|d| d.as_millis() as u64)
183            .unwrap_or(0)
184    }
185
186    /// Write JSON beside the P64 (atomic-ish: write temp then rename when possible).
187    pub fn write_beside_p64(&self, p64_path: &Path) -> Result<PathBuf, String> {
188        let path = Self::path_for_p64(p64_path);
189        let json = serde_json::to_string_pretty(self).map_err(|e| format!("serialize: {e}"))?;
190        let tmp = path.with_extension("json.tmp");
191        std::fs::write(&tmp, json.as_bytes())
192            .map_err(|e| format!("write {}: {e}", tmp.display()))?;
193        std::fs::rename(&tmp, &path).or_else(|_| {
194            std::fs::write(&path, json.as_bytes())
195                .map_err(|e| format!("write {}: {e}", path.display()))
196        })?;
197        Ok(path)
198    }
199
200    /// Loads `beside_p64`; error when absent/invalid.
201    pub fn load_beside_p64(p64_path: &Path) -> Result<Option<Self>, String> {
202        let path = Self::path_for_p64(p64_path);
203        if !path.is_file() {
204            return Ok(None);
205        }
206        let bytes = std::fs::read(&path).map_err(|e| format!("read {}: {e}", path.display()))?;
207        let p: Self =
208            serde_json::from_slice(&bytes).map_err(|e| format!("parse {}: {e}", path.display()))?;
209        Ok(Some(p))
210    }
211
212    /// Build a profile from an explore winner (minimal attested fields).
213    pub fn from_explore_winner(
214        source_import: &str,
215        p64_path: &Path,
216        layout: &str,
217        inference_mode: &str,
218        backend: &str,
219        tok_s: f64,
220        tokens: u32,
221        toggle_label: &str,
222    ) -> Self {
223        let p64_bytes = std::fs::metadata(p64_path).map(|m| m.len()).unwrap_or(0);
224        let ffn_f16 = toggle_label.contains("ffn_f16=on");
225        let layout_l = layout.to_ascii_lowercase();
226        let helper = crate::q42::model_helper::helper_path_for_p64(p64_path);
227        let q42_helper_path = if helper.is_file() {
228            helper.display().to_string()
229        } else {
230            String::new()
231        };
232
233        // Snapshot ambient toggles (best-effort; campaign may pin env). `llm_bench` only exists
234        // natively or under `wasm-llm`; the slim wasm profiles record the toggles as OFF.
235        #[cfg(any(not(target_arch = "wasm32"), feature = "wasm-llm"))]
236        let (kv_int8, resident_decode, coop_gemv, ffn_fusion, ternary_ffn) = (
237            crate::llm_bench::kv_int8_enabled(),
238            crate::llm_bench::resident_decode_enabled(),
239            crate::llm_bench::coop_gemv_enabled(),
240            crate::llm_bench::ffn_fusion_in_resident(),
241            crate::llm_bench::ternary_ffn_enabled(),
242        );
243        #[cfg(all(target_arch = "wasm32", not(feature = "wasm-llm")))]
244        let (kv_int8, resident_decode, coop_gemv, ffn_fusion, ternary_ffn) =
245            (false, false, false, false, false);
246
247        Self {
248            version: EXECUTION_PROFILE_VERSION,
249            written_unix_ms: Self::now_ms(),
250            source_import: source_import.to_string(),
251            p64_path: p64_path.display().to_string(),
252            q42_helper_path,
253            layout: layout.to_string(),
254            inference_mode: inference_mode.to_string(),
255            backend: backend.to_string(),
256            toggles: ExecutionToggles {
257                kv_int8,
258                resident_decode,
259                coop_gemv,
260                ffn_fusion,
261                ffn_f16,
262                ternary_ffn,
263            },
264            metrics: ExecutionMetrics {
265                decode_proxy_tok_s: Some(tok_s),
266                decode_proxy_tokens: tokens,
267                p64_bytes,
268                coherence_ok: None,
269                delta_ppl: None,
270            },
271            representation: RepresentationNotes {
272                weight_path: layout.to_string(),
273                kv_class: if kv_int8 { "int8".into() } else { "f32".into() },
274                ternary_158_available: false, // filled true when convert emits ternary FFN
275                f16_layout: layout_l.contains("f16"),
276                soa_layout: layout_l.contains("soa"),
277            },
278            notes: vec![
279                "Target: competitive native package (layout×mode×toggles) with coherent decode."
280                    .into(),
281                "BitNet ternary ~1.58b (≈1.6 bits/weight, type 1158) is an FFN compression lever when present."
282                    .into(),
283                format!("explore toggle label: {toggle_label}"),
284            ],
285            objectives: ObjectiveScores {
286                throughput: Some(tok_s),
287                format_fitness: None,
288                correctness: None,
289                grounding: None,
290                governance: None,
291                resource: None,
292            },
293        }
294    }
295
296    /// Env lines a campaign / operator can apply before load (PowerShell-friendly comments separate).
297    pub fn apply_env_script_ps1(&self) -> String {
298        let mut s = String::new();
299        s.push_str("# Qualia execution profile — apply before llm load / decode-proxy\n");
300        s.push_str(&format!(
301            "$env:QUALIA_INFERENCE_MODE='{}'\n",
302            self.inference_mode
303        ));
304        if self.backend != "auto" && !self.backend.is_empty() {
305            s.push_str(&format!("$env:QUALIA_WGPU_BACKEND='{}'\n", self.backend));
306        }
307        s.push_str(&format!(
308            "$env:QUALIA_LLM_KV_INT8='{}'\n",
309            if self.toggles.kv_int8 { "1" } else { "0" }
310        ));
311        s.push_str(&format!(
312            "$env:QUALIA_LLM_FFN_F16='{}'\n",
313            if self.toggles.ffn_f16 { "1" } else { "0" }
314        ));
315        s.push_str(&format!(
316            "$env:QUALIA_LLM_FFN_FUSION='{}'\n",
317            if self.toggles.ffn_fusion { "1" } else { "0" }
318        ));
319        s
320    }
321}
322
323#[cfg(test)]
324mod tests {
325    use super::*;
326    use std::io::Write;
327
328    #[test]
329    fn round_trip_beside_p64() {
330        let dir = std::env::temp_dir().join(format!("qualia-exec-profile-{}", std::process::id()));
331        let _ = std::fs::create_dir_all(&dir);
332        let p64 = dir.join("toy.p64");
333        {
334            let mut f = std::fs::File::create(&p64).unwrap();
335            f.write_all(b"p64\0toy").unwrap();
336        }
337        let mut prof = ExecutionProfile::from_explore_winner(
338            "toy.gguf", &p64, "f16", "portable", "auto", 12.5, 16, "baseline",
339        );
340        prof.representation.ternary_158_available = true;
341        let written = prof.write_beside_p64(&p64).expect("write");
342        assert!(written.is_file());
343        let loaded = ExecutionProfile::load_beside_p64(&p64)
344            .expect("load")
345            .expect("some");
346        assert_eq!(loaded.layout, "f16");
347        assert_eq!(loaded.metrics.decode_proxy_tok_s, Some(12.5));
348        assert!(loaded.representation.ternary_158_available);
349        let _ = std::fs::remove_dir_all(&dir);
350    }
351
352    #[test]
353    fn exactness_profile_policy_admission_gate() {
354        assert!(admit_for_policy_decision(&ExactnessProfile::Exact).is_ok());
355        assert!(admit_for_policy_decision(&ExactnessProfile::DeterministicApproximate {
356            abs_bound: 0.0,
357            rel_bound: 0.0,
358        })
359        .is_ok());
360        assert!(admit_for_policy_decision(&ExactnessProfile::DeterministicApproximate {
361            abs_bound: 1e-6,
362            rel_bound: 1e-6,
363        })
364        .is_err());
365        assert!(admit_for_policy_decision(&ExactnessProfile::InteractiveApproximate).is_err());
366
367        let outcomes = [
368            SolverVerificationOutcome::WitnessChecked,
369            SolverVerificationOutcome::UnsatisfiableWithinDomain,
370            SolverVerificationOutcome::UnknownWithinBudget,
371            SolverVerificationOutcome::GlobalImpossibilityProved,
372        ];
373        assert_eq!(outcomes.len(), 4);
374    }
375}