1use serde::{Deserialize, Serialize};
11use std::path::{Path, PathBuf};
12
13pub const EXECUTION_PROFILE_VERSION: u32 = 1;
15
16pub const EXECUTION_PROFILE_SUFFIX: &str = "execution-profile.json";
18
19#[repr(C)]
21#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
22pub enum ExactnessProfile {
23 Exact,
25 DeterministicApproximate { abs_bound: f64, rel_bound: f64 },
27 InteractiveApproximate,
29}
30
31#[repr(C)]
34#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
35pub enum SolverVerificationOutcome {
36 WitnessChecked,
38 UnsatisfiableWithinDomain,
40 UnknownWithinBudget,
42 GlobalImpossibilityProved,
44}
45
46pub 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#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
72pub struct ExecutionProfile {
73 pub version: u32,
74 pub written_unix_ms: u64,
76 pub source_import: String,
78 pub p64_path: String,
80 #[serde(default)]
82 pub q42_helper_path: String,
83 pub layout: String,
85 pub inference_mode: String,
87 pub backend: String,
89 pub toggles: ExecutionToggles,
91 pub metrics: ExecutionMetrics,
93 pub representation: RepresentationNotes,
95 #[serde(default)]
97 pub notes: Vec<String>,
98 #[serde(default)]
100 pub objectives: ObjectiveScores,
101}
102
103#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
105pub struct ExecutionToggles {
106 pub kv_int8: bool,
108 pub resident_decode: bool,
110 pub coop_gemv: bool,
112 pub ffn_fusion: bool,
114 pub ffn_f16: bool,
116 pub ternary_ffn: bool,
118}
119
120#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
122pub struct ExecutionMetrics {
123 pub decode_proxy_tok_s: Option<f64>,
125 pub decode_proxy_tokens: u32,
127 pub p64_bytes: u64,
129 pub coherence_ok: Option<bool>,
131 pub delta_ppl: Option<f64>,
133}
134
135#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
137pub struct RepresentationNotes {
138 pub weight_path: String,
140 pub kv_class: String,
142 pub ternary_158_available: bool,
144 pub f16_layout: bool,
146 pub soa_layout: bool,
148}
149
150#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
152pub struct ObjectiveScores {
153 pub throughput: Option<f64>,
155 pub format_fitness: Option<f64>,
157 pub correctness: Option<f64>,
159 pub grounding: Option<f64>,
161 pub governance: Option<f64>,
163 pub resource: Option<f64>,
165}
166
167impl ExecutionProfile {
168 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 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 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 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 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 #[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, 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 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}