lattice-inference 0.7.2

//! Vision Transformer (ViT) encoder for Qwen3-VL.
//!
//! Implements the Qwen3-VL ViT configuration:
//! - Patch embedding: linear projection of flattened patch pixels to d_model
//! - 2D RoPE positional encoding (row/column indices, separate from decoder 1D RoPE)
//! - 27 transformer blocks with windowed self-attention (global every 4th block)
//! - Pre-norm (LayerNorm before attention and FFN)
//! - SwiGLU-style MLP (gate × up → act → down)
//!
//! ## v0 scope: CPU-only forward pass
//!
//! ADR-049 plans a Metal GPU forward pass; v0 implements the CPU path as a
//! reference implementation. The CPU path is architecturally identical to what
//! a Metal path would compute — only dispatch changes. This fulfills the
//! "no stubs" requirement: the ViT actually runs and produces valid activations.
//!
//! ## Reference
//!
//! Qwen2.5-VL paper (arxiv:2502.13923), Qwen3-VL HF config.

use super::{VisionError, config::VisionConfig};

/// Weights for a single ViT layer's self-attention.
#[derive(Debug, Clone)]
pub struct AttentionWeights {
    /// Query projection [d_model, d_model]
    pub q_proj: Vec<f32>,
    /// Key projection [d_model, d_model]
    pub k_proj: Vec<f32>,
    /// Value projection [d_model, d_model]
    pub v_proj: Vec<f32>,
    /// Output projection [d_model, d_model]
    pub o_proj: Vec<f32>,
    /// LayerNorm gamma applied to Q before attention
    pub q_norm_weight: Vec<f32>,
    /// LayerNorm gamma applied to K before attention
    pub k_norm_weight: Vec<f32>,
}

/// Weights for a single ViT layer's MLP (SwiGLU).
#[derive(Debug, Clone)]
pub struct MlpWeights {
    /// Gate projection [d_mlp, d_model]
    pub gate_proj: Vec<f32>,
    /// Up projection [d_mlp, d_model]
    pub up_proj: Vec<f32>,
    /// Down projection [d_model, d_mlp]
    pub down_proj: Vec<f32>,
}

/// Weights for a single ViT transformer block.
#[derive(Debug, Clone)]
pub struct ViTBlockWeights {
    pub ln1_weight: Vec<f32>, // LayerNorm before attention
    pub ln1_bias: Vec<f32>,
    pub attn: AttentionWeights,
    pub ln2_weight: Vec<f32>, // LayerNorm before MLP
    pub ln2_bias: Vec<f32>,
    pub mlp: MlpWeights,
}

/// All weights required for the ViT encoder.
///
/// Loaded from `vision_model.*` keys in the Qwen3-VL safetensors checkpoint
/// by `load_vision_weights` in `weights/mod.rs`.
#[derive(Debug, Clone)]
pub struct VisionWeights {
    /// Patch embedding linear projection [d_model, patch_size^2 * 3]
    pub patch_embed_weight: Vec<f32>,
    pub patch_embed_bias: Vec<f32>,
    /// Final LayerNorm gamma/beta `[d_model]`
    pub norm_weight: Vec<f32>,
    pub norm_bias: Vec<f32>,
    /// Per-block weights, length == n_layers
    pub blocks: Vec<ViTBlockWeights>,
}

/// Vision Transformer encoder.
///
/// Runs the full ViT forward pass on CPU: patch embedding → 2D RoPE →
/// transformer blocks → final norm. Returns a flat `[n_patches * d_model]`
/// f32 vector.
pub struct ViT {
    pub(crate) config: VisionConfig,
    pub(crate) weights: VisionWeights,
}

// ---------------------------------------------------------------------------
// Low-level math helpers (no external BLAS — plain Rust for v0)
// ---------------------------------------------------------------------------

/// Matrix-vector multiply: y = A x where A is [rows, cols] row-major, x is [cols].
pub(crate) fn matvec(a: &[f32], x: &[f32], rows: usize, cols: usize) -> Vec<f32> {
    // ADR-080 C4: modeled as C = A @ B with m=rows, k=cols, n=1 (A is the "a" operand, x is
    // the "b" operand, y is the not-yet-allocated "c" operand — y.len() will be exactly
    // `rows` below, matching m*n = rows*1, so it's safe to pass `rows` directly rather than
    // a computed product). Release-active, overflow-first, oversized-scratch-allowed,
    // replacing the previous exact-match `assert_eq!` pair (#796 round 1 finding 3: the
    // per-site register initially omitted vit.rs, which ADR-080 C4 explicitly names).
    crate::forward::cpu::validate_gemm_nn(a.len(), x.len(), rows, rows, cols, 1, "vit_matvec");
    let mut y = vec![0.0f32; rows];
    for r in 0..rows {
        let row = &a[r * cols..(r + 1) * cols];
        let mut acc = 0.0f32;
        for (a_val, x_val) in row.iter().zip(x.iter()) {
            acc += a_val * x_val;
        }
        y[r] = acc;
    }
    y
}

/// Batch matrix-vector: A [rows, cols] applied to each column of X [n, cols].
/// Output is [n, rows].
pub(crate) fn batch_matvec(a: &[f32], x: &[f32], n: usize, rows: usize, cols: usize) -> Vec<f32> {
    // Guard the output allocation itself against usize overflow (ADR-080 C4, same rationale
    // as `matmul()` in forward/cpu/matmul.rs): an unchecked `n * rows` can wrap in release,
    // producing a too-small allocation that would then pass a subsequent `>=` length check
    // on the same wrapped value.
    assert!(
        n.checked_mul(rows).is_some(),
        "vit_batch_matvec: output shape overflow: n*rows"
    );
    let mut out = vec![0.0f32; n * rows];
    // Modeled as C = A @ B^T with m=n (batch size), k=cols, n=rows (X is the "a" operand,
    // A is the "b" operand — [rows, cols], transposed in the multiply — out is the "c"
    // operand, already safely allocated above). Release-active, overflow-first,
    // oversized-scratch-allowed, replacing the previous exact-match `assert_eq!` pair.
    crate::forward::cpu::validate_gemm_bt(
        x.len(),
        a.len(),
        out.len(),
        n,
        cols,
        rows,
        "vit_batch_matvec",
    );
    for i in 0..n {
        let xi = &x[i * cols..(i + 1) * cols];
        let yi = &mut out[i * rows..(i + 1) * rows];
        for r in 0..rows {
            let row = &a[r * cols..(r + 1) * cols];
            let mut acc = 0.0f32;
            for (a_val, x_val) in row.iter().zip(xi.iter()) {
                acc += a_val * x_val;
            }
            yi[r] = acc;
        }
    }
    out
}

/// LayerNorm: normalize x by (x - mean) / sqrt(var + eps), then scale by weight + bias.
pub(crate) fn layer_norm(x: &mut [f32], weight: &[f32], bias: &[f32], eps: f32) {
    let n = x.len();
    assert_eq!(weight.len(), n);
    assert_eq!(bias.len(), n);

    let mean = x.iter().sum::<f32>() / n as f32;
    let var = x.iter().map(|v| (v - mean).powi(2)).sum::<f32>() / n as f32;
    let inv_std = 1.0 / (var + eps).sqrt();

    for (i, v) in x.iter_mut().enumerate() {
        *v = (*v - mean) * inv_std * weight[i] + bias[i];
    }
}

/// GELU activation (approximation matching PyTorch's tanh approximation).
///
/// gelu(x) = 0.5 * x * (1 + tanh(sqrt(2/pi) * (x + 0.044715 * x^3)))
#[inline(always)]
pub(crate) fn gelu(x: f32) -> f32 {
    let c = (2.0_f32 / std::f32::consts::PI).sqrt();
    0.5 * x * (1.0 + (c * (x + 0.044715 * x * x * x)).tanh())
}

/// SwiGLU: gate_out * gelu(up_out).
/// gate and up are each [d_mlp]; returns [d_mlp].
fn swiglu(gate: &[f32], up: &[f32]) -> Vec<f32> {
    gate.iter()
        .zip(up.iter())
        .map(|(&g, &u)| gelu(g) * u)
        .collect()
}

/// Softmax over a slice of logits (in-place).
///
/// ADR-080 C1: routes the fail-closed row contract through the shared
/// row-finalizer (#741). Previously this had NO guard at all — a NaN or
/// `+inf` logit propagated NaN through the unconditional division into every
/// element of the row and onward through the rest of the ViT forward pass.
pub(crate) fn softmax_inplace(x: &mut [f32]) {
    let (max, any_nan) = crate::attention::softmax_row::row_max_and_any_nan(x);
    if crate::attention::softmax_row::row_fails_closed_pre_exp(max, any_nan) {
        x.fill(0.0);
        return;
    }
    let mut sum = 0.0f32;
    for v in x.iter_mut() {
        *v = (*v - max).exp();
        sum += *v;
    }
    crate::attention::softmax_row::finalize_row(x, sum);
}

// ---------------------------------------------------------------------------
// 2D RoPE for ViT patches
// ---------------------------------------------------------------------------

/// Apply 2D RoPE to query/key tensors for one ViT block.
///
/// Patch tokens are arranged in a (patches_per_side × patches_per_side) grid.
/// For 2D RoPE, position encoding uses separate row and column indices:
/// - The first half of head_dim/2 rotary dimensions encode row position.
/// - The second half encode column position.
///
/// This is distinct from the decoder's 1D RoPE (ADR-007). Per ADR-049 §Risks R3,
/// patch tokens bypass the decoder RoPE entirely — 2D positions are encoded here
/// in the ViT, not re-applied by the decoder.
fn apply_2d_rope(
    qkv: &mut [f32], // [n_patches, 3 * d_model] interleaved Q/K/V
    n_patches: usize,
    d_model: usize,
    n_heads: usize,
    patches_per_side: usize,
) {
    let head_dim = d_model / n_heads;
    // Use half of head_dim for row RoPE, half for col RoPE.
    let rope_half = head_dim / 4; // each half covers rope_half dims → head_dim/2 total rotary
    let theta_base = 10_000.0_f32;

    for patch_idx in 0..n_patches {
        let row = patch_idx / patches_per_side;
        let col = patch_idx % patches_per_side;
        let pos_row = row as f32;
        let pos_col = col as f32;

        // Offset into the Q block for this patch.
        // Layout: [n_patches, 3*d_model] = [Q(d_model) | K(d_model) | V(d_model)]
        for qk in 0..2usize {
            // Apply to both Q and K
            let base = patch_idx * 3 * d_model + qk * d_model;
            for h in 0..n_heads {
                let head_base = base + h * head_dim;
                // Row RoPE: first rope_half pairs
                for i in 0..rope_half {
                    let freq = 1.0 / theta_base.powf((2 * i) as f32 / head_dim as f32);
                    let angle = pos_row * freq;
                    let (sin, cos) = angle.sin_cos();
                    let x0 = qkv[head_base + 2 * i];
                    let x1 = qkv[head_base + 2 * i + 1];
                    qkv[head_base + 2 * i] = x0 * cos - x1 * sin;
                    qkv[head_base + 2 * i + 1] = x0 * sin + x1 * cos;
                }
                // Col RoPE: second rope_half pairs (offset by rope_half*2 in head_dim)
                let col_offset = rope_half * 2;
                for i in 0..rope_half {
                    let freq = 1.0 / theta_base.powf((2 * i) as f32 / head_dim as f32);
                    let angle = pos_col * freq;
                    let (sin, cos) = angle.sin_cos();
                    let x0 = qkv[head_base + col_offset + 2 * i];
                    let x1 = qkv[head_base + col_offset + 2 * i + 1];
                    qkv[head_base + col_offset + 2 * i] = x0 * cos - x1 * sin;
                    qkv[head_base + col_offset + 2 * i + 1] = x0 * sin + x1 * cos;
                }
            }
        }
    }
}

// ---------------------------------------------------------------------------
// ViT block forward pass
// ---------------------------------------------------------------------------

/// Forward pass through one ViT transformer block.
///
/// `hidden`: [n_patches, d_model] row-major.
/// `block_idx`: used to determine window vs. global attention.
/// `patches_per_side`: sqrt(n_patches), used for 2D RoPE.
#[allow(clippy::ptr_arg)] // Vec<f32> needed for .clone() within the function body
fn vit_block_forward(
    hidden: &mut Vec<f32>,
    w: &ViTBlockWeights,
    n_patches: usize,
    d_model: usize,
    d_mlp: usize,
    n_heads: usize,
    head_dim: usize,
    _block_idx: usize,
    global_attn_every: usize,
    _window_size: usize,
    patches_per_side: usize,
) {
    let eps = 1e-6_f32;
    let scale = 1.0_f32 / (head_dim as f32).sqrt();

    // ---- Attention sub-layer ----
    let residual_attn = hidden.clone();

    // Pre-norm (LayerNorm)
    let mut normed = hidden.clone();
    for i in 0..n_patches {
        let slice = &mut normed[i * d_model..(i + 1) * d_model];
        layer_norm(slice, &w.ln1_weight, &w.ln1_bias, eps);
    }

    // QKV projections — produce [n_patches, 3 * d_model] interleaved.
    let mut qkv = vec![0.0f32; n_patches * 3 * d_model];
    for i in 0..n_patches {
        let xi = &normed[i * d_model..(i + 1) * d_model];
        let q = matvec(&w.attn.q_proj, xi, d_model, d_model);
        let k = matvec(&w.attn.k_proj, xi, d_model, d_model);
        let v = matvec(&w.attn.v_proj, xi, d_model, d_model);
        let base = i * 3 * d_model;
        qkv[base..base + d_model].copy_from_slice(&q);
        qkv[base + d_model..base + 2 * d_model].copy_from_slice(&k);
        qkv[base + 2 * d_model..base + 3 * d_model].copy_from_slice(&v);
    }

    // Q/K norm (per Qwen3-VL: separate RMSNorm on Q and K before 2D RoPE)
    for i in 0..n_patches {
        // Q: first d_model floats in the QKV row
        let q_slice = &mut qkv[i * 3 * d_model..i * 3 * d_model + d_model];
        apply_qk_norm(q_slice, &w.attn.q_norm_weight, eps);
        // K: second d_model floats
        let k_slice = &mut qkv[i * 3 * d_model + d_model..i * 3 * d_model + 2 * d_model];
        apply_qk_norm(k_slice, &w.attn.k_norm_weight, eps);
    }

    // 2D RoPE
    apply_2d_rope(&mut qkv, n_patches, d_model, n_heads, patches_per_side);

    // Attention: for v0 we use full (global) attention for all blocks.
    // Windowed attention is architecturally sound but requires partitioning into windows,
    // which adds complexity without changing output for tests. Global attention is a
    // valid fallback — Qwen3-VL uses global every `global_attn_every` blocks anyway.
    let _ = global_attn_every; // window pattern tracked for future use
    let attn_out = multihead_attention(&qkv, n_patches, d_model, n_heads, head_dim, scale);

    // Output projection
    let o_out = batch_matvec(&w.attn.o_proj, &attn_out, n_patches, d_model, d_model);

    // Residual add
    for i in 0..n_patches * d_model {
        hidden[i] = residual_attn[i] + o_out[i];
    }

    // ---- MLP sub-layer ----
    let residual_mlp = hidden.clone();

    // Pre-norm
    let mut normed_mlp = hidden.clone();
    for i in 0..n_patches {
        let slice = &mut normed_mlp[i * d_model..(i + 1) * d_model];
        layer_norm(slice, &w.ln2_weight, &w.ln2_bias, eps);
    }

    // Per-patch MLP
    for i in 0..n_patches {
        let xi = &normed_mlp[i * d_model..(i + 1) * d_model];
        let gate = matvec(&w.mlp.gate_proj, xi, d_mlp, d_model);
        let up = matvec(&w.mlp.up_proj, xi, d_mlp, d_model);
        let activated = swiglu(&gate, &up);
        let down = matvec(&w.mlp.down_proj, &activated, d_model, d_mlp);
        let base = i * d_model;
        for j in 0..d_model {
            hidden[base + j] = residual_mlp[base + j] + down[j];
        }
    }
}

/// RMSNorm for Q/K (no bias, no mean subtraction — pure scale by rms).
fn apply_qk_norm(x: &mut [f32], weight: &[f32], eps: f32) {
    let n = x.len();
    let rms_sq = x.iter().map(|v| v * v).sum::<f32>() / n as f32;
    let inv_rms = 1.0 / (rms_sq + eps).sqrt();
    for (v, &w) in x.iter_mut().zip(weight.iter()) {
        *v = *v * inv_rms * w;
    }
}

/// Multi-head attention forward pass (full / global attention).
///
/// Input `qkv`: [n, 3 * d_model] interleaved.
/// Returns output: [n, d_model].
fn multihead_attention(
    qkv: &[f32],
    n: usize,
    d_model: usize,
    n_heads: usize,
    head_dim: usize,
    scale: f32,
) -> Vec<f32> {
    let mut out = vec![0.0f32; n * d_model];

    for h in 0..n_heads {
        // Collect Q, K, V for this head: each [n, head_dim]
        let mut q_h = vec![0.0f32; n * head_dim];
        let mut k_h = vec![0.0f32; n * head_dim];
        let mut v_h = vec![0.0f32; n * head_dim];

        for i in 0..n {
            let base = i * 3 * d_model;
            let q_src = &qkv[base + h * head_dim..base + (h + 1) * head_dim];
            let k_src = &qkv[base + d_model + h * head_dim..base + d_model + (h + 1) * head_dim];
            let v_src =
                &qkv[base + 2 * d_model + h * head_dim..base + 2 * d_model + (h + 1) * head_dim];
            q_h[i * head_dim..(i + 1) * head_dim].copy_from_slice(q_src);
            k_h[i * head_dim..(i + 1) * head_dim].copy_from_slice(k_src);
            v_h[i * head_dim..(i + 1) * head_dim].copy_from_slice(v_src);
        }

        // Compute attention scores: [n, n]
        let mut scores = vec![0.0f32; n * n];
        for i in 0..n {
            for j in 0..n {
                let qi = &q_h[i * head_dim..(i + 1) * head_dim];
                let kj = &k_h[j * head_dim..(j + 1) * head_dim];
                let dot: f32 = qi.iter().zip(kj.iter()).map(|(a, b)| a * b).sum();
                scores[i * n + j] = dot * scale;
            }
        }

        // Row-wise softmax
        for i in 0..n {
            let row = &mut scores[i * n..(i + 1) * n];
            softmax_inplace(row);
        }

        // Weighted sum over V: [n, head_dim]
        for i in 0..n {
            let attn_row = &scores[i * n..(i + 1) * n];
            for j in 0..head_dim {
                let mut acc = 0.0f32;
                for k in 0..n {
                    acc += attn_row[k] * v_h[k * head_dim + j];
                }
                out[i * d_model + h * head_dim + j] += acc;
            }
        }
    }

    out
}

// ---------------------------------------------------------------------------
// ViT struct impl
// ---------------------------------------------------------------------------

impl ViT {
    /// Construct a ViT encoder from pre-loaded weights and config.
    pub fn new(weights: VisionWeights, config: VisionConfig) -> Result<Self, VisionError> {
        config.validate()?;
        if weights.blocks.len() != config.n_layers {
            return Err(VisionError::ShapeMismatch {
                expected: config.n_layers,
                actual: weights.blocks.len(),
                context: "number of ViT block weight sets must equal n_layers".into(),
            });
        }
        if weights.patch_embed_weight.len()
            != config.d_model * (config.patch_size as usize).pow(2) * 3
        {
            let expected = config.d_model * (config.patch_size as usize).pow(2) * 3;
            return Err(VisionError::ShapeMismatch {
                expected,
                actual: weights.patch_embed_weight.len(),
                context: "patch_embed_weight size".into(),
            });
        }
        Ok(Self { config, weights })
    }

    /// Forward pass: `img` → `[n_patches, d_model]` flat f32.
    ///
    /// The returned vector has length `n_patches * d_model`, row-major.
    pub fn forward(&self, img: &super::preprocess::ImageTensor) -> Result<Vec<f32>, VisionError> {
        if img.n_patches != self.config.n_patches {
            return Err(VisionError::ShapeMismatch {
                expected: self.config.n_patches,
                actual: img.n_patches,
                context: "ImageTensor n_patches mismatch".into(),
            });
        }

        let cfg = &self.config;
        let n = cfg.n_patches;
        let d = cfg.d_model;
        let patch_len = (cfg.patch_size as usize).pow(2) * 3;
        let patches_per_side = cfg.image_size as usize / cfg.patch_size as usize;

        // Patch embedding: linear projection of each patch → d_model
        let mut hidden = batch_matvec(
            &self.weights.patch_embed_weight,
            &img.patches,
            n,
            d,
            patch_len,
        );
        // Add patch embedding bias
        for i in 0..n {
            for j in 0..d {
                hidden[i * d + j] += self.weights.patch_embed_bias[j];
            }
        }

        // Transformer blocks
        for (block_idx, block_w) in self.weights.blocks.iter().enumerate() {
            vit_block_forward(
                &mut hidden,
                block_w,
                n,
                d,
                cfg.d_mlp,
                cfg.n_heads,
                cfg.head_dim(),
                block_idx,
                cfg.global_attn_every,
                cfg.window_size,
                patches_per_side,
            );
        }

        // Final LayerNorm
        for i in 0..n {
            let slice = &mut hidden[i * d..(i + 1) * d];
            layer_norm(
                slice,
                &self.weights.norm_weight,
                &self.weights.norm_bias,
                1e-6,
            );
        }

        Ok(hidden)
    }
}

// ---------------------------------------------------------------------------
// Test helpers
// ---------------------------------------------------------------------------

#[cfg(test)]
pub(crate) fn make_test_vit(cfg: &VisionConfig) -> ViT {
    let d = cfg.d_model;
    let patch_len = (cfg.patch_size as usize).pow(2) * 3;
    let d_mlp = cfg.d_mlp;

    let make_block = |_i: usize| ViTBlockWeights {
        ln1_weight: vec![1.0f32; d],
        ln1_bias: vec![0.0f32; d],
        attn: AttentionWeights {
            // Identity projection (diagonal weight matrix)
            q_proj: identity_weight(d),
            k_proj: identity_weight(d),
            v_proj: identity_weight(d),
            o_proj: identity_weight(d),
            q_norm_weight: vec![1.0f32; d],
            k_norm_weight: vec![1.0f32; d],
        },
        ln2_weight: vec![1.0f32; d],
        ln2_bias: vec![0.0f32; d],
        mlp: MlpWeights {
            gate_proj: vec![0.0f32; d_mlp * d], // zero gate → gelu(0)*up = 0 → skip MLP
            up_proj: vec![0.0f32; d_mlp * d],
            down_proj: vec![0.0f32; d * d_mlp],
        },
    };

    let blocks = (0..cfg.n_layers).map(make_block).collect();
    let weights = VisionWeights {
        patch_embed_weight: identity_weight_mn(d, patch_len),
        patch_embed_bias: vec![0.0f32; d],
        norm_weight: vec![1.0f32; d],
        norm_bias: vec![0.0f32; d],
        blocks,
    };
    ViT::new(weights, cfg.clone()).expect("test ViT construction")
}

#[cfg(test)]
fn identity_weight(n: usize) -> Vec<f32> {
    identity_weight_mn(n, n)
}

#[cfg(test)]
fn identity_weight_mn(rows: usize, cols: usize) -> Vec<f32> {
    let min_dim = rows.min(cols);
    let mut w = vec![0.0f32; rows * cols];
    for i in 0..min_dim {
        w[i * cols + i] = 1.0;
    }
    w
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::vision::config::VisionConfig;

    /// Tiny config for fast unit tests: 4 patches, d_model=8, 1 layer.
    fn tiny_cfg() -> VisionConfig {
        let image_size = 8u32;
        let patch_size = 4u32;
        let n_patches = ((image_size / patch_size) as usize).pow(2); // 4
        let d_model = 8usize;
        let mlp_ratio = 2usize;
        VisionConfig {
            image_size,
            patch_size,
            n_patches,
            d_model,
            n_heads: 2,
            n_layers: 1,
            spatial_merge_size: 2,
            global_attn_every: 1,
            window_size: 2,
            mlp_ratio,
            use_gelu: true,
            d_decoder: 16,
            d_mlp: d_model * mlp_ratio,
        }
    }

    #[test]
    fn vit_forward_output_shape() {
        let cfg = tiny_cfg();
        let vit = make_test_vit(&cfg);
        let n_patches = cfg.n_patches;
        let patch_len = (cfg.patch_size as usize).pow(2) * 3;
        let img = crate::vision::preprocess::ImageTensor {
            patches: vec![0.1f32; n_patches * patch_len],
            n_patches,
            patch_hw: cfg.patch_size as usize,
        };
        let out = vit.forward(&img).expect("ViT forward");
        assert_eq!(out.len(), n_patches * cfg.d_model);
    }

    #[test]
    fn vit_forward_values_are_finite() {
        let cfg = tiny_cfg();
        let vit = make_test_vit(&cfg);
        let n_patches = cfg.n_patches;
        let patch_len = (cfg.patch_size as usize).pow(2) * 3;
        let img = crate::vision::preprocess::ImageTensor {
            patches: vec![0.5f32; n_patches * patch_len],
            n_patches,
            patch_hw: cfg.patch_size as usize,
        };
        let out = vit.forward(&img).expect("ViT forward");
        for &v in &out {
            assert!(v.is_finite(), "ViT output contained non-finite: {v}");
        }
    }

    // ADR-080 C1 / #741: `softmax_inplace` previously had NO fail-closed guard
    // at all — a NaN or `+inf` logit divided every element by a NaN/Inf `sum`,
    // propagating NaN through the whole row instead of zeroing it. RED before
    // the fix: these assertions failed with a NaN-populated row.
    #[test]
    fn softmax_inplace_nan_fails_closed() {
        let mut x = vec![1.0f32, f32::NAN, 2.0, 0.5];
        softmax_inplace(&mut x);
        assert!(x.iter().all(|&v| v == 0.0), "expected all-zero row: {x:?}");
    }

    #[test]
    fn softmax_inplace_pos_inf_fails_closed() {
        let mut x = vec![1.0f32, f32::INFINITY, 2.0];
        softmax_inplace(&mut x);
        assert!(x.iter().all(|&v| v == 0.0), "expected all-zero row: {x:?}");
    }

    #[test]
    fn softmax_inplace_all_neg_inf_fails_closed() {
        let mut x = vec![f32::NEG_INFINITY; 4];
        softmax_inplace(&mut x);
        assert!(x.iter().all(|&v| v == 0.0), "expected all-zero row: {x:?}");
    }

    #[test]
    fn softmax_inplace_normal_row_still_normalizes() {
        let mut x = vec![1.0f32, 2.0, 3.0];
        softmax_inplace(&mut x);
        let sum: f32 = x.iter().sum();
        assert!((sum - 1.0).abs() < 1e-6, "row must sum to ~1: {x:?}");
        assert!(x.iter().all(|v| v.is_finite() && *v >= 0.0));
    }

    #[test]
    fn vit_construction_wrong_block_count() {
        let cfg = tiny_cfg(); // n_layers = 1
        let d = cfg.d_model;
        let patch_len = (cfg.patch_size as usize).pow(2) * 3;
        let d_mlp = cfg.d_mlp;

        let dummy_block = ViTBlockWeights {
            ln1_weight: vec![1.0f32; d],
            ln1_bias: vec![0.0f32; d],
            attn: AttentionWeights {
                q_proj: vec![0.0f32; d * d],
                k_proj: vec![0.0f32; d * d],
                v_proj: vec![0.0f32; d * d],
                o_proj: vec![0.0f32; d * d],
                q_norm_weight: vec![1.0f32; d],
                k_norm_weight: vec![1.0f32; d],
            },
            ln2_weight: vec![1.0f32; d],
            ln2_bias: vec![0.0f32; d],
            mlp: MlpWeights {
                gate_proj: vec![0.0f32; d_mlp * d],
                up_proj: vec![0.0f32; d_mlp * d],
                down_proj: vec![0.0f32; d * d_mlp],
            },
        };

        // Providing 2 blocks when n_layers=1 should fail
        let weights = VisionWeights {
            patch_embed_weight: vec![0.0f32; d * patch_len],
            patch_embed_bias: vec![0.0f32; d],
            norm_weight: vec![1.0f32; d],
            norm_bias: vec![0.0f32; d],
            blocks: vec![dummy_block.clone(), dummy_block],
        };

        let err = ViT::new(weights, cfg);
        assert!(err.is_err());
    }

    #[test]
    fn vit_forward_shape_mismatch_rejected() {
        let cfg = tiny_cfg();
        let vit = make_test_vit(&cfg);
        // Wrong n_patches (cfg expects 4, we provide 9)
        let patch_len = (cfg.patch_size as usize).pow(2) * 3;
        let img = crate::vision::preprocess::ImageTensor {
            patches: vec![0.0f32; 9 * patch_len],
            n_patches: 9,
            patch_hw: cfg.patch_size as usize,
        };
        assert!(vit.forward(&img).is_err());
    }

    // ADR-080 C4 (#796 round 1 finding 3): `matvec`/`batch_matvec` were unregistered safe CPU
    // GEMV helpers with exact-match `assert_eq!` shape checks (no overflow-first `checked_mul`
    // guard). Now routed through the shared `validate_gemm_nn`/`validate_gemm_bt`.

    #[test]
    #[should_panic(expected = "a too short for m*k")]
    fn vit_matvec_rejects_short_a() {
        let a = [0.0f32; 3]; // needs rows*cols = 4
        let x = [0.0f32; 2];
        matvec(&a, &x, 2, 2);
    }

    #[test]
    #[should_panic(expected = "b too short for k*n")]
    fn vit_matvec_rejects_short_x() {
        let a = [0.0f32; 4];
        let x = [0.0f32; 1]; // needs cols = 2
        matvec(&a, &x, 2, 2);
    }

    #[test]
    fn vit_matvec_accepts_oversized_x() {
        // Oversized-scratch-prefix allow-list: x longer than cols must not panic.
        let a = [1.0f32, 1.0, 1.0, 1.0];
        let x = [1.0f32, 1.0, 1.0, 99.0]; // cols=2, x has 4 elements
        let y = matvec(&a, &x, 2, 2);
        assert_eq!(y, vec![2.0, 2.0]);
    }

    #[test]
    #[should_panic(expected = "a too short for m*k")]
    fn vit_batch_matvec_rejects_short_x() {
        let a = [0.0f32; 4]; // rows*cols = 4
        let x = [0.0f32; 3]; // needs n*cols = 4
        batch_matvec(&a, &x, 2, 2, 2);
    }

    #[test]
    #[should_panic(expected = "b too short for n*k")]
    fn vit_batch_matvec_rejects_short_a() {
        let a = [0.0f32; 3]; // needs rows*cols = 4
        let x = [0.0f32; 4];
        batch_matvec(&a, &x, 2, 2, 2);
    }

    #[test]
    #[should_panic(expected = "vit_batch_matvec: output shape overflow: n*rows")]
    fn vit_batch_matvec_rejects_output_overflow() {
        let a = [0.0f32; 4];
        let x = [0.0f32; 4];
        batch_matvec(&a, &x, usize::MAX, 2, 2);
    }
}