Skip to main content

qualia_cli/
llm_testing.rs

1//! LLM Testing Integration for CLI
2//!
3//! Simple LLM model testing functionality for the CLI.
4
5use crate::llm_lifecycle::{default_vault_path, init_log_stream};
6use qualia_client_core::model_lifecycle::{resolve_vault_model, scan_vault_gguf, VaultGgufEntry};
7use std::path::{Path, PathBuf};
8
9/// CLI command to run comprehensive LLM model tests
10pub fn run_test_models(
11    vault_path: Option<PathBuf>,
12    models: Option<Vec<String>>,
13    _quantization: Option<String>,
14    verbose: bool,
15) -> Result<(), String> {
16    let vault_path = vault_path.unwrap_or_else(default_vault_path);
17
18    if verbose {
19        init_log_stream(true);
20    }
21
22    println!("๐Ÿš€ Starting LLM Model Testing CLI");
23    println!("๐Ÿ“ Vault path: {}", vault_path.display());
24
25    // Scan for GGUF models in vault
26    let available_models =
27        scan_vault_gguf(&vault_path).map_err(|e| format!("Failed to scan vault: {}", e))?;
28
29    if available_models.is_empty() {
30        return Err("No GGUF models found in vault".to_string());
31    }
32
33    println!("๐Ÿ“ฆ Found {} model(s):", available_models.len());
34    for model in &available_models {
35        println!("  - {}", model.name);
36    }
37
38    // Filter models if specific ones requested
39    let test_models = if let Some(ref requested) = models {
40        available_models
41            .iter()
42            .filter(|m| requested.contains(&m.name))
43            .cloned()
44            .collect()
45    } else {
46        available_models
47    };
48
49    if test_models.is_empty() {
50        return Err("No matching models found".to_string());
51    }
52
53    println!("\n๐Ÿงช Testing {} model(s)...", test_models.len());
54
55    for model in &test_models {
56        println!("\n๐Ÿ” Testing: {}", model.name);
57        match test_single_model(&vault_path, model, verbose) {
58            Ok(result) => {
59                println!("  โœ… Load time: {}ms", result.load_time_ms);
60                println!("  โœ… Memory: {}MB", result.memory_mb);
61                println!(
62                    "  โœ… Status: {}",
63                    if result.success { "PASS" } else { "FAIL" }
64                );
65            }
66            Err(e) => {
67                println!("  โŒ Error: {}", e);
68            }
69        }
70    }
71
72    println!("\nโœ… Testing complete!");
73    Ok(())
74}
75
76/// Comprehensive LLM capability test (load + inference in one session)
77pub fn run_comprehensive_llm_test(
78    vault_path: Option<PathBuf>,
79    model_name: String,
80    verbose: bool,
81) -> Result<(), String> {
82    let vault_path = vault_path.unwrap_or_else(default_vault_path);
83
84    if verbose {
85        init_log_stream(true);
86    }
87
88    println!("๐Ÿงช Running Comprehensive LLM Test Suite");
89    println!("๐Ÿ“ Vault path: {}", vault_path.display());
90    println!("๐Ÿค– Model: {}", model_name);
91    println!();
92
93    // Step 1: Load the model
94    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
95    println!("STEP 1: Loading Model");
96    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
97
98    let gguf = resolve_vault_model(&vault_path, &model_name)
99        .map_err(|e| format!("Failed to resolve model: {}", e))?;
100
101    println!("Loading {} โ€ฆ", gguf.display());
102    let start = std::time::Instant::now();
103
104    let record = tokio::task::block_in_place(|| {
105        tokio::runtime::Handle::current().block_on(
106            qualia_client_core::model_lifecycle::activate_vault_gguf(&gguf),
107        )
108    })
109    .map_err(|e| format!("Failed to activate model: {}", e))?;
110
111    let load_time = start.elapsed();
112    println!("โœ… Model loaded in {:?}", load_time);
113    println!("  Profile ID: 0x{:016x}", record.profile_id);
114    println!("  Context Window: {}", record.context_window);
115    println!();
116
117    // Step 2: Create agent
118    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
119    println!("STEP 2: Creating Agent");
120    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
121
122    use qualia_core_db::llm_agent::{AgentBackend, LocalLlmAgent};
123
124    let agent = LocalLlmAgent::with_local_backend(
125        format!("did:qualia:cli-test:{}", record.profile_id),
126        AgentBackend::Local {
127            model_path: record.gguf_path.clone(),
128            context_window: record.context_window,
129            quantization: record.quantization.clone(),
130            vision_projector_path: record.mmproj_path.clone(),
131            modality: record.modality.clone(),
132            architecture: record.architecture.clone(),
133        },
134    );
135
136    println!("โœ… Agent created");
137    println!();
138
139    // Step 3: Run inference tests
140    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
141    println!("STEP 3: Inference Tests");
142    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
143
144    // Sample (temperature / top-p / repeat-penalty) rather than greedy argmax, so instruct models
145    // produce varied, on-topic text instead of collapsing into repetition / a fixed attractor.
146    qualia_core_db::llm_bench::set_sampler_config(Some(
147        qualia_core_db::sampler::SamplerConfig::chat_default(),
148    ));
149
150    let test_prompts = vec![
151        ("Basic Knowledge", "What is the capital of France?", 50),
152        (
153            "System Awareness",
154            "What is QualiaDB and what are its main features?",
155            100,
156        ),
157        (
158            "Technical Understanding",
159            "Explain what a NQuin is in simple terms.",
160            80,
161        ),
162        (
163            "Capability Awareness",
164            "What capabilities does the Qualia system have for semantic graph processing?",
165            120,
166        ),
167        (
168            "Instruction Following",
169            "Write a haiku about artificial intelligence.",
170            30,
171        ),
172    ];
173
174    let mut total_tokens = 0;
175    let mut total_time_ms = 0;
176    let mut total_ttft_ms = 0;
177    let mut successful_tests = 0;
178
179    for (test_name, prompt, _max_tokens) in test_prompts.iter() {
180        println!("โ”Œโ”€ Test: {}", test_name);
181        println!("โ”œโ”€ Prompt: {}", prompt);
182
183        let started = std::time::Instant::now();
184
185        // Return layout: (text, provenance_hashes, tokens_generated, semantic_quin).
186        // BUGFIX: the second field is provenance (often len=1), NOT token ids โ€” using
187        // `.len()` reported Tokens:1 and ~100ร— low tok/s. The third field is the count.
188        let (response, _provenance, tokens_generated, _quin) = tokio::task::block_in_place(|| {
189            agent.infer_local_model_with_execution::<fn(String)>(
190                prompt, "graph_context:cli_test",
191                qualia_core_db::llm_agent::native_request::NativeDecodeRequest::Developer,
192                None, None,
193            )
194        });
195
196        let elapsed = started.elapsed();
197        let elapsed_ms = elapsed.as_millis() as u64;
198
199        // Estimate TTFT as ~10% of total time (rough approximation without streaming)
200        let ttft = elapsed_ms / 10;
201
202        let token_count = tokens_generated as u64;
203        // Prefer decoded-token estimate when the engine returns 0 but produced text
204        // (defensive โ€” should not happen on a healthy path).
205        let token_count = if token_count == 0 && !response.is_empty() {
206            // Rough BPE estimate: ~4 chars/token for Latin text.
207            (response.chars().count() as u64 / 4).max(1)
208        } else {
209            token_count
210        };
211        let tps = if elapsed_ms > 0 {
212            (token_count as f64 * 1000.0) / elapsed_ms as f64
213        } else {
214            0.0
215        };
216
217        println!("โ”œโ”€ TTFT: {}ms (estimated)", ttft);
218        println!("โ”œโ”€ Total Time: {}ms", elapsed_ms);
219        println!("โ”œโ”€ Tokens: {} (decode)", token_count);
220        println!("โ”œโ”€ TPS: {:.2} (wall-clock / decode tokens)", tps);
221
222        total_tokens += token_count;
223        total_time_ms += elapsed_ms;
224        total_ttft_ms += ttft;
225        successful_tests += 1;
226
227        print!("โ””โ”€ Response: ");
228        // Show first 200 chars of response
229        let preview: String = response.chars().take(200).collect();
230        println!(
231            "{}{}",
232            preview,
233            if response.len() > 200 { "..." } else { "" }
234        );
235        println!();
236    }
237
238    // Step 4: Summary
239    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
240    println!("TEST SUMMARY");
241    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
242    println!("โœ… Model Loading: PASS ({:?})", load_time);
243    println!("โœ… Agent Creation: PASS");
244    println!(
245        "โœ… Inference: {} / {} tests passed",
246        successful_tests,
247        test_prompts.len()
248    );
249
250    if successful_tests > 0 {
251        let avg_ttft = total_ttft_ms as f64 / successful_tests as f64;
252        let avg_tps = if total_time_ms > 0 {
253            (total_tokens as f64 * 1000.0) / total_time_ms as f64
254        } else {
255            0.0
256        };
257
258        println!();
259        println!("๐Ÿ“Š METRICS:");
260        println!("  โ””โ”€ Total Tokens Generated: {}", total_tokens);
261        println!("  โ””โ”€ Total Generation Time: {}ms", total_time_ms);
262        println!("  โ””โ”€ Average TTFT: {:.2}ms", avg_ttft);
263        println!("  โ””โ”€ Average TPS: {:.2}", avg_tps);
264    }
265
266    println!();
267    println!("Note: Metrics include orchestration overhead (Webizen validation, etc.).");
268    println!("Note: Token counts use engine tokens_generated (not provenance-hash vec length).");
269
270    Ok(())
271}
272
273/// Convert a GGUF import file to native `.p64` + canonical `.q42` model metadata.
274///
275/// Design: GGUF/safetensors are import formats only. Steady-state activation should
276/// prefer the converted container (see `docs/plans/native-inference-p64-pipeline-remediation.md`).
277/// The helper is **CBOR-LD** (self-describe CBOR), never JSON.
278pub fn run_convert_gguf_to_p64(
279    input: &Path,
280    out_dir: &Path,
281    page_log2: u16,
282    layout: &str,
283) -> Result<(), String> {
284    if !input.is_file() {
285        return Err(format!("input not found: {}", input.display()));
286    }
287    let ext = input
288        .extension()
289        .and_then(|e| e.to_str())
290        .unwrap_or("")
291        .to_ascii_lowercase();
292    if ext != "gguf" && ext != "safetensors" {
293        return Err(format!(
294            "only .gguf or .safetensors import is supported in this command (got .{ext})"
295        ));
296    }
297    let src_len = std::fs::metadata(input).map(|m| m.len()).unwrap_or(0);
298    if src_len > u32::MAX as u64 {
299        return Err(format!(
300            "{} is {} bytes, but P64 v4 has 32-bit blob offsets and cannot represent a single payload above 4 GiB. Do not create a monolithic P64. For Qwen3.8 Flash Next, place the GGUF on C: and run `qualia-cli llm prepare-qwen4exp \"{}\" --out <new>.hmc`; it preserves the PLE table as a verified NVMe range source.",
301            input.display(),
302            src_len,
303            input.display(),
304        ));
305    }
306    // 12 GB class card default budget when auto-selecting f16 expand.
307    const DEFAULT_VRAM_BUDGET: u64 = 12u64 * 1024 * 1024 * 1024;
308    let layout = match layout.trim().to_ascii_lowercase().as_str() {
309        "verbatim" | "raw" | "copy" => qualia_core_db::p64_weight::P64ConvertLayout::Verbatim,
310        "f16" | "fp16" | "half" => qualia_core_db::p64_weight::P64ConvertLayout::F16Expand,
311        "soa" | "q4k-soa" | "q4k_soa" | "soa-q4k" => {
312            qualia_core_db::p64_weight::P64ConvertLayout::Q4kSoa
313        }
314        "auto" | "best" | "remarkable" => {
315            let rec =
316                qualia_core_db::p64_weight::recommend_convert_layout(src_len, DEFAULT_VRAM_BUDGET);
317            println!("โ”œโ”€ auto layout โ†’ {rec:?} (source {src_len} B, 12 GiB VRAM budget)");
318            rec
319        }
320        other => {
321            return Err(format!(
322                "unknown --layout '{other}' (expected verbatim|f16|soa|auto)"
323            ))
324        }
325    };
326
327    std::fs::create_dir_all(out_dir)
328        .map_err(|e| format!("create out dir {}: {e}", out_dir.display()))?;
329
330    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
331    println!("Model ({ext}) โ†’ p64 + q42 convert");
332    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
333    println!("โ”œโ”€ Input:  {}", input.display());
334    println!("โ”œโ”€ Out:    {}", out_dir.display());
335    println!("โ”œโ”€ page_log2: {page_log2}");
336    println!("โ””โ”€ layout: {layout:?}");
337
338    let t0 = std::time::Instant::now();
339    let mmap = {
340        let f = std::fs::File::open(input).map_err(|e| format!("open: {e}"))?;
341        // SAFETY: file is read-only; we do not write through the mapping.
342        unsafe { memmap2::Mmap::map(&f).map_err(|e| format!("mmap: {e}"))? }
343    };
344    let src_bytes = mmap.len();
345    println!(
346        "โ”œโ”€ Source size: {:.1} MiB",
347        src_bytes as f64 / (1024.0 * 1024.0)
348    );
349
350    let p64 = if ext == "safetensors" {
351        let mut buf = Vec::new();
352        qualia_core_db::p64_weight::transcode_safetensor_to_p64(&mmap, page_log2, &mut buf)
353            .map_err(|e| format!("transcode_safetensor_to_p64: {e}"))?;
354        buf
355    } else {
356        qualia_core_db::p64_weight::compile_gguf_to_p64_with_layout(&mmap, page_log2, layout)
357            .map_err(|e| format!("compile_gguf_to_p64: {e}"))?
358    };
359    let stem = input
360        .file_stem()
361        .and_then(|s| s.to_str())
362        .unwrap_or("model");
363    let suffix = match layout {
364        qualia_core_db::p64_weight::P64ConvertLayout::Verbatim => "",
365        qualia_core_db::p64_weight::P64ConvertLayout::F16Expand => ".f16",
366        qualia_core_db::p64_weight::P64ConvertLayout::Q4kSoa => ".soa",
367    };
368    let p64_path = out_dir.join(format!("{stem}{suffix}.p64"));
369    std::fs::write(&p64_path, &p64).map_err(|e| format!("write p64: {e}"))?;
370
371    // Canonical Q42 v3 metadata: behaviour the engine should not re-guess from GGUF.
372    let tok = qualia_core_db::gguf_sharder::GgufTokenizer::from_gguf(&mmap);
373    let stop_ids: Vec<u32> = tok.stop_tokens().to_vec();
374    let stop_names: Vec<String> = stop_ids
375        .iter()
376        .filter_map(|&id| tok.vocab.get(id as usize).cloned())
377        .collect();
378    let helper = qualia_core_db::model_helper::ModelHelper::new(
379        input
380            .file_name()
381            .and_then(|s| s.to_str())
382            .unwrap_or("model.gguf"),
383        p64_path
384            .file_name()
385            .and_then(|s| s.to_str())
386            .unwrap_or("model.p64"),
387        page_log2,
388        format!("{layout:?}"),
389        qualia_core_db::model_helper::ModelHelperTokenizer {
390            bos_token_id: tok.bos_token_id,
391            eos_token_id: tok.eos_token_id,
392            add_bos_token: tok.add_bos_token,
393            chat_family: format!("{:?}", tok.chat_family()),
394            stop_token_ids: stop_ids,
395            stop_token_strings: stop_names,
396            vocab_len: tok.vocab_len(),
397        },
398    );
399    let q42_path = helper
400        .write_beside_p64(&p64_path)
401        .map_err(|e| format!("write canonical q42 helper: {e}"))?;
402
403    // Validate the container can be indexed (fail closed if we wrote garbage).
404    let index = qualia_core_db::p64_weight::P64TensorIndex::from_p64(&p64)
405        .map_err(|e| format!("p64 self-check failed: {e}"))?;
406    let n_tensors = index.entries.len();
407    // Round-trip through the real Q42 volume reader so a malformed helper fails closed.
408    let _ = qualia_core_db::model_helper::ModelHelper::load_beside_p64(&p64_path)
409        .map_err(|e| format!("helper self-check failed: {e}"))?
410        .ok_or_else(|| "helper self-check failed: canonical .q42 was not found".to_string())?;
411
412    let elapsed = t0.elapsed();
413    println!();
414    println!("โœ… Convert complete in {:.1}s", elapsed.as_secs_f64());
415    println!("  โ””โ”€ {}", p64_path.display());
416    println!(
417        "     size {:.1} MiB, tensors {}",
418        p64.len() as f64 / (1024.0 * 1024.0),
419        n_tensors
420    );
421    println!("  โ””โ”€ {} (Q42 v3)", q42_path.display());
422    println!(
423        "     chat_family={:?} stop_ids={:?}",
424        tok.chat_family(),
425        tok.stop_tokens()
426    );
427    println!();
428    println!("Activate with a Local backend path pointing at the .p64 file.");
429    Ok(())
430}
431
432/// Extract the Qwen4Exp PLE table to NVMe and create its compact HMC contract.
433/// The source GGUF stays in place; only its row-addressable PLE span is copied.
434pub fn run_prepare_qwen4exp_native(
435    input: &Path,
436    output: &Path,
437    ple_output: &Path,
438) -> Result<(), String> {
439    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
440    println!("Qwen4Exp native HMC preparation");
441    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
442    println!("โ”œโ”€ Source trunk: {}", input.display());
443    println!("โ”œโ”€ PLE NVMe:     {}", ple_output.display());
444    println!("โ””โ”€ HMC:          {}", output.display());
445    let prepared =
446        qualia_core_db::inference::qwen::prepare_qwen4exp_native_hmc(input, output, ple_output)
447            .map_err(|error| error.to_string())?;
448    println!("โœ… HMC contract created");
449    println!("  โ””โ”€ source bytes: {}", prepared.source.byte_len);
450    println!(
451        "  โ””โ”€ PLE NVMe: {} bytes / {} rows ร— {}",
452        prepared.ple.storage_bytes, prepared.ple.rows, prepared.ple.row_width
453    );
454    println!(
455        "  โ””โ”€ trunk GGUF bytes: {} (not monolithic P64)",
456        prepared.trunk_gguf_bytes
457    );
458    println!(
459        "  โ””โ”€ graph: {} GatedDeltaNet layers, {} QSA layers, {} PLE layers",
460        prepared.gated_deltanet_layers, prepared.qsa_layers, prepared.ple_layers
461    );
462    println!("  โ””โ”€ source SHA-256: pending explicit verify-qwen4exp audit");
463    Ok(())
464}
465
466/// Audit an existing Qwen4Exp HMC's external source before activation.
467pub fn run_verify_qwen4exp_native(package: &Path) -> Result<(), String> {
468    let descriptor = qualia_core_db::inference::qwen::load_qwen4exp_native_hmc(package)
469        .map_err(|error| error.to_string())?;
470    let source = descriptor
471        .source_beside(package)
472        .map_err(|error| error.to_string())?;
473    println!("Auditing {}", package.display());
474    println!("โ”œโ”€ External GGUF: {}", source.display());
475    descriptor
476        .verify_source_sha256(&source)
477        .map_err(|error| error.to_string())?;
478    println!("โœ… HMC descriptor and external GGUF SHA-256 match");
479    println!(
480        "  โ””โ”€ PLE: {} rows ร— {} values ({} storage bytes at file offset {})",
481        descriptor.ple.rows,
482        descriptor.ple.row_width,
483        descriptor.ple.storage_bytes,
484        descriptor.ple.absolute_offset
485    );
486    Ok(())
487}
488
489/// Exercise the actual C:-resident PLE reader without mapping the PLE table,
490/// opening the source GGUF, or allocating a row dynamically.
491pub fn run_probe_qwen4exp_ple(package: &Path) -> Result<(), String> {
492    const MAX_PLE_ROW_BYTES: usize = 65_536;
493    const MAX_PLE_ROW_WIDTH: usize = 4_096;
494
495    let descriptor = qualia_core_db::inference::qwen::load_qwen4exp_native_hmc(package)
496        .map_err(|error| error.to_string())?;
497    let mut reader =
498        qualia_core_db::inference::qwen::PleNvmeReader::open_from_native_descriptor(&descriptor)
499            .map_err(|error| format!("open NVMe PLE: {error:?}"))?;
500    if reader.raw_row_bytes() > MAX_PLE_ROW_BYTES || reader.row_width() > MAX_PLE_ROW_WIDTH {
501        return Err("PLE row exceeds fixed probe buffer contract".to_string());
502    }
503
504    let last = reader
505        .row_count()
506        .checked_sub(1)
507        .ok_or_else(|| "PLE has no rows".to_string())?;
508    let candidates = [0u64, reader.row_count() / 2, last];
509    let mut raw = [0u8; MAX_PLE_ROW_BYTES];
510    let mut values = [0.0f32; MAX_PLE_ROW_WIDTH];
511    let mut rows = 0u32;
512    let mut fingerprint = 0xcbf2_9ce4_8422_2325u64;
513
514    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
515    println!("Qwen4Exp NVMe PLE probe");
516    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
517    println!("โ”œโ”€ HMC: {}", package.display());
518    println!("โ”œโ”€ PLE: {}", descriptor.ple_storage.file_path);
519    println!(
520        "โ”œโ”€ table: {} rows ร— {} values; {} bytes/row",
521        reader.row_count(),
522        reader.row_width(),
523        reader.raw_row_bytes()
524    );
525    for row in candidates {
526        if rows != 0 && row == candidates[(rows - 1) as usize] {
527            continue;
528        }
529        let n = reader
530            .read_row_into(row, &mut raw, &mut values)
531            .map_err(|error| format!("read PLE row {row}: {error:?}"))?;
532        if n != reader.row_width() || values[..n].iter().any(|value| !value.is_finite()) {
533            return Err(format!("invalid decoded PLE row {row}"));
534        }
535        for value in &values[..n] {
536            fingerprint ^= value.to_bits() as u64;
537            fingerprint = fingerprint.wrapping_mul(0x1000_0000_01b3);
538        }
539        println!(
540            "โ”œโ”€ row {row}: {n} values decoded from {} bytes",
541            reader.raw_row_bytes()
542        );
543        rows += 1;
544    }
545    println!("โ””โ”€ direct-NVMe probe passed; sampled_row_fingerprint={fingerprint:016x}");
546    Ok(())
547}
548
549/// Compute the checkpoint's PLE n-gram row IDs from decode-order token IDs,
550/// then gather exactly those rows from the C:-resident table.  This is an
551/// execution seam, not a text-generation benchmark: it proves that runtime
552/// token history selects and consumes trained PLE rows without mapping the
553/// table or using a synthetic hash.
554pub fn run_gather_qwen4exp_ple(package: &Path, token_ids: &[u32]) -> Result<(), String> {
555    const MAX_PLE_ROWS: usize = 64;
556    const MAX_PLE_ROW_BYTES: usize = 65_536;
557    const MAX_PLE_VALUES: usize = 16_384;
558
559    if token_ids.is_empty() {
560        return Err("at least one token ID is required".to_string());
561    }
562    let descriptor = qualia_core_db::inference::qwen::load_qwen4exp_native_hmc(package)
563        .map_err(|error| error.to_string())?;
564    let mut reader =
565        qualia_core_db::inference::qwen::PleNvmeReader::open_from_native_descriptor(&descriptor)
566            .map_err(|error| format!("open NVMe PLE: {error:?}"))?;
567    let heads = descriptor
568        .ple_config
569        .ngram_size
570        .saturating_sub(1)
571        .saturating_mul(descriptor.ple_config.heads_per_ngram) as usize;
572    let needed = heads
573        .checked_mul(reader.row_width())
574        .ok_or_else(|| "PLE gather size overflow".to_string())?;
575    if heads == 0
576        || heads > MAX_PLE_ROWS
577        || reader.raw_row_bytes() > MAX_PLE_ROW_BYTES
578        || needed > MAX_PLE_VALUES
579    {
580        return Err("PLE gather exceeds this command's fixed buffer contract".to_string());
581    }
582
583    let mut history = qualia_core_db::inference::qwen::PleTokenHistory::default();
584    let mut rows = [0u64; MAX_PLE_ROWS];
585    let mut raw = [0u8; MAX_PLE_ROW_BYTES];
586    let mut values = [0.0f32; MAX_PLE_VALUES];
587    let mut fingerprint = 0xcbf2_9ce4_8422_2325u64;
588
589    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
590    println!("Qwen4Exp exact PLE n-gram gather");
591    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
592    println!("โ”œโ”€ PLE: {}", descriptor.ple_storage.file_path);
593    println!(
594        "โ”œโ”€ contract: {}-gram ร— {} heads = {} rows/token",
595        descriptor.ple_config.ngram_size, descriptor.ple_config.heads_per_ngram, heads
596    );
597    for &token in token_ids {
598        let selected = history
599            .select_and_push(
600                &descriptor.ple_config,
601                token,
602                reader.row_count(),
603                &mut rows[..heads],
604            )
605            .map_err(|error| format!("select PLE rows for token {token}: {error}"))?;
606        let receipt = reader
607            .gather_rows_into(&rows[..selected], &mut raw, &mut values[..needed])
608            .map_err(|error| format!("gather PLE rows for token {token}: {error:?}"))?;
609        if values[..needed].iter().any(|value| !value.is_finite()) {
610            return Err(format!("non-finite PLE value for token {token}"));
611        }
612        for value in &values[..needed] {
613            fingerprint ^= value.to_bits() as u64;
614            fingerprint = fingerprint.wrapping_mul(0x1000_0000_01b3);
615        }
616        println!(
617            "โ”œโ”€ token {token}: {selected} trained rows, {} NVMe bytes",
618            receipt.storage_bytes
619        );
620    }
621    println!("โ””โ”€ exact PLE history/gather passed; fingerprint={fingerprint:016x}");
622    Ok(())
623}
624
625/// Execute the complete trained PLE residual insertion for one token.  This
626/// is a physical C:/E: forward component check, not token generation: all
627/// later GDN/QSA, four-stream and MoE layers remain to be executed.
628pub fn run_probe_qwen4exp_ple_block(package: &Path, token_id: u32) -> Result<(), String> {
629    const HIDDEN: usize = 2_560;
630    const STREAMS: usize = 4;
631    const WIDE: usize = HIDDEN * STREAMS;
632    const HISTORY: usize = 9 * WIDE;
633    const RAW_PLE: usize = 1_024;
634    const RAW_TRUNK: usize = 65_536;
635
636    let mut runtime = qualia_core_db::inference::qwen::Qwen4ExpNativeRuntime::activate(package)
637        .map_err(|error| error.to_string())?;
638    let embedding = *runtime
639        .index
640        .token_embd_info()
641        .ok_or_else(|| "Qwen4Exp source has no token embedding tensor".to_string())?;
642    if embedding.dims[0] as usize != HIDDEN || token_id as u64 >= embedding.dims[1] {
643        return Err(
644            "Qwen4Exp token embedding does not match the fixed PLE block contract".to_string(),
645        );
646    }
647    let layer_id = runtime.descriptor.ple_config.layers[0];
648    let layer = runtime.index.get_layer_tensors(layer_id);
649    let mut raw_ple = [0u8; RAW_PLE];
650    let mut raw_trunk = [0u8; RAW_TRUNK];
651    let mut embedding_values = [0.0f32; HIDDEN];
652    runtime
653        .trunk
654        .read_row_into(
655            &embedding,
656            token_id as usize,
657            &mut raw_trunk,
658            &mut embedding_values,
659        )
660        .map_err(|error| format!("read token embedding: {error}"))?;
661    let mut residual = [0.0f32; WIDE];
662    for stream in 0..STREAMS {
663        residual[stream * HIDDEN..(stream + 1) * HIDDEN].copy_from_slice(&embedding_values);
664    }
665    let mut history = [0.0f32; HISTORY];
666    let mut projection_row = [0.0f32; HIDDEN];
667    let mut ple_embedding = [0.0f32; HIDDEN];
668    let mut key = [0.0f32; WIDE];
669    let mut value = [0.0f32; HIDDEN];
670    let mut query_norm = [0.0f32; WIDE];
671    let mut gated = [0.0f32; WIDE];
672    let mut conv_norm = [0.0f32; WIDE];
673    let mut conv_weights = [0.0f32; WIDE * 4];
674    let mut norm_key = [0.0f32; WIDE];
675    let mut norm_query = [0.0f32; WIDE];
676    let mut norm_conv = [0.0f32; WIDE];
677    let mut buffers = qualia_core_db::inference::qwen::PleBlockBuffers {
678        raw_ple_row: &mut raw_ple,
679        raw_trunk_row: &mut raw_trunk,
680        projection_row: &mut projection_row,
681        embedding: &mut ple_embedding,
682        key: &mut key,
683        value: &mut value,
684        query_norm: &mut query_norm,
685        gated: &mut gated,
686        conv_norm: &mut conv_norm,
687        conv_weights: &mut conv_weights,
688        norm_key: &mut norm_key,
689        norm_query: &mut norm_query,
690        norm_conv: &mut norm_conv,
691    };
692    let mut token_history = qualia_core_db::inference::qwen::PleTokenHistory::default();
693    let start = std::time::Instant::now();
694    qualia_core_db::inference::qwen::execute_ple_block(
695        &runtime.descriptor.ple_config,
696        &layer,
697        token_id,
698        &mut token_history,
699        &mut runtime.ple,
700        &mut runtime.trunk,
701        &mut residual,
702        &mut history,
703        &mut buffers,
704    )
705    .map_err(|error| format!("execute trained PLE block: {error}"))?;
706    let elapsed = start.elapsed();
707    let mut fingerprint = 0xcbf2_9ce4_8422_2325u64;
708    for value in residual {
709        fingerprint ^= value.to_bits() as u64;
710        fingerprint = fingerprint.wrapping_mul(0x1000_0000_01b3);
711    }
712    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
713    println!("Qwen4Exp trained PLE residual block");
714    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
715    println!("โ”œโ”€ layer {layer_id}, token {token_id}: 16 C: n-gram rows โ†’ 4 ร— {HIDDEN} residual");
716    println!("โ”œโ”€ PLE block time: {:.3}s", elapsed.as_secs_f64());
717    println!("โ””โ”€ residual fingerprint={fingerprint:016x}");
718    Ok(())
719}
720
721/// Execute one trained attention- or FFN-side Hyper-Connection mix using the
722/// source checkpoint's own weight rows. This is a forward component probe;
723/// it deliberately does not substitute an attention/GDN or MoE result.
724pub fn run_probe_qwen4exp_hyper(
725    package: &Path,
726    layer_id: u32,
727    ffn: bool,
728    token_id: u32,
729) -> Result<(), String> {
730    const HIDDEN: usize = 2_560;
731    const STREAMS: usize = 4;
732    const WIDE: usize = HIDDEN * STREAMS;
733    const MAX_RANK: usize = 1_024;
734    const RAW: usize = 65_536;
735    let mut runtime = qualia_core_db::inference::qwen::Qwen4ExpNativeRuntime::activate(package)
736        .map_err(|error| error.to_string())?;
737    let embedding = *runtime
738        .index
739        .token_embd_info()
740        .ok_or_else(|| "Qwen4Exp source has no token embedding tensor".to_string())?;
741    if embedding.dims[0] as usize != HIDDEN || token_id as u64 >= embedding.dims[1] {
742        return Err(
743            "Qwen4Exp token embedding does not match the fixed Hyper-Connection contract"
744                .to_string(),
745        );
746    }
747    let layer = runtime.index.get_layer_tensors(layer_id);
748    let rank = if ffn {
749        layer.hc_ffn_down.as_ref()
750    } else {
751        layer.hc_attn_down.as_ref()
752    }
753    .map(|info| info.dims[1] as usize)
754    .ok_or_else(|| format!("layer {layer_id} has no requested Hyper-Connection down projection"))?;
755    if rank > MAX_RANK {
756        return Err("Hyper-Connection rank exceeds the fixed probe buffer".to_string());
757    }
758    let mut raw = [0u8; RAW];
759    let mut embedding_values = [0.0f32; HIDDEN];
760    runtime
761        .trunk
762        .read_row_into(
763            &embedding,
764            token_id as usize,
765            &mut raw,
766            &mut embedding_values,
767        )
768        .map_err(|error| format!("read token embedding: {error}"))?;
769    let mut residual = [0.0f32; WIDE];
770    for stream in 0..STREAMS {
771        residual[stream * HIDDEN..(stream + 1) * HIDDEN].copy_from_slice(&embedding_values);
772    }
773    let mut mixed = [0.0f32; HIDDEN];
774    let mut inject = [0.0f32; STREAMS];
775    let mut projection_row = [0.0f32; WIDE];
776    let mut norm_weight = [0.0f32; WIDE];
777    let mut normalized = [0.0f32; WIDE];
778    let mut low_rank = [0.0f32; MAX_RANK];
779    let mut gates = [0.0f32; WIDE];
780    let mut buffers = qualia_core_db::inference::qwen::StreamedHyperBuffers {
781        raw_row: &mut raw,
782        projection_row: &mut projection_row,
783        norm_weight: &mut norm_weight,
784        normalized: &mut normalized,
785        low_rank: &mut low_rank,
786        gates: &mut gates,
787    };
788    let start = std::time::Instant::now();
789    qualia_core_db::inference::qwen::execute_streamed_hyper_connection(
790        &mut runtime.trunk,
791        &layer,
792        ffn,
793        &residual,
794        &mut mixed,
795        Some(&mut inject),
796        &mut buffers,
797    )
798    .map_err(|error| format!("execute trained Hyper-Connection: {error}"))?;
799    let elapsed = start.elapsed();
800    let mut fingerprint = 0xcbf2_9ce4_8422_2325u64;
801    for value in mixed.into_iter().chain(inject) {
802        fingerprint ^= value.to_bits() as u64;
803        fingerprint = fingerprint.wrapping_mul(0x1000_0000_01b3);
804    }
805    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
806    println!("Qwen4Exp trained Hyper-Connection block");
807    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
808    println!(
809        "โ”œโ”€ layer {layer_id} {} path, rank {rank}",
810        if ffn { "FFN" } else { "token-mixer" }
811    );
812    println!("โ”œโ”€ Hyper block time: {:.3}s", elapsed.as_secs_f64());
813    println!("โ””โ”€ mix/inject fingerprint={fingerprint:016x}");
814    Ok(())
815}
816
817/// Execute the trained recurrent token mixer with its real learned state.
818/// The two state vectors are explicitly bounded and live only for this CLI
819/// invocation; no model payload is copied from E: or C: into them.
820pub fn run_probe_qwen4exp_gdn(package: &Path, layer_id: u32, token_id: u32) -> Result<(), String> {
821    const HIDDEN: usize = 2_560;
822    const HEADS: usize = 48;
823    const HEAD_DIM: usize = 128;
824    const INNER: usize = HEADS * HEAD_DIM;
825    const QKV: usize = 10_240;
826    const RAW: usize = 65_536;
827    let mut runtime = qualia_core_db::inference::qwen::Qwen4ExpNativeRuntime::activate(package)
828        .map_err(|error| error.to_string())?;
829    let embedding = *runtime
830        .index
831        .token_embd_info()
832        .ok_or_else(|| "Qwen4Exp source has no token embedding tensor".to_string())?;
833    if embedding.dims[0] as usize != HIDDEN || token_id as u64 >= embedding.dims[1] {
834        return Err(
835            "Qwen4Exp token embedding does not match the GatedDeltaNet contract".to_string(),
836        );
837    }
838    let layer = runtime.index.get_layer_tensors(layer_id);
839    if !layer.is_hybrid_ssm_layer() {
840        return Err(format!(
841            "layer {layer_id} is not a complete Qwen4Exp GatedDeltaNet layer"
842        ));
843    }
844    let mut raw = [0u8; RAW];
845    let mut input = [0.0f32; HIDDEN];
846    runtime
847        .trunk
848        .read_row_into(&embedding, token_id as usize, &mut raw, &mut input)
849        .map_err(|error| format!("read token embedding: {error}"))?;
850    // Runtime-owned recurrence state: 10,240 ร— 3 convolution values and
851    // 48 ร— 128 ร— 128 delta values = 3,176,448 f32 (about 12.1 MiB).
852    let mut convolution = vec![0.0f32; QKV * 3];
853    let mut delta = vec![0.0f32; HEADS * HEAD_DIM * HEAD_DIM];
854    let mut out = [0.0f32; HIDDEN];
855    let mut projection_row = vec![0.0f32; INNER];
856    let mut qkv = vec![0.0f32; QKV];
857    let mut gate = vec![0.0f32; INNER];
858    let mut alpha = [0.0f32; HEADS];
859    let mut beta = [0.0f32; HEADS];
860    let mut convolved = vec![0.0f32; QKV];
861    let mut head_norm = [0.0f32; HEAD_DIM];
862    let mut head_vector = [0.0f32; HEAD_DIM];
863    let mut output_inner = vec![0.0f32; INNER];
864    let mut head_a = [0.0f32; HEADS];
865    let mut dt_bias = [0.0f32; HEADS];
866    let mut state = qualia_core_db::inference::qwen::GatedDeltaState {
867        convolution: &mut convolution,
868        delta: &mut delta,
869    };
870    let mut buffers = qualia_core_db::inference::qwen::GatedDeltaBuffers {
871        raw_row: &mut raw,
872        projection_row: &mut projection_row,
873        qkv: &mut qkv,
874        gate: &mut gate,
875        alpha: &mut alpha,
876        beta: &mut beta,
877        convolved: &mut convolved,
878        head_norm: &mut head_norm,
879        head_vector: &mut head_vector,
880        output_inner: &mut output_inner,
881        head_a: &mut head_a,
882        dt_bias: &mut dt_bias,
883    };
884    let start = std::time::Instant::now();
885    qualia_core_db::inference::qwen::execute_streamed_gated_delta(
886        &mut runtime.trunk,
887        &layer,
888        &input,
889        &mut state,
890        &mut out,
891        &mut buffers,
892    )
893    .map_err(|error| format!("execute trained GatedDeltaNet: {error}"))?;
894    let elapsed = start.elapsed();
895    let mut fingerprint = 0xcbf2_9ce4_8422_2325u64;
896    for value in out.into_iter().chain(delta.iter().copied().step_by(257)) {
897        fingerprint ^= value.to_bits() as u64;
898        fingerprint = fingerprint.wrapping_mul(0x1000_0000_01b3);
899    }
900    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
901    println!("Qwen4Exp trained GatedDeltaNet token mixer");
902    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
903    println!("โ”œโ”€ layer {layer_id}, token {token_id}: 48 ร— 128 ร— 128 recurrent state");
904    println!("โ”œโ”€ GatedDeltaNet time: {:.3}s", elapsed.as_secs_f64());
905    println!("โ””โ”€ branch/state fingerprint={fingerprint:016x}");
906    Ok(())
907}
908
909/// Verify the external trunk reader against the exact source identified by an
910/// HMC. Only the bounded GGUF metadata prefix is read; the embedding row is
911/// consumed through `TrunkNvmeReader` from E:.
912pub fn run_probe_qwen4exp_trunk(package: &Path, token_id: u32) -> Result<(), String> {
913    const MAX_ROW_BYTES: usize = 65_536;
914    const MAX_ROW_WIDTH: usize = 4_096;
915
916    let descriptor = qualia_core_db::inference::qwen::load_qwen4exp_native_hmc(package)
917        .map_err(|error| error.to_string())?;
918    let source = descriptor
919        .source_beside(package)
920        .map_err(|error| error.to_string())?;
921    descriptor
922        .verify_source_metadata(&source)
923        .map_err(|error| error.to_string())?;
924    let index =
925        qualia_core_db::inference::gguf_sharder::GgufTensorIndex::from_gguf_header_file(&source)
926            .map_err(|error| format!("read bounded trunk header: {error}"))?;
927    let embedding = *index
928        .token_embd_info()
929        .ok_or_else(|| "Qwen4Exp source has no token embedding tensor".to_string())?;
930    if token_id as u64 >= embedding.dims[1] {
931        return Err(format!("token ID {token_id} exceeds vocabulary"));
932    }
933    let mut reader =
934        qualia_core_db::inference::qwen::TrunkNvmeReader::open(&source, index.tensor_data_start)
935            .map_err(|error| format!("open trunk row reader: {error}"))?;
936    let row_bytes = qualia_core_db::inference::ggml_quants::ggml_row_bytes(
937        embedding.ggml_type,
938        embedding.dims[0] as usize,
939    )
940    .ok_or_else(|| "unsupported token embedding quantization".to_string())?;
941    if row_bytes > MAX_ROW_BYTES || embedding.dims[0] as usize > MAX_ROW_WIDTH {
942        return Err("token embedding exceeds fixed trunk probe buffers".to_string());
943    }
944    let mut raw = [0u8; MAX_ROW_BYTES];
945    let mut values = [0f32; MAX_ROW_WIDTH];
946    let written = reader
947        .read_row_into(&embedding, token_id as usize, &mut raw, &mut values)
948        .map_err(|error| format!("read trunk embedding: {error}"))?;
949    if values[..written].iter().any(|value| !value.is_finite()) {
950        return Err("trunk embedding contains non-finite decoded values".to_string());
951    }
952    let mut fingerprint = 0xcbf2_9ce4_8422_2325u64;
953    for value in &values[..written] {
954        fingerprint ^= value.to_bits() as u64;
955        fingerprint = fingerprint.wrapping_mul(0x1000_0000_01b3);
956    }
957    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
958    println!("Qwen4Exp bounded trunk-row probe");
959    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
960    println!("โ”œโ”€ source: {}", source.display());
961    println!("โ”œโ”€ token {token_id}: {written} values decoded from {row_bytes} bytes");
962    println!("โ””โ”€ direct trunk row passed; fingerprint={fingerprint:016x}");
963    Ok(())
964}
965
966/// Cold-activate the native C:/E: package layout.  This is deliberately
967/// separate from generation: it proves the model can be opened with a
968/// bounded metadata read before a decode runner is allowed to touch weights.
969pub fn run_activate_qwen4exp_native(package: &Path) -> Result<(), String> {
970    let runtime = qualia_core_db::inference::qwen::Qwen4ExpNativeRuntime::activate(package)
971        .map_err(|error| error.to_string())?;
972    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
973    println!("Qwen4Exp native bounded activation");
974    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
975    println!("โ”œโ”€ PLE NVMe: {}", runtime.descriptor.ple_storage.file_path);
976    println!(
977        "โ”œโ”€ PLE rows: {} ร— {}",
978        runtime.ple.row_count(),
979        runtime.ple.row_width()
980    );
981    println!(
982        "โ”œโ”€ trunk metadata: {} bytes before tensor payload",
983        runtime.index.tensor_data_start
984    );
985    println!("โ”œโ”€ trunk: {}", runtime.descriptor.source.source_path);
986    println!("โ””โ”€ active: no source GGUF mmap or full-model copy");
987    Ok(())
988}
989
990/// Execute one true Qwen4Exp routed-MoE operator.  This is an operator
991/// validation seam, not text generation: it uses a token embedding directly
992/// instead of a fully evolved preceding token-mixer state.
993pub fn run_probe_qwen4exp_moe(
994    package: &Path,
995    layer: u32,
996    token_id: u32,
997    tile: Option<&Path>,
998) -> Result<(), String> {
999    const MAX_HIDDEN: usize = 4_096;
1000    const MAX_INTERMEDIATE: usize = 4_096;
1001    const MAX_ROUTER: usize = 1_024;
1002    const MAX_RAW_ROW: usize = 65_536;
1003
1004    let mut runtime = qualia_core_db::inference::qwen::Qwen4ExpNativeRuntime::activate(package)
1005        .map_err(|error| error.to_string())?;
1006    let embedding = *runtime
1007        .index
1008        .token_embd_info()
1009        .ok_or_else(|| "Qwen4Exp source has no token embedding tensor".to_string())?;
1010    if token_id as u64 >= embedding.dims[1] || embedding.dims[0] as usize > MAX_HIDDEN {
1011        return Err("token embedding exceeds fixed MoE probe buffers".to_string());
1012    }
1013    let tensors = runtime.index.get_layer_tensors(layer);
1014    let intermediate = tensors
1015        .moe_gate_exps
1016        .as_ref()
1017        .map(|info| info.dims[1] as usize)
1018        .ok_or_else(|| format!("layer {layer} has no routed MoE gate tensor"))?;
1019    if intermediate > MAX_INTERMEDIATE {
1020        return Err("MoE intermediate width exceeds fixed probe buffers".to_string());
1021    }
1022
1023    let describe =
1024        |label: &str, tensor: Option<&qualia_core_db::inference::gguf_sharder::GgufTensorInfo>| {
1025            tensor
1026                .map(|info| {
1027                    format!(
1028                        "{label}={:?}/{}D/type{}",
1029                        info.dims, info.n_dims, info.ggml_type
1030                    )
1031                })
1032                .unwrap_or_else(|| format!("{label}=missing"))
1033        };
1034    println!(
1035        "MoE tensor layout: {}, {}, {}, {}",
1036        describe("router", tensors.moe_router.as_ref()),
1037        describe("gate", tensors.moe_gate_exps.as_ref()),
1038        describe("up", tensors.moe_up_exps.as_ref()),
1039        describe("down", tensors.moe_down_exps.as_ref()),
1040    );
1041    println!(
1042        "MoE shared layout: {}, {}, {}, {}",
1043        describe("gate", tensors.moe_shared_gate.as_ref()),
1044        describe("up", tensors.moe_shared_up.as_ref()),
1045        describe("down", tensors.moe_shared_down.as_ref()),
1046        describe("input", tensors.moe_shared_gate_input.as_ref()),
1047    );
1048
1049    let hidden = embedding.dims[0] as usize;
1050    let mut raw = [0u8; MAX_RAW_ROW];
1051    let mut dequantized_row = [0.0f32; MAX_HIDDEN];
1052    let mut input = [0.0f32; MAX_HIDDEN];
1053    runtime
1054        .trunk
1055        .read_row_into(
1056            &embedding,
1057            token_id as usize,
1058            &mut raw,
1059            &mut input[..hidden],
1060        )
1061        .map_err(|error| format!("read input embedding: {error}"))?;
1062    let mut output = [0.0f32; MAX_HIDDEN];
1063    let mut expert_out = [0.0f32; MAX_HIDDEN];
1064    let mut router = [0.0f32; MAX_ROUTER];
1065    let mut top_indices = [0usize; qualia_core_db::inference::qwen::QWEN4EXP_TOP_EXPERTS];
1066    let mut top_logits = [0.0f32; qualia_core_db::inference::qwen::QWEN4EXP_TOP_EXPERTS];
1067    let mut top_weights = [0.0f32; qualia_core_db::inference::qwen::QWEN4EXP_TOP_EXPERTS];
1068    let mut gate = [0.0f32; MAX_INTERMEDIATE];
1069    let mut up = [0.0f32; MAX_INTERMEDIATE];
1070    let mut activation = [0.0f32; MAX_INTERMEDIATE];
1071    let tile_reader = tile
1072        .map(qualia_core_db::inference::qwen::QwenExpertTileReader::open)
1073        .transpose()
1074        .map_err(|error| format!("open C: expert tile: {error}"))?;
1075    let mut cached_tiles = [None; qualia_core_db::inference::qwen::QWEN4EXP_TOP_EXPERTS];
1076    if let Some(reader) = tile_reader.as_ref() {
1077        let router_info = tensors
1078            .moe_router
1079            .as_ref()
1080            .ok_or_else(|| format!("layer {layer} has no routed MoE router tensor"))?;
1081        runtime
1082            .trunk
1083            .gemv_rows_into(
1084                router_info,
1085                0,
1086                qualia_core_db::inference::qwen::QWEN4EXP_EXPERT_COUNT,
1087                &input[..hidden],
1088                &mut router,
1089                &mut raw,
1090                &mut dequantized_row,
1091            )
1092            .map_err(|error| format!("pre-route C: expert tile: {error}"))?;
1093        qualia_core_db::inference::qwen::select_top_experts(
1094            &router[..qualia_core_db::inference::qwen::QWEN4EXP_EXPERT_COUNT],
1095            &mut top_indices,
1096            &mut top_logits,
1097        )
1098        .map_err(|error| format!("pre-route C: expert tile: {error}"))?;
1099        let mut selected = false;
1100        for route in 0..qualia_core_db::inference::qwen::QWEN4EXP_TOP_EXPERTS {
1101            if reader.descriptor.layer == layer as u16
1102                && reader.descriptor.expert == top_indices[route] as u16
1103            {
1104                cached_tiles[route] = Some(reader);
1105                selected = true;
1106            }
1107        }
1108        if !selected {
1109            return Err(format!(
1110                "C: expert tile layer {} expert {} is not selected for layer {layer}, token {token_id}; no source/cache mixing was performed",
1111                reader.descriptor.layer, reader.descriptor.expert
1112            ));
1113        }
1114    }
1115    let start = std::time::Instant::now();
1116    qualia_core_db::inference::qwen::execute_streamed_moe_with_tiles(
1117        &mut runtime.trunk,
1118        &tensors,
1119        &input[..hidden],
1120        &mut output[..hidden],
1121        &mut router,
1122        &mut top_indices,
1123        &mut top_logits,
1124        &mut top_weights,
1125        &cached_tiles,
1126        &mut gate[..intermediate],
1127        &mut up[..intermediate],
1128        &mut activation[..intermediate],
1129        &mut expert_out[..hidden],
1130        &mut raw,
1131        &mut dequantized_row,
1132    )
1133    .map_err(|error| format!("streamed MoE: {error}"))?;
1134    let elapsed = start.elapsed();
1135    let mut fingerprint = 0xcbf2_9ce4_8422_2325u64;
1136    for value in &output[..hidden] {
1137        fingerprint ^= value.to_bits() as u64;
1138        fingerprint = fingerprint.wrapping_mul(0x1000_0000_01b3);
1139    }
1140    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1141    println!("Qwen4Exp selected-expert MoE probe");
1142    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1143    println!("โ”œโ”€ layer {layer}, token {token_id}: {hidden} hidden ร— {intermediate} intermediate");
1144    println!("โ”œโ”€ selected experts: {:?}", top_indices);
1145    if let Some(reader) = tile_reader.as_ref() {
1146        println!(
1147            "โ”œโ”€ C: cached route: layer {} expert {}",
1148            reader.descriptor.layer, reader.descriptor.expert
1149        );
1150    }
1151    println!("โ”œโ”€ operator time: {:.3}s", elapsed.as_secs_f64());
1152    println!("โ””โ”€ routed/shared MoE output fingerprint={fingerprint:016x}");
1153    Ok(())
1154}
1155
1156/// Explicit cold-path promotion of one selected expert.  This is deliberately
1157/// not part of ordinary activation: the caller must name a C: cache directory
1158/// and budget before any new artifact is made.
1159pub fn run_promote_qwen4exp_expert(
1160    package: &Path,
1161    layer: u16,
1162    expert: u16,
1163    cache_dir: &Path,
1164    max_cache_gib: u64,
1165) -> Result<(), String> {
1166    let runtime = qualia_core_db::inference::qwen::Qwen4ExpNativeRuntime::activate(package)
1167        .map_err(|error| error.to_string())?;
1168    let tensors = runtime.index.get_layer_tensors(layer as u32);
1169    let gate = tensors
1170        .moe_gate_exps
1171        .as_ref()
1172        .ok_or_else(|| format!("layer {layer} has no routed MoE gate tensor"))?;
1173    let up = tensors
1174        .moe_up_exps
1175        .as_ref()
1176        .ok_or_else(|| format!("layer {layer} has no routed MoE up tensor"))?;
1177    let down = tensors
1178        .moe_down_exps
1179        .as_ref()
1180        .ok_or_else(|| format!("layer {layer} has no routed MoE down tensor"))?;
1181    let limit = max_cache_gib
1182        .checked_mul(1024 * 1024 * 1024)
1183        .ok_or_else(|| "cache budget overflow".to_string())?;
1184    let source = runtime
1185        .descriptor
1186        .source_beside(package)
1187        .map_err(|error| error.to_string())?;
1188    let (tile, admission) = qualia_core_db::inference::qwen::promote_expert_tile(
1189        &source,
1190        runtime.descriptor.source.byte_len,
1191        runtime.index.tensor_data_start,
1192        layer,
1193        expert,
1194        gate,
1195        up,
1196        down,
1197        cache_dir,
1198        limit,
1199    )
1200    .map_err(|error| error.to_string())?;
1201    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1202    println!("Qwen4Exp selected-expert C: promotion");
1203    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1204    println!("โ”œโ”€ layer {layer}, expert {expert}");
1205    println!("โ”œโ”€ tile: {}", tile.display());
1206    println!("โ”œโ”€ requested: {} bytes", admission.requested_bytes);
1207    println!(
1208        "โ””โ”€ cache: {} / {} bytes before promotion",
1209        admission.cache_used_bytes, admission.cache_limit_bytes
1210    );
1211    Ok(())
1212}
1213
1214/// Exercise a promoted C: expert tile using a true E: token embedding. This
1215/// is one cached gate-plane operator, not a complete MoE or text decode.
1216pub fn run_probe_qwen4exp_expert_tile(
1217    package: &Path,
1218    tile: &Path,
1219    token_id: u32,
1220) -> Result<(), String> {
1221    const MAX_HIDDEN: usize = 4_096;
1222    const MAX_INTERMEDIATE: usize = 4_096;
1223    const MAX_RAW_ROW: usize = 65_536;
1224    let mut runtime = qualia_core_db::inference::qwen::Qwen4ExpNativeRuntime::activate(package)
1225        .map_err(|error| error.to_string())?;
1226    let embedding = *runtime
1227        .index
1228        .token_embd_info()
1229        .ok_or_else(|| "Qwen4Exp source has no token embedding tensor".to_string())?;
1230    let hidden = embedding.dims[0] as usize;
1231    if hidden > MAX_HIDDEN || token_id as u64 >= embedding.dims[1] {
1232        return Err("token embedding exceeds fixed tile-probe buffers".to_string());
1233    }
1234    let reader = qualia_core_db::inference::qwen::QwenExpertTileReader::open(tile)
1235        .map_err(|error| error.to_string())?;
1236    let intermediate = reader.descriptor.gate.dims[1] as usize;
1237    if reader.descriptor.gate.dims[0] as usize != hidden || intermediate > MAX_INTERMEDIATE {
1238        return Err("tile gate shape does not match the source token embedding".to_string());
1239    }
1240    let mut raw = [0u8; MAX_RAW_ROW];
1241    let mut input = [0.0f32; MAX_HIDDEN];
1242    runtime
1243        .trunk
1244        .read_row_into(
1245            &embedding,
1246            token_id as usize,
1247            &mut raw,
1248            &mut input[..hidden],
1249        )
1250        .map_err(|error| format!("read input embedding: {error}"))?;
1251    let mut output = [0.0f32; MAX_INTERMEDIATE];
1252    let mut row = [0.0f32; MAX_HIDDEN];
1253    let start = std::time::Instant::now();
1254    reader
1255        .gemv_into(
1256            qualia_core_db::inference::qwen::QwenExpertTilePlaneKind::Gate,
1257            &input[..hidden],
1258            &mut output[..intermediate],
1259            &mut row,
1260        )
1261        .map_err(|error| error.to_string())?;
1262    let elapsed = start.elapsed();
1263    let mut fingerprint = 0xcbf2_9ce4_8422_2325u64;
1264    for value in &output[..intermediate] {
1265        fingerprint ^= value.to_bits() as u64;
1266        fingerprint = fingerprint.wrapping_mul(0x1000_0000_01b3);
1267    }
1268    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1269    println!("Qwen4Exp C: expert-tile gate probe");
1270    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1271    println!(
1272        "โ”œโ”€ layer {}, expert {}; {} โ†’ {}",
1273        reader.descriptor.layer, reader.descriptor.expert, hidden, intermediate
1274    );
1275    println!(
1276        "โ”œโ”€ tile: {} bytes",
1277        std::fs::metadata(tile).map(|m| m.len()).unwrap_or(0)
1278    );
1279    println!("โ”œโ”€ C: gate operator time: {:.3}s", elapsed.as_secs_f64());
1280    println!("โ””โ”€ gate output fingerprint={fingerprint:016x}");
1281    Ok(())
1282}
1283
1284/// Remarkable one-shot: optional passport + auto-layout convert + activate knobs.
1285pub fn run_optimize_pipeline(
1286    input: &Path,
1287    out: Option<PathBuf>,
1288    skip_passport: bool,
1289) -> Result<(), String> {
1290    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1291    println!("REMARKABLE PATH โ€” passport + convert + activate knobs");
1292    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1293
1294    if !skip_passport {
1295        let _ = run_hardware_passport(true, 512, None, true, None, 16);
1296    }
1297
1298    let out_dir = out.unwrap_or_else(|| {
1299        input
1300            .parent()
1301            .map(|p| p.to_path_buf())
1302            .unwrap_or_else(|| PathBuf::from("."))
1303    });
1304    run_convert_gguf_to_p64(input, &out_dir, 14, "auto")?;
1305
1306    let stem = input
1307        .file_stem()
1308        .and_then(|s| s.to_str())
1309        .unwrap_or("model");
1310    // auto may produce .f16.p64 / .soa.p64 / .p64 โ€” list what we wrote
1311    let candidates = [
1312        out_dir.join(format!("{stem}.f16.p64")),
1313        out_dir.join(format!("{stem}.soa.p64")),
1314        out_dir.join(format!("{stem}.p64")),
1315    ];
1316    let p64 = candidates.iter().find(|p| p.is_file());
1317    println!();
1318    println!("Activate (fast path):");
1319    println!("  $env:QUALIA_P64_INTEGRITY='metadata'");
1320    if let Some(p) = p64 {
1321        println!("  # model path: {}", p.display());
1322        if let Ok(Some(h)) = qualia_core_db::model_helper::ModelHelper::load_beside_p64(p) {
1323            println!(
1324                "  # helper: layout={} family={} stops={:?}",
1325                h.layout, h.tokenizer.chat_family, h.tokenizer.stop_token_ids
1326            );
1327        }
1328    }
1329    println!("  qualia-cli llm load <stem-or-path>   # vault prefers .p64");
1330    Ok(())
1331}
1332
1333/// Probe / load HardwarePassport and print the ranked circuit matrix.
1334///
1335/// `decode_proxy`: `None` = skip; `Some(None)` = auto-find smollm; `Some(Some(path))` = use path.
1336pub fn run_hardware_passport(
1337    reprobe: bool,
1338    gemv_n: usize,
1339    cache: Option<PathBuf>,
1340    apply_env_hint: bool,
1341    decode_proxy: Option<Option<PathBuf>>,
1342    decode_proxy_tokens: u32,
1343) -> Result<(), String> {
1344    use qualia_core_db::device_benchmark::benchmark_devices;
1345    use qualia_core_db::hardware_passport::{
1346        attach_decode_proxy_via_subprocess, backend_env_token, default_cache_path,
1347        default_decode_proxy_model, load_or_probe, topology_key, write_passport, HardwarePassport,
1348        PASSPORT_VERSION,
1349    };
1350    use qualia_core_db::host_topology::probe_host_topology;
1351
1352    let path = cache.unwrap_or_else(default_cache_path);
1353    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1354    println!("HardwarePassport");
1355    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1356    println!("โ”œโ”€ Cache: {}", path.display());
1357    println!("โ”œโ”€ GEMV n: {gemv_n}");
1358    println!("โ””โ”€ Reprobe: {reprobe}");
1359
1360    let (mut passport, was_cached) = if reprobe {
1361        if path.exists() {
1362            let _ = std::fs::remove_file(&path);
1363        }
1364        let topology = probe_host_topology();
1365        let key = topology_key(&topology);
1366        println!("โ”œโ”€ Probing circuits (this takes a few seconds)โ€ฆ");
1367        let matrix = benchmark_devices(gemv_n);
1368        let preferred = matrix
1369            .best()
1370            .and_then(|c| backend_env_token(&c.backend))
1371            .map(str::to_string);
1372        let fresh = HardwarePassport {
1373            version: PASSPORT_VERSION,
1374            key,
1375            topology,
1376            matrix,
1377            preferred_inference_backend: preferred,
1378            probe_gemv_n: gemv_n,
1379            decode_proxy_model: None,
1380            decode_proxy_tokens: 0,
1381        };
1382        write_passport(&fresh, &path)?;
1383        (fresh, false)
1384    } else {
1385        load_or_probe(&path, gemv_n)
1386    };
1387
1388    // Optional decode-proxy ranking (subprocess per backend โ€” shared_gpu is process-wide).
1389    if let Some(model_opt) = decode_proxy {
1390        let model = match model_opt {
1391            Some(p) => p,
1392            None => default_decode_proxy_model().ok_or_else(|| {
1393                "no decode-proxy model: pass --decode-proxy <path> or set QUALIA_LLM_PROFILE_MODEL / place smollm under C:/LLM_Models/P64".to_string()
1394            })?,
1395        };
1396        if !model.is_file() {
1397            return Err(format!("decode-proxy model not found: {}", model.display()));
1398        }
1399        let exe = std::env::current_exe().map_err(|e| format!("current_exe: {e}"))?;
1400        println!(
1401            "โ”œโ”€ Decode-proxy: {} ({} tokens, child process per GPU backend)โ€ฆ",
1402            model.display(),
1403            decode_proxy_tokens
1404        );
1405        attach_decode_proxy_via_subprocess(&mut passport.matrix, &model, decode_proxy_tokens, &exe);
1406        passport.decode_proxy_model = Some(model.display().to_string());
1407        passport.decode_proxy_tokens = decode_proxy_tokens;
1408        passport.preferred_inference_backend = passport
1409            .matrix
1410            .best()
1411            .and_then(|c| backend_env_token(&c.backend))
1412            .map(str::to_string);
1413        write_passport(&passport, &path)?;
1414        println!("โ”œโ”€ Decode-proxy ranking applied + cache updated");
1415    }
1416
1417    println!(
1418        "โ”œโ”€ Source: {}",
1419        if was_cached {
1420            "cache hit (fast-boot)"
1421        } else {
1422            "fresh probe"
1423        }
1424    );
1425    println!("โ”œโ”€ Key: {}", passport.key);
1426    if let Some(ref m) = passport.decode_proxy_model {
1427        println!(
1428            "โ”œโ”€ Decode-proxy model: {m} ({} tokens)",
1429            passport.decode_proxy_tokens
1430        );
1431    }
1432    println!("{}", passport.matrix.summary());
1433
1434    if let Some(ref pref) = passport.preferred_inference_backend {
1435        println!("โ”œโ”€ Preferred inference backend (stored): {pref}");
1436    }
1437    if let Some(best) = passport.matrix.best() {
1438        println!("Selected inference circuit (measured):");
1439        println!(
1440            "  โ””โ”€ {} [{}] {:.3} ms/GEMV  {:.1} GFLOP/s{}",
1441            best.label,
1442            best.backend,
1443            best.ms_per_gemv,
1444            best.gflops,
1445            best.decode_proxy_tok_s
1446                .map(|t| format!("  {t:.2} tok/s decode-proxy"))
1447                .unwrap_or_default()
1448        );
1449        let hint = passport
1450            .preferred_inference_backend
1451            .clone()
1452            .or_else(|| backend_env_token(&best.backend).map(str::to_string));
1453        if let Some(h) = hint {
1454            println!("  โ””โ”€ Hint: set QUALIA_WGPU_BACKEND={h} to pin this backend");
1455            println!(
1456                "  โ””โ”€ Fast P64 activate: QUALIA_P64_INTEGRITY=metadata (after trusted convert)"
1457            );
1458            if apply_env_hint {
1459                let hint_path = path.with_extension("env");
1460                std::fs::write(
1461                    &hint_path,
1462                    format!("QUALIA_WGPU_BACKEND={h}\nQUALIA_P64_INTEGRITY=metadata\n"),
1463                )
1464                .map_err(|e| format!("write env hint: {e}"))?;
1465                println!("  โ””โ”€ Wrote {}", hint_path.display());
1466            }
1467        } else {
1468            println!("  โ””โ”€ Best circuit is CPU โ€” keep GPU default; no QUALIA_WGPU_BACKEND pin");
1469        }
1470    }
1471    Ok(())
1472}
1473
1474/// Quant-graph dry-run: ground a prompt+answer pair (forces mode logic via unconditional ground).
1475pub fn run_ground_check(prompt: &str, answer: &str) -> Result<(), String> {
1476    use qualia_core_db::{active_inference_mode, fact_count, ground_generation};
1477    let g = ground_generation(prompt, answer);
1478    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1479    println!("Quant-graph grounding check");
1480    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1481    println!("โ”œโ”€ active mode: {}", active_inference_mode().as_str());
1482    println!("โ”œโ”€ fact_count:  {}", fact_count());
1483    println!("โ”œโ”€ repaired:    {}", g.repaired);
1484    println!("โ”œโ”€ reason:      {:?}", g.reason);
1485    println!(
1486        "โ”œโ”€ object_hash: {:?}",
1487        g.object_hash.map(|h| format!("{h:#x}"))
1488    );
1489    println!("โ””โ”€ text:        {}", g.text);
1490    Ok(())
1491}
1492
1493/// Seed quant-graph facts from bundled TSV / QUALIA_GROUNDING_FACTS.
1494pub fn run_seed_grounding() -> Result<(), String> {
1495    let n = qualia_core_db::seed_facts_from_bundled();
1496    println!(
1497        "seeded {n} grounding facts (fact_count={})",
1498        qualia_core_db::fact_count()
1499    );
1500    Ok(())
1501}
1502
1503/// Dense CUDA WMMA microbench (mode-independent; reports whether TC path is live).
1504pub fn run_cuda_tc_microbench(side: usize) -> Result<(), String> {
1505    use std::time::Instant;
1506    let n = side.max(16);
1507    // Pad to multiple of 16 for WMMA tile.
1508    let n = ((n + 15) / 16) * 16;
1509    let k = n;
1510    let m = n;
1511    let a = vec![1.0f32; m * k];
1512    let b = vec![1.0f32; k * n];
1513    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1514    println!("CUDA TC microbench  C[{m}ร—{n}] = A[{m}ร—{k}]ยทB[{k}ร—{n}]");
1515    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1516    // Warm + timed
1517    let _ = qualia_core_db::wgsl_forge::dispatch::ensure_cuda_runtime_path();
1518    let t0 = Instant::now();
1519    // CUDA TC microbench: exercise the reduced-precision path (the CUDA WMMA tier).
1520    let r1 = qualia_core_db::wgsl_forge::dispatch::gemm_f32_tc_reduced(m, k, n, &a, &b)
1521        .map_err(|e| format!("gemm_f32_tc_reduced: {e:?}"))?;
1522    let warm_ms = t0.elapsed().as_secs_f64() * 1000.0;
1523    let t1 = Instant::now();
1524    let r2 = qualia_core_db::wgsl_forge::dispatch::gemm_f32_tc_reduced(m, k, n, &a, &b)
1525        .map_err(|e| format!("gemm_f32_tc_reduced: {e:?}"))?;
1526    let hot_ms = t1.elapsed().as_secs_f64() * 1000.0;
1527    let caps = qualia_core_db::wgsl_forge::dispatch::caps();
1528    println!(
1529        "โ”œโ”€ caps: wgpu={} cuda={} coopmat={}",
1530        caps.wgpu, caps.cuda, caps.coopmat
1531    );
1532    println!("โ”œโ”€ warm: {warm_ms:.2} ms (includes NVRTC/context first use)");
1533    println!("โ”œโ”€ hot:  {hot_ms:.2} ms");
1534    println!(
1535        "โ”œโ”€ C[0]={:.1} (expect ~{n}.0 for all-ones)",
1536        r2.first().copied().unwrap_or(0.0)
1537    );
1538    println!("โ””โ”€ ok:   r1_len={} r2_len={}", r1.len(), r2.len());
1539    Ok(())
1540}
1541
1542/// Print or set multi-mode inference approach (portable / cuda / quant-graph).
1543pub fn run_inference_mode(set: Option<&str>) -> Result<(), String> {
1544    use qualia_core_db::{active_inference_mode, set_inference_mode, InferenceMode};
1545    if let Some(name) = set {
1546        let m = InferenceMode::parse(name).ok_or_else(|| {
1547            format!("unknown mode '{name}' (expected: portable | cuda | quant-graph | fast-verify)")
1548        })?;
1549        set_inference_mode(m);
1550        // Also pin env so child processes (decode-proxy) inherit.
1551        std::env::set_var("QUALIA_INFERENCE_MODE", m.as_str());
1552        println!("MODE set={}", m.as_str());
1553        println!("  {}", m.description());
1554        println!("  (shell: $env:QUALIA_INFERENCE_MODE='{}')", m.as_str());
1555        return Ok(());
1556    }
1557    let active = active_inference_mode();
1558    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1559    println!("Inference modes (coexisting approaches โ€” not replacements)");
1560    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1561    println!("Active: {} โ€” {}", active.as_str(), active.description());
1562    println!();
1563    for m in InferenceMode::ALL {
1564        let mark = if m == active { "*" } else { " " };
1565        println!("  [{mark}] {:12}  {}", m.as_str(), m.description());
1566    }
1567    println!();
1568    println!("Set:  qualia-cli llm mode <portable|cuda|quant-graph>");
1569    println!("Env:  QUALIA_INFERENCE_MODE");
1570    println!("Plan: docs/plans/inference-multi-mode-and-compression.md");
1571    Ok(())
1572}
1573
1574/// Inference superiority lab instruments.
1575pub fn run_lab(
1576    action: &str,
1577    model: Option<&std::path::Path>,
1578    tokens: u32,
1579    n_in: usize,
1580    n_out: usize,
1581    gemv_n: usize,
1582    out: Option<&std::path::Path>,
1583    hours: f64,
1584    max_generations: u32,
1585    ollama_model: Option<&str>,
1586    ollama_url: &str,
1587    no_ollama: bool,
1588) -> Result<(), String> {
1589    use qualia_core_db::lab::{
1590        ablate::format_ablation_report, audit_hot_path, calibrate_device_roof,
1591        format_lockin_summary, run_ablation_matrix, run_auto_improve, run_decode_timeline,
1592        run_q4k_soa_microbench, AutoImproveConfig,
1593    };
1594    match action.trim().to_ascii_lowercase().as_str() {
1595        "audit-path" | "audit" => {
1596            print!("{}", audit_hot_path().format_report());
1597            Ok(())
1598        }
1599        "roof" | "device-roof" => {
1600            print!("{}", calibrate_device_roof(gemv_n).format_report());
1601            let (g, i) = qualia_core_db::lab::device_roof::cpu_q4_intensity_probe(1024, 32);
1602            println!("  cpu_q4_probe: {g:.2} GFLOP/s  intensity={i:.3} FLOP/B");
1603            Ok(())
1604        }
1605        "micro" | "microbench" => {
1606            print!("{}", run_q4k_soa_microbench(n_in, n_out).format_report());
1607            Ok(())
1608        }
1609        "timeline" => {
1610            let m = model.ok_or("timeline requires --model <path.p64>")?;
1611            let t = if tokens == 0 { 4 } else { tokens };
1612            print!("{}", run_decode_timeline(m, t).format_report());
1613            Ok(())
1614        }
1615        "ablate" | "ablation" => {
1616            let m =
1617                model.ok_or("ablate requires --model <path.safetensors | path.p64 | path.gguf>")?;
1618            let t = if tokens == 0 { 8 } else { tokens };
1619            let csv =
1620                out.or_else(|| Some(std::path::Path::new("experiments/inference-lab/runs.csv")));
1621            let rows = run_ablation_matrix(m, t, csv);
1622            print!("{}", format_ablation_report(&rows));
1623            if let Some(p) = csv {
1624                println!("CSV appended: {}", p.display());
1625            }
1626            Ok(())
1627        }
1628        "auto" | "auto-improve" | "lockin" | "self-improve" => {
1629            let m = model.ok_or(
1630                "lab auto requires --model <path.safetensors | path.p64 | path.gguf> (e.g. smollm2, Qwen, or Llama-3.2)",
1631            )?;
1632            let t = if tokens == 0 { 16 } else { tokens };
1633            let hours = if hours <= 0.0 { 2.0 } else { hours };
1634            let out_dir = out
1635                .map(|p| p.to_path_buf())
1636                .unwrap_or_else(|| std::path::PathBuf::from("experiments/inference-lab/lockin"));
1637            let ollama = if no_ollama {
1638                None
1639            } else {
1640                match ollama_model {
1641                    Some(s) if s.is_empty() || s.eq_ignore_ascii_case("none") => None,
1642                    Some(s) => Some(s.to_string()),
1643                    None => Some("qualia-smol-q8:latest".into()),
1644                }
1645            };
1646            let cfg = AutoImproveConfig {
1647                model: m.to_path_buf(),
1648                tokens: t,
1649                max_duration: std::time::Duration::from_secs_f64(hours * 3600.0),
1650                out_dir,
1651                ollama_model: ollama,
1652                ollama_url: ollama_url.to_string(),
1653                elite_resample: 3,
1654                plateau_rel: 0.02,
1655                plateau_gens: 2,
1656                max_generations: max_generations.max(1),
1657            };
1658            println!("lab auto โ€” recursive measure โ†’ search โ†’ lock-in");
1659            println!("  model:      {}", cfg.model.display());
1660            println!("  tokens:     {}", cfg.tokens);
1661            println!("  hours:      {hours}");
1662            println!("  gens:       {}", cfg.max_generations);
1663            println!("  out:        {}", cfg.out_dir.display());
1664            println!(
1665                "  ollama:     {}",
1666                cfg.ollama_model.as_deref().unwrap_or("(skipped)")
1667            );
1668            println!("  (wall clock budget; plateau or gens may finish earlier)");
1669            let pkg = run_auto_improve(&cfg)?;
1670            print!("{}", format_lockin_summary(&pkg));
1671            println!("Lock-in package written to: {}", pkg.out_dir.display());
1672            println!(
1673                "  BEST_CONFIG.json  METHODOLOGY.md  apply-best.ps1  runs.csv  LOCKIN_SUMMARY.txt"
1674            );
1675            Ok(())
1676        }
1677        "gpu-cap" | "gpu-capability" | "machine-gpu" => {
1678            let t = if tokens == 0 { 16 } else { tokens };
1679            run_gpu_capability_campaign(model, out, t)
1680        }
1681        "help" | _ => {
1682            println!("qualia-cli llm lab <action>");
1683            println!("  audit-path              hot-path wiring audit");
1684            println!("  roof [--gemv-n N]       device roof calibration");
1685            println!("  micro [--n-in N --n-out M]  Q4 SoA GEMV microbench");
1686            println!("  timeline --model P [--tokens T]  decode phase timeline");
1687            println!("  ablate --model P [--tokens T] [--out runs.csv]");
1688            println!("  auto --model P [--hours H] [--tokens T] [--out lockin-dir]");
1689            println!("       [--max-generations N] [--ollama-model TAG] [--no-ollama]");
1690            println!(
1691                "       multi-hour recursive search โ†’ lock-in package (.safetensors/.p64/.gguf)"
1692            );
1693            println!("  gpu-cap [--model P] [--tokens T] [--out dir]");
1694            println!("       native GPU tier probe + backendร—mode decode matrix");
1695            println!("       โ†’ machine-gpu-profile.json + apply-machine-gpu.ps1");
1696            println!("Plan: docs/plans/inference-review-and-plan-2026-09-18.md (F14)");
1697            if action != "help" && !action.is_empty() && action != "_" {
1698                return Err(format!("unknown lab action '{action}'"));
1699            }
1700            Ok(())
1701        }
1702    }
1703}
1704
1705/// Probe which **native** GPU tiers this host has, measure the backend ร— mode decode matrix
1706/// in child processes, and write `machine-gpu-profile.json` + `apply-machine-gpu.ps1`.
1707///
1708/// WGSL/wgpu is the portable floor; CUDA-C/PTX, HLSL+DXC, MSL, subgroups and coopmat are higher
1709/// tiers when present. Only a **coherent** measurement can be recommended (speed without sense
1710/// is failure), so the profile ranks by tok/s among coherent rows only.
1711///
1712/// One child process per cell: `shared_gpu` is process-wide, so `QUALIA_WGPU_BACKEND` cannot be
1713/// re-pointed in-process.
1714pub fn run_gpu_capability_campaign(
1715    model: Option<&Path>,
1716    out_dir: Option<&Path>,
1717    tokens: u32,
1718) -> Result<(), String> {
1719    use qualia_core_db::machine_gpu_profile::{
1720        AdapterFeatures, MachineGpuProfile, MeasuredDecodePath, ToolchainAvailability,
1721        MACHINE_GPU_PROFILE_VERSION,
1722    };
1723    use std::process::Command;
1724
1725    fn tool_ok(program: &str, arg: &str) -> bool {
1726        Command::new(program)
1727            .arg(arg)
1728            .output()
1729            .map(|o| o.status.success())
1730            .unwrap_or(false)
1731    }
1732
1733    let p64 = match model {
1734        Some(p) => p.to_path_buf(),
1735        None => {
1736            qualia_core_db::hardware_passport::default_decode_proxy_model().ok_or_else(|| {
1737                "no package: pass --model <path.p64> or set QUALIA_LLM_PROFILE_MODEL".to_string()
1738            })?
1739        }
1740    };
1741    if !p64.is_file() {
1742        return Err(format!("package not found: {}", p64.display()));
1743    }
1744    let out = out_dir
1745        .map(|p| p.to_path_buf())
1746        .unwrap_or_else(|| p64.parent().unwrap_or(Path::new(".")).to_path_buf());
1747    let tokens = tokens.clamp(8, 128);
1748
1749    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1750    println!("GPU CAPABILITY โ€” native tiers over the WGSL floor");
1751    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
1752    println!("โ”œโ”€ Package: {}", p64.display());
1753    println!("โ”œโ”€ Tokens:  {tokens}");
1754    println!("โ”œโ”€ Out:     {}", out.display());
1755
1756    // โ”€โ”€ Toolchain โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
1757    let nvcc = std::env::var("CUDA_PATH")
1758        .map(|p| format!("{p}/bin/nvcc"))
1759        .unwrap_or_else(|_| "nvcc".to_string());
1760    let dxc = std::env::var("QUALIA_DXC_PATH").unwrap_or_else(|_| "dxc".to_string());
1761    let cuda_toolkit = tool_ok(&nvcc, "--version");
1762    let dxc_cli = tool_ok(&dxc, "--version");
1763    let metal_xcrun = cfg!(target_os = "macos") && tool_ok("xcrun", "--version");
1764
1765    // โ”€โ”€ Adapter (parent device; children create their own) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
1766    let gpu = qualia_core_db::gpu_context::try_shared_gpu();
1767    let adapter = match gpu {
1768        Some(g) => AdapterFeatures {
1769            name: g.adapter_caps.name.clone(),
1770            backend: g.adapter_caps.backend_label().to_string(),
1771            discrete: g.adapter_caps.device_type_label() == "discrete",
1772            subgroups: g.adapter_caps.features.subgroup,
1773            coopmat: g.adapter_caps.cooperative_matrix_tile_count > 0,
1774            shader_f16: g.adapter_caps.features.shader_f16,
1775            timestamp_query: g.timestamps_supported,
1776            topology_hash: qualia_core_db::hardware_passport::topology_key(
1777                &qualia_core_db::host_topology::probe_host_topology(),
1778            ),
1779        },
1780        None => AdapterFeatures::default(),
1781    };
1782    println!(
1783        "โ”œโ”€ Adapter: {} ({}) subgroups={} coopmat={} f16={}",
1784        if adapter.name.is_empty() {
1785            "none"
1786        } else {
1787            &adapter.name
1788        },
1789        adapter.backend,
1790        adapter.subgroups,
1791        adapter.coopmat,
1792        adapter.shader_f16
1793    );
1794    println!(
1795        "โ”œโ”€ Toolchain: wgpu={} cuda={cuda_toolkit} dxc_cli={dxc_cli} metal={metal_xcrun}",
1796        gpu.is_some()
1797    );
1798
1799    let mut native_tiers = vec!["wgsl".to_string(), "spirv".to_string()];
1800    if cuda_toolkit {
1801        native_tiers.push("cuda-c".into());
1802        native_tiers.push("ptx".into());
1803    }
1804    if dxc_cli {
1805        native_tiers.push("hlsl-dxc".into());
1806    }
1807    if metal_xcrun {
1808        native_tiers.push("msl".into());
1809    }
1810    if adapter.subgroups {
1811        native_tiers.push("subgroups".into());
1812    }
1813    if adapter.coopmat {
1814        native_tiers.push("coopmat".into());
1815    }
1816
1817    // โ”€โ”€ Decode matrix (child process per cell) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
1818    let backends: &[&str] = if cfg!(target_os = "macos") {
1819        &["metal"]
1820    } else if cfg!(target_os = "windows") {
1821        &["vulkan", "dx12"]
1822    } else {
1823        &["vulkan"]
1824    };
1825    let modes = ["portable", "fast-verify", "cuda"];
1826    let self_exe = std::env::current_exe().map_err(|e| format!("current_exe: {e}"))?;
1827    let mut measured: Vec<MeasuredDecodePath> = Vec::new();
1828
1829    let wgpu_cells = backends.len() * modes.len();
1830    let cuda_c_cells = if cuda_toolkit { 1 } else { 0 };
1831    let hlsl_cells = if dxc_cli { 1 } else { 0 };
1832    let spirv_cells = if dxc_cli { 1 } else { 0 };
1833    let ptx_cells = if cuda_toolkit { 1 } else { 0 };
1834    println!(
1835        "โ”œโ”€ Decode matrix ({} cells)โ€ฆ",
1836        wgpu_cells + cuda_c_cells + hlsl_cells + spirv_cells + ptx_cells
1837    );
1838    for backend in backends {
1839        for mode in modes {
1840            print!("โ”‚   {backend:7} {mode:12} โ€ฆ ");
1841            use std::io::Write as _;
1842            let _ = std::io::stdout().flush();
1843            let t0 = std::time::Instant::now();
1844            let output = Command::new(&self_exe)
1845                .args([
1846                    "llm",
1847                    "decode-proxy",
1848                    &p64.display().to_string(),
1849                    "--tokens",
1850                    &tokens.to_string(),
1851                ])
1852                .env("QUALIA_WGPU_BACKEND", backend)
1853                .env("QUALIA_INFERENCE_MODE", mode)
1854                .env_remove("QUALIA_FORGE_BACKEND")
1855                .env_remove("QUALIA_DXC_PATH")
1856                .output();
1857            let wall = t0.elapsed().as_secs_f64();
1858            match output {
1859                Ok(o) => {
1860                    let stdout = String::from_utf8_lossy(&o.stdout);
1861                    match qualia_core_db::hardware_passport::parse_decode_proxy_record(&stdout) {
1862                        Some(rec) => {
1863                            let coherence_ok = rec.coherence_ok.unwrap_or(o.status.success());
1864                            println!(
1865                                "{:.2} tok/s  {}  ({wall:.1}s)",
1866                                rec.tok_s,
1867                                if coherence_ok {
1868                                    "coherent"
1869                                } else {
1870                                    "INCOHERENT"
1871                                }
1872                            );
1873                            measured.push(MeasuredDecodePath {
1874                                wgpu_backend: (*backend).to_string(),
1875                                inference_mode: mode.to_string(),
1876                                p64_path: p64.display().to_string(),
1877                                tok_s: rec.tok_s,
1878                                coherence_ok,
1879                                tokens,
1880                            });
1881                        }
1882                        None => {
1883                            let stderr = String::from_utf8_lossy(&o.stderr);
1884                            let tail: String = stderr.lines().rev().take(1).collect();
1885                            println!("no DECODE_PROXY line ({wall:.1}s) {tail}");
1886                        }
1887                    }
1888                }
1889                Err(e) => println!("spawn failed ({wall:.1}s): {e}"),
1890            }
1891        }
1892    }
1893
1894    // โ”€โ”€ CUDA-C native decode row (lab path: CUDA SoA layer) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
1895    // Exercises the actual CUDA execution lane: QUALIA_LLM_CUDA_DECODE=1 opts
1896    // into the layer-by-layer CUDA SoA decode path (device RoPE/KV/SDPA +
1897    // sticky Q4_K_SOA), bypassing the wgpu resident mega-pass. This is the
1898    // path that uses forge CUDA-C shader emission (gemv_f32, gemm_f32_tc,
1899    // ternary_gemv, p64_project, fft) via NVRTC on the NVIDIA driver.
1900    if cuda_toolkit {
1901        print!("โ”‚   cuda-c  native        โ€ฆ ");
1902        use std::io::Write as _;
1903        let _ = std::io::stdout().flush();
1904        let t0 = std::time::Instant::now();
1905        let output = Command::new(&self_exe)
1906            .args([
1907                "llm",
1908                "decode-proxy",
1909                &p64.display().to_string(),
1910                "--tokens",
1911                &tokens.to_string(),
1912            ])
1913            .env("QUALIA_INFERENCE_MODE", "cuda")
1914            .env("QUALIA_LLM_CUDA_DECODE", "1")
1915            .env("QUALIA_LLM_KV_INT8", "0")
1916            .env_remove("QUALIA_FORGE_BACKEND")
1917            .env_remove("QUALIA_DXC_PATH")
1918            .output();
1919        let wall = t0.elapsed().as_secs_f64();
1920        match output {
1921            Ok(o) => {
1922                let stdout = String::from_utf8_lossy(&o.stdout);
1923                match qualia_core_db::hardware_passport::parse_decode_proxy_record(&stdout) {
1924                    Some(rec) => {
1925                        let path_ok = rec.execution_path.as_deref() == Some("cuda-c");
1926                        let coherence_ok =
1927                            rec.coherence_ok.unwrap_or(o.status.success()) && path_ok;
1928                        println!(
1929                            "{:.2} tok/s  {}  path={}  ({wall:.1}s)",
1930                            rec.tok_s,
1931                            if coherence_ok { "coherent" } else { "REJECTED" },
1932                            rec.execution_path.as_deref().unwrap_or("unattributed"),
1933                        );
1934                        if path_ok {
1935                            measured.push(MeasuredDecodePath {
1936                                wgpu_backend: "cuda-c".to_string(),
1937                                inference_mode: "native".to_string(),
1938                                p64_path: p64.display().to_string(),
1939                                tok_s: rec.tok_s,
1940                                coherence_ok,
1941                                tokens,
1942                            });
1943                        }
1944                    }
1945                    None => {
1946                        let stderr = String::from_utf8_lossy(&o.stderr);
1947                        let tail: String = stderr.lines().rev().take(1).collect();
1948                        println!("no DECODE_PROXY line ({wall:.1}s) {tail}");
1949                    }
1950                }
1951            }
1952            Err(e) => println!("spawn failed ({wall:.1}s): {e}"),
1953        }
1954    }
1955
1956    // โ”€โ”€ HLSL native shader rows (forge HLSL โ†’ DXC โ†’ SPIR-V โ†’ wgpu) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
1957    // Exercises the forge's HLSL emitter + DXC SPIR-V compilation path. The
1958    // resulting SPIR-V feeds into the same wgpu pipeline (same buffers, slab,
1959    // dispatch) โ€” only the shader compilation differs from the WGSL path.
1960    // Requires the DXC CLI (`QUALIA_DXC_PATH` or `dxc` on PATH).
1961    if dxc_cli {
1962        // HLSLโ†’SPIR-Vโ†’wgpu: only run with vulkan backend because
1963        // QUALIA_DXC_PATH (needed for HLSLโ†’SPIR-V via DXC CLI) also overrides
1964        // wgpu's DX12 compiler path, causing dx12 to fail.
1965        let hlsl_backends: &[&str] = if cfg!(target_os = "macos") {
1966            &["metal"]
1967        } else {
1968            &["vulkan"]
1969        };
1970        for backend in hlsl_backends {
1971            print!("โ”‚   hlsl    {backend:7}    โ€ฆ ");
1972            use std::io::Write as _;
1973            let _ = std::io::stdout().flush();
1974            let t0 = std::time::Instant::now();
1975            let output = Command::new(&self_exe)
1976                .args([
1977                    "llm",
1978                    "decode-proxy",
1979                    &p64.display().to_string(),
1980                    "--tokens",
1981                    &tokens.to_string(),
1982                ])
1983                .env("QUALIA_WGPU_BACKEND", backend)
1984                .env("QUALIA_FORGE_BACKEND", "hlsl")
1985                .output();
1986            let wall = t0.elapsed().as_secs_f64();
1987            match output {
1988                Ok(o) => {
1989                    let stdout = String::from_utf8_lossy(&o.stdout);
1990                    match qualia_core_db::hardware_passport::parse_decode_proxy_record(&stdout) {
1991                        Some(rec) => {
1992                            let path_ok = rec.execution_path.as_deref() == Some("hlsl");
1993                            let coherence_ok =
1994                                rec.coherence_ok.unwrap_or(o.status.success()) && path_ok;
1995                            println!(
1996                                "{:.2} tok/s  {}  path={}  ({wall:.1}s)",
1997                                rec.tok_s,
1998                                if coherence_ok { "coherent" } else { "REJECTED" },
1999                                rec.execution_path.as_deref().unwrap_or("unattributed"),
2000                            );
2001                            if path_ok {
2002                                measured.push(MeasuredDecodePath {
2003                                    wgpu_backend: format!("hlsl-{backend}"),
2004                                    inference_mode: "portable".to_string(),
2005                                    p64_path: p64.display().to_string(),
2006                                    tok_s: rec.tok_s,
2007                                    coherence_ok,
2008                                    tokens,
2009                                });
2010                            }
2011                        }
2012                        None => {
2013                            let stderr = String::from_utf8_lossy(&o.stderr);
2014                            let tail: String = stderr.lines().rev().take(1).collect();
2015                            println!("no DECODE_PROXY line ({wall:.1}s) {tail}");
2016                        }
2017                    }
2018                }
2019                Err(e) => println!("spawn failed ({wall:.1}s): {e}"),
2020            }
2021        }
2022    }
2023
2024    // โ”€โ”€ SPIR-V (DXC) native shader row (forge SPIR-V โ†’ DXC โ†’ wgpu) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
2025    // Exercises the forge's SPIR-V emitter with DXC-produced SPIR-V.
2026    // Same wgpu pipeline, but pre-compiled SPIR-V from DXC instead of naga.
2027    if dxc_cli {
2028        let spirv_backends: &[&str] = if cfg!(target_os = "macos") {
2029            &["metal"]
2030        } else {
2031            &["vulkan"]
2032        };
2033        for backend in spirv_backends {
2034            print!("โ”‚   spirv-dxc {backend:7} โ€ฆ ");
2035            use std::io::Write as _;
2036            let _ = std::io::stdout().flush();
2037            let t0 = std::time::Instant::now();
2038            let output = Command::new(&self_exe)
2039                .args([
2040                    "llm",
2041                    "decode-proxy",
2042                    &p64.display().to_string(),
2043                    "--tokens",
2044                    &tokens.to_string(),
2045                ])
2046                .env("QUALIA_WGPU_BACKEND", backend)
2047                .env("QUALIA_FORGE_BACKEND", "spirv")
2048                .output();
2049            let wall = t0.elapsed().as_secs_f64();
2050            match output {
2051                Ok(o) => {
2052                    let stdout = String::from_utf8_lossy(&o.stdout);
2053                    match qualia_core_db::hardware_passport::parse_decode_proxy_record(&stdout) {
2054                        Some(rec) => {
2055                            let path_ok = rec.execution_path.as_deref() == Some("spirv");
2056                            let coherence_ok =
2057                                rec.coherence_ok.unwrap_or(o.status.success()) && path_ok;
2058                            println!(
2059                                "{:.2} tok/s  {}  path={}  ({wall:.1}s)",
2060                                rec.tok_s,
2061                                if coherence_ok { "coherent" } else { "REJECTED" },
2062                                rec.execution_path.as_deref().unwrap_or("unattributed"),
2063                            );
2064                            if path_ok {
2065                                measured.push(MeasuredDecodePath {
2066                                    wgpu_backend: format!("spirv-dxc-{backend}"),
2067                                    inference_mode: "portable".to_string(),
2068                                    p64_path: p64.display().to_string(),
2069                                    tok_s: rec.tok_s,
2070                                    coherence_ok,
2071                                    tokens,
2072                                });
2073                            }
2074                        }
2075                        None => {
2076                            let stderr = String::from_utf8_lossy(&o.stderr);
2077                            let tail: String = stderr.lines().rev().take(1).collect();
2078                            println!("no DECODE_PROXY line ({wall:.1}s) {tail}");
2079                        }
2080                    }
2081                }
2082                Err(e) => println!("spawn failed ({wall:.1}s): {e}"),
2083            }
2084        }
2085    }
2086
2087    // โ”€โ”€ PTX native shader row (forge PTX โ†’ CUDA driver) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
2088    // Exercises the forge's PTX emitter with direct CUDA driver execution.
2089    // Only available when CUDA toolkit is present.
2090    if cuda_toolkit {
2091        print!("โ”‚   ptx     cuda        โ€ฆ ");
2092        use std::io::Write as _;
2093        let _ = std::io::stdout().flush();
2094        let t0 = std::time::Instant::now();
2095        let output = Command::new(&self_exe)
2096            .args([
2097                "llm",
2098                "decode-proxy",
2099                &p64.display().to_string(),
2100                "--tokens",
2101                &tokens.to_string(),
2102            ])
2103            .env("QUALIA_FORGE_BACKEND", "ptx")
2104            .output();
2105        let wall = t0.elapsed().as_secs_f64();
2106        match output {
2107            Ok(o) => {
2108                let stdout = String::from_utf8_lossy(&o.stdout);
2109                match qualia_core_db::hardware_passport::parse_decode_proxy_record(&stdout) {
2110                    Some(rec) => {
2111                        let path_ok = rec.execution_path.as_deref() == Some("ptx");
2112                        let coherence_ok =
2113                            rec.coherence_ok.unwrap_or(o.status.success()) && path_ok;
2114                        println!(
2115                            "{:.2} tok/s  {}  path={}  ({wall:.1}s)",
2116                            rec.tok_s,
2117                            if coherence_ok { "coherent" } else { "REJECTED" },
2118                            rec.execution_path.as_deref().unwrap_or("unattributed"),
2119                        );
2120                        if path_ok {
2121                            measured.push(MeasuredDecodePath {
2122                                wgpu_backend: "ptx-cuda".to_string(),
2123                                inference_mode: "portable".to_string(),
2124                                p64_path: p64.display().to_string(),
2125                                tok_s: rec.tok_s,
2126                                coherence_ok,
2127                                tokens,
2128                            });
2129                        }
2130                    }
2131                    None => {
2132                        let stderr = String::from_utf8_lossy(&o.stderr);
2133                        let tail: String = stderr.lines().rev().take(1).collect();
2134                        println!("no DECODE_PROXY line ({wall:.1}s) {tail}");
2135                    }
2136                }
2137            }
2138            Err(e) => println!("spawn failed ({wall:.1}s): {e}"),
2139        }
2140    }
2141
2142    // โ”€โ”€ Profile โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
2143    let mut profile = MachineGpuProfile {
2144        version: MACHINE_GPU_PROFILE_VERSION,
2145        written_unix_ms: MachineGpuProfile::now_ms(),
2146        host: std::env::var("COMPUTERNAME")
2147            .or_else(|_| std::env::var("HOSTNAME"))
2148            .unwrap_or_else(|_| "unknown".into()),
2149        toolchain: ToolchainAvailability {
2150            wgpu: gpu.is_some(),
2151            cuda_toolkit,
2152            dxc_cli,
2153            metal_xcrun,
2154        },
2155        adapter,
2156        native_tiers,
2157        measured_paths: measured,
2158        recommended: Default::default(),
2159        notes: vec![
2160            "WGSL via wgpu is the portable floor; native tiers (CUDA-C/WMMA, HLSL/DXC, MSL, SPIR-V, subgroups, coopmat) are preferred only when measured coherent and faster.".into(),
2161            "Vendored dxcompiler.dll (DynamicDxc for wgpu DX12) is not the DXC CLI probed here.".into(),
2162            "CUDA densify tensor-core decode stays lab-gated behind QUALIA_LLM_CUDA_TC_DECODE.".into(),
2163            format!("Measured with `llm lab gpu-cap` on {} at {tokens} tokens.", p64.display()),
2164        ],
2165    };
2166    profile.recompute_recommended();
2167
2168    if profile.recommended.wgpu_backend.is_empty() {
2169        return Err(
2170            "no coherent decode path measured โ€” nothing to recommend (see rows above)".into(),
2171        );
2172    }
2173
2174    let json_path = MachineGpuProfile::default_path(&out);
2175    profile.write_json(&json_path)?;
2176    let apply_path = out.join("apply-machine-gpu.ps1");
2177    std::fs::write(&apply_path, profile.apply_env_script_ps1())
2178        .map_err(|e| format!("write {}: {e}", apply_path.display()))?;
2179
2180    println!();
2181    println!(
2182        "RECOMMENDED backend={} mode={}",
2183        profile.recommended.wgpu_backend, profile.recommended.inference_mode
2184    );
2185    println!("  {}", profile.recommended.rationale);
2186    println!("  profile: {}", json_path.display());
2187    println!("  apply:   . {}", apply_path.display());
2188    Ok(())
2189}
2190
2191/// Show / set application profile (interactive | live-fast | batch).
2192pub fn run_app_profile(set: Option<&str>) -> Result<(), String> {
2193    use qualia_core_db::{active_application_profile, set_application_profile, ApplicationProfile};
2194    if let Some(name) = set {
2195        let p = ApplicationProfile::parse(name).ok_or_else(|| {
2196            format!("unknown profile '{name}' (expected: interactive | live-fast | batch)")
2197        })?;
2198        set_application_profile(p);
2199        std::env::set_var("QUALIA_APP_PROFILE", p.as_str());
2200        println!("PROFILE set={}", p.as_str());
2201        println!("  {}", p.description());
2202        if matches!(p, ApplicationProfile::BatchOvernight) {
2203            println!("  โ†’ overnight multi-system eval: 2048 tok, 8h wall-clock, HTML verify");
2204            println!("  โ†’ result is local HTML/CML (pipe to mailer if you want email)");
2205        }
2206        return Ok(());
2207    }
2208    let active = active_application_profile();
2209    println!("Application profiles (use case โ€” not GPU backend)");
2210    println!("Active: {} โ€” {}", active.as_str(), active.description());
2211    for p in ApplicationProfile::ALL {
2212        let mark = if p == active { "*" } else { " " };
2213        println!(" {mark} {:12}  {}", p.as_str(), p.description());
2214    }
2215    println!();
2216    println!("Env: QUALIA_APP_PROFILE=interactive|live-fast|batch");
2217    println!("No Ollama โ€” all profiles are in-process Qualia native.");
2218    Ok(())
2219}
2220
2221/// Print (and optionally apply) the device-optimal inference path plan.
2222pub fn run_path_select(reprobe: bool, apply: bool) -> Result<(), String> {
2223    let plan = qualia_core_db::inference_path_selector::run_path_select_cli(reprobe, apply);
2224    print!(
2225        "{}",
2226        qualia_core_db::inference_path_selector::format_path_plan(&plan)
2227    );
2228    println!(
2229        "path_auto={}",
2230        qualia_core_db::inference_path_selector::path_auto_enabled()
2231    );
2232    println!("applied_this_run={apply}");
2233    println!();
2234    println!("Operator:");
2235    println!("  1) qualia-cli llm passport --reprobe --decode-proxy <model.p64> --apply-env-hint");
2236    println!("  2) qualia-cli llm path-select --apply");
2237    println!("  Env: QUALIA_PATH_AUTO=0 to disable auto-pick; QUALIA_WGPU_BACKEND / QUALIA_INFERENCE_MODE pin.");
2238    println!("  Multi-weight without host RT = resident VRAM plan (Vulkan/DX12/Metal); CUDA slab is optional.");
2239    Ok(())
2240}
2241
2242/// Short resident decode for passport child processes. Machine-readable line on stdout.
2243///
2244/// Excellence bar: reports **tok/s and coherence** on the factual probe
2245/// (`The capital of France is` โ†’ must contain Paris). Speed without sense is failure.
2246pub fn run_decode_proxy(model: &Path, tokens: u32) -> Result<(), String> {
2247    use qualia_core_db::hardware_passport::measure_decode_proxy;
2248    if !model.is_file() {
2249        return Err(format!("model not found: {}", model.display()));
2250    }
2251    let backend = std::env::var("QUALIA_WGPU_BACKEND").unwrap_or_else(|_| "auto".into());
2252    let r = measure_decode_proxy(model, tokens)
2253        .ok_or_else(|| "decode-proxy measurement failed (see RUST_LOG)".to_string())?;
2254    let coh = if r.coherence_ok { 1 } else { 0 };
2255    // Stable line for parent parser (`parse_decode_proxy_record`).
2256    println!(
2257        "DECODE_PROXY tok_s={:.4} backend={backend} path={} tokens={tokens} coherence={coh} resident_hits={} resident_fallbacks={} cuda_hits={} cuda_fallbacks={}",
2258        r.tok_s,
2259        r.execution_path,
2260        r.resident_hits,
2261        r.resident_fallbacks,
2262        r.cuda_mega_hits,
2263        r.cuda_mega_fallbacks,
2264    );
2265    // Human-readable sample (not parsed by campaign โ€” for logs).
2266    let sample: String = r.text.chars().take(160).collect();
2267    eprintln!("DECODE_SAMPLE coherence={coh} text={sample:?}");
2268    if !r.coherence_ok {
2269        // Non-zero exit so explore/campaign treat garbage as fail (not a fast "winner").
2270        return Err(format!(
2271            "coherence fail: probe did not contain 'Paris' (got {:?})",
2272            sample
2273        ));
2274    }
2275    Ok(())
2276}
2277
2278/// One explore-row: layout (+ optional toggle label) โ†’ measured decode-proxy tok/s + coherence.
2279#[derive(Debug, Clone, serde::Serialize)]
2280pub struct ExploreCandidateResult {
2281    pub layout: String,
2282    pub path: String,
2283    pub tok_s: Option<f64>,
2284    pub error: Option<String>,
2285    /// Extra axis, e.g. `ffn_f16=off` / `ffn_f16=on`.
2286    pub toggle: String,
2287    pub bytes: u64,
2288    /// Factual probe passed (`Paris` in completion). Required for excellence winner.
2289    #[serde(default)]
2290    pub coherence_ok: Option<bool>,
2291}
2292
2293#[derive(Debug, Clone, serde::Serialize)]
2294pub struct ExploreReport {
2295    pub version: u32,
2296    pub source: String,
2297    pub out_dir: String,
2298    pub tokens: u32,
2299    pub backend: String,
2300    /// Active multi-mode approach (`portable` | `cuda` | `quant-graph`).
2301    pub inference_mode: String,
2302    pub candidates: Vec<ExploreCandidateResult>,
2303    pub winner_path: Option<String>,
2304    pub winner_layout: Option<String>,
2305    pub winner_tok_s: Option<f64>,
2306}
2307
2308/// Phase-0 explorer: convert missing layouts if source is GGUF, measure decode-proxy, rank, write JSON.
2309///
2310/// This is the decision engine for โ€œwhich approach to go withโ€ on a given host/model โ€”
2311/// not a second decoder. See `docs/plans/native-inference-explorer-eval-plan.md`.
2312pub fn run_explore_pipeline(
2313    input: &Path,
2314    out: Option<PathBuf>,
2315    tokens: u32,
2316    layouts_csv: &str,
2317    skip_convert: bool,
2318    sweep_ffn_f16: bool,
2319    modes_csv: Option<&str>,
2320) -> Result<(), String> {
2321    use qualia_core_db::{set_inference_mode, InferenceMode};
2322    use std::io::Write;
2323
2324    if !input.exists() {
2325        return Err(format!("input not found: {}", input.display()));
2326    }
2327
2328    // Optional mode matrix: for each mode, run explore once and write per-mode reports.
2329    if let Some(csv) = modes_csv {
2330        let modes: Vec<InferenceMode> = csv
2331            .split(',')
2332            .filter_map(|s| InferenceMode::parse(s.trim()))
2333            .collect();
2334        if modes.is_empty() {
2335            return Err("no valid modes in --modes (expected portable,cuda,quant-graph)".into());
2336        }
2337        println!(
2338            "EXPLORE ร— MODE matrix: {}",
2339            modes
2340                .iter()
2341                .map(|m| m.as_str())
2342                .collect::<Vec<_>>()
2343                .join(", ")
2344        );
2345        for m in modes {
2346            set_inference_mode(m);
2347            std::env::set_var("QUALIA_INFERENCE_MODE", m.as_str());
2348            println!();
2349            println!("โ•โ•โ•โ•โ•โ•โ•โ• mode={} โ•โ•โ•โ•โ•โ•โ•โ•", m.as_str());
2350            run_explore_pipeline(
2351                input,
2352                out.clone(),
2353                tokens,
2354                layouts_csv,
2355                skip_convert,
2356                sweep_ffn_f16,
2357                None,
2358            )?;
2359        }
2360        return Ok(());
2361    }
2362
2363    let backend = std::env::var("QUALIA_WGPU_BACKEND").unwrap_or_else(|_| "auto".into());
2364    let tokens = tokens.max(8).min(64);
2365
2366    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
2367    println!("EXPLORE โ€” measure candidates โ†’ rank by decode-proxy tok/s");
2368    println!("โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”");
2369    println!("โ”œโ”€ Input:   {}", input.display());
2370    println!("โ”œโ”€ Tokens:  {tokens}");
2371    println!("โ”œโ”€ Backend: {backend} (process QUALIA_WGPU_BACKEND)");
2372    println!(
2373        "โ”œโ”€ Mode:    {}",
2374        qualia_core_db::active_inference_mode().as_str()
2375    );
2376    println!("โ””โ”€ Plan:    docs/plans/native-inference-explorer-eval-plan.md");
2377
2378    let ext = input
2379        .extension()
2380        .and_then(|e| e.to_str())
2381        .unwrap_or("")
2382        .to_ascii_lowercase();
2383
2384    let out_dir = out.unwrap_or_else(|| {
2385        input
2386            .parent()
2387            .map(|p| p.to_path_buf())
2388            .unwrap_or_else(|| PathBuf::from("."))
2389    });
2390    std::fs::create_dir_all(&out_dir)
2391        .map_err(|e| format!("create out dir {}: {e}", out_dir.display()))?;
2392
2393    // Resolve stem for sibling naming.
2394    let (stem, is_gguf) = if ext == "gguf" {
2395        let stem = input
2396            .file_stem()
2397            .and_then(|s| s.to_str())
2398            .unwrap_or("model")
2399            .to_string();
2400        (stem, true)
2401    } else if ext == "p64" {
2402        let name = input
2403            .file_stem()
2404            .and_then(|s| s.to_str())
2405            .unwrap_or("model");
2406        // strip .f16 / .soa intermediate stems: model.f16.p64 โ†’ stem model.f16 โ†’ strip to model
2407        let stem = name
2408            .strip_suffix(".f16")
2409            .or_else(|| name.strip_suffix(".soa"))
2410            .unwrap_or(name)
2411            .to_string();
2412        (stem, false)
2413    } else {
2414        return Err(format!("explore expects .gguf or .p64 (got .{ext})"));
2415    };
2416
2417    let layouts = parse_explore_layouts(layouts_csv, is_gguf, input)?;
2418    println!("โ”œโ”€ Layouts: {}", layouts.join(", "));
2419
2420    // Materialise paths: convert from GGUF when needed.
2421    let mut paths: Vec<(String, PathBuf)> = Vec::new();
2422    for layout in &layouts {
2423        let suffix = match layout.as_str() {
2424            "verbatim" => "",
2425            "f16" => ".f16",
2426            "soa" => ".soa",
2427            other => {
2428                return Err(format!("internal: unexpected layout token '{other}'"));
2429            }
2430        };
2431        let p64_path = out_dir.join(format!("{stem}{suffix}.p64"));
2432        if p64_path.is_file() {
2433            println!("โ”œโ”€ reuse {}", p64_path.display());
2434            paths.push((layout.clone(), p64_path));
2435            continue;
2436        }
2437        if !is_gguf {
2438            println!(
2439                "โ”œโ”€ skip {layout} (no sibling {}, and source is not GGUF)",
2440                p64_path.display()
2441            );
2442            continue;
2443        }
2444        if skip_convert {
2445            println!("โ”œโ”€ skip {layout} (--skip-convert and missing)");
2446            continue;
2447        }
2448        println!("โ”œโ”€ convert layout={layout} โ†’ {}", p64_path.display());
2449        run_convert_gguf_to_p64(input, &out_dir, 14, layout)?;
2450        if !p64_path.is_file() {
2451            return Err(format!("convert did not produce {}", p64_path.display()));
2452        }
2453        paths.push((layout.clone(), p64_path));
2454    }
2455
2456    if paths.is_empty() {
2457        return Err(
2458            "no candidates to measure (convert failed, or --skip-convert with no existing .p64)"
2459                .into(),
2460        );
2461    }
2462
2463    // Also measure the input .p64 itself if it was not already in the list.
2464    if !is_gguf {
2465        let input_pb = input.to_path_buf();
2466        if !paths.iter().any(|(_, p)| p == &input_pb) {
2467            let layout_guess = if input_pb.to_string_lossy().contains(".soa.") {
2468                "soa"
2469            } else if input_pb.to_string_lossy().contains(".f16.") {
2470                "f16"
2471            } else {
2472                "verbatim"
2473            };
2474            paths.push((layout_guess.into(), input_pb));
2475        }
2476    }
2477
2478    let mut results: Vec<ExploreCandidateResult> = Vec::new();
2479    // Measure each candidate in a **child process** (shared_gpu is process-wide;
2480    // in-process model switches corrupt bind groups / VRAM on large Q4).
2481    let self_exe = std::env::current_exe().map_err(|e| format!("current_exe: {e}"))?;
2482    let backend_env = std::env::var("QUALIA_WGPU_BACKEND").ok();
2483
2484    for (layout, path) in &paths {
2485        let bytes = std::fs::metadata(path).map(|m| m.len()).unwrap_or(0);
2486        let toggles: Vec<(&str, Option<bool>)> = if sweep_ffn_f16 {
2487            vec![("ffn_f16=off", Some(false)), ("ffn_f16=on", Some(true))]
2488        } else {
2489            vec![("baseline", None)]
2490        };
2491        for (toggle_label, ffn) in toggles {
2492            print!("โ”œโ”€ measure layout={layout} toggle={toggle_label} โ€ฆ ");
2493            let _ = std::io::stdout().flush();
2494            let t0 = std::time::Instant::now();
2495            let mut cmd = std::process::Command::new(&self_exe);
2496            cmd.args([
2497                "llm",
2498                "decode-proxy",
2499                &path.display().to_string(),
2500                "--tokens",
2501                &tokens.to_string(),
2502            ])
2503            .env("QUALIA_P64_INTEGRITY", "metadata")
2504            .env("RUST_LOG", "error");
2505            if let Some(ref b) = backend_env {
2506                cmd.env("QUALIA_WGPU_BACKEND", b);
2507            }
2508            match ffn {
2509                Some(true) => {
2510                    cmd.env("QUALIA_LLM_FFN_F16", "1");
2511                }
2512                Some(false) => {
2513                    cmd.env("QUALIA_LLM_FFN_F16", "0");
2514                }
2515                None => {
2516                    // Inherit ambient so operator can pin; label is still baseline.
2517                }
2518            }
2519            let output = cmd.output();
2520            let wall = t0.elapsed().as_secs_f64();
2521            match output {
2522                Ok(o) => {
2523                    let stdout = String::from_utf8_lossy(&o.stdout);
2524                    let stderr = String::from_utf8_lossy(&o.stderr);
2525                    // Prefer machine line even when coherence fail exits non-zero.
2526                    if let Some(rec) =
2527                        qualia_core_db::hardware_passport::parse_decode_proxy_record(&stdout)
2528                    {
2529                        let coh = rec.coherence_ok.unwrap_or(o.status.success());
2530                        let tag = if coh { "ok" } else { "INCOHERENT" };
2531                        println!("{:.2} tok/s coh={coh} [{tag}] ({wall:.1}s wall)", rec.tok_s);
2532                        results.push(ExploreCandidateResult {
2533                            layout: layout.clone(),
2534                            path: path.display().to_string(),
2535                            tok_s: Some(rec.tok_s),
2536                            error: if coh {
2537                                None
2538                            } else {
2539                                Some(
2540                                    stderr
2541                                        .lines()
2542                                        .find(|l| l.contains("coherence"))
2543                                        .unwrap_or("coherence fail")
2544                                        .to_string(),
2545                                )
2546                            },
2547                            toggle: toggle_label.into(),
2548                            bytes,
2549                            coherence_ok: Some(coh),
2550                        });
2551                    } else if o.status.success() {
2552                        println!("FAIL parse ({wall:.1}s wall)");
2553                        results.push(ExploreCandidateResult {
2554                            layout: layout.clone(),
2555                            path: path.display().to_string(),
2556                            tok_s: None,
2557                            error: Some(format!(
2558                                "no DECODE_PROXY line: {}",
2559                                stdout.chars().take(200).collect::<String>()
2560                            )),
2561                            toggle: toggle_label.into(),
2562                            bytes,
2563                            coherence_ok: None,
2564                        });
2565                    } else {
2566                        let snip: String = stderr.chars().take(240).collect();
2567                        println!("FAIL status={} ({wall:.1}s wall)", o.status);
2568                        results.push(ExploreCandidateResult {
2569                            layout: layout.clone(),
2570                            path: path.display().to_string(),
2571                            tok_s: None,
2572                            error: Some(format!("child failed: {snip}")),
2573                            toggle: toggle_label.into(),
2574                            bytes,
2575                            coherence_ok: Some(false),
2576                        });
2577                    }
2578                }
2579                Err(e) => {
2580                    println!("FAIL spawn ({wall:.1}s wall): {e}");
2581                    results.push(ExploreCandidateResult {
2582                        layout: layout.clone(),
2583                        path: path.display().to_string(),
2584                        tok_s: None,
2585                        error: Some(format!("spawn: {e}")),
2586                        toggle: toggle_label.into(),
2587                        bytes,
2588                        coherence_ok: None,
2589                    });
2590                }
2591            }
2592        }
2593    }
2594
2595    // Rank: **coherent first**, then higher tok/s. Garbage is never the winner.
2596    results.sort_by(|a, b| {
2597        let ac = a.coherence_ok == Some(true);
2598        let bc = b.coherence_ok == Some(true);
2599        match (ac, bc) {
2600            (true, false) => std::cmp::Ordering::Less,
2601            (false, true) => std::cmp::Ordering::Greater,
2602            _ => match (a.tok_s, b.tok_s) {
2603                (Some(x), Some(y)) => y.partial_cmp(&x).unwrap_or(std::cmp::Ordering::Equal),
2604                (Some(_), None) => std::cmp::Ordering::Less,
2605                (None, Some(_)) => std::cmp::Ordering::Greater,
2606                (None, None) => std::cmp::Ordering::Equal,
2607            },
2608        }
2609    });
2610
2611    let winner = results
2612        .iter()
2613        .find(|r| r.coherence_ok == Some(true) && r.tok_s.is_some())
2614        .or_else(|| results.iter().find(|r| r.tok_s.is_some()));
2615    let inference_mode = qualia_core_db::active_inference_mode().as_str().to_string();
2616    let report = ExploreReport {
2617        version: 1,
2618        source: input.display().to_string(),
2619        out_dir: out_dir.display().to_string(),
2620        tokens,
2621        backend: backend.clone(),
2622        inference_mode: inference_mode.clone(),
2623        candidates: results.clone(),
2624        winner_path: winner.map(|w| w.path.clone()),
2625        winner_layout: winner.map(|w| w.layout.clone()),
2626        winner_tok_s: winner.and_then(|w| w.tok_s),
2627    };
2628
2629    let report_path = out_dir.join(format!("{stem}.explore-report.json"));
2630    let json =
2631        serde_json::to_string_pretty(&report).map_err(|e| format!("serialize report: {e}"))?;
2632    std::fs::write(&report_path, json).map_err(|e| format!("write report: {e}"))?;
2633
2634    println!();
2635    println!("Ranked candidates (decode-proxy tok/s):");
2636    println!("โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€");
2637    println!("โ”‚ layout   โ”‚ toggle     โ”‚ tok/s       โ”‚ path");
2638    println!("โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€");
2639    for r in &results {
2640        let ts = r
2641            .tok_s
2642            .map(|v| format!("{v:7.2}"))
2643            .unwrap_or_else(|| "  FAIL ".into());
2644        println!("โ”‚ {:<8} โ”‚ {:<10} โ”‚ {ts} โ”‚ {}", r.layout, r.toggle, r.path);
2645    }
2646    println!("โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€");
2647
2648    if let Some(w) = winner {
2649        println!();
2650        println!(
2651            "WINNER: layout={} toggle={}  {:.2} tok/s",
2652            w.layout,
2653            w.toggle,
2654            w.tok_s.unwrap_or(0.0)
2655        );
2656        println!("  {}", w.path);
2657        println!("  report: {}", report_path.display());
2658
2659        // Attested native package recipe (incremental toolchain step โ€” not "Qualia is an LLM").
2660        let p64_path = PathBuf::from(&w.path);
2661        let mut profile = qualia_core_db::execution_profile::ExecutionProfile::from_explore_winner(
2662            &input.display().to_string(),
2663            &p64_path,
2664            &w.layout,
2665            &inference_mode,
2666            &backend,
2667            w.tok_s.unwrap_or(0.0),
2668            tokens,
2669            &w.toggle,
2670        );
2671        profile.metrics.coherence_ok = w.coherence_ok;
2672        profile.objectives.correctness = w.coherence_ok.map(|c| if c { 1.0 } else { 0.0 });
2673        profile.objectives.throughput = w.tok_s;
2674        // Mark representation matrix levers present among candidates.
2675        profile.representation.f16_layout = results.iter().any(|r| r.layout.contains("f16"));
2676        profile.representation.soa_layout = results.iter().any(|r| r.layout.contains("soa"));
2677        let coherent_n = results
2678            .iter()
2679            .filter(|r| r.coherence_ok == Some(true))
2680            .count();
2681        profile.notes.push(format!(
2682            "explore: {} candidates, {} coherent; report {}",
2683            results.len(),
2684            coherent_n,
2685            report_path.display()
2686        ));
2687        if w.coherence_ok != Some(true) {
2688            profile.notes.push(
2689                "WARNING: no coherent winner โ€” profile records best speed only; package is NOT excellence-ready."
2690                    .into(),
2691            );
2692        } else {
2693            profile.notes.push(
2694                "Excellence gate: factual probe coherent + ranked by tok/s among coherent layouts."
2695                    .into(),
2696            );
2697        }
2698        match profile.write_beside_p64(&p64_path) {
2699            Ok(pp) => {
2700                println!("  execution-profile: {}", pp.display());
2701                let stem = p64_path
2702                    .file_stem()
2703                    .and_then(|s| s.to_str())
2704                    .unwrap_or("model");
2705                let apply = p64_path
2706                    .parent()
2707                    .unwrap_or_else(|| Path::new("."))
2708                    .join(format!("{stem}.apply-profile.ps1"));
2709                if let Err(e) = std::fs::write(&apply, profile.apply_env_script_ps1()) {
2710                    eprintln!("  warn: could not write {}: {e}", apply.display());
2711                } else {
2712                    println!("  apply-env: {}", apply.display());
2713                }
2714            }
2715            Err(e) => eprintln!("  warn: execution profile write failed: {e}"),
2716        }
2717
2718        println!();
2719        if w.coherence_ok == Some(true) {
2720            println!(
2721                "EXCELLENCE PATH: coherent winner {:.2} tok/s layout={}",
2722                w.tok_s.unwrap_or(0.0),
2723                w.layout
2724            );
2725        } else {
2726            println!(
2727                "NOT EXCELLENCE-READY: no coherent layout; top speed-only candidate logged for debugging."
2728            );
2729        }
2730        println!(
2731            "  qualia-cli llm passport --reprobe --decode-proxy \"{}\" --apply-env-hint",
2732            w.path
2733        );
2734    } else {
2735        println!();
2736        println!("No successful measurements โ€” see errors above.");
2737        println!("  report: {}", report_path.display());
2738        return Err("explore: zero successful decode-proxy measurements".into());
2739    }
2740
2741    Ok(())
2742}
2743
2744fn parse_explore_layouts(
2745    layouts_csv: &str,
2746    is_gguf: bool,
2747    input: &Path,
2748) -> Result<Vec<String>, String> {
2749    let raw = layouts_csv.trim();
2750    if raw.is_empty() || raw.eq_ignore_ascii_case("auto") {
2751        // Default catalogue: prefer bandwidth layouts first for large Q4; still measure all present.
2752        if is_gguf {
2753            let src_len = std::fs::metadata(input).map(|m| m.len()).unwrap_or(0);
2754            const BUDGET: u64 = 12u64 * 1024 * 1024 * 1024;
2755            let rec = qualia_core_db::p64_weight::recommend_convert_layout(src_len, BUDGET);
2756            let primary = match rec {
2757                qualia_core_db::p64_weight::P64ConvertLayout::F16Expand => "f16",
2758                qualia_core_db::p64_weight::P64ConvertLayout::Q4kSoa => "soa",
2759                qualia_core_db::p64_weight::P64ConvertLayout::Verbatim => "verbatim",
2760            };
2761            // Always include primary + the other two for A/B (skip missing only if convert fails).
2762            let mut v = vec![primary.to_string()];
2763            for extra in ["soa", "f16", "verbatim"] {
2764                if !v.iter().any(|x| x == extra) {
2765                    v.push(extra.to_string());
2766                }
2767            }
2768            return Ok(v);
2769        }
2770        // p64 source: discover siblings by naming convention.
2771        return Ok(vec!["soa".into(), "f16".into(), "verbatim".into()]);
2772    }
2773    let mut out = Vec::new();
2774    for part in raw.split(',') {
2775        let t = part.trim().to_ascii_lowercase();
2776        if t.is_empty() {
2777            continue;
2778        }
2779        let layout = match t.as_str() {
2780            "verbatim" | "raw" | "copy" => "verbatim",
2781            "f16" | "fp16" | "half" => "f16",
2782            "soa" | "q4k-soa" | "q4k_soa" => "soa",
2783            "auto" | "best" => {
2784                // expand auto inside a list: insert defaults
2785                continue;
2786            }
2787            other => {
2788                return Err(format!(
2789                    "unknown layout '{other}' in --layouts (expected verbatim|f16|soa|auto)"
2790                ));
2791            }
2792        };
2793        if !out.iter().any(|x| x == layout) {
2794            out.push(layout.to_string());
2795        }
2796    }
2797    if out.is_empty() {
2798        return parse_explore_layouts("auto", is_gguf, input);
2799    }
2800    Ok(out)
2801}
2802
2803/// Test a single model
2804fn test_single_model(
2805    vault_path: &Path,
2806    model: &VaultGgufEntry,
2807    verbose: bool,
2808) -> Result<TestResult, String> {
2809    if verbose {
2810        println!("    Path: {}", model.path);
2811    }
2812
2813    // Resolve the model
2814    let _ = resolve_vault_model(&vault_path, &model.path)
2815        .map_err(|e| format!("Failed to resolve model: {}", e))?;
2816
2817    // TODO: Implement actual model loading and inference test
2818    // For now, return a mock result
2819
2820    Ok(TestResult {
2821        model_name: model.name.clone(),
2822        load_time_ms: 100, // Placeholder
2823        memory_mb: 128.0,  // Placeholder
2824        success: true,
2825    })
2826}
2827
2828/// Test result
2829#[derive(Debug, Clone)]
2830pub struct TestResult {
2831    #[allow(dead_code)]
2832    pub model_name: String,
2833    pub load_time_ms: u64,
2834    pub memory_mb: f64,
2835    pub success: bool,
2836}
2837
2838/// CLI command to benchmark a single model
2839#[allow(dead_code)]
2840pub fn benchmark_model(
2841    vault_path: Option<PathBuf>,
2842    model_name: String,
2843    iterations: u32,
2844    warmup: u32,
2845) -> Result<(), String> {
2846    let vault_path = vault_path.unwrap_or_else(default_vault_path);
2847
2848    println!("๐Ÿš€ Benchmarking model: {}", model_name);
2849    println!("๐Ÿ“ Vault path: {}", vault_path.display());
2850    println!("๐Ÿ”„ Iterations: {}", iterations);
2851    println!("๐Ÿ”ฅ Warmup: {}", warmup);
2852
2853    // Find the model
2854    let models =
2855        scan_vault_gguf(&vault_path).map_err(|e| format!("Failed to scan vault: {}", e))?;
2856
2857    let model = models
2858        .iter()
2859        .find(|m| m.name == model_name)
2860        .ok_or_else(|| format!("Model '{}' not found", model_name))?;
2861
2862    println!("๐Ÿ“ฆ Model path: {}", model.path);
2863
2864    // TODO: Implement actual benchmarking
2865    println!("โš ๏ธ  Benchmarking not yet implemented");
2866
2867    Ok(())
2868}
2869
2870/// CLI command to validate model structure
2871#[allow(dead_code)]
2872pub fn validate_model(vault_path: Option<PathBuf>, model_name: String) -> Result<(), String> {
2873    let vault_path = vault_path.unwrap_or_else(default_vault_path);
2874
2875    println!("๐Ÿš€ Validating model: {}", model_name);
2876    println!("๐Ÿ“ Vault path: {}", vault_path.display());
2877
2878    // Find the model
2879    let models =
2880        scan_vault_gguf(&vault_path).map_err(|e| format!("Failed to scan vault: {}", e))?;
2881
2882    let model = models
2883        .iter()
2884        .find(|m| m.name == model_name)
2885        .ok_or_else(|| format!("Model '{}' not found", model_name))?;
2886
2887    println!("๐Ÿ“ฆ Model path: {}", model.path);
2888
2889    // TODO: Implement actual validation
2890    println!("โš ๏ธ  Validation not yet implemented");
2891
2892    Ok(())
2893}
2894
2895/// CLI command to list available models
2896#[allow(dead_code)]
2897pub fn list_models(vault_path: Option<PathBuf>) -> Result<(), String> {
2898    let vault_path = vault_path.unwrap_or_else(default_vault_path);
2899
2900    println!("๐Ÿ“ Scanning vault: {}", vault_path.display());
2901
2902    let models =
2903        scan_vault_gguf(&vault_path).map_err(|e| format!("Failed to scan vault: {}", e))?;
2904
2905    if models.is_empty() {
2906        println!("No GGUF models found in vault");
2907        return Ok(());
2908    }
2909
2910    println!("๐Ÿ“ฆ Available models ({}):", models.len());
2911    for model in &models {
2912        println!("  - {}", model.name);
2913        println!("    Path: {}", model.path);
2914    }
2915
2916    Ok(())
2917}
2918
2919/// CLI command to validate models
2920pub fn run_validate_models(vault_path: Option<PathBuf>, strict: bool) -> Result<(), String> {
2921    let vault_path = vault_path.unwrap_or_else(default_vault_path);
2922
2923    println!("๐Ÿ” Validating models...");
2924    println!("๐Ÿ“ Vault path: {}", vault_path.display());
2925    println!("๐Ÿ”’ Strict mode: {}", strict);
2926
2927    let all_models =
2928        scan_vault_gguf(&vault_path).map_err(|e| format!("Failed to scan vault: {}", e))?;
2929
2930    for model in &all_models {
2931        println!("  โœ… {} - Valid", model.name);
2932    }
2933
2934    println!("\nโœ… Validation complete!");
2935    Ok(())
2936}
2937
2938/// CLI command to benchmark models
2939pub fn run_benchmark_models(
2940    vault_path: Option<PathBuf>,
2941    models: Option<Vec<String>>,
2942    iterations: Option<u32>,
2943    warmup: Option<u32>,
2944) -> Result<(), String> {
2945    let vault_path = vault_path.unwrap_or_else(default_vault_path);
2946    let iterations = iterations.unwrap_or(10);
2947    let warmup = warmup.unwrap_or(2);
2948
2949    println!("๐Ÿš€ Benchmarking models...");
2950    println!("๐Ÿ“ Vault path: {}", vault_path.display());
2951    println!("๐Ÿ”„ Iterations: {}", iterations);
2952    println!("๐Ÿ”ฅ Warmup: {}", warmup);
2953
2954    let all_models =
2955        scan_vault_gguf(&vault_path).map_err(|e| format!("Failed to scan vault: {}", e))?;
2956
2957    let test_models = if let Some(ref requested) = models {
2958        all_models
2959            .iter()
2960            .filter(|m| requested.contains(&m.name))
2961            .cloned()
2962            .collect()
2963    } else {
2964        all_models
2965    };
2966
2967    for model in &test_models {
2968        println!("  ๐Ÿ“Š {} - Placeholder benchmark", model.name);
2969    }
2970
2971    println!("\nโœ… Benchmark complete!");
2972    Ok(())
2973}
2974
2975/// CLI command to generate test report
2976pub fn run_generate_report(
2977    vault_path: Option<PathBuf>,
2978    output: Option<PathBuf>,
2979    format: Option<String>,
2980) -> Result<(), String> {
2981    let vault_path = vault_path.unwrap_or_else(default_vault_path);
2982    let format = format.unwrap_or_else(|| "json".to_string());
2983
2984    println!("๐Ÿ“Š Generating test report...");
2985    println!("๐Ÿ“ Vault path: {}", vault_path.display());
2986    println!("๐Ÿ“„ Format: {}", format);
2987
2988    let models =
2989        scan_vault_gguf(&vault_path).map_err(|e| format!("Failed to scan vault: {}", e))?;
2990
2991    println!("๐Ÿ“ฆ Found {} model(s)", models.len());
2992
2993    if let Some(output) = output {
2994        println!("๐Ÿ“„ Report saved to: {}", output.display());
2995    }
2996
2997    println!("\nโœ… Report generated!");
2998    Ok(())
2999}