fuel-transformers 0.20.0

// SPDX-License-Identifier: MIT OR Apache-2.0
//! Qwen3-VL text language model ported to the lazy-graph API.
//!
//! Qwen3-VL extends the Qwen3 decoder (see [`crate::models::lazy_qwen3`]) with
//! two VL-specific changes:
//!
//! 1. **MROPE** (multi-axis RoPE): three independent rotary position
//!    streams `(t, h, w)` are interleaved along `head_dim`. The
//!    `mrope_section = [t_dim, h_dim, w_dim]` slice (summing to
//!    `head_dim/2`) is doubled into six repeated sections
//!    `[t, h, w, t, h, w]` (summing to `head_dim`) so that the standard
//!    rotate-half RoPE op consumes the combined `[seq, head_dim]` cos/sin
//!    tables unchanged. Section `i` draws its position from axis
//!    `i % 3` (temporal / height / width).
//! 2. **Per-token MROPE positions** instead of a scalar `start_pos`:
//!    `forward_embeds_with_mrope_positions(embeds, &positions)` takes
//!    a slice of `(t, h, w)` triples, one per sequence position. Vision
//!    tokens carry the patch's `(h, w)` grid coordinate; text tokens
//!    repeat the same scalar in all three axes.
//!
//! Everything else — per-head QK-norm, GQA, SwiGLU, optional Q/K/V/O
//! biases, sliding-window gate — is inherited from the Qwen3 shape and
//! re-implemented here without disturbing [`crate::models::lazy_qwen3`].

use fuel_ir::Shape;
use fuel_ir::error::Result;
use fuel_tensor::Device;
use fuel_tensor::{lazy::LayerWeights, lazy::Tensor, lazy::WeightStorage};
use std::sync::Arc;

/// Per-token MROPE position tuple: `(temporal, height, width)`.
pub type MropePos = [u32; 3];

/// Qwen3-VL text-side configuration. Mirrors [`crate::models::lazy_qwen3::Qwen3Config`]
/// with one addition: `mrope_section` controls the per-axis dimension
/// split for the multi-axis rotary table.
#[derive(Debug, Clone, PartialEq)]
pub struct Qwen3VlTextConfig {
    pub vocab_size: usize,
    pub hidden_size: usize,
    pub intermediate_size: usize,
    pub num_hidden_layers: usize,
    pub num_attention_heads: usize,
    pub num_key_value_heads: usize,
    pub head_dim: usize,
    pub max_position_embeddings: usize,
    pub sliding_window: Option<usize>,
    pub max_window_layers: usize,
    pub use_sliding_window: bool,
    pub rope_theta: f64,
    pub rms_norm_eps: f64,
    pub attention_bias: bool,
    pub tie_word_embeddings: bool,
    /// Per-axis section sizes `[t_dim, h_dim, w_dim]`. Must sum to
    /// `head_dim / 2`. The repeated layout `[t, h, w, t, h, w]` covers
    /// the full `head_dim` so that the standard rotate-half RoPE rule
    /// (`x[j+half]` paired with `x[j]`) lands on a section with the
    /// same axis owner and the same `freq_idx = j % (head_dim / 2)`.
    pub mrope_section: [usize; 3],
}

// ROADMAP item 8 (II): config-from-path — the DEEP nested-artifact case. Qwen3-VL's
// text stack lives ENTIRELY under a `text_config` sub-object of the multimodal
// config.json (with a `vision_config` sibling to ignore), and `mrope_section` is
// nested again under `text_config.rope_scaling`. So the raw's TOP LEVEL is just
// `text_config`, and `resolve` builds the flat config from the inner object,
// lifting mrope_section from its nested rope_scaling. kv + head_dim route through
// `fuel_loaders::hf_config` (Qwen3-VL ships an explicit, decoupled head_dim, e.g.
// 128 vs 2560/32=80).
#[derive(Debug, Clone, serde::Deserialize)]
struct Qwen3VlRopeScalingRaw {
    mrope_section: [usize; 3],
}

#[derive(Debug, Clone, serde::Deserialize)]
struct Qwen3VlTextInnerRaw {
    vocab_size: usize,
    hidden_size: usize,
    intermediate_size: usize,
    num_hidden_layers: usize,
    num_attention_heads: usize,
    #[serde(default)]
    num_key_value_heads: Option<usize>,
    #[serde(default)]
    head_dim: Option<usize>,
    max_position_embeddings: usize,
    #[serde(default)]
    sliding_window: Option<usize>,
    #[serde(default)]
    max_window_layers: Option<usize>,
    #[serde(default)]
    use_sliding_window: bool,
    #[serde(default = "default_qwen3_vl_rope_theta")]
    rope_theta: f64,
    #[serde(default = "default_qwen3_vl_rms_norm_eps")]
    rms_norm_eps: f64,
    #[serde(default)]
    attention_bias: bool,
    #[serde(default)]
    tie_word_embeddings: bool,
    rope_scaling: Qwen3VlRopeScalingRaw,
}

/// The multimodal config.json wrapper: the text stack is under `text_config`.
#[derive(Debug, Clone, serde::Deserialize)]
struct Qwen3VlTextConfigRaw {
    text_config: Qwen3VlTextInnerRaw,
}

fn default_qwen3_vl_rope_theta() -> f64 {
    5_000_000.0
}
fn default_qwen3_vl_rms_norm_eps() -> f64 {
    1e-6
}

impl Qwen3VlTextConfigRaw {
    fn from_json_str(json: &str) -> fuel_ir::error::Result<Self> {
        serde_json::from_str(json)
            .map_err(|e| fuel_ir::error::Error::Msg(format!("parsing Qwen3-VL config.json: {e}")))
    }

    fn resolve(self) -> Result<Qwen3VlTextConfig> {
        let t = self.text_config;
        Ok(Qwen3VlTextConfig {
            vocab_size: t.vocab_size,
            hidden_size: t.hidden_size,
            intermediate_size: t.intermediate_size,
            num_hidden_layers: t.num_hidden_layers,
            num_attention_heads: t.num_attention_heads,
            num_key_value_heads: fuel_loaders::hf_config::num_key_value_heads(
                t.num_key_value_heads,
                t.num_attention_heads,
            )?,
            head_dim: fuel_loaders::hf_config::head_dim(
                t.head_dim,
                t.hidden_size,
                t.num_attention_heads,
            )?,
            max_position_embeddings: t.max_position_embeddings,
            sliding_window: t.sliding_window,
            max_window_layers: t.max_window_layers.unwrap_or(t.num_hidden_layers),
            use_sliding_window: t.use_sliding_window,
            rope_theta: t.rope_theta,
            rms_norm_eps: t.rms_norm_eps,
            attention_bias: t.attention_bias,
            tie_word_embeddings: t.tie_word_embeddings,
            // Lifted from the nested `text_config.rope_scaling`.
            mrope_section: t.rope_scaling.mrope_section,
        })
    }
}

impl Qwen3VlTextConfig {
    /// Parse a HuggingFace Qwen3-VL `config.json` string into a
    /// [`Qwen3VlTextConfig`], reading the nested `text_config` sub-object.
    ///
    /// ROADMAP item 8 (II), nested-artifact extension — see the born-red
    /// `qwen3_vl_text_config_from_hf_json_parses_the_nested_text_config`.
    pub fn from_hf_json_str(json: &str) -> fuel_ir::error::Result<Self> {
        Qwen3VlTextConfigRaw::from_json_str(json)?.resolve()
    }
}

#[derive(Debug, Clone)]
pub struct Qwen3VlTextLayerExtras {
    /// `[head_dim]` — per-head RmsNorm gain for Q.
    pub q_norm_gain: Arc<[f32]>,
    /// `[head_dim]` — per-head RmsNorm gain for K.
    pub k_norm_gain: Arc<[f32]>,
}

#[derive(Debug, Clone)]
pub struct Qwen3VlTextWeights {
    pub token_embedding: Arc<[f32]>,
    pub layers: Vec<LayerWeights>,
    pub layer_extras: Vec<Qwen3VlTextLayerExtras>,
    pub final_norm_gain: Arc<[f32]>,
    pub output: WeightStorage,
}

#[derive(Debug, Clone)]
pub struct Qwen3VlTextModel {
    pub config: Qwen3VlTextConfig,
    pub weights: Qwen3VlTextWeights,
}

impl Qwen3VlTextModel {
    /// Run the LM end-to-end from token ids. `mrope_positions` carries
    /// one `(t, h, w)` triple per token; for pure-text inputs all three
    /// axes share the same scalar position (so MROPE collapses to
    /// 1D RoPE).
    pub fn forward(&self, tokens: &[u32], mrope_positions: &[MropePos]) -> Result<Tensor> {
        let h_norm = self.run_backbone(tokens, mrope_positions)?;
        self.apply_lm_head(&h_norm)
    }

    /// Pre-embedded entry point. `embeds` shape `(1, seq, hidden_size)`,
    /// `mrope_positions.len() == seq`. Used by the Qwen3-VL composition
    /// after image tokens have been substituted into the text embedding
    /// stream.
    pub fn forward_embeds(&self, embeds: &Tensor, mrope_positions: &[MropePos]) -> Result<Tensor> {
        let h_norm = self.run_backbone_embeds(embeds, mrope_positions)?;
        self.apply_lm_head(&h_norm)
    }

    /// Hidden-state variant of [`Self::forward_embeds`]. Returns the
    /// post-final-RmsNorm states `(1, seq, hidden_size)` for downstream
    /// hosts that do not want the `lm_head` projection.
    pub fn forward_hidden_embeds(
        &self,
        embeds: &Tensor,
        mrope_positions: &[MropePos],
    ) -> Result<Tensor> {
        self.run_backbone_embeds_with_deepstack(embeds, mrope_positions, &[])
    }

    /// Deepstack-aware forward. `deepstack_per_layer[i]` (if `Some`) is
    /// added into the post-layer hidden states after decoder layer `i`,
    /// matching the eager Qwen3-VL injection convention where vision
    /// residuals captured at vision layers `deepstack_visual_indexes[i]`
    /// flow into the text-side hidden stream at text layer `i`. The
    /// residual must be shaped `(1, seq, hidden_size)` and already
    /// positioned so non-visual rows are zero. The slice length may be
    /// shorter than the number of layers; remaining layers receive no
    /// injection (mirrors `if i < deepstack.len()` in eager).
    pub fn forward_embeds_with_deepstack(
        &self,
        embeds: &Tensor,
        mrope_positions: &[MropePos],
        deepstack_per_layer: &[Option<Tensor>],
    ) -> Result<Tensor> {
        let h_norm =
            self.run_backbone_embeds_with_deepstack(embeds, mrope_positions, deepstack_per_layer)?;
        self.apply_lm_head(&h_norm)
    }

    /// Token-embedding lookup anchored on `anchor`'s graph. Lets the
    /// composition host concatenate vision features with the resulting
    /// text embeddings before calling [`Self::forward_embeds`].
    pub fn embed_tokens_anchored(&self, anchor: &Tensor, tokens: &[u32]) -> Result<Tensor> {
        let cfg = &self.config;
        anchor.embed_tokens_anchored(
            self.weights.token_embedding.clone(),
            cfg.vocab_size,
            cfg.hidden_size,
            tokens,
        )
    }

    fn apply_lm_head(&self, h_norm: &Tensor) -> Result<Tensor> {
        let cfg = &self.config;
        self.weights
            .output
            .apply_linear(h_norm, cfg.hidden_size, cfg.vocab_size)
    }

    fn run_backbone(&self, tokens: &[u32], mrope_positions: &[MropePos]) -> Result<Tensor> {
        let cfg = &self.config;
        let weights = &self.weights;
        let seq = tokens.len();
        if seq == 0 {
            return Err(fuel_ir::error::Error::Msg(
                "Qwen3VlTextModel::forward: tokens must be non-empty".into(),
            )
            .bt());
        }

        let h = Tensor::embed_tokens(
            weights.token_embedding.clone(),
            cfg.vocab_size,
            cfg.hidden_size,
            tokens,
            &Device::cpu(),
        )?;
        self.run_backbone_embeds(&h, mrope_positions)
    }

    fn run_backbone_embeds(&self, embeds: &Tensor, mrope_positions: &[MropePos]) -> Result<Tensor> {
        self.run_backbone_embeds_with_deepstack(embeds, mrope_positions, &[])
    }

    fn run_backbone_embeds_with_deepstack(
        &self,
        embeds: &Tensor,
        mrope_positions: &[MropePos],
        deepstack_per_layer: &[Option<Tensor>],
    ) -> Result<Tensor> {
        let cfg = &self.config;
        let weights = &self.weights;
        let dims = embeds.shape();
        let dims = dims.dims();
        if dims.len() != 3 || dims[0] != 1 || dims[2] != cfg.hidden_size {
            return Err(fuel_ir::error::Error::Msg(format!(
                "Qwen3VlTextModel::forward_embeds: expected embeds shape \
                 (1, seq, hidden_size={}), got {:?}",
                cfg.hidden_size, dims,
            ))
            .bt());
        }
        let seq = dims[1];
        if seq == 0 {
            return Err(fuel_ir::error::Error::Msg(
                "Qwen3VlTextModel::forward_embeds: seq must be > 0".into(),
            )
            .bt());
        }
        if mrope_positions.len() != seq {
            return Err(fuel_ir::error::Error::Msg(format!(
                "Qwen3VlTextModel::forward_embeds: mrope_positions.len() ({}) \
                 must equal seq ({seq})",
                mrope_positions.len(),
            ))
            .bt());
        }
        if cfg.num_attention_heads * cfg.head_dim != cfg.hidden_size {
            return Err(fuel_ir::error::Error::Msg(
                "Qwen3VlTextConfig: num_attention_heads * head_dim must equal hidden_size".into(),
            )
            .bt());
        }
        if weights.layers.len() != weights.layer_extras.len() {
            return Err(fuel_ir::error::Error::Msg(format!(
                "Qwen3VlTextWeights: layers ({}) must have matching layer_extras ({})",
                weights.layers.len(),
                weights.layer_extras.len(),
            ))
            .bt());
        }

        let (cos_data, sin_data) = build_mrope_tables(
            cfg.rope_theta,
            mrope_positions,
            cfg.head_dim,
            &cfg.mrope_section,
        )?;
        let rope_shape = Shape::from_dims(&[seq, cfg.head_dim]);
        let rope_cos = embeds.const_f32_like(cos_data, rope_shape.clone())?;
        let rope_sin = embeds.const_f32_like(sin_data, rope_shape)?;

        let mut h = embeds.clone();
        for (layer_idx, (layer, extras)) in weights
            .layers
            .iter()
            .zip(weights.layer_extras.iter())
            .enumerate()
        {
            let uses_window = cfg.use_sliding_window && layer_idx < cfg.max_window_layers;
            h = self.apply_layer(&h, layer, extras, &rope_cos, &rope_sin, uses_window)?;
            if let Some(Some(residual)) = deepstack_per_layer.get(layer_idx) {
                h = h.add(residual)?;
            }
        }
        h.rms_norm_affine(
            std::sync::Arc::clone(&weights.final_norm_gain),
            cfg.rms_norm_eps,
        )
    }

    fn build_layer_mask(&self, anchor: &Tensor, seq: usize, uses_window: bool) -> Tensor {
        let cfg = &self.config;
        let window = if uses_window {
            cfg.sliding_window.unwrap_or(seq + 1)
        } else {
            seq + 1
        };
        let mut mask_data = vec![0.0_f32; seq * seq];
        for i in 0..seq {
            for j in 0..seq {
                if j > i || j + window <= i {
                    mask_data[i * seq + j] = f32::NEG_INFINITY;
                }
            }
        }
        anchor.const_f32_like(mask_data, Shape::from_dims(&[1, 1, seq, seq]))
        .expect(
                "build_layer_mask: buffer is vec![_; seq*seq] and the shape's elem_count is seq*seq -- \n             both derived from `seq` in this function; the loop writes in place",
        )
    }

    fn apply_layer(
        &self,
        x: &Tensor,
        layer: &LayerWeights,
        extras: &Qwen3VlTextLayerExtras,
        rope_cos: &Tensor,
        rope_sin: &Tensor,
        uses_window: bool,
    ) -> Result<Tensor> {
        let cfg = &self.config;
        let x_shape = x.shape();
        let dims = x_shape.dims();
        let seq = dims[1];
        let kv_dim = cfg.num_key_value_heads * cfg.head_dim;

        let x_norm = x.rms_norm_affine(
            std::sync::Arc::clone(&layer.attn_norm_gain),
            cfg.rms_norm_eps,
        )?;

        let q = layer
            .attn_q
            .apply_linear(&x_norm, cfg.hidden_size, cfg.hidden_size)?
            .add_optional_trailing_bias(layer.attn_q_bias.as_ref())?;
        let k = layer
            .attn_k
            .apply_linear(&x_norm, cfg.hidden_size, kv_dim)?
            .add_optional_trailing_bias(layer.attn_k_bias.as_ref())?;
        let v = layer
            .attn_v
            .apply_linear(&x_norm, cfg.hidden_size, kv_dim)?
            .add_optional_trailing_bias(layer.attn_v_bias.as_ref())?;

        let q = q.split_heads(cfg.num_attention_heads, cfg.head_dim)?;
        let k = k.split_heads(cfg.num_key_value_heads, cfg.head_dim)?;
        let v = v.split_heads(cfg.num_key_value_heads, cfg.head_dim)?;

        let q = q.rms_norm_affine(std::sync::Arc::clone(&extras.q_norm_gain), cfg.rms_norm_eps)?;
        let k = k.rms_norm_affine(std::sync::Arc::clone(&extras.k_norm_gain), cfg.rms_norm_eps)?;

        let q_r = q.rope_with_tables(rope_cos, rope_sin)?;
        let k_r = k.rope_with_tables(rope_cos, rope_sin)?;

        let n_rep = cfg.num_attention_heads / cfg.num_key_value_heads;
        let k_full = k_r.repeat_interleave(1_usize, n_rep)?;
        let v_full = v.repeat_interleave(1_usize, n_rep)?;

        let k_t = k_full.transpose()?;
        let scale = 1.0_f64 / (cfg.head_dim as f64).sqrt();
        let scores = q_r.matmul(&k_t)?;
        let scores_scaled = scores.mul_scalar(scale);
        let mask = self.build_layer_mask(x, seq, uses_window);
        let scores_masked = scores_scaled.broadcast_add(&mask)?;
        let attn = scores_masked.softmax_last_dim()?;
        let attn_v = attn.matmul(&v_full)?;

        let merged = attn_v.merge_heads()?;
        let attn_out = layer
            .attn_o
            .apply_linear(&merged, cfg.hidden_size, cfg.hidden_size)?;

        let h1 = x.add(&attn_out)?;
        let h1_norm = h1.rms_norm_affine(
            std::sync::Arc::clone(&layer.ffn_norm_gain),
            cfg.rms_norm_eps,
        )?;
        let gate = layer
            .ffn_gate
            .apply_linear(&h1_norm, cfg.hidden_size, cfg.intermediate_size)?;
        let up = layer
            .ffn_up
            .apply_linear(&h1_norm, cfg.hidden_size, cfg.intermediate_size)?;
        let swiglu = gate.silu().mul(&up)?;
        let ffn_out =
            layer
                .ffn_down
                .apply_linear(&swiglu, cfg.intermediate_size, cfg.hidden_size)?;
        h1.add(&ffn_out)
    }
}

fn validate_mrope_section(section: &[usize; 3], head_dim: usize) -> Result<()> {
    let half = head_dim / 2;
    if head_dim == 0 || !head_dim.is_multiple_of(2) {
        return Err(fuel_ir::error::Error::Msg(format!(
            "mrope_section: head_dim ({head_dim}) must be a positive even number",
        ))
        .bt());
    }
    let sum: usize = section.iter().sum();
    if sum != half {
        return Err(fuel_ir::error::Error::Msg(format!(
            "mrope_section {section:?} must sum to head_dim/2 ({half}), got {sum}",
        ))
        .bt());
    }
    Ok(())
}

/// Build the MROPE cos/sin tables for `seq` tokens at the supplied
/// `(t, h, w)` positions. Output is laid out as `[seq, head_dim]` so it
/// drops straight into [`Tensor::rope_with_tables`].
///
/// Section layout follows the HF convention: `mrope_section * 2`
/// produces six repeated chunks `[t, h, w, t, h, w]` summing to
/// `head_dim`. Section `i` is owned by axis `i % 3`. Because each of
/// the two halves replays the same `[t, h, w]` pattern in the same
/// order with the same sizes, the section owner and the
/// `freq_idx = j % (head_dim / 2)` both match between `j` and `j + half`
/// — exactly what rotate-half RoPE expects.
fn build_mrope_tables(
    base: f64,
    mrope_positions: &[MropePos],
    head_dim: usize,
    mrope_section: &[usize; 3],
) -> Result<(Vec<f32>, Vec<f32>)> {
    // GAP-289: the guard lives INSIDE, not beside. It used to sit at the sole
    // call site, which is safe only while there is exactly one caller who
    // remembers it -- a domain enforced by convention rather than by the
    // signature. Building it in is the only version that survives a second
    // caller. `half` below is `head_dim / 2`, so an odd head_dim truncates.
    validate_mrope_section(mrope_section, head_dim)?;
    let seq = mrope_positions.len();
    let half = head_dim / 2;
    let mut cos = vec![0.0_f32; seq * head_dim];
    let mut sin = vec![0.0_f32; seq * head_dim];

    // Inverse frequencies sized to head_dim/2 (matches the
    // duplicated-half layout the rest of the codebase uses).
    let inv_freq: Vec<f64> = (0..half)
        .map(|i| base.powf(-2.0 * (i as f64) / (head_dim as f64)))
        .collect();

    // Map j in 0..head_dim to its section owner (which axis: 0/1/2).
    // Sections come in order [t, h, w, t, h, w] with sizes
    // [s0, s1, s2, s0, s1, s2].
    let sections_repeated = [
        mrope_section[0],
        mrope_section[1],
        mrope_section[2],
        mrope_section[0],
        mrope_section[1],
        mrope_section[2],
    ];
    let mut axis_of_j = vec![0_usize; head_dim];
    let mut offset = 0_usize;
    for (i, &sec_size) in sections_repeated.iter().enumerate() {
        for k in 0..sec_size {
            axis_of_j[offset + k] = i % 3;
        }
        offset += sec_size;
    }
    debug_assert_eq!(offset, head_dim);

    for (p, pos) in mrope_positions.iter().enumerate() {
        for j in 0..head_dim {
            let axis = axis_of_j[j];
            let pos_val = pos[axis] as f64;
            let freq_idx = j % half;
            let theta = pos_val * inv_freq[freq_idx];
            cos[p * head_dim + j] = theta.cos() as f32;
            sin[p * head_dim + j] = theta.sin() as f32;
        }
    }
    Ok((cos, sin))
}

// ---- HuggingFace safetensors loader ----------------------------------------

impl Qwen3VlTextWeights {
    /// Load Qwen3-VL text-side weights from HF safetensors.
    /// HF layout follows the Qwen3 decoder, but the text submodule sits
    /// under the `model.language_model.*` prefix (with the composition's
    /// `lm_head` typically at the top level). Optional fallbacks accept
    /// either the `model.language_model.*` or the bare `language_model.*`
    /// prefix to cover variants.
    pub fn load_from_mmapped(
        st: &fuel_loaders::safetensors::MmapedSafetensors,
        cfg: &Qwen3VlTextConfig,
    ) -> Result<Self> {
        use fuel_tensor::{lazy::load_tensor_as_f32, lazy::load_transposed_matrix_preserve_dtype};
        let h = cfg.hidden_size;
        let q_dim = cfg.num_attention_heads * cfg.head_dim;
        let kv_dim = cfg.num_key_value_heads * cfg.head_dim;
        let inter = cfg.intermediate_size;

        // Try the standard composition prefix first; fall back to the
        // bare `language_model.*` form if the safetensors shard uses it.
        let prefix = if st.get("model.language_model.embed_tokens.weight").is_ok() {
            "model.language_model"
        } else if st.get("language_model.embed_tokens.weight").is_ok() {
            "language_model"
        } else {
            // Fall back to vanilla LLaMA-style prefix used by Qwen3.
            "model"
        };

        let token_embedding: Arc<[f32]> = Arc::from(load_tensor_as_f32(
            st,
            &format!("{prefix}.embed_tokens.weight"),
        )?);

        let mut layers: Vec<LayerWeights> = Vec::with_capacity(cfg.num_hidden_layers);
        let mut layer_extras: Vec<Qwen3VlTextLayerExtras> =
            Vec::with_capacity(cfg.num_hidden_layers);
        for i in 0..cfg.num_hidden_layers {
            let p = format!("{prefix}.layers.{i}");
            let attn_q = load_transposed_matrix_preserve_dtype(
                st,
                &format!("{p}.self_attn.q_proj.weight"),
                q_dim,
                h,
            )?;
            let attn_k = load_transposed_matrix_preserve_dtype(
                st,
                &format!("{p}.self_attn.k_proj.weight"),
                kv_dim,
                h,
            )?;
            let attn_v = load_transposed_matrix_preserve_dtype(
                st,
                &format!("{p}.self_attn.v_proj.weight"),
                kv_dim,
                h,
            )?;
            let attn_o = load_transposed_matrix_preserve_dtype(
                st,
                &format!("{p}.self_attn.o_proj.weight"),
                h,
                q_dim,
            )?;
            let (attn_q_bias, attn_k_bias, attn_v_bias) = if cfg.attention_bias {
                (
                    Some(Arc::<[f32]>::from(load_tensor_as_f32(
                        st,
                        &format!("{p}.self_attn.q_proj.bias"),
                    )?)),
                    Some(Arc::<[f32]>::from(load_tensor_as_f32(
                        st,
                        &format!("{p}.self_attn.k_proj.bias"),
                    )?)),
                    Some(Arc::<[f32]>::from(load_tensor_as_f32(
                        st,
                        &format!("{p}.self_attn.v_proj.bias"),
                    )?)),
                )
            } else {
                (None, None, None)
            };
            let ffn_gate = load_transposed_matrix_preserve_dtype(
                st,
                &format!("{p}.mlp.gate_proj.weight"),
                inter,
                h,
            )?;
            let ffn_up = load_transposed_matrix_preserve_dtype(
                st,
                &format!("{p}.mlp.up_proj.weight"),
                inter,
                h,
            )?;
            let ffn_down = load_transposed_matrix_preserve_dtype(
                st,
                &format!("{p}.mlp.down_proj.weight"),
                h,
                inter,
            )?;
            let attn_norm_gain: Arc<[f32]> = Arc::from(load_tensor_as_f32(
                st,
                &format!("{p}.input_layernorm.weight"),
            )?);
            let ffn_norm_gain: Arc<[f32]> = Arc::from(load_tensor_as_f32(
                st,
                &format!("{p}.post_attention_layernorm.weight"),
            )?);
            layers.push(LayerWeights {
                attn_q,
                attn_q_bias,
                attn_k,
                attn_k_bias,
                attn_v,
                attn_v_bias,
                attn_o,
                ffn_gate,
                ffn_up,
                ffn_down,
                attn_norm_gain,
                ffn_norm_gain,
            });
            let q_norm_gain: Arc<[f32]> = Arc::from(load_tensor_as_f32(
                st,
                &format!("{p}.self_attn.q_norm.weight"),
            )?);
            let k_norm_gain: Arc<[f32]> = Arc::from(load_tensor_as_f32(
                st,
                &format!("{p}.self_attn.k_norm.weight"),
            )?);
            layer_extras.push(Qwen3VlTextLayerExtras {
                q_norm_gain,
                k_norm_gain,
            });
        }
        let final_norm_gain: Arc<[f32]> =
            Arc::from(load_tensor_as_f32(st, &format!("{prefix}.norm.weight"))?);
        let output = if cfg.tie_word_embeddings {
            crate::models::lazy_llama_full::tied_lm_head_from_embeddings(
                &token_embedding,
                cfg.vocab_size,
                h,
            )
        } else {
            load_transposed_matrix_preserve_dtype(st, "lm_head.weight", cfg.vocab_size, h)?
        };
        Ok(Self {
            token_embedding,
            layers,
            layer_extras,
            final_norm_gain,
            output,
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // ROADMAP item 8 (II), DEEP nested-artifact case. Golden values from
    // Qwen/Qwen3-VL-4B-Instruct's real config.json: the ENTIRE text stack is under
    // `text_config`, `mrope_section` is under `text_config.rope_scaling`, and a
    // `vision_config` sibling (to ignore) sits beside `text_config`. head_dim is
    // EXPLICIT and DECOUPLED (128 vs 2560/32 = 80).
    const QWEN3_VL_4B_CONFIG_JSON: &str = r#"{
        "architectures": ["Qwen3VLForConditionalGeneration"],
        "model_type": "qwen3_vl",
        "image_token_id": 151655,
        "tie_word_embeddings": true,
        "text_config": {
            "model_type": "qwen3_vl_text",
            "vocab_size": 151936,
            "hidden_size": 2560,
            "intermediate_size": 9728,
            "num_hidden_layers": 36,
            "num_attention_heads": 32,
            "num_key_value_heads": 8,
            "head_dim": 128,
            "max_position_embeddings": 262144,
            "rms_norm_eps": 1e-06,
            "rope_theta": 5000000,
            "attention_bias": false,
            "tie_word_embeddings": true,
            "rope_scaling": {
                "mrope_interleaved": true,
                "mrope_section": [24, 20, 20],
                "rope_type": "default"
            }
        },
        "vision_config": {
            "depth": 24,
            "hidden_size": 1024,
            "patch_size": 16
        }
    }"#;

    #[test]
    fn qwen3_vl_text_config_from_hf_json_parses_the_nested_text_config() {
        let cfg = Qwen3VlTextConfig::from_hf_json_str(QWEN3_VL_4B_CONFIG_JSON).unwrap();
        // All of these are lifted out of the nested `text_config` object.
        assert_eq!(cfg.hidden_size, 2560);
        assert_eq!(cfg.num_hidden_layers, 36);
        assert_eq!(cfg.num_attention_heads, 32);
        assert_eq!(cfg.vocab_size, 151_936);
        assert_eq!(cfg.intermediate_size, 9728);
        // GQA: default would be num_attention_heads (32); 8 proves the key was READ.
        assert_eq!(cfg.num_key_value_heads, 8);
        // head_dim EXPLICIT and decoupled — 128, NOT 2560/32 = 80.
        assert_eq!(cfg.head_dim, 128);
        assert_ne!(cfg.head_dim, 2560 / 32);
        assert_eq!(cfg.rope_theta, 5_000_000.0);
        assert_eq!(cfg.max_position_embeddings, 262_144);
        assert!(cfg.tie_word_embeddings);
        // absent under text_config → resolved
        assert_eq!(cfg.sliding_window, None);
        assert_eq!(cfg.max_window_layers, 36); // → num_hidden_layers
        // THE DEEP-NEST ASSERTION: mrope_section is lifted from
        // text_config.rope_scaling (nested twice), and vision_config was ignored.
        assert_eq!(cfg.mrope_section, [24, 20, 20]);
    }

    /// A SECOND distinct config under text_config, with a DIFFERENT nested
    /// mrope_section — proving the value is READ from two-levels-deep, not
    /// hardcoded, AND the omitted rope_theta defaults.
    #[test]
    fn qwen3_vl_text_config_reads_a_second_distinct_nested_config() {
        let json = r#"{
            "model_type": "qwen3_vl",
            "text_config": {
                "vocab_size": 100000,
                "hidden_size": 2048,
                "intermediate_size": 6144,
                "num_hidden_layers": 28,
                "num_attention_heads": 16,
                "num_key_value_heads": 4,
                "head_dim": 128,
                "max_position_embeddings": 32768,
                "rope_scaling": { "mrope_section": [16, 24, 24] }
            }
        }"#;
        let cfg = Qwen3VlTextConfig::from_hf_json_str(json).unwrap();
        assert_eq!(cfg.hidden_size, 2048);
        assert_eq!(cfg.num_key_value_heads, 4);
        assert_eq!(cfg.head_dim, 128);
        assert_eq!(cfg.mrope_section, [16, 24, 24]);
        assert_ne!(cfg.mrope_section, [24, 20, 20]);
        assert_eq!(cfg.rope_theta, 5_000_000.0); // defaulted
    }

    /// `num_key_value_heads` ABSENT (under text_config) → num_attention_heads;
    /// true MQA (1) survives.
    #[test]
    fn qwen3_vl_text_config_gqa_default_and_true_mqa() {
        let base = |kv: &str| {
            format!(
                r#"{{
                "model_type": "qwen3_vl",
                "text_config": {{
                    "vocab_size": 1000, "hidden_size": 64, "intermediate_size": 128,
                    "num_hidden_layers": 2, "num_attention_heads": 8, "head_dim": 8,
                    "max_position_embeddings": 128,
                    "rope_scaling": {{ "mrope_section": [1, 1, 2] }} {kv}
                }}
            }}"#
            )
        };
        let absent = Qwen3VlTextConfig::from_hf_json_str(&base("")).unwrap();
        assert_eq!(absent.num_key_value_heads, 8);
        let mqa =
            Qwen3VlTextConfig::from_hf_json_str(&base(", \"num_key_value_heads\": 1")).unwrap();
        assert_eq!(mqa.num_key_value_heads, 1);
    }

    /// A config MISSING the `text_config` wrapper is an ERROR — the parser reads
    /// the nested object, not the top level.
    #[test]
    fn qwen3_vl_text_config_missing_text_config_errors() {
        let json = r#"{
            "model_type": "qwen3_vl",
            "vocab_size": 1000,
            "hidden_size": 64,
            "num_attention_heads": 8,
            "head_dim": 8
        }"#;
        assert!(Qwen3VlTextConfig::from_hf_json_str(json).is_err());
    }

    fn tiny_cfg() -> Qwen3VlTextConfig {
        Qwen3VlTextConfig {
            vocab_size: 32,
            hidden_size: 16,
            intermediate_size: 32,
            num_hidden_layers: 2,
            num_attention_heads: 4,
            num_key_value_heads: 2,
            head_dim: 4,
            max_position_embeddings: 64,
            sliding_window: None,
            max_window_layers: 0,
            use_sliding_window: false,
            rope_theta: 10_000.0,
            rms_norm_eps: 1e-5,
            attention_bias: false,
            tie_word_embeddings: false,
            mrope_section: [1, 1, 0],
        }
    }

    fn tiny_weights(cfg: &Qwen3VlTextConfig) -> Qwen3VlTextWeights {
        let mut s: u32 = 24680;
        let next = move || -> f32 {
            s = s.wrapping_mul(1103515245).wrapping_add(12345);
            ((s >> 16) as u16 as f32 / 65535.0 - 0.5) * 0.05
        };
        let vec_of = |n: usize, next: &mut dyn FnMut() -> f32| -> Arc<[f32]> {
            Arc::from((0..n).map(|_| next()).collect::<Vec<_>>())
        };
        let h = cfg.hidden_size;
        let i = cfg.intermediate_size;
        let kv = cfg.num_key_value_heads * cfg.head_dim;
        let mut nb: Box<dyn FnMut() -> f32> = Box::new(next);
        let token_embedding = vec_of(cfg.vocab_size * h, &mut *nb);
        let mut layers = Vec::new();
        let mut layer_extras = Vec::new();
        for _ in 0..cfg.num_hidden_layers {
            layers.push(LayerWeights {
                attn_q: WeightStorage::F32(vec_of(h * h, &mut *nb)),
                attn_q_bias: if cfg.attention_bias {
                    Some(vec_of(h, &mut *nb))
                } else {
                    None
                },
                attn_k: WeightStorage::F32(vec_of(h * kv, &mut *nb)),
                attn_k_bias: if cfg.attention_bias {
                    Some(vec_of(kv, &mut *nb))
                } else {
                    None
                },
                attn_v: WeightStorage::F32(vec_of(h * kv, &mut *nb)),
                attn_v_bias: if cfg.attention_bias {
                    Some(vec_of(kv, &mut *nb))
                } else {
                    None
                },
                attn_o: WeightStorage::F32(vec_of(h * h, &mut *nb)),
                ffn_gate: WeightStorage::F32(vec_of(h * i, &mut *nb)),
                ffn_up: WeightStorage::F32(vec_of(h * i, &mut *nb)),
                ffn_down: WeightStorage::F32(vec_of(i * h, &mut *nb)),
                attn_norm_gain: Arc::from(vec![1.0_f32; h]),
                ffn_norm_gain: Arc::from(vec![1.0_f32; h]),
            });
            layer_extras.push(Qwen3VlTextLayerExtras {
                q_norm_gain: Arc::from(vec![1.0_f32; cfg.head_dim]),
                k_norm_gain: Arc::from(vec![1.0_f32; cfg.head_dim]),
            });
        }
        let final_norm_gain = Arc::from(vec![1.0_f32; h]);
        let output = WeightStorage::F32(vec_of(h * cfg.vocab_size, &mut *nb));
        Qwen3VlTextWeights {
            token_embedding,
            layers,
            layer_extras,
            final_norm_gain,
            output,
        }
    }

    fn scalar_positions(seq: usize) -> Vec<MropePos> {
        (0..seq as u32).map(|p| [p, p, p]).collect()
    }

    #[test]
    fn forward_shape_and_finite_tiny() {
        let cfg = tiny_cfg();
        let model = Qwen3VlTextModel {
            config: cfg.clone(),
            weights: tiny_weights(&cfg),
        };
        let tokens = vec![1_u32, 2, 3];
        let positions = scalar_positions(tokens.len());
        let logits = model.forward(&tokens, &positions).unwrap();
        assert_eq!(logits.shape().dims(), &[1, tokens.len(), cfg.vocab_size]);
        for &v in &logits.realize_f32() {
            assert!(v.is_finite(), "non-finite logit: {v}");
        }
    }

    #[test]
    fn mrope_positions_change_attention() {
        // Two MROPE position grids that differ on the height axis in
        // a way RoPE's translation-invariance can't absorb (varying
        // pairwise distances). `mrope_section = [1, 1, 0]` gives the
        // height axis its own RoPE slot, so changing pairwise h
        // distances MUST change the attention output. Anchor case for
        // verifying MROPE actually wires the per-axis positions
        // through, instead of collapsing to temporal-axis-only RoPE.
        let cfg = tiny_cfg();
        let model = Qwen3VlTextModel {
            config: cfg.clone(),
            weights: tiny_weights(&cfg),
        };
        let tokens = vec![1_u32, 2, 3, 4];

        // Both grids share the same temporal axis. Grid `a` has h
        // positions matching the temporal axis (uniform spacing);
        // grid `b` clusters two h positions together so the pairwise
        // distance pattern is *different*, not just translated.
        let positions_a: Vec<MropePos> = vec![[0, 0, 0], [1, 1, 1], [2, 2, 2], [3, 3, 3]];
        let positions_b: Vec<MropePos> = vec![[0, 0, 0], [1, 1, 1], [2, 7, 2], [3, 8, 3]];

        let out_a = model.forward(&tokens, &positions_a).unwrap().realize_f32();
        let out_b = model.forward(&tokens, &positions_b).unwrap().realize_f32();
        let max_diff = out_a
            .iter()
            .zip(out_b.iter())
            .map(|(a, b)| (a - b).abs())
            .fold(0.0_f32, f32::max);
        assert!(
            max_diff > 1e-6,
            "different MROPE height pairwise distances must yield different \
             logits (max diff {max_diff})",
        );
    }

    #[test]
    fn forward_embeds_matches_forward() {
        let cfg = tiny_cfg();
        let model = Qwen3VlTextModel {
            config: cfg.clone(),
            weights: tiny_weights(&cfg),
        };
        let tokens = vec![1_u32, 2, 3];
        let positions = scalar_positions(tokens.len());
        let logits_ref = model.forward(&tokens, &positions).unwrap().realize_f32();

        let anchor =
            Tensor::from_f32(vec![0.0_f32], Shape::from_dims(&[1]), &Device::cpu()).unwrap();
        let embeds = model.embed_tokens_anchored(&anchor, &tokens).unwrap();
        let logits_via_embeds = model
            .forward_embeds(&embeds, &positions)
            .unwrap()
            .realize_f32();
        assert_eq!(logits_ref.len(), logits_via_embeds.len());
        let max_diff = logits_ref
            .iter()
            .zip(logits_via_embeds.iter())
            .map(|(a, b)| (a - b).abs())
            .fold(0.0_f32, f32::max);
        assert!(
            max_diff < 1e-5,
            "forward vs forward_embeds must agree (max diff {max_diff})",
        );
    }

    #[test]
    fn forward_embeds_rejects_mismatched_positions() {
        let cfg = tiny_cfg();
        let model = Qwen3VlTextModel {
            config: cfg.clone(),
            weights: tiny_weights(&cfg),
        };
        let anchor =
            Tensor::from_f32(vec![0.0_f32], Shape::from_dims(&[1]), &Device::cpu()).unwrap();
        let embeds = model
            .embed_tokens_anchored(&anchor, &[1_u32, 2, 3])
            .unwrap();
        let bad_positions = scalar_positions(2); // seq is 3, only 2 supplied
        assert!(model.forward_embeds(&embeds, &bad_positions).is_err());
    }

    #[test]
    fn mrope_section_validation_catches_bad_sum() {
        let mut cfg = tiny_cfg();
        cfg.mrope_section = [2, 2, 0]; // sum 4 != head_dim/2 == 2
        let model = Qwen3VlTextModel {
            config: cfg.clone(),
            weights: tiny_weights(&cfg),
        };
        let tokens = vec![1_u32, 2];
        let positions = scalar_positions(tokens.len());
        assert!(model.forward(&tokens, &positions).is_err());
    }

    /// **GAP-195: `use_sliding_window: true` with `sliding_window: None` is DENSE.**
    ///
    /// `build_layer_mask` computes `cfg.sliding_window.unwrap_or(seq + 1)`, and
    /// `j + (seq + 1) <= i` is unsatisfiable for `i < seq`, so the windowed
    /// branch excludes nothing and collapses to plain causal. **The shipped
    /// prefill path therefore leaves every layer dense when the width is
    /// absent, whatever the flag says.**
    ///
    /// ⚠️ **THE CODE IS ALREADY CORRECT. This test is COVERAGE, not a fix, and
    /// it passed on its first run — which is exactly why it is worthless on its
    /// own.** A naive assertion here passes for the wrong reason if the mask
    /// pipeline is inert, so it is paired with
    /// [`a_real_width_does_narrow_the_mask`], which fails in that case. Neither
    /// arm may be deleted without the other losing its meaning.
    ///
    /// **Why this family and not the flag-bearing others:** Qwen3 and Qwen3Moe
    /// carry this shape and were given explicit tests by `322e3049`; Qwen2's
    /// width is a bare `usize`, so the shape cannot arise. `Qwen3VlText` is the
    /// third family with `use_sliding_window` + `Option<usize>` and had no test
    /// of the flag-true/width-absent configuration — its `tiny_cfg` sets the
    /// flag FALSE, so none of the existing five ever construct it.
    #[test]
    fn flag_true_with_no_width_is_dense() {
        let mut cfg = tiny_cfg();
        cfg.use_sliding_window = true;
        cfg.sliding_window = None; // the hazard configuration
        cfg.max_window_layers = cfg.num_hidden_layers; // every layer "windowed"
        let model = Qwen3VlTextModel {
            config: cfg.clone(),
            weights: tiny_weights(&cfg),
        };
        let anchor =
            Tensor::from_f32(vec![0.0_f32], Shape::from_dims(&[1]), &Device::cpu()).unwrap();
        let seq = 4;

        let windowed = model.build_layer_mask(&anchor, seq, true).realize_f32();
        let dense = model.build_layer_mask(&anchor, seq, false).realize_f32();

        // FOUNDATION: a mask that examined nothing would compare equal trivially.
        assert_eq!(windowed.len(), seq * seq, "mask is not seq x seq");
        assert!(
            windowed.contains(&f32::NEG_INFINITY),
            "no position is masked at all -- the causal mask itself is inert, so \
             equality below would prove nothing"
        );
        assert_eq!(
            windowed, dense,
            "flag=true with width=None produced a DIFFERENT mask from the dense \
             path. GAP-195: `sliding_window.unwrap_or(seq + 1)` must exclude \
             nothing, so a config with the flag set and no width is dense at \
             every layer. If this fires, decode now disagrees with the shipped \
             prefill path in the direction GAP-195 exists to prevent."
        );
    }

    /// **The retained sibling, and it is load-bearing rather than decorative.**
    ///
    /// [`flag_true_with_no_width_is_dense`] asserts an EQUALITY, so it passes
    /// under total inertness: a `build_layer_mask` that ignored `window`
    /// entirely, or a refactor that made both branches identical, turns it
    /// green while proving nothing. **This arm fails in exactly that case.**
    ///
    /// Sabotage-verified rather than assumed: changing the production
    /// `unwrap_or(seq + 1)` to `unwrap_or(2)` reddens the equality arm, and
    /// making `build_layer_mask` ignore `uses_window` reddens this one. The two
    /// arms fail on disjoint defects.
    #[test]
    fn a_real_width_does_narrow_the_mask() {
        let mut cfg = tiny_cfg();
        cfg.use_sliding_window = true;
        cfg.sliding_window = Some(2); // a width that must actually exclude
        cfg.max_window_layers = cfg.num_hidden_layers;
        let model = Qwen3VlTextModel {
            config: cfg.clone(),
            weights: tiny_weights(&cfg),
        };
        let anchor =
            Tensor::from_f32(vec![0.0_f32], Shape::from_dims(&[1]), &Device::cpu()).unwrap();
        let seq = 4;

        let windowed = model.build_layer_mask(&anchor, seq, true).realize_f32();
        let dense = model.build_layer_mask(&anchor, seq, false).realize_f32();

        assert_ne!(
            windowed, dense,
            "a width of 2 over seq=4 produced the SAME mask as the dense path. \
             The window is not being applied at all, which makes the equality \
             asserted by `flag_true_with_no_width_is_dense` vacuous -- it would \
             hold for every config. Investigate the mask, not this assertion."
        );
        // Direction, not just difference: windowing may only ADD exclusions.
        let extra = windowed
            .iter()
            .zip(dense.iter())
            .filter(|(w, d)| **w == f32::NEG_INFINITY && **d != f32::NEG_INFINITY)
            .count();
        assert!(
            extra > 0,
            "the windowed mask differs from dense but masks no ADDITIONAL \
             position -- the difference is in the wrong direction"
        );
    }

    /// GAP-289: `build_mrope_tables` must guard ITSELF, not trust its caller.
    ///
    /// The checks used to live at the sole call site. That is safe exactly while
    /// there is one caller who remembers -- a load-bearing domain enforced by
    /// convention instead of by the signature. **This test calls the function
    /// DIRECTLY, which is the thing a second caller would do**, and it could not
    /// have been written before the fn returned `Result`.
    ///
    /// # ⚠️ What the unguarded function actually did -- three behaviours, not one
    ///
    /// `axis_of_j` has `head_dim` slots, but `sections_repeated` sums to
    /// `2 * the section sum`. So without the guard:
    ///
    /// - **over-sum** -- index-out-of-bounds **panic** at the
    ///   `axis_of_j[offset + k]` write, in every profile;
    /// - **under-sum** -- `debug_assert_eq!(offset, head_dim)` fires in debug and
    ///   is **compiled out in release**, where the unowned features keep
    ///   `axis_of_j == 0` and the table is **silently wrong**;
    /// - **odd `head_dim`** -- lands in one of the two above depending on the
    ///   section.
    ///
    /// So "it silently truncates" holds only for the release under-sum case.
    /// Both directions are covered below; the under-sum arm is the one whose
    /// failure was invisible in a release build.
    ///
    /// Born-red by sabotage: deleting the internal `validate_mrope_section(...)?`
    /// reddens this test. **Measured, and stated precisely rather than as "it
    /// goes red": the first decline arm then dies INSIDE the function with an
    /// index-out-of-bounds panic, not at the assertion** -- the guard's absence
    /// is a never-panic violation, not merely a missing error.
    #[test]
    fn build_mrope_tables_guards_itself_rather_than_trusting_its_caller() {
        let positions: Vec<MropePos> = vec![[0, 0, 0], [1, 1, 1]];

        // CONTROL: head_dim 8 -> half 4, and [2,1,1] sums to 4. Must still build.
        let (cos, sin) = build_mrope_tables(10_000.0, &positions, 8, &[2, 1, 1])
            .expect("control: a conforming head_dim/section must still build");
        assert_eq!(cos.len(), positions.len() * 8);
        assert_eq!(sin.len(), positions.len() * 8);

        // An odd head_dim: `half = head_dim / 2` truncates, so this is a DECLINE
        // rather than a silently wrong table.
        let err = build_mrope_tables(10_000.0, &positions, 7, &[2, 1, 1])
            .expect_err("an odd head_dim must DECLINE, not truncate");
        let msg = format!("{err}");
        assert!(
            msg.contains("head_dim") && msg.contains('7'),
            "the decline must name the operand and its value, got: {msg}"
        );

        // A section that does not sum to head_dim/2 leaves features unowned.
        let err = build_mrope_tables(10_000.0, &positions, 8, &[2, 1, 2])
            .expect_err("a non-summing mrope_section must DECLINE, not truncate");
        let msg = format!("{err}");
        assert!(
            msg.contains("mrope_section") && msg.contains('4') && msg.contains('5'),
            "the decline must name the relation and BOTH sides, got: {msg}"
        );

        // UNDER-sum: the direction that is SILENT in release, because the
        // `debug_assert_eq!` guarding it is compiled out there.
        let err = build_mrope_tables(10_000.0, &positions, 8, &[1, 1, 1])
            .expect_err("an under-summing mrope_section must DECLINE, not leave features unowned");
        let msg = format!("{err}");
        assert!(
            msg.contains("mrope_section") && msg.contains('4') && msg.contains('3'),
            "the decline must name the relation and BOTH sides, got: {msg}"
        );
    }
}