Skip to main content

qualia_cli/
qwen_testing.rs

1//! Developer/debug Qwen4Exp numerical probes and explicitly selected developer decode.
2//! Diagnostic probe commands use NativeDecodeRequest::Developer; product generation uses --authority.
3
4use std::path::Path;
5
6/// Execute a fully connected trained recurrent/MoE layer. The explicit bounded
7/// scratch belongs to the CLI decode owner; core hot operators receive only
8/// caller-owned slices.
9pub fn run_probe_qwen4exp_gdn_moe_layer(
10    package: &Path,
11    layer_id: u32,
12    token_id: u32,
13) -> Result<(), String> {
14    const HIDDEN: usize = 2_560;
15    const WIDE: usize = HIDDEN * 4;
16    const HEADS: usize = 48;
17    const HEAD_DIM: usize = 128;
18    const INNER: usize = HEADS * HEAD_DIM;
19    const QKV: usize = 10_240;
20    const RANK: usize = 320;
21    const EXPERTS: usize = 512;
22    const INTERMEDIATE: usize = 640;
23    const RAW: usize = 65_536;
24    let mut runtime = qualia_core_db::inference::qwen::Qwen4ExpNativeRuntime::activate(package)
25        .map_err(|error| error.to_string())?;
26    let embedding = *runtime
27        .index
28        .token_embd_info()
29        .ok_or_else(|| "Qwen4Exp source has no token embedding tensor".to_string())?;
30    if embedding.dims[0] as usize != HIDDEN || token_id as u64 >= embedding.dims[1] {
31        return Err("Qwen4Exp token embedding does not match the layer contract".to_string());
32    }
33    let layer = runtime.index.get_layer_tensors(layer_id);
34    if !layer.is_hybrid_ssm_layer() {
35        return Err(format!(
36            "layer {layer_id} is not a Qwen4Exp GatedDeltaNet layer"
37        ));
38    }
39    let mut embedding_raw = [0u8; RAW];
40    let mut embedding_values = [0.0f32; HIDDEN];
41    runtime
42        .trunk
43        .read_row_into(
44            &embedding,
45            token_id as usize,
46            &mut embedding_raw,
47            &mut embedding_values,
48        )
49        .map_err(|error| format!("read token embedding: {error}"))?;
50    let mut residual = vec![0.0f32; WIDE];
51    for stream in 0..4 {
52        residual[stream * HIDDEN..(stream + 1) * HIDDEN].copy_from_slice(&embedding_values);
53    }
54    let mut attn_raw = [0u8; RAW];
55    let mut ffn_raw = [0u8; RAW];
56    let mut gdn_raw = [0u8; RAW];
57    let mut moe_raw = [0u8; RAW];
58    let mut attn_projection = vec![0.0f32; WIDE];
59    let mut ffn_projection = vec![0.0f32; WIDE];
60    let mut attn_norm = vec![0.0f32; WIDE];
61    let mut ffn_norm = vec![0.0f32; WIDE];
62    let mut attn_normalized = vec![0.0f32; WIDE];
63    let mut ffn_normalized = vec![0.0f32; WIDE];
64    let mut attn_low_rank = vec![0.0f32; RANK];
65    let mut ffn_low_rank = vec![0.0f32; RANK];
66    let mut attn_gates = vec![0.0f32; WIDE];
67    let mut ffn_gates = vec![0.0f32; WIDE];
68    let mut convolution = vec![0.0f32; QKV * 3];
69    let mut delta = vec![0.0f32; HEADS * HEAD_DIM * HEAD_DIM];
70    let mut gdn_projection = vec![0.0f32; INNER];
71    let mut qkv = vec![0.0f32; QKV];
72    let mut gate = vec![0.0f32; INNER];
73    let mut alpha = [0.0f32; HEADS];
74    let mut beta = [0.0f32; HEADS];
75    let mut convolved = vec![0.0f32; QKV];
76    let mut head_norm = [0.0f32; HEAD_DIM];
77    let mut head_vector = [0.0f32; HEAD_DIM];
78    let mut output_inner = vec![0.0f32; INNER];
79    let mut head_a = [0.0f32; HEADS];
80    let mut dt_bias = [0.0f32; HEADS];
81    let mut moe_dequantized = vec![0.0f32; HIDDEN];
82    let mut router_logits = vec![0.0f32; EXPERTS];
83    let mut top_indices = [0usize; 10];
84    let mut top_logits = [0.0f32; 10];
85    let mut top_weights = [0.0f32; 10];
86    let mut moe_gate = vec![0.0f32; INTERMEDIATE];
87    let mut moe_up = vec![0.0f32; INTERMEDIATE];
88    let mut activation = vec![0.0f32; INTERMEDIATE];
89    let mut expert_out = vec![0.0f32; HIDDEN];
90    let mut attn_mixed = [0.0f32; HIDDEN];
91    let mut gdn_branch = [0.0f32; HIDDEN];
92    let mut ffn_mixed = [0.0f32; HIDDEN];
93    let mut moe_branch = [0.0f32; HIDDEN];
94    let mut attn_inject = [0.0f32; 4];
95    let mut ffn_inject = [0.0f32; 4];
96    let mut state = qualia_core_db::inference::qwen::GatedDeltaState {
97        convolution: &mut convolution,
98        delta: &mut delta,
99    };
100    let mut buffers = qualia_core_db::inference::qwen::StreamedGdnMoeLayerBuffers {
101        attn_hyper: qualia_core_db::inference::qwen::StreamedHyperBuffers {
102            raw_row: &mut attn_raw,
103            projection_row: &mut attn_projection,
104            norm_weight: &mut attn_norm,
105            normalized: &mut attn_normalized,
106            low_rank: &mut attn_low_rank,
107            gates: &mut attn_gates,
108        },
109        ffn_hyper: qualia_core_db::inference::qwen::StreamedHyperBuffers {
110            raw_row: &mut ffn_raw,
111            projection_row: &mut ffn_projection,
112            norm_weight: &mut ffn_norm,
113            normalized: &mut ffn_normalized,
114            low_rank: &mut ffn_low_rank,
115            gates: &mut ffn_gates,
116        },
117        gdn: qualia_core_db::inference::qwen::GatedDeltaBuffers {
118            raw_row: &mut gdn_raw,
119            projection_row: &mut gdn_projection,
120            qkv: &mut qkv,
121            gate: &mut gate,
122            alpha: &mut alpha,
123            beta: &mut beta,
124            convolved: &mut convolved,
125            head_norm: &mut head_norm,
126            head_vector: &mut head_vector,
127            output_inner: &mut output_inner,
128            head_a: &mut head_a,
129            dt_bias: &mut dt_bias,
130        },
131        moe: qualia_core_db::inference::qwen::StreamedMoeBuffers {
132            raw_row: &mut moe_raw,
133            dequantized_row: &mut moe_dequantized,
134            router_logits: &mut router_logits,
135            top_indices: &mut top_indices,
136            top_logits: &mut top_logits,
137            top_weights: &mut top_weights,
138            gate: &mut moe_gate,
139            up: &mut moe_up,
140            activation: &mut activation,
141            expert_out: &mut expert_out,
142        },
143        attn_mixed: &mut attn_mixed,
144        token_mixer_branch: &mut gdn_branch,
145        ffn_mixed: &mut ffn_mixed,
146        moe_branch: &mut moe_branch,
147        attn_inject: &mut attn_inject,
148        ffn_inject: &mut ffn_inject,
149    };
150    let start = std::time::Instant::now();
151    qualia_core_db::inference::qwen::execute_streamed_gdn_moe_layer(
152        &mut runtime.trunk,
153        &layer,
154        &mut residual,
155        &mut state,
156        &mut buffers,
157    )
158    .map_err(|error| format!("execute trained Qwen4Exp layer: {error}"))?;
159    let elapsed = start.elapsed();
160    let mut fingerprint = 0xcbf2_9ce4_8422_2325u64;
161    for value in residual.iter().chain(delta.iter().step_by(257)) {
162        fingerprint ^= value.to_bits() as u64;
163        fingerprint = fingerprint.wrapping_mul(0x1000_0000_01b3);
164    }
165    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
166    println!("Qwen4Exp complete trained recurrent/MoE layer");
167    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
168    println!("├─ layer {layer_id}, token {token_id}: Hyper → GDN → Hyper → top-10 MoE");
169    println!("├─ complete layer time: {:.3}s", elapsed.as_secs_f64());
170    println!("└─ residual/state fingerprint={fingerprint:016x}");
171    Ok(())
172}
173
174/// Execute the real QSA projection, four-cell indexer and sparse causal GQA
175/// path at position zero.  It is deliberately a component probe: its cache is
176/// local to this call and no text/token-rate claim is made from it.
177pub fn run_probe_qwen4exp_qsa(package: &Path, layer_id: u32, token_id: u32) -> Result<(), String> {
178    const HIDDEN: usize = 2_560;
179    const QUERY: usize = 6_144;
180    const KV: usize = 512;
181    const INDEX_QUERY: usize = 512;
182    const INDEX_KEY: usize = 128;
183    const CACHE: usize = 16;
184    const RAW: usize = 65_536;
185    let mut runtime = qualia_core_db::inference::qwen::Qwen4ExpNativeRuntime::activate(package)
186        .map_err(|error| error.to_string())?;
187    let embedding = *runtime
188        .index
189        .token_embd_info()
190        .ok_or_else(|| "Qwen4Exp source has no token embedding tensor".to_string())?;
191    if embedding.dims[0] as usize != HIDDEN || token_id as u64 >= embedding.dims[1] {
192        return Err("Qwen4Exp token embedding does not match the QSA contract".to_string());
193    }
194    let layer = runtime.index.get_layer_tensors(layer_id);
195    if !layer.has_qwen_sparse_attention() {
196        return Err(format!(
197            "layer {layer_id} is not a complete Qwen4Exp QSA layer"
198        ));
199    }
200    let mut embedding_raw = [0u8; RAW];
201    let mut input = [0.0f32; HIDDEN];
202    runtime
203        .trunk
204        .read_row_into(
205            &embedding,
206            token_id as usize,
207            &mut embedding_raw,
208            &mut input,
209        )
210        .map_err(|error| format!("read token embedding: {error}"))?;
211    let mut keys = vec![0.0f32; CACHE * KV];
212    let mut values = vec![0.0f32; CACHE * KV];
213    let mut indexer_keys = vec![0.0f32; CACHE * INDEX_KEY];
214    let mut raw = [0u8; RAW];
215    let mut projection = vec![0.0f32; QUERY];
216    let mut q_full = vec![0.0f32; QUERY * 2];
217    let mut key = [0.0f32; KV];
218    let mut value = [0.0f32; KV];
219    let mut index_query = [0.0f32; INDEX_QUERY];
220    let mut index_key = [0.0f32; INDEX_KEY];
221    let mut q_norm = [0.0f32; 256];
222    let mut k_norm = [0.0f32; 256];
223    let mut index_q_norm = [0.0f32; INDEX_KEY];
224    let mut index_k_norm = [0.0f32; INDEX_KEY];
225    let mut selected = [0usize; CACHE];
226    let mut scores = [0.0f32; CACHE];
227    let mut block_selected = [0usize; CACHE];
228    let mut block_scores = [0.0f32; CACHE];
229    let mut attention = [0.0f32; QUERY];
230    let mut out = [0.0f32; HIDDEN];
231    let mut state = qualia_core_db::inference::qwen::QsaState {
232        keys: &mut keys,
233        values: &mut values,
234        indexer_keys: &mut indexer_keys,
235        tokens: 0,
236    };
237    let mut buffers = qualia_core_db::inference::qwen::StreamedQsaBuffers {
238        raw_row: &mut raw,
239        projection_row: &mut projection,
240        q_full: &mut q_full,
241        key: &mut key,
242        value: &mut value,
243        index_query: &mut index_query,
244        index_key: &mut index_key,
245        q_norm: &mut q_norm,
246        k_norm: &mut k_norm,
247        index_q_norm: &mut index_q_norm,
248        index_k_norm: &mut index_k_norm,
249        selected: &mut selected,
250        scores: &mut scores,
251        block_selected: &mut block_selected,
252        block_scores: &mut block_scores,
253        attention: &mut attention,
254    };
255    let start = std::time::Instant::now();
256    qualia_core_db::inference::qwen::execute_streamed_qsa(
257        &mut runtime.trunk,
258        &layer,
259        &input,
260        &mut state,
261        runtime.index.hyperparams.effective_rope_freq_base(),
262        &mut out,
263        &mut buffers,
264    )
265    .map_err(|error| format!("execute trained Qwen4Exp QSA: {error}"))?;
266    let elapsed = start.elapsed();
267    let mut fingerprint = 0xcbf2_9ce4_8422_2325u64;
268    for value in out.iter().chain(keys.iter().take(KV)) {
269        fingerprint ^= value.to_bits() as u64;
270        fingerprint = fingerprint.wrapping_mul(0x1000_0000_01b3);
271    }
272    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
273    println!("Qwen4Exp trained sparse-attention token mixer");
274    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
275    println!("├─ layer {layer_id}, token {token_id}: raw index key → four-cell QSA → GQA");
276    println!("├─ QSA component time: {:.3}s", elapsed.as_secs_f64());
277    println!("└─ branch/cache fingerprint={fingerprint:016x}");
278    Ok(())
279}
280
281/// Real multi-token Qwen4Exp generation: prompt → token embedding → PLE →
282/// all 48 trained layers (HC → GDN|QSA → HC → MoE) → final HC mixer →
283/// streamed `output.weight` argmax → native tokenizer decode.  Every step
284/// streams rows from the C: PLE payload and E: trunk; no model residency.
285#[allow(clippy::too_many_arguments)]
286pub fn run_decode_qwen4exp(
287    package: &Path,
288    prompt: Option<&str>,
289    token_ids: &[u32],
290    max_tokens: usize,
291    context: usize,
292    chat: bool,
293    trunk_mmap: bool,
294) -> Result<(), String> {
295    use qualia_core_db::inference::qwen::{
296        decode_tokens, Qwen4ExpDecodeReceipt, Qwen4ExpDecodeScratch, Qwen4ExpSession,
297        Qwen4ExpTrunkResidency,
298    };
299
300    let residency = if trunk_mmap {
301        Qwen4ExpTrunkResidency::Mapped
302    } else {
303        Qwen4ExpTrunkResidency::Streamed
304    };
305    let mut runtime =
306        qualia_core_db::inference::qwen::Qwen4ExpNativeRuntime::activate_with_residency(
307            package, residency,
308        )
309        .map_err(|error| error.to_string())?;
310
311    // The tokenizer lives in the bounded GGUF header prefix (KV section
312    // ends before the tensor index); read exactly that many bytes.
313    let source = runtime
314        .descriptor
315        .source_beside(package)
316        .map_err(|error| error.to_string())?;
317    let header_len = runtime.index.tensor_data_start as usize;
318    let mut header = vec![0u8; header_len];
319    {
320        use std::io::Read;
321        let mut file = std::fs::File::open(&source)
322            .map_err(|error| format!("open source GGUF for tokenizer: {error}"))?;
323        file.read_exact(&mut header)
324            .map_err(|error| format!("read GGUF header for tokenizer: {error}"))?;
325    }
326    let tokenizer = qualia_core_db::gguf_sharder::GgufTokenizer::from_gguf(&header);
327
328    let prompt_tokens: Vec<u32> = if !token_ids.is_empty() {
329        token_ids.to_vec()
330    } else if let Some(text) = prompt {
331        if chat {
332            tokenizer.encode_chat_prompt(text)
333        } else {
334            tokenizer.encode_prompt(text)
335        }
336    } else {
337        return Err("decode-qwen4exp needs --prompt or --token-ids".to_string());
338    };
339    if prompt_tokens.is_empty() {
340        return Err("prompt produced no tokens".to_string());
341    }
342    if prompt_tokens.len() + max_tokens > context {
343        return Err(format!(
344            "prompt ({} tokens) + max_tokens ({max_tokens}) exceeds QSA cache capacity {context}",
345            prompt_tokens.len()
346        ));
347    }
348
349    let hidden = runtime.index.emb_dim();
350    let mut session =
351        Qwen4ExpSession::new(&runtime.index, context).map_err(|error| error.to_string())?;
352    let mut scratch = Qwen4ExpDecodeScratch::new(hidden);
353    let stops: Vec<u32> = tokenizer.stop_tokens().to_vec();
354    let mut receipt = Qwen4ExpDecodeReceipt::default();
355    let mut trace = Vec::new();
356    decode_tokens(
357        qualia_core_db::inference::inference_agent::NativeDecodeRequest::Developer,
358        &mut runtime,
359        &mut session,
360        &mut scratch,
361        &prompt_tokens,
362        max_tokens,
363        &|id| stops.contains(&id),
364        &mut receipt,
365        &mut trace,
366    )
367    .map_err(|error| format!("Qwen4Exp decode: {error}"))?;
368
369    let generated = receipt.generated_tokens.len();
370    let text = tokenizer.decode(&receipt.generated_tokens);
371    let secs = receipt.elapsed.as_secs_f64();
372    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
373    println!("Qwen4Exp native multi-token decode (real execution)");
374    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
375    println!("├─ execution mode: Developer (explicit --developer)");
376    println!("├─ prompt tokens: {}", receipt.prompt_tokens);
377    println!(
378        "├─ generated tokens: {generated}  ids={:?}",
379        receipt.generated_tokens
380    );
381    println!("├─ decoded text: {text}");
382    println!(
383        "├─ elapsed: {secs:.3}s  ({:.3} tokens/s generated)",
384        generated as f64 / secs.max(1e-9)
385    );
386    println!(
387        "├─ trunk {}: {} reads, {} rows, {:.2} MiB",
388        if trunk_mmap { "access (mmap)" } else { "I/O" },
389        receipt.trunk_reads,
390        receipt.trunk_rows,
391        receipt.trunk_bytes as f64 / (1024.0 * 1024.0)
392    );
393    println!(
394        "├─ PLE I/O: {} reads, {} rows, {:.2} MiB",
395        receipt.ple_reads,
396        receipt.ple_rows,
397        receipt.ple_bytes as f64 / (1024.0 * 1024.0)
398    );
399    println!(
400        "└─ resident state: {:.2} MiB persistent + {:.2} MiB scratch",
401        receipt.state_bytes as f64 / (1024.0 * 1024.0),
402        receipt.scratch_bytes as f64 / (1024.0 * 1024.0)
403    );
404    Ok(())
405}
406
407/// Lab instrument: trace one real token step end-to-end.  Every earlier
408/// prompt token runs through the full graph first so the traced step sees
409/// the same recurrent/cache state generation would; the traced step then
410/// reports a per-layer fingerprint/RMS/abs-max table plus the top-k
411/// vocabulary logits — this localizes which stage corrupts the forward
412/// signal instead of asserting aggregate correctness.
413pub fn run_probe_qwen4exp_trace(
414    package: &Path,
415    prompt: Option<&str>,
416    token_ids: &[u32],
417    chat: bool,
418    context: usize,
419    topk: usize,
420    rank_tokens: &[u32],
421    dump: Option<&Path>,
422) -> Result<(), String> {
423    use qualia_core_db::inference::qwen::{
424        decode_step, Qwen4ExpDecodeScratch, Qwen4ExpSession, StreamedArgmax,
425        QWEN4EXP_TRACE_META_LAYER,
426    };
427
428    let mut runtime = qualia_core_db::inference::qwen::Qwen4ExpNativeRuntime::activate(package)
429        .map_err(|error| error.to_string())?;
430    let source = runtime
431        .descriptor
432        .source_beside(package)
433        .map_err(|error| error.to_string())?;
434    let header_len = runtime.index.tensor_data_start as usize;
435    let mut header = vec![0u8; header_len];
436    {
437        use std::io::Read;
438        let mut file = std::fs::File::open(&source)
439            .map_err(|error| format!("open source GGUF for tokenizer: {error}"))?;
440        file.read_exact(&mut header)
441            .map_err(|error| format!("read GGUF header for tokenizer: {error}"))?;
442    }
443    let tokenizer = qualia_core_db::gguf_sharder::GgufTokenizer::from_gguf(&header);
444
445    let prompt_tokens: Vec<u32> = if !token_ids.is_empty() {
446        token_ids.to_vec()
447    } else if let Some(text) = prompt {
448        if chat {
449            tokenizer.encode_chat_prompt(text)
450        } else {
451            tokenizer.encode_prompt(text)
452        }
453    } else {
454        return Err("probe-qwen4exp-trace needs --prompt or --token-ids".to_string());
455    };
456    if prompt_tokens.is_empty() {
457        return Err("prompt produced no tokens".to_string());
458    }
459    if prompt_tokens.len() > context {
460        return Err(format!(
461            "prompt ({} tokens) exceeds QSA cache capacity {context}",
462            prompt_tokens.len()
463        ));
464    }
465
466    let hidden = runtime.index.emb_dim();
467    let mut session =
468        Qwen4ExpSession::new(&runtime.index, context).map_err(|error| error.to_string())?;
469    let mut scratch = Qwen4ExpDecodeScratch::new(hidden);
470
471    let start = std::time::Instant::now();
472    let (&traced_token, prefix) = prompt_tokens.split_last().unwrap();
473    for &token in prefix {
474        decode_step(
475            qualia_core_db::inference::inference_agent::NativeDecodeRequest::Developer,
476            &mut runtime,
477            &mut session,
478            &mut scratch,
479            token,
480            &mut Vec::new(),
481            false,
482        )
483        .map_err(|error| format!("prefix decode: {error}"))?;
484    }
485    let mut trace = Vec::new();
486    let winner = decode_step(
487        qualia_core_db::inference::inference_agent::NativeDecodeRequest::Developer,
488        &mut runtime,
489        &mut session,
490        &mut scratch,
491        traced_token,
492        &mut trace,
493        dump.is_some(),
494    )
495    .map_err(|error| format!("traced decode: {error}"))?;
496
497    let logits = *runtime
498        .index
499        .logits_projection_info()
500        .ok_or("missing output.weight tensor")?;
501    let mut top = vec![
502        StreamedArgmax {
503            token_id: 0,
504            logit: f32::NEG_INFINITY,
505        };
506        topk.max(1)
507    ];
508    let mut raw = vec![0u8; 65_536];
509    let mut row = vec![0f32; hidden];
510    runtime
511        .trunk
512        .topk_rows(&logits, scratch.final_mixed(), &mut raw, &mut row, &mut top)
513        .map_err(|error| format!("top-k projection: {error}"))?;
514    let mut ranks = vec![(0.0f32, 0u64); rank_tokens.len()];
515    if !rank_tokens.is_empty() {
516        runtime
517            .trunk
518            .logits_and_ranks(
519                &logits,
520                scratch.final_mixed(),
521                rank_tokens,
522                &mut raw,
523                &mut row,
524                &mut ranks,
525            )
526            .map_err(|error| format!("rank projection: {error}"))?;
527    }
528
529    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
530    println!("Qwen4Exp per-stage trace (one real token step)");
531    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
532    println!(
533        "├─ prompt tokens: {}  traced token: {traced_token}",
534        prompt_tokens.len()
535    );
536    println!("├─ prompt ids: {:?}", prompt_tokens);
537    println!("├─ step wall time: {:.3}s", start.elapsed().as_secs_f64());
538    println!("├─ layer  stage           fingerprint          rms        abs_max");
539    for record in &trace {
540        let layer = if record.layer == QWEN4EXP_TRACE_META_LAYER {
541            " -- ".to_string()
542        } else {
543            format!("{:4}", record.layer)
544        };
545        println!(
546            "│  {}  {:<14} {:016x}  {:<10.4} {:<10.4}",
547            layer, record.stage, record.fingerprint, record.rms, record.abs_max
548        );
549    }
550    println!(
551        "├─ argmax: id={} logit={:.4}",
552        winner.token_id, winner.logit
553    );
554    for (rank, entry) in top.iter().enumerate() {
555        let text = tokenizer.decode(&[entry.token_id]);
556        println!(
557            "│  top{rank}: id={} logit={:.4} text={text:?}",
558            entry.token_id, entry.logit
559        );
560    }
561    for (index, (&token, &(logit, rank))) in rank_tokens.iter().zip(ranks.iter()).enumerate() {
562        let text = tokenizer.decode(&[token]);
563        println!("│  probe{index}: id={token} logit={logit:.4} rank={rank} text={text:?}");
564    }
565    if let Some(path) = dump {
566        // Stage dump: u32 layer, u32 stage-name len, name bytes, u32 value
567        // count, then little-endian f32 values.  Numpy parses it directly for
568        // per-stage comparison against a reference forward pass.
569        use std::io::Write;
570        let mut file = std::fs::File::create(path)
571            .map_err(|error| format!("create dump {}: {error}", path.display()))?;
572        for record in &trace {
573            file.write_all(&record.layer.to_le_bytes())
574                .and_then(|()| file.write_all(&(record.stage.len() as u32).to_le_bytes()))
575                .and_then(|()| file.write_all(record.stage.as_bytes()))
576                .and_then(|()| file.write_all(&(record.values.len() as u32).to_le_bytes()))
577                .and_then(|()| {
578                    for value in &record.values {
579                        file.write_all(&value.to_le_bytes())?;
580                    }
581                    Ok(())
582                })
583                .map_err(|error| format!("write dump {}: {error}", path.display()))?;
584        }
585        println!(
586            "├─ dumped {} stage vectors to {}",
587            trace.len(),
588            path.display()
589        );
590    }
591    println!("└─ done");
592    Ok(())
593}