edgefirst_decoder/

schema.rs

// SPDX-FileCopyrightText: Copyright 2025-2026 Au-Zone Technologies
// SPDX-License-Identifier: Apache-2.0

//! Schema v2 metadata types for EdgeFirst model configuration.
//!
//! Schema v2 introduces a two-layer output model that separates the logical
//! contract (what the model produces semantically) from the physical
//! realization (what tensors the converter emitted). Each entry in the
//! top-level [`SchemaV2::outputs`] array is a [`LogicalOutput`]. A logical
//! output either IS a physical tensor (when the converter did not split it
//! further) or contains a `outputs` array of [`PhysicalOutput`] children
//! that realize it.
//!
//! # Example — YOLOv8 detection, flat (TFLite)
//!
//! ```
//! use edgefirst_decoder::schema::SchemaV2;
//!
//! let json = r#"{
//!   "schema_version": 2,
//!   "outputs": [
//!     {
//!       "name": "boxes", "type": "boxes",
//!       "shape": [1, 64, 8400],
//!       "dshape": [{"batch": 1}, {"num_features": 64}, {"num_boxes": 8400}],
//!       "encoding": "dfl", "decoder": "ultralytics", "normalized": true,
//!       "dtype": "int8",
//!       "quantization": {"scale": 0.00392, "zero_point": 0, "dtype": "int8"}
//!     },
//!     {
//!       "name": "scores", "type": "scores",
//!       "shape": [1, 80, 8400],
//!       "dshape": [{"batch": 1}, {"num_classes": 80}, {"num_boxes": 8400}],
//!       "decoder": "ultralytics", "score_format": "per_class",
//!       "dtype": "int8",
//!       "quantization": {"scale": 0.00392, "zero_point": 0, "dtype": "int8"}
//!     }
//!   ]
//! }"#;
//!
//! let schema: SchemaV2 = serde_json::from_str(json).unwrap();
//! assert_eq!(schema.schema_version, 2);
//! assert_eq!(schema.outputs.len(), 2);
//! ```

use crate::configs::{self, deserialize_dshape, DimName, QuantTuple};
use crate::{ConfigOutput, ConfigOutputs, DecoderError, DecoderResult};
use serde::{Deserialize, Serialize};

pub use edgefirst_tensor::{
    FitMode, Interpolation, LetterboxPlacement, NormalizationPreset, PadSpace,
};

/// Highest `schema_version` this parser accepts. Files with a higher
/// version are rejected rather than silently parsed against the wrong
/// grammar.
pub const MAX_SUPPORTED_SCHEMA_VERSION: u32 = 2;

/// Root of the edgefirst.json schema v2 metadata.
///
/// All fields except [`SchemaV2::schema_version`] are optional, so
/// third-party integrations can include only the sections relevant to
/// their use case.
///
/// The struct is `#[non_exhaustive]` so new optional sections can be added
/// without a breaking change. Outside this crate, start from
/// [`SchemaV2::new`] (or [`Default`], or a parser) and assign fields:
///
/// ```rust
/// use edgefirst_decoder::schema::{NmsMode, SchemaV2};
///
/// let mut schema = SchemaV2::new();
/// schema.nms = Some(NmsMode::ClassAware);
/// schema.nms_multi_label = Some(true);
/// assert_eq!(schema.schema_version, 2);
/// ```
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct SchemaV2 {
    /// Schema version. Always 2 for v2 metadata.
    pub schema_version: u32,

    /// Input tensor specification (shape, named dims, camera adaptor).
    ///
    /// Required for decoders that need to know the model input resolution:
    /// DFL dist2bbox scaling, box normalization against input dimensions,
    /// and per-scale anchor grid generation.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub input: Option<InputSpec>,

    /// Logical outputs describing the model's output tensors and their
    /// semantic roles.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub outputs: Vec<LogicalOutput>,

    /// HAL NMS mode. Omitted for end-to-end models with embedded NMS.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub nms: Option<NmsMode>,

    /// Emit one box per class above the score threshold (validation decode).
    /// Tracked decode ignores it; an explicit decoder setting overrides it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub nms_multi_label: Option<bool>,

    /// YOLO architecture version for Ultralytics decoders.
    ///
    /// Values: `yolov5`, `yolov8`, `yolo11`, `yolo26`. `yolo26` is
    /// end-to-end (embedded NMS).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub decoder_version: Option<DecoderVersion>,
}

impl SchemaV2 {
    /// An empty v2 schema: `schema_version` 2 and every section unset.
    pub fn new() -> Self {
        Self::default()
    }
}

impl Default for SchemaV2 {
    fn default() -> Self {
        Self {
            schema_version: 2,
            input: None,
            outputs: Vec::new(),
            nms: None,
            nms_multi_label: None,
            decoder_version: None,
        }
    }
}

/// Input tensor specification.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InputSpec {
    /// Input tensor shape in the model's native layout (NCHW or NHWC).
    pub shape: Vec<usize>,

    /// Named dimensions ordered to match `shape`. Empty means the layout
    /// is unspecified and consumers must infer from the format.
    #[serde(
        default,
        deserialize_with = "deserialize_dshape",
        skip_serializing_if = "Vec::is_empty"
    )]
    pub dshape: Vec<(DimName, usize)>,

    /// Camera adaptor input format (`rgb`, `rgba`, `bgr`, `bgra`, `grey`,
    /// `yuyv`). Free-form string rather than an enum because new adaptor
    /// formats can appear without breaking parsing.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cameraadaptor: Option<String>,

    /// Pre-processing the model expects: normalization, resize policy and
    /// letterbox geometry. `None` means the producer did not declare it;
    /// consumers fall back to `validation.normalization` /
    /// `validation.preprocessing`, then to unsigned + centred letterbox.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub preprocessing: Option<Preprocessing>,
}

impl InputSpec {
    /// Channel count of the model input, when the layout can be resolved.
    ///
    /// With a `dshape`, it is the size of the single axis not named
    /// `batch`, `height` or `width`. Without one, a rank-4 `shape` resolves
    /// only when exactly one of axis 1 (NCHW) and axis 3 (NHWC) holds 1 to
    /// 4 channels.
    ///
    /// ```
    /// use edgefirst_decoder::schema::InputSpec;
    ///
    /// let nchw: InputSpec = serde_json::from_str(r#"{"shape": [1, 3, 512, 512]}"#).unwrap();
    /// assert_eq!(nchw.channels(), Some(3));
    /// let ambiguous: InputSpec = serde_json::from_str(r#"{"shape": [1, 3, 4, 3]}"#).unwrap();
    /// assert_eq!(ambiguous.channels(), None);
    /// ```
    pub fn channels(&self) -> Option<usize> {
        if !self.dshape.is_empty() {
            let mut rest = self.dshape.iter().enumerate().filter(|(_, (name, _))| {
                !matches!(name, DimName::Batch | DimName::Height | DimName::Width)
            });
            return match (rest.next(), rest.next()) {
                (Some((i, _)), None) => self.shape.get(i).copied(),
                _ => None,
            };
        }
        let [_, c1, _, c3] = self.shape.as_slice() else {
            return None;
        };
        let is_channels = |c: usize| (1..=4).contains(&c);
        match (is_channels(*c1), is_channels(*c3)) {
            (true, false) => Some(*c1),
            (false, true) => Some(*c3),
            _ => None,
        }
    }
}

/// Input pre-processing declared by the model producer.
///
/// Every field is optional; an absent field means "not declared" rather
/// than a specific default, so consumers can apply their own fallback.
///
/// ```
/// use edgefirst_decoder::schema::{InputSpec, NormalizationPreset, NormalizationConfig};
///
/// let input: InputSpec = serde_json::from_str(r#"{
///   "shape": [1, 3, 512, 512],
///   "preprocessing": {
///     "normalization": "imagenet",
///     "resize": "letterbox",
///     "letterbox": {"placement": "topleft", "pad": [0, 0, 0], "pad_space": "normalized"}
///   }
/// }"#).unwrap();
/// let pre = input.preprocessing.unwrap();
/// assert_eq!(pre.normalization, Some(NormalizationConfig::Preset(NormalizationPreset::Imagenet)));
/// ```
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Preprocessing {
    /// Per-channel normalization applied to 0–255 input values.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub normalization: Option<NormalizationConfig>,

    /// How a frame is fitted to the fixed model input.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub resize: Option<FitMode>,

    /// Resampling filter of the reference pipeline. Informational: a
    /// runtime may use a different filter and should report the deviation.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub interpolation: Option<Interpolation>,

    /// Letterbox geometry; meaningful when `resize` is `letterbox`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub letterbox: Option<Letterbox>,
}

/// Input normalization: a named preset or explicit per-channel
/// `mean`/`std`, both defined as `(x - mean) / std` on 0–255 values.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(untagged)]
pub enum NormalizationConfig {
    /// Named preset shared with `validation.normalization`.
    Preset(NormalizationPreset),
    /// Explicit coefficients on the 0–255 scale. A single element applies
    /// to every channel.
    MeanStd {
        /// Per-channel mean on the 0–255 scale.
        mean: Vec<f32>,
        /// Per-channel standard deviation on the 0–255 scale.
        std: Vec<f32>,
    },
}

impl NormalizationConfig {
    /// Resolve to per-channel `(mean, std)` vectors on the 0–255 scale,
    /// each of length `channels`.
    ///
    /// # Errors
    ///
    /// [`DecoderError::InvalidConfig`] when the coefficient count is neither
    /// 1 nor `channels`, when any `std` is zero or non-finite, or when the
    /// `imagenet` preset is used with a channel count other than 3.
    ///
    /// ```
    /// use edgefirst_decoder::schema::{NormalizationConfig, NormalizationPreset};
    ///
    /// let (mean, std) = NormalizationConfig::Preset(NormalizationPreset::Signed)
    ///     .mean_std(3)
    ///     .unwrap();
    /// assert_eq!(mean, vec![127.5; 3]);
    /// assert_eq!(std, vec![127.5; 3]);
    /// ```
    pub fn mean_std(&self, channels: usize) -> DecoderResult<(Vec<f32>, Vec<f32>)> {
        let (mean, std): (&[f32], &[f32]) = match self {
            NormalizationConfig::Preset(NormalizationPreset::Imagenet) if channels != 3 => {
                return Err(DecoderError::InvalidConfig(format!(
                    "imagenet normalization needs 3 channels, got {channels}"
                )));
            }
            NormalizationConfig::Preset(p) => {
                // Every preset but imagenet (3 channels only) is uniform.
                let table = edgefirst_tensor::Normalization::preset(*p);
                let n = if channels == 3 { 3 } else { 1 };
                return Ok((
                    broadcast_channels("mean", &table.mean()[..n], channels)?,
                    broadcast_channels("std", &table.std()[..n], channels)?,
                ));
            }
            NormalizationConfig::MeanStd { mean, std } => (mean, std),
        };
        let mean = broadcast_channels("mean", mean, channels)?;
        let std = broadcast_channels("std", std, channels)?;
        if let Some(bad) = mean.iter().find(|m| !m.is_finite()) {
            return Err(DecoderError::InvalidConfig(format!(
                "normalization mean must be finite, got {bad}"
            )));
        }
        if let Some(bad) = std.iter().find(|s| **s <= 0.0 || !s.is_finite()) {
            return Err(DecoderError::InvalidConfig(format!(
                "normalization std must be finite and positive, got {bad}"
            )));
        }
        Ok((mean, std))
    }
}

fn broadcast_channels(field: &str, values: &[f32], channels: usize) -> DecoderResult<Vec<f32>> {
    match values.len() {
        1 => Ok(vec![values[0]; channels]),
        n if n == channels => Ok(values.to_vec()),
        n => Err(DecoderError::InvalidConfig(format!(
            "normalization {field} has {n} values; expected 1 or {channels}"
        ))),
    }
}

/// Letterbox geometry for `resize: letterbox`.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Letterbox {
    /// Where the scaled image sits inside the input. Absent means centred.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub placement: Option<LetterboxPlacement>,

    /// Per-channel pad value, in the space named by `pad_space`. Absent
    /// means 114 per channel in pixel space.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub pad: Option<Vec<f32>>,

    /// Space `pad` is expressed in. Absent means pixel space.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub pad_space: Option<PadSpace>,
}

/// Logical output: the semantic contract the model exposes.
///
/// When `outputs` is empty, the logical output IS the physical tensor
/// (`dtype` and `quantization` carry the tensor-level fields directly).
/// When `outputs` contains one or more [`PhysicalOutput`] entries, those
/// children are the real physical tensors and the logical `shape` is
/// the reconstructed shape produced by the fallback merge path.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct LogicalOutput {
    /// Logical output name (optional at the logical level).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,

    /// Semantic type. `None` marks the output as "additional" — carried in
    /// the schema for completeness (e.g. diagnostic or auxiliary tensors)
    /// but not participating in decoder dispatch. See
    /// [`SchemaV2::to_legacy_config_outputs`] for how typeless outputs are
    /// filtered out of the legacy config, and the module docs for when to
    /// use this vs. a recognised [`LogicalType`] variant.
    #[serde(rename = "type", default, skip_serializing_if = "Option::is_none")]
    pub type_: Option<LogicalType>,

    /// Reconstructed logical shape (what the fallback dequant+merge path
    /// produces).
    pub shape: Vec<usize>,

    /// Named dimensions ordered to match `shape`.
    #[serde(
        default,
        deserialize_with = "deserialize_dshape",
        skip_serializing_if = "Vec::is_empty"
    )]
    pub dshape: Vec<(DimName, usize)>,

    /// Decoder to use for post-processing. Omitted for outputs consumed
    /// directly (e.g. `protos`) where no decode step is required.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub decoder: Option<DecoderKind>,

    /// Box encoding. Required on `boxes` logical outputs in v2.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub encoding: Option<BoxEncoding>,

    /// Score format. Scores only.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub score_format: Option<ScoreFormat>,

    /// Coordinate format. `true` means `[0, 1]` normalized; `false` means
    /// pixel coordinates relative to the letterboxed model input. `None`
    /// means unspecified (decoder must infer). `boxes` and `detections`
    /// only.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub normalized: Option<bool>,

    /// Anchor boxes for anchor-encoded logical outputs. Required when
    /// `encoding: anchor`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub anchors: Option<Vec<[f32; 2]>>,

    /// Spatial stride. For non-split logical outputs this is a spatial
    /// hint (e.g. `protos` at stride 4). For per-scale splits each child
    /// carries its own `stride` instead.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub stride: Option<Stride>,

    /// Tensor dtype. Present when `outputs` is empty (this logical IS the
    /// physical tensor).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub dtype: Option<DType>,

    /// Quantization parameters. Present when `outputs` is empty. `None`
    /// means the tensor is not quantized (float model).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub quantization: Option<Quantization>,

    /// Physical children that realize this logical output. Empty when the
    /// logical IS the physical tensor. At most one level of nesting is
    /// permitted.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub outputs: Vec<PhysicalOutput>,

    /// Activation already applied by the model graph or runtime. The
    /// HAL must NOT re-apply an activation declared here.
    ///
    /// On per-scale models the converter writes this on the logical
    /// parent (e.g. `scores.activation_applied = sigmoid`) when the
    /// model graph already includes the activation; the per-physical
    /// children inherit it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub activation_applied: Option<Activation>,

    /// Activation NOT yet applied. The HAL MUST apply the declared
    /// activation before consuming the tensor.
    ///
    /// On per-scale models the converter writes this on the logical
    /// parent (e.g. `scores.activation_required = sigmoid`) when the
    /// score-activation step was stripped from the model graph and
    /// must be re-applied by the runtime; per-physical children
    /// inherit the parent's declaration.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub activation_required: Option<Activation>,

    /// Semantic segmentation decode fields (`decoder: semantic` and the
    /// mask-classification types). Serialized flat on the logical output.
    #[serde(flatten)]
    pub semantic: SemanticParams,
}

/// Semantic segmentation decode fields of a logical output.
///
/// Serialized flat alongside the other logical-output fields. All fields
/// are optional; absent means the decoder default.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct SemanticParams {
    /// Upsampling of the score map to the requested resolution.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub upsample: Option<Upsample>,

    /// Default decode mode; callers may override it at runtime.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub decode_mode: Option<DecodeMode>,

    /// Foreground threshold for single-channel outputs, in the space of
    /// the tensor after `activation_applied` (probability for sigmoid,
    /// logit otherwise).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub threshold: Option<f32>,

    /// Channel index of the background class, when the model has one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub background_index: Option<u32>,

    /// `class_logits` only: index of the "no object" class. Absent means
    /// the last class.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub no_object_index: Option<u32>,

    /// `mask_logits` only: activation applied across the mask logits.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mask_activation: Option<MaskActivation>,
}

/// Score-map upsampling.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct Upsample {
    /// Resampling filter.
    pub method: UpsampleMethod,
    /// PyTorch `align_corners` semantics for bilinear and bicubic.
    #[serde(default)]
    pub align_corners: bool,
}

/// Score-map upsampling filter.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum UpsampleMethod {
    Bilinear,
    Nearest,
    Bicubic,
}

edgefirst_tensor::ef_vocabulary! {
    /// Semantic decode mode. The code is the one the C `EF_DECODE_MODE_*`
    /// enumerators and the Python `DecodeMode` enum use; the string is the
    /// `edgefirst.json` name and the `decode` override grammar.
    #[derive(Serialize, Deserialize)]
    #[serde(rename_all = "snake_case")]
    #[non_exhaustive]
    pub enum DecodeMode {
        /// Upsample class scores, then argmax (reference).
        Accurate = 0, "accurate", ACCURATE,
        /// Argmax at output resolution, then nearest upsample of the class map.
        Fast = 1, "fast", FAST,
    }
    #[doc(hidden)]
    pub mod decode_mode_code;
}

/// Activation over mask-classification mask logits.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum MaskActivation {
    /// Independent sigmoid per query (MaskFormer, Mask2Former, OneFormer).
    Sigmoid,
    /// Softmax across the query axis (kMaX-DeepLab).
    SoftmaxOverQueries,
}

impl LogicalOutput {
    /// Returns `true` if this logical output has been split into physical
    /// children by the converter.
    pub fn is_split(&self) -> bool {
        !self.outputs.is_empty()
    }
}

/// Physical output: a concrete tensor produced by the converter.
///
/// Physical outputs carry only tensor-level fields (`dtype`,
/// `quantization`, `stride`, `activation_applied`/`activation_required`).
/// Semantic fields live on the [`LogicalOutput`] parent.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PhysicalOutput {
    /// Physical tensor name as produced by the converter. This name is
    /// used to bind the metadata to the tensor returned by the inference
    /// runtime.
    pub name: String,

    /// Semantic type. Matches the parent's type or declares a sub-split
    /// such as `boxes_xy` or `boxes_wh`. `None` marks the child as
    /// type-opaque: it still binds to a physical tensor by `name`/`shape`
    /// during merging, but is not used to disambiguate against typed
    /// siblings. Useful when a converter emits extra per-scale tensors
    /// the HAL has no semantic for but the user manages downstream.
    #[serde(rename = "type", default, skip_serializing_if = "Option::is_none")]
    pub type_: Option<PhysicalType>,

    /// Physical tensor shape.
    pub shape: Vec<usize>,

    /// Named dimensions ordered to match `shape`. Disambiguates NHWC vs
    /// NCHW per-child rather than assuming a model-wide layout.
    #[serde(
        default,
        deserialize_with = "deserialize_dshape",
        skip_serializing_if = "Vec::is_empty"
    )]
    pub dshape: Vec<(DimName, usize)>,

    /// Quantized data type.
    pub dtype: DType,

    /// Quantization parameters. Always present in v2; `null` means float
    /// (no quantization).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub quantization: Option<Quantization>,

    /// FPN stride. Present on per-scale splits; absent on channel
    /// sub-splits (e.g. `boxes_xy`/`boxes_wh`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub stride: Option<Stride>,

    /// Zero-based index into the parent's strides array. Used for
    /// parallel iteration with precomputed per-scale state.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scale_index: Option<usize>,

    /// Activation already applied by the NPU. The HAL must NOT re-apply
    /// an activation declared here (e.g. Hailo applies sigmoid to score
    /// tensors on-chip).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub activation_applied: Option<Activation>,

    /// Activation NOT yet applied. The HAL MUST apply the declared
    /// activation before consuming the tensor.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub activation_required: Option<Activation>,
}

/// Quantization parameters for a quantized tensor.
///
/// Supports per-tensor (scalar `scale`) and per-channel (array `scale`)
/// quantization. Symmetric quantization is indicated by an absent or
/// all-zero `zero_point`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Quantization {
    /// Scale factor(s). One element for per-tensor quantization, or one
    /// element per slice for per-channel quantization.
    #[serde(deserialize_with = "deserialize_scalar_or_vec_f32")]
    pub scale: Vec<f32>,

    /// Zero point offset(s). Omit or set to all-zero for symmetric
    /// quantization. For per-channel quantization, length must match
    /// `scale` length.
    #[serde(
        default,
        deserialize_with = "deserialize_opt_scalar_or_vec_i32",
        skip_serializing_if = "Option::is_none"
    )]
    pub zero_point: Option<Vec<i32>>,

    /// Tensor dimension index that `scale`/`zero_point` arrays correspond
    /// to. Required when per-channel; ignored otherwise.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub axis: Option<usize>,

    /// Quantized data type. Required on v2 metadata files; may be absent
    /// on programmatically-constructed configurations where the dtype is
    /// resolved at decode time from the actual tensor.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub dtype: Option<DType>,
}

impl Quantization {
    /// Returns `true` when per-tensor (scalar scale).
    pub fn is_per_tensor(&self) -> bool {
        self.scale.len() == 1
    }

    /// Returns `true` when per-channel (array scale of length > 1).
    pub fn is_per_channel(&self) -> bool {
        self.scale.len() > 1
    }

    /// Returns `true` when all zero points are 0 (or absent).
    pub fn is_symmetric(&self) -> bool {
        match &self.zero_point {
            None => true,
            Some(zps) => zps.iter().all(|&z| z == 0),
        }
    }

    /// Returns the zero point for the given channel index, or 0 when the
    /// quantization is symmetric.
    pub fn zero_point_at(&self, channel: usize) -> i32 {
        match &self.zero_point {
            None => 0,
            Some(zps) if zps.len() == 1 => zps[0],
            Some(zps) => zps.get(channel).copied().unwrap_or(0),
        }
    }

    /// Returns the scale for the given channel index.
    pub fn scale_at(&self, channel: usize) -> f32 {
        if self.scale.len() == 1 {
            self.scale[0]
        } else {
            self.scale.get(channel).copied().unwrap_or(0.0)
        }
    }
}

/// Convert a schema-level `Quantization` (which also carries the quantized
/// `dtype`) into the tensor-crate `edgefirst_tensor::Quantization` attached
/// to a `Tensor<T>` at runtime. The `dtype` field is dropped — the tensor's
/// `T` supplies the storage element type directly.
///
/// Returns `Err` on any length-mismatch / axis-out-of-range condition; the
/// schema's `Quantization::validate_shape` has looser rules (accepts absent
/// axis on per-channel) that the tensor crate does not. Callers should prefer
/// the v2 parse path which normalizes.
impl TryFrom<&Quantization> for edgefirst_tensor::Quantization {
    type Error = edgefirst_tensor::Error;

    fn try_from(q: &Quantization) -> Result<Self, Self::Error> {
        match (q.scale.as_slice(), q.zero_point.as_deref(), q.axis) {
            // Per-tensor symmetric: single scale, no zp, no axis.
            ([scale], None, None) => Ok(Self::per_tensor_symmetric(*scale)),
            // Per-tensor asymmetric: single scale, single zp.
            ([scale], Some([zp]), None) => Ok(Self::per_tensor(*scale, *zp)),
            // Per-tensor asymmetric with redundant axis — treat as per-tensor.
            ([scale], Some([zp]), Some(_)) => Ok(Self::per_tensor(*scale, *zp)),
            ([scale], None, Some(_)) => Ok(Self::per_tensor_symmetric(*scale)),
            // Per-channel — axis required.
            (scales, None, Some(axis)) if scales.len() > 1 => {
                Self::per_channel_symmetric(scales.to_vec(), axis)
            }
            (scales, Some(zps), Some(axis)) if scales.len() > 1 => {
                Self::per_channel(scales.to_vec(), zps.to_vec(), axis)
            }
            // Per-channel without axis — invalid.
            (scales, _, None) if scales.len() > 1 => {
                Err(edgefirst_tensor::Error::QuantizationInvalid {
                    field: "axis",
                    expected: "Some(axis) for per-channel".into(),
                    got: "None".into(),
                })
            }
            _ => Err(edgefirst_tensor::Error::QuantizationInvalid {
                field: "scale",
                expected: "non-empty".into(),
                got: format!("len={}", q.scale.len()),
            }),
        }
    }
}

/// Accept a scalar or a JSON array when deserializing a `Vec<f32>`.
fn deserialize_scalar_or_vec_f32<'de, D>(de: D) -> Result<Vec<f32>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    #[derive(Deserialize)]
    #[serde(untagged)]
    enum OneOrMany {
        One(f32),
        Many(Vec<f32>),
    }
    match OneOrMany::deserialize(de)? {
        OneOrMany::One(v) => Ok(vec![v]),
        OneOrMany::Many(vs) => Ok(vs),
    }
}

/// Accept a scalar or a JSON array when deserializing an `Option<Vec<i32>>`.
fn deserialize_opt_scalar_or_vec_i32<'de, D>(de: D) -> Result<Option<Vec<i32>>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    #[derive(Deserialize)]
    #[serde(untagged)]
    enum OneOrMany {
        One(i32),
        Many(Vec<i32>),
    }
    match Option::<OneOrMany>::deserialize(de)? {
        None => Ok(None),
        Some(OneOrMany::One(v)) => Ok(Some(vec![v])),
        Some(OneOrMany::Many(vs)) => Ok(Some(vs)),
    }
}

/// FPN stride. `Square(s)` means `(s, s)`; `Rect(sx, sy)` supports
/// non-square inputs.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(untagged)]
pub enum Stride {
    Square(u32),
    Rect([u32; 2]),
}

impl Stride {
    /// Horizontal stride.
    pub fn x(self) -> u32 {
        match self {
            Stride::Square(s) => s,
            Stride::Rect([sx, _]) => sx,
        }
    }

    /// Vertical stride.
    pub fn y(self) -> u32 {
        match self {
            Stride::Square(s) => s,
            Stride::Rect([_, sy]) => sy,
        }
    }
}

/// Semantic type of a logical output.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum LogicalType {
    /// Bounding box coordinates.
    Boxes,
    /// Per-class or class-aggregate scores.
    Scores,
    /// Objectness scores (YOLOv5-style `obj_x_class`).
    Objectness,
    /// End-to-end class indices.
    Classes,
    /// Mask coefficients for instance segmentation.
    MaskCoefs,
    /// Instance segmentation prototypes.
    Protos,
    /// Facial / keypoint landmarks.
    Landmarks,
    /// Fully decoded post-NMS detections (end-to-end models).
    Detections,
    /// Semantic segmentation per-pixel class scores (ModelPack, or any
    /// per-pixel model with `decoder: semantic`).
    Segmentation,
    /// Semantic segmentation class map: argmax already applied in the
    /// graph, one class index per pixel.
    Masks,
    /// ModelPack anchor-grid raw output requiring anchor decode.
    Detection,
    /// Mask-classification per-query class logits `[1, Q, K+1]`.
    /// Reserved: described by the schema, not yet decoded by the HAL.
    ClassLogits,
    /// Mask-classification per-query mask logits `[1, Q, H, W]`.
    /// Reserved: described by the schema, not yet decoded by the HAL.
    MaskLogits,
}

/// Semantic type of a physical output.
///
/// Physical outputs either share their parent's type (per-scale splits
/// carry the parent's name) or declare a channel sub-split such as
/// `boxes_xy` / `boxes_wh`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PhysicalType {
    Boxes,
    Scores,
    Objectness,
    Classes,
    MaskCoefs,
    Protos,
    Landmarks,
    Detections,
    Segmentation,
    Masks,
    Detection,
    ClassLogits,
    MaskLogits,
    /// ARA-2 xy channel sub-split.
    BoxesXy,
    /// ARA-2 wh channel sub-split.
    BoxesWh,
}

/// Box encoding for `boxes` logical outputs.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum BoxEncoding {
    /// Distribution Focal Loss: `reg_max × 4` channels, softmax +
    /// weighted sum recovers 4 coordinates (YOLOv8, YOLO11).
    Dfl,
    /// Direct 4-channel coordinates, already decoded (YOLO26,
    /// ARA-2 post-split).
    #[serde(alias = "ltrb")]
    Direct,
    /// Anchor-based grid offsets with sigmoid + anchor-scale transform
    /// per cell (YOLOv5, SSD MobileNet, ModelPack).
    Anchor,
}

/// Score format for `scores` logical outputs.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ScoreFormat {
    /// Each anchor outputs `[nc]` class probabilities directly
    /// (YOLOv8, YOLO11, YOLO26).
    PerClass,
    /// Each anchor outputs `[nc]` class probabilities; final confidence
    /// is `objectness × class_score` via a separate `objectness` logical
    /// output (YOLOv5).
    ObjXClass,
}

/// Activation function applied to or required by a physical tensor.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Activation {
    Sigmoid,
    Softmax,
    Tanh,
}

/// Decoder framework for a logical output.
///
/// Numbered by [`configs::DecoderType`], the declaration of this
/// vocabulary; see [`DecoderKind::code`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[repr(u32)]
pub enum DecoderKind {
    /// Au-Zone ModelPack anchor-based YOLO decoder.
    #[serde(rename = "modelpack")]
    ModelPack = configs::decoder_type_code::MODELPACK,
    /// Ultralytics anchor-free DFL decoder (YOLOv5/v8/v11/v26).
    #[serde(rename = "ultralytics")]
    Ultralytics = configs::decoder_type_code::ULTRALYTICS,
    /// Generic semantic segmentation decoder (per-pixel scores or class
    /// map).
    #[serde(rename = "semantic")]
    Semantic = configs::decoder_type_code::SEMANTIC,
}

impl DecoderKind {
    /// The shared code, identical to [`configs::DecoderType::code`].
    pub const fn code(self) -> u32 {
        self as u32
    }
}

/// YOLO architecture version for Ultralytics decoders.
///
/// Numbered by [`configs::DecoderVersion`], the declaration of this
/// vocabulary; see [`DecoderVersion::code`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[repr(u32)]
pub enum DecoderVersion {
    Yolov5 = configs::decoder_version_code::YOLOV5,
    Yolov8 = configs::decoder_version_code::YOLOV8,
    Yolo11 = configs::decoder_version_code::YOLO11,
    Yolo26 = configs::decoder_version_code::YOLO26,
}

impl DecoderVersion {
    /// The shared code, identical to [`configs::DecoderVersion::code`].
    pub const fn code(self) -> u32 {
        self as u32
    }

    /// Returns `true` for architectures with embedded NMS (YOLO26).
    pub fn is_end_to_end(self) -> bool {
        matches!(self, DecoderVersion::Yolo26)
    }
}

/// HAL NMS mode.
///
/// Numbered by [`configs::Nms`], the declaration of this vocabulary; see
/// [`NmsMode::code`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[repr(u32)]
pub enum NmsMode {
    /// Suppress overlapping boxes regardless of class label.
    ClassAgnostic = configs::nms_code::CLASS_AGNOSTIC,
    /// Only suppress boxes sharing a class label and overlapping above
    /// the IoU threshold.
    ClassAware = configs::nms_code::CLASS_AWARE,
}

/// Quantized or floating-point data type of a model's logical I/O.
///
/// A subset of [`edgefirst_tensor::DType`], numbered and named by it: the
/// discriminant is that enum's code and the serialized string is its
/// [`as_str`](edgefirst_tensor::DType::as_str) (`"i8"`, `"u8"`, ...,
/// `"f32"`). The older spellings (`"int8"`, `"uint8"`, ..., `"float32"`)
/// are still accepted on input; see [`DType::from_str_code`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u32)]
pub enum DType {
    Int8 = edgefirst_tensor::protocol::dtype::I8,
    Uint8 = edgefirst_tensor::protocol::dtype::U8,
    Int16 = edgefirst_tensor::protocol::dtype::I16,
    Uint16 = edgefirst_tensor::protocol::dtype::U16,
    Int32 = edgefirst_tensor::protocol::dtype::I32,
    Uint32 = edgefirst_tensor::protocol::dtype::U32,
    Float16 = edgefirst_tensor::protocol::dtype::F16,
    Float32 = edgefirst_tensor::protocol::dtype::F32,
    /// Class maps from an in-graph argmax (TensorFlow/TFLite exports).
    Int64 = edgefirst_tensor::protocol::dtype::I64,
}

/// The pre-`edgefirst_tensor::DType` spellings, accepted on input only.
const DTYPE_LEGACY_NAMES: [(&str, DType); 9] = [
    ("int8", DType::Int8),
    ("uint8", DType::Uint8),
    ("int16", DType::Int16),
    ("uint16", DType::Uint16),
    ("int32", DType::Int32),
    ("uint32", DType::Uint32),
    ("float16", DType::Float16),
    ("float32", DType::Float32),
    ("int64", DType::Int64),
];

impl DType {
    /// Every variant, for exhaustive cross-surface tests.
    pub fn all() -> &'static [DType] {
        &[
            DType::Int8,
            DType::Uint8,
            DType::Int16,
            DType::Uint16,
            DType::Int32,
            DType::Uint32,
            DType::Float16,
            DType::Float32,
            DType::Int64,
        ]
    }

    /// The shared code, identical to [`edgefirst_tensor::DType::code`].
    pub const fn code(self) -> u32 {
        self as u32
    }

    /// The tensor dtype with the same code.
    pub fn to_tensor_dtype(self) -> edgefirst_tensor::DType {
        match self {
            DType::Int8 => edgefirst_tensor::DType::I8,
            DType::Uint8 => edgefirst_tensor::DType::U8,
            DType::Int16 => edgefirst_tensor::DType::I16,
            DType::Uint16 => edgefirst_tensor::DType::U16,
            DType::Int32 => edgefirst_tensor::DType::I32,
            DType::Uint32 => edgefirst_tensor::DType::U32,
            DType::Float16 => edgefirst_tensor::DType::F16,
            DType::Float32 => edgefirst_tensor::DType::F32,
            DType::Int64 => edgefirst_tensor::DType::I64,
        }
    }

    /// The model I/O dtype for a tensor dtype; `None` for one a model's
    /// logical I/O does not carry (`u64`, `f64`).
    pub fn from_tensor_dtype(dtype: edgefirst_tensor::DType) -> Option<Self> {
        Self::all()
            .iter()
            .copied()
            .find(|d| d.code() == dtype.code())
    }

    /// Decode a shared code; `None` for an unknown code or a tensor dtype a
    /// model's logical I/O does not carry.
    pub fn from_code(code: u32) -> Option<Self> {
        edgefirst_tensor::DType::from_code(code).and_then(Self::from_tensor_dtype)
    }

    /// The string form, identical to [`edgefirst_tensor::DType::as_str`].
    pub fn as_str(self) -> &'static str {
        self.to_tensor_dtype().as_str()
    }

    /// Parse the string form, also accepting the older `"int8"`, `"uint8"`,
    /// ..., `"float32"` spellings.
    pub fn from_str_code(s: &str) -> Option<Self> {
        edgefirst_tensor::DType::from_str_code(s)
            .and_then(Self::from_tensor_dtype)
            .or_else(|| {
                DTYPE_LEGACY_NAMES
                    .iter()
                    .find(|(name, _)| *name == s)
                    .map(|(_, d)| *d)
            })
    }

    /// Every accepted input spelling, current and legacy.
    pub fn accepted_names() -> impl Iterator<Item = &'static str> {
        Self::all()
            .iter()
            .map(|d| d.as_str())
            .chain(DTYPE_LEGACY_NAMES.iter().map(|(name, _)| *name))
    }
}

impl Serialize for DType {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_str())
    }
}

impl<'de> Deserialize<'de> for DType {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let s = std::borrow::Cow::<'de, str>::deserialize(deserializer)?;
        DType::from_str_code(&s).ok_or_else(|| {
            let expected: Vec<&str> = DType::accepted_names().collect();
            serde::de::Error::custom(format!(
                "unknown dtype `{s}`, expected one of: {}",
                expected.join(", ")
            ))
        })
    }
}

impl DType {
    /// Returns the tensor's byte width per element.
    pub fn size_bytes(self) -> usize {
        match self {
            DType::Int8 | DType::Uint8 => 1,
            DType::Int16 | DType::Uint16 | DType::Float16 => 2,
            DType::Int32 | DType::Uint32 | DType::Float32 => 4,
            DType::Int64 => 8,
        }
    }

    /// Returns `true` for integer dtypes (quantized tensors).
    pub fn is_integer(self) -> bool {
        matches!(
            self,
            DType::Int8
                | DType::Uint8
                | DType::Int16
                | DType::Uint16
                | DType::Int32
                | DType::Uint32
                | DType::Int64
        )
    }

    /// Returns `true` for floating-point dtypes.
    pub fn is_float(self) -> bool {
        matches!(self, DType::Float16 | DType::Float32)
    }
}

// =============================================================================
// Parsing entry points + legacy v1 compatibility shim.
// =============================================================================

impl SchemaV2 {
    /// Parse schema metadata from a JSON string.
    ///
    /// Auto-detects the schema version from the `schema_version` field.
    /// Absent or `1` → legacy v1 metadata converted to v2 in memory.
    /// `2` → parsed as v2 directly. Any version higher than
    /// [`MAX_SUPPORTED_SCHEMA_VERSION`] is rejected with
    /// [`DecoderError::NotSupported`].
    pub fn parse_json(s: &str) -> DecoderResult<Self> {
        let value: serde_json::Value = serde_json::from_str(s)?;
        Self::from_json_value(value)
    }

    /// Parse schema metadata from a YAML string.
    ///
    /// Same version-detection logic as [`SchemaV2::parse_json`].
    pub fn parse_yaml(s: &str) -> DecoderResult<Self> {
        let value: serde_yaml::Value = serde_yaml::from_str(s)?;
        let json = serde_json::to_value(value)
            .map_err(|e| DecoderError::InvalidConfig(format!("yaml→json bridge failed: {e}")))?;
        Self::from_json_value(json)
    }

    /// Parse schema metadata from a file, auto-detecting JSON vs YAML
    /// from the file extension. Unknown extensions are parsed as JSON
    /// first then as YAML as a fallback.
    pub fn parse_file(path: impl AsRef<std::path::Path>) -> DecoderResult<Self> {
        let path = path.as_ref();
        let content = std::fs::read_to_string(path)
            .map_err(|e| DecoderError::InvalidConfig(format!("read {}: {e}", path.display())))?;
        let ext = path
            .extension()
            .and_then(|e| e.to_str())
            .map(str::to_ascii_lowercase);
        match ext.as_deref() {
            Some("json") => Self::parse_json(&content),
            Some("yaml") | Some("yml") => Self::parse_yaml(&content),
            _ => Self::parse_json(&content).or_else(|_| Self::parse_yaml(&content)),
        }
    }

    /// Parse from an already-deserialized `serde_json::Value`. Useful for
    /// callers that have already done the initial deserialization step.
    pub fn from_json_value(value: serde_json::Value) -> DecoderResult<Self> {
        let version = value
            .get("schema_version")
            .and_then(|v| v.as_u64())
            .map(|v| v as u32)
            .unwrap_or(1);

        if version > MAX_SUPPORTED_SCHEMA_VERSION {
            return Err(DecoderError::NotSupported(format!(
                "schema_version {version} is not supported by this HAL \
                 (maximum supported version is {MAX_SUPPORTED_SCHEMA_VERSION}); \
                 upgrade the HAL or downgrade the metadata"
            )));
        }

        if version >= 2 {
            serde_json::from_value(value).map_err(DecoderError::Json)
        } else {
            let v1: ConfigOutputs = serde_json::from_value(value).map_err(DecoderError::Json)?;
            Self::from_v1(&v1)
        }
    }

    /// Convert a legacy v1 [`ConfigOutputs`] to an equivalent v2
    /// [`SchemaV2`] in memory.
    ///
    /// The conversion preserves:
    /// - Output order and types (mapped to their v2 [`LogicalType`]).
    /// - Quantization (v1 `QuantTuple(scale, zp)` → v2 [`Quantization`] with
    ///   a single scalar scale/zero_point and unspecified dtype).
    /// - `dshape`, `shape`, `anchors`, `normalized` fields.
    /// - Root-level `nms` and `decoder_version`.
    ///
    /// Fields v1 does not carry (tensor `dtype`, per-channel quant, box
    /// encoding, score format, activation metadata, stride on physical
    /// children) are left as `None`. The v2 decoder is expected to infer
    /// these from the runtime tensor type and the legacy decoder
    /// dispatch rules.
    pub fn from_v1(v1: &ConfigOutputs) -> DecoderResult<Self> {
        let outputs = v1
            .outputs
            .iter()
            .map(logical_from_v1)
            .collect::<DecoderResult<Vec<_>>>()?;
        Ok(SchemaV2 {
            schema_version: 2,
            input: None,
            outputs,
            nms: v1.nms.as_ref().and_then(NmsMode::from_v1),
            nms_multi_label: v1.nms_multi_label,
            decoder_version: v1.decoder_version.as_ref().map(DecoderVersion::from_v1),
        })
    }
}

impl SchemaV2 {
    /// Downconvert a v2 schema to a legacy [`ConfigOutputs`] for the
    /// v1 decoder dispatch path.
    ///
    /// Each [`LogicalOutput`] maps to one [`ConfigOutput`] variant
    /// selected by [`LogicalType`]; per-tensor scalar quantization
    /// becomes a `QuantTuple(scale, zp)`; and `decoder`, `anchors`,
    /// `normalized` are copied verbatim.
    ///
    /// This conversion does **not** reject logical outputs that also
    /// declare physical children (per-scale FPN splits, or channel
    /// sub-splits such as ARA-2 `boxes_xy` / `boxes_wh`). The returned
    /// legacy config captures the logical-level metadata, while the
    /// physical-to-logical merge is handled separately by the
    /// `DecodeProgram` that
    /// [`DecoderBuilder::build`](crate::DecoderBuilder::build)
    /// compiles alongside this legacy config.
    ///
    /// Returns [`DecoderError::NotSupported`] when the schema uses
    /// features the v1 decoder cannot express at the logical level:
    /// - Per-channel quantization arrays on a logical output.
    /// - `encoding: dfl` on a **flat** logical output (no physical
    ///   children). DFL combined with per-scale children is handled by
    ///   the merge path (see `DecodeProgram`)
    ///   which decodes the distribution before producing the merged
    ///   post-decode `(1, 4, total_anchors)` tensor the legacy decoder
    ///   consumes.
    pub fn to_legacy_config_outputs(&self) -> DecoderResult<ConfigOutputs> {
        let mut outputs = Vec::with_capacity(self.outputs.len());
        for logical in &self.outputs {
            // Typeless logical outputs are carried for round-tripping
            // but are not required for decoding. Skip them — the decoder
            // builder will surface its own "missing required output"
            // error if a decode-critical role (e.g. `boxes`) is absent,
            // which is more actionable than a serde "missing type" error.
            if logical.type_.is_none() {
                continue;
            }
            // Flat DFL (no children) remains unsupported — the HAL has
            // no path that applies softmax + dist2bbox to a single
            // `(1, 4·reg_max, anchors)` tensor yet. DFL with per-scale
            // children is decoded by the merge path, so we let it
            // through here and rely on the merged logical shape (post-
            // decode 4 channels) being valid for the legacy dispatch.
            if logical.type_ == Some(LogicalType::Boxes)
                && logical.encoding == Some(BoxEncoding::Dfl)
                && logical.outputs.is_empty()
            {
                return Err(DecoderError::NotSupported(format!(
                    "`boxes` output `{}` has `encoding: dfl` on a flat \
                     logical (no per-scale children); the HAL's DFL \
                     decode kernel only runs inside the per-scale merge \
                     path. Split the boxes output into per-FPN-level \
                     children (Hailo convention) or pre-decode to 4 \
                     channels in the model graph (TFLite convention).",
                    logical.name.as_deref().unwrap_or("<anonymous>"),
                )));
            }
            if let Some(q) = &logical.quantization {
                if q.is_per_channel() {
                    return Err(DecoderError::NotSupported(format!(
                        "logical `{}` uses per-channel quantization \
                         (axis {:?}, {} scales); the v1 decoder only \
                         supports per-tensor quantization",
                        logical.name.as_deref().unwrap_or("<anonymous>"),
                        q.axis,
                        q.scale.len(),
                    )));
                }
            }
            outputs.push(logical_to_legacy_config_output(logical)?);
        }
        Ok(ConfigOutputs {
            outputs,
            nms: self.nms.map(NmsMode::to_v1),
            nms_multi_label: self.nms_multi_label,
            decoder_version: self.decoder_version.map(|v| v.to_v1()),
        })
    }

    /// Validate the schema against the rules the HAL enforces.
    ///
    /// Rules checked:
    /// - `schema_version` in `[1, MAX_SUPPORTED_SCHEMA_VERSION]`.
    /// - Physical children, when present, carry non-empty `name` fields
    ///   so tensor binding by name is unambiguous.
    /// - All physical children of a given logical output have pairwise
    ///   distinct shapes (shape-based binding safety, per HailoRT spec).
    /// - For a `boxes` logical output with `encoding: dfl`, every
    ///   physical child shape has a `num_features` (or last) dimension
    ///   divisible by 4 (the box-coordinate count).
    /// - Per-scale splits carry `stride` on every child.
    /// - Mixed per-scale + channel-sub-split decompositions are
    ///   rejected (the spec permits only one merge strategy per logical).
    /// - `end2end` models (decoder_version=yolo26 with `detections`
    ///   output) do not also declare per-scale split children on that
    ///   output.
    pub fn validate(&self) -> DecoderResult<()> {
        if self.schema_version == 0 || self.schema_version > MAX_SUPPORTED_SCHEMA_VERSION {
            return Err(DecoderError::InvalidConfig(format!(
                "schema_version {} outside supported range [1, {MAX_SUPPORTED_SCHEMA_VERSION}]",
                self.schema_version
            )));
        }

        if let Some(input) = &self.input {
            if let Some(pre) = &input.preprocessing {
                validate_preprocessing(input, pre)?;
            }
        }

        for logical in &self.outputs {
            validate_logical(logical)?;
        }

        Ok(())
    }
}

fn validate_preprocessing(input: &InputSpec, pre: &Preprocessing) -> DecoderResult<()> {
    let channels = input.channels();
    let mut vectors: Vec<(&str, &[f32])> = Vec::new();
    if let Some(NormalizationConfig::MeanStd { mean, std }) = &pre.normalization {
        vectors.push(("normalization mean", mean));
        vectors.push(("normalization std", std));
    }
    if let Some(pad) = pre.letterbox.as_ref().and_then(|l| l.pad.as_ref()) {
        vectors.push(("letterbox pad", pad));
    }

    // A single value broadcasts; longer vectors must match the input
    // channels, or each other when the channel count is unknown.
    let mut expected = channels;
    for (field, values) in &vectors {
        if values.is_empty() || values.iter().any(|v| !v.is_finite()) {
            return Err(DecoderError::InvalidConfig(format!(
                "{field} {values:?} must hold one or more finite values"
            )));
        }
        if values.len() == 1 {
            continue;
        }
        match expected {
            Some(n) if n != values.len() => {
                return Err(DecoderError::InvalidConfig(format!(
                    "{field} has {} values; expected 1 or {n} (one per input channel)",
                    values.len()
                )));
            }
            Some(_) => {}
            None => expected = Some(values.len()),
        }
    }

    if let Some(norm) = &pre.normalization {
        let n = match (norm, expected) {
            (_, Some(n)) => n,
            // Presets other than imagenet and scalar coefficients are
            // channel-agnostic; imagenet is RGB.
            (NormalizationConfig::Preset(NormalizationPreset::Imagenet), None) => 3,
            (_, None) => 1,
        };
        norm.mean_std(n)?;
    }
    Ok(())
}

fn validate_logical(logical: &LogicalOutput) -> DecoderResult<()> {
    if logical.outputs.is_empty() {
        return Ok(());
    }

    // All children must carry a name for unambiguous tensor binding.
    for child in &logical.outputs {
        if child.name.is_empty() {
            return Err(DecoderError::InvalidConfig(format!(
                "physical child of logical `{}` is missing `name`; name is \
                 required for tensor binding",
                logical.name.as_deref().unwrap_or("<anonymous>")
            )));
        }
    }

    // Uniqueness of physical child shapes *within the same type* — two
    // children with distinct types (e.g. ARA-2 `boxes_xy` + `boxes_wh`)
    // may legitimately share shape, since type disambiguates the binding.
    //
    // Typeless children are excluded from this check: shape uniqueness
    // only matters when we need to bind a tensor by type+shape, and
    // typeless children are treated as opaque passthrough — name-based
    // binding still disambiguates them from each other.
    for (i, a) in logical.outputs.iter().enumerate() {
        for b in &logical.outputs[i + 1..] {
            let (Some(ta), Some(tb)) = (a.type_, b.type_) else {
                continue;
            };
            if a.shape == b.shape && ta == tb {
                return Err(DecoderError::InvalidConfig(format!(
                    "physical children `{}` and `{}` share shape {:?} and \
                     type; tensor binding cannot be resolved",
                    a.name, b.name, a.shape
                )));
            }
        }
    }

    // Merge strategy must be uniform: either all children carry `stride`
    // (per-scale split) or none (channel sub-split). Mixed decompositions
    // are ill-defined.
    let strided: Vec<_> = logical.outputs.iter().map(|c| c.stride.is_some()).collect();
    let all_strided = strided.iter().all(|&b| b);
    let none_strided = strided.iter().all(|&b| !b);
    if !(all_strided || none_strided) {
        return Err(DecoderError::InvalidConfig(format!(
            "logical `{}` mixes per-scale children (with stride) and \
             channel sub-split children (without stride); decomposition \
             must be uniform",
            logical.name.as_deref().unwrap_or("<anonymous>")
        )));
    }

    // DFL boxes: every child's feature axis must be divisible by 4
    // (otherwise `reg_max` is not an integer).
    if logical.type_ == Some(LogicalType::Boxes) && logical.encoding == Some(BoxEncoding::Dfl) {
        for child in &logical.outputs {
            if let Some(feat) = last_feature_axis(child) {
                if feat % 4 != 0 {
                    return Err(DecoderError::InvalidConfig(format!(
                        "DFL boxes child `{}` feature axis {feat} is not \
                         divisible by 4 (reg_max×4)",
                        child.name
                    )));
                }
            }
        }
    }

    Ok(())
}

/// Resolve the channel / feature count from a physical child's dshape
/// when present, otherwise from the last dimension of its shape.
pub(crate) fn last_feature_axis(child: &PhysicalOutput) -> Option<usize> {
    // Prefer explicit named dimensions: NumFeatures, NumClasses,
    // NumProtos, BoxCoords, NumAnchorsXFeatures.
    for (name, size) in &child.dshape {
        if matches!(
            name,
            DimName::NumFeatures
                | DimName::NumClasses
                | DimName::NumProtos
                | DimName::BoxCoords
                | DimName::NumAnchorsXFeatures
        ) {
            return Some(*size);
        }
    }
    child.shape.last().copied()
}

fn quantization_from_v1(q: Option<QuantTuple>) -> Option<Quantization> {
    q.map(|QuantTuple(scale, zp)| Quantization {
        scale: vec![scale],
        zero_point: Some(vec![zp]),
        axis: None,
        dtype: None,
    })
}

fn logical_from_v1(v1: &ConfigOutput) -> DecoderResult<LogicalOutput> {
    match v1 {
        ConfigOutput::Detection(d) => {
            // v1 Detection covers two semantic cases that v2 separates:
            //   - ModelPack anchor-grid (decoder=modelpack, anchors present)
            //   - YOLO legacy combined (decoder=ultralytics, no anchors)
            // Both map to v2 LogicalType::Detection; the decoder dispatch
            // still differentiates via the `decoder` + `anchors` fields.
            let encoding = match (d.decoder, d.anchors.is_some()) {
                (configs::DecoderType::ModelPack, true) => Some(BoxEncoding::Anchor),
                (configs::DecoderType::Ultralytics, _) => Some(BoxEncoding::Direct),
                // ModelPack without anchors — keep encoding unset; the
                // decoder may not need it.
                (configs::DecoderType::ModelPack, false) => None,
                (configs::DecoderType::Semantic, _) => None,
            };
            Ok(LogicalOutput {
                name: None,
                type_: Some(LogicalType::Detection),
                shape: d.shape.clone(),
                dshape: d.dshape.clone(),
                decoder: Some(DecoderKind::from_v1(d.decoder)),
                encoding,
                score_format: None,
                normalized: d.normalized,
                anchors: d.anchors.clone(),
                stride: None,
                dtype: None,
                quantization: quantization_from_v1(d.quantization),
                outputs: Vec::new(),
                activation_applied: None,
                activation_required: None,
                semantic: Default::default(),
            })
        }
        ConfigOutput::Boxes(b) => Ok(LogicalOutput {
            name: None,
            type_: Some(LogicalType::Boxes),
            shape: b.shape.clone(),
            dshape: b.dshape.clone(),
            decoder: Some(DecoderKind::from_v1(b.decoder)),
            // v1 boxes are always pre-decoded 4-channel (the legacy
            // convention). Explicitly declare Direct so the v2 dispatch
            // doesn't try DFL decoding on them.
            encoding: Some(BoxEncoding::Direct),
            score_format: None,
            normalized: b.normalized,
            anchors: None,
            stride: None,
            dtype: None,
            quantization: quantization_from_v1(b.quantization),
            outputs: Vec::new(),
            activation_applied: None,
            activation_required: None,
            semantic: Default::default(),
        }),
        ConfigOutput::Scores(s) => Ok(LogicalOutput {
            name: None,
            type_: Some(LogicalType::Scores),
            shape: s.shape.clone(),
            dshape: s.dshape.clone(),
            decoder: Some(DecoderKind::from_v1(s.decoder)),
            encoding: None,
            // v1 does not declare score format explicitly; assume per_class
            // (YOLOv8-style). YOLOv5 users must migrate to v2 to get
            // obj_x_class behaviour.
            score_format: Some(ScoreFormat::PerClass),
            normalized: None,
            anchors: None,
            stride: None,
            dtype: None,
            quantization: quantization_from_v1(s.quantization),
            outputs: Vec::new(),
            activation_applied: None,
            activation_required: None,
            semantic: Default::default(),
        }),
        ConfigOutput::Protos(p) => Ok(LogicalOutput {
            name: None,
            type_: Some(LogicalType::Protos),
            shape: p.shape.clone(),
            dshape: p.dshape.clone(),
            // protos are consumed directly; decoder field is informational.
            decoder: Some(DecoderKind::from_v1(p.decoder)),
            encoding: None,
            score_format: None,
            normalized: None,
            anchors: None,
            stride: None,
            dtype: None,
            quantization: quantization_from_v1(p.quantization),
            outputs: Vec::new(),
            activation_applied: None,
            activation_required: None,
            semantic: Default::default(),
        }),
        ConfigOutput::MaskCoefficients(m) => Ok(LogicalOutput {
            name: None,
            type_: Some(LogicalType::MaskCoefs),
            shape: m.shape.clone(),
            dshape: m.dshape.clone(),
            decoder: Some(DecoderKind::from_v1(m.decoder)),
            encoding: None,
            score_format: None,
            normalized: None,
            anchors: None,
            stride: None,
            dtype: None,
            quantization: quantization_from_v1(m.quantization),
            outputs: Vec::new(),
            activation_applied: None,
            activation_required: None,
            semantic: Default::default(),
        }),
        ConfigOutput::Segmentation(seg) => Ok(LogicalOutput {
            name: None,
            type_: Some(LogicalType::Segmentation),
            shape: seg.shape.clone(),
            dshape: seg.dshape.clone(),
            decoder: Some(DecoderKind::from_v1(seg.decoder)),
            encoding: None,
            score_format: None,
            normalized: None,
            anchors: None,
            stride: None,
            dtype: None,
            quantization: quantization_from_v1(seg.quantization),
            outputs: Vec::new(),
            activation_applied: None,
            activation_required: None,
            semantic: Default::default(),
        }),
        ConfigOutput::Mask(m) => Ok(LogicalOutput {
            name: None,
            type_: Some(LogicalType::Masks),
            shape: m.shape.clone(),
            dshape: m.dshape.clone(),
            decoder: Some(DecoderKind::from_v1(m.decoder)),
            encoding: None,
            score_format: None,
            normalized: None,
            anchors: None,
            stride: None,
            dtype: None,
            quantization: quantization_from_v1(m.quantization),
            outputs: Vec::new(),
            activation_applied: None,
            activation_required: None,
            semantic: Default::default(),
        }),
        ConfigOutput::Classes(c) => Ok(LogicalOutput {
            name: None,
            type_: Some(LogicalType::Classes),
            shape: c.shape.clone(),
            dshape: c.dshape.clone(),
            decoder: Some(DecoderKind::from_v1(c.decoder)),
            encoding: None,
            score_format: None,
            normalized: None,
            anchors: None,
            stride: None,
            dtype: None,
            quantization: quantization_from_v1(c.quantization),
            outputs: Vec::new(),
            activation_applied: None,
            activation_required: None,
            semantic: Default::default(),
        }),
    }
}

impl DecoderKind {
    /// Convert a legacy v1 [`configs::DecoderType`] to a v2 [`DecoderKind`].
    pub fn from_v1(v: configs::DecoderType) -> Self {
        match v {
            configs::DecoderType::ModelPack => DecoderKind::ModelPack,
            configs::DecoderType::Ultralytics => DecoderKind::Ultralytics,
            configs::DecoderType::Semantic => DecoderKind::Semantic,
        }
    }

    /// Convert back to the legacy v1 [`configs::DecoderType`].
    pub fn to_v1(self) -> configs::DecoderType {
        match self {
            DecoderKind::ModelPack => configs::DecoderType::ModelPack,
            DecoderKind::Ultralytics => configs::DecoderType::Ultralytics,
            DecoderKind::Semantic => configs::DecoderType::Semantic,
        }
    }
}

impl DecoderVersion {
    /// Convert a legacy v1 [`configs::DecoderVersion`] to a v2 [`DecoderVersion`].
    pub fn from_v1(v: &configs::DecoderVersion) -> Self {
        match v {
            configs::DecoderVersion::Yolov5 => DecoderVersion::Yolov5,
            configs::DecoderVersion::Yolov8 => DecoderVersion::Yolov8,
            configs::DecoderVersion::Yolo11 => DecoderVersion::Yolo11,
            configs::DecoderVersion::Yolo26 => DecoderVersion::Yolo26,
        }
    }

    /// Convert back to the legacy v1 [`configs::DecoderVersion`].
    pub fn to_v1(self) -> configs::DecoderVersion {
        match self {
            DecoderVersion::Yolov5 => configs::DecoderVersion::Yolov5,
            DecoderVersion::Yolov8 => configs::DecoderVersion::Yolov8,
            DecoderVersion::Yolo11 => configs::DecoderVersion::Yolo11,
            DecoderVersion::Yolo26 => configs::DecoderVersion::Yolo26,
        }
    }
}

impl NmsMode {
    /// The shared code, identical to [`configs::Nms::code`].
    pub const fn code(self) -> u32 {
        self as u32
    }

    /// Convert a legacy v1 [`configs::Nms`]; `Auto` defers to the builder default.
    pub fn from_v1(v: &configs::Nms) -> Option<Self> {
        match v {
            configs::Nms::Auto => None,
            configs::Nms::ClassAgnostic => Some(NmsMode::ClassAgnostic),
            configs::Nms::ClassAware => Some(NmsMode::ClassAware),
        }
    }

    /// Convert back to the legacy v1 [`configs::Nms`].
    pub fn to_v1(self) -> configs::Nms {
        match self {
            NmsMode::ClassAgnostic => configs::Nms::ClassAgnostic,
            NmsMode::ClassAware => configs::Nms::ClassAware,
        }
    }
}

/// Convert a quantized v2 [`Quantization`] to a v1 [`QuantTuple`]. Only
/// valid for per-tensor scalar quantization.
fn quantization_to_legacy(q: &Quantization) -> DecoderResult<QuantTuple> {
    if q.is_per_channel() {
        return Err(DecoderError::NotSupported(
            "per-channel quantization cannot be expressed as a v1 QuantTuple".into(),
        ));
    }
    let scale = *q.scale.first().unwrap_or(&0.0);
    let zp = q.zero_point_at(0);
    Ok(QuantTuple(scale, zp))
}

/// Drop axes named `padding` (always size 1 per spec) from the given
/// shape/dshape pair. ARA-2 emits logical shapes like
/// `[1, 4, 8400, 1]` with a trailing `padding=1` dim to satisfy the
/// converter's rank requirements — the decoder only cares about the
/// semantic axes, so squeezing is safe.
pub(crate) fn squeeze_padding_dims(
    shape: Vec<usize>,
    dshape: Vec<(DimName, usize)>,
) -> (Vec<usize>, Vec<(DimName, usize)>) {
    // dshape is `#[serde(default)]`; a logical output without named dims
    // arrives here with an empty dshape. `zip` would stop at the shorter
    // iterator and silently truncate shape to `[]`, so short-circuit.
    if dshape.is_empty() {
        return (shape, dshape);
    }
    let keep: Vec<bool> = dshape
        .iter()
        .map(|(n, _)| !matches!(n, DimName::Padding))
        .collect();
    let shape = shape
        .into_iter()
        .zip(keep.iter())
        .filter_map(|(s, &k)| k.then_some(s))
        .collect();
    let dshape = dshape
        .into_iter()
        .zip(keep.iter())
        .filter_map(|(d, &k)| k.then_some(d))
        .collect();
    (shape, dshape)
}

/// Return the list of axis indices in `dshape` that carry the
/// `padding` dim name. Indices are returned in descending order so
/// that `remove_axis` calls can be applied directly without tracking
/// index shifts.
pub(crate) fn padding_axes(dshape: &[(DimName, usize)]) -> Vec<usize> {
    let mut v: Vec<usize> = dshape
        .iter()
        .enumerate()
        .filter_map(|(i, (n, _))| matches!(n, DimName::Padding).then_some(i))
        .collect();
    v.sort_by(|a, b| b.cmp(a));
    v
}

fn logical_to_legacy_config_output(logical: &LogicalOutput) -> DecoderResult<ConfigOutput> {
    let decoder = match logical.decoder {
        None => configs::DecoderType::Ultralytics,
        Some(DecoderKind::Semantic) => {
            return Err(DecoderError::NotSupported(format!(
                "logical `{}` uses decoder `Semantic`, which this HAL \
                 version does not decode",
                logical.name.as_deref().unwrap_or("<anonymous>")
            )))
        }
        Some(kind) => kind.to_v1(),
    };
    let quantization = logical
        .quantization
        .as_ref()
        .map(quantization_to_legacy)
        .transpose()?;
    // Squeeze explicit `padding` dims before handing to the legacy
    // dispatch: the v1 decoder's `verify_yolo_*` helpers require rank-3
    // shapes, but v2 metadata often carries an explicit `padding: 1`
    // axis (ARA-2). ModelPack boxes are validated as 4D, so keep
    // padding dims for ModelPack outputs.
    let (shape, dshape) = match logical.decoder {
        Some(DecoderKind::ModelPack) => (logical.shape.clone(), logical.dshape.clone()),
        _ => squeeze_padding_dims(logical.shape.clone(), logical.dshape.clone()),
    };

    let ty = logical.type_.ok_or_else(|| {
        // Defense-in-depth: `to_legacy_config_outputs` already filters
        // typeless outputs, so reaching here means a new caller added a
        // bypass. Surface it as an internal error rather than panicking.
        DecoderError::InvalidConfig(format!(
            "logical output `{}` has no type; typeless outputs should be \
             filtered before legacy conversion",
            logical.name.as_deref().unwrap_or("<anonymous>")
        ))
    })?;

    let ctx = LegacyConvertCtx {
        decoder,
        quantization,
        shape,
        dshape,
        normalized: logical.normalized,
        anchors: logical.anchors.clone(),
    };

    match ty {
        LogicalType::Boxes => Ok(boxes_to_legacy(&ctx)),
        LogicalType::Scores => Ok(scores_to_legacy(&ctx)),
        LogicalType::Protos => Ok(protos_to_legacy(&ctx)),
        LogicalType::MaskCoefs => Ok(mask_coefs_to_legacy(&ctx)),
        LogicalType::Segmentation => Ok(segmentation_to_legacy(&ctx)),
        LogicalType::Masks => Ok(masks_to_legacy(&ctx)),
        LogicalType::Classes => Ok(classes_to_legacy(&ctx)),
        LogicalType::Detection | LogicalType::Detections => Ok(detection_to_legacy(&ctx)),
        // Objectness / Landmarks have no direct v1 equivalent; the v1
        // YOLOv5 path embedded objectness in the combined Detection.
        LogicalType::Objectness
        | LogicalType::Landmarks
        | LogicalType::ClassLogits
        | LogicalType::MaskLogits => Err(DecoderError::NotSupported(format!(
            "logical type {:?} has no legacy v1 equivalent; use the \
                 native v2 decoder path",
            ty
        ))),
    }
}

/// Shared fields for per-`LogicalType` legacy conversion helpers.
struct LegacyConvertCtx {
    decoder: configs::DecoderType,
    quantization: Option<QuantTuple>,
    shape: Vec<usize>,
    dshape: Vec<(DimName, usize)>,
    normalized: Option<bool>,
    anchors: Option<Vec<[f32; 2]>>,
}

fn boxes_to_legacy(ctx: &LegacyConvertCtx) -> ConfigOutput {
    ConfigOutput::Boxes(configs::Boxes {
        decoder: ctx.decoder,
        quantization: ctx.quantization,
        shape: ctx.shape.clone(),
        dshape: ctx.dshape.clone(),
        normalized: ctx.normalized,
    })
}

fn scores_to_legacy(ctx: &LegacyConvertCtx) -> ConfigOutput {
    ConfigOutput::Scores(configs::Scores {
        decoder: ctx.decoder,
        quantization: ctx.quantization,
        shape: ctx.shape.clone(),
        dshape: ctx.dshape.clone(),
    })
}

fn protos_to_legacy(ctx: &LegacyConvertCtx) -> ConfigOutput {
    ConfigOutput::Protos(configs::Protos {
        decoder: ctx.decoder,
        quantization: ctx.quantization,
        shape: ctx.shape.clone(),
        dshape: ctx.dshape.clone(),
    })
}

fn mask_coefs_to_legacy(ctx: &LegacyConvertCtx) -> ConfigOutput {
    ConfigOutput::MaskCoefficients(configs::MaskCoefficients {
        decoder: ctx.decoder,
        quantization: ctx.quantization,
        shape: ctx.shape.clone(),
        dshape: ctx.dshape.clone(),
    })
}

fn segmentation_to_legacy(ctx: &LegacyConvertCtx) -> ConfigOutput {
    ConfigOutput::Segmentation(configs::Segmentation {
        decoder: ctx.decoder,
        quantization: ctx.quantization,
        shape: ctx.shape.clone(),
        dshape: ctx.dshape.clone(),
    })
}

fn masks_to_legacy(ctx: &LegacyConvertCtx) -> ConfigOutput {
    ConfigOutput::Mask(configs::Mask {
        decoder: ctx.decoder,
        quantization: ctx.quantization,
        shape: ctx.shape.clone(),
        dshape: ctx.dshape.clone(),
    })
}

fn classes_to_legacy(ctx: &LegacyConvertCtx) -> ConfigOutput {
    ConfigOutput::Classes(configs::Classes {
        decoder: ctx.decoder,
        quantization: ctx.quantization,
        shape: ctx.shape.clone(),
        dshape: ctx.dshape.clone(),
    })
}

fn detection_to_legacy(ctx: &LegacyConvertCtx) -> ConfigOutput {
    // Detection covers ModelPack anchor-grid and legacy YOLO combined.
    // Detections (plural) is end-to-end; maps to Detection with the
    // appropriate dimension layout.
    ConfigOutput::Detection(configs::Detection {
        anchors: ctx.anchors.clone(),
        decoder: ctx.decoder,
        quantization: ctx.quantization,
        shape: ctx.shape.clone(),
        dshape: ctx.dshape.clone(),
        normalized: ctx.normalized,
    })
}

#[cfg(test)]
#[cfg_attr(coverage_nightly, coverage(off))]
mod tests {
    use super::*;

    #[test]
    fn nms_multi_label_true_round_trips_through_json() {
        let json = r#"{
            "schema_version": 2,
            "nms": "class_aware",
            "nms_multi_label": true,
            "outputs": [{
                "name": "output0", "type": "detection",
                "shape": [1, 84, 8400],
                "dshape": [{"batch": 1}, {"num_features": 84}, {"num_boxes": 8400}],
                "dtype": "float32", "decoder": "ultralytics", "encoding": "direct",
                "normalized": true
            }]
        }"#;
        let schema = SchemaV2::parse_json(json).unwrap();
        assert_eq!(schema.nms_multi_label, Some(true));

        let text = serde_json::to_string(&schema).unwrap();
        let value: serde_json::Value = serde_json::from_str(&text).unwrap();
        assert_eq!(value["nms_multi_label"], serde_json::json!(true));
        let again = SchemaV2::parse_json(&text).unwrap();
        assert_eq!(again, schema);

        let legacy = schema.to_legacy_config_outputs().unwrap();
        assert_eq!(legacy.nms_multi_label, Some(true));
        let back = SchemaV2::from_v1(&legacy).unwrap();
        assert_eq!(back.nms_multi_label, Some(true));
    }

    #[test]
    fn schema_default_is_v2() {
        let s = SchemaV2::default();
        assert_eq!(s.schema_version, 2);
        assert!(s.outputs.is_empty());
    }

    #[test]
    fn fixtures_round_trip_through_serde() {
        let yolov8 =
            edgefirst_bench::testdata::read_to_string("per_scale/synthetic_yolov8n_schema.json");
        let _: super::SchemaV2 = serde_json::from_str(&yolov8).expect("yolov8n fixture must parse");

        let yolo26 =
            edgefirst_bench::testdata::read_to_string("per_scale/synthetic_yolo26n_schema.json");
        let _: super::SchemaV2 = serde_json::from_str(&yolo26).expect("yolo26n fixture must parse");

        let flat =
            edgefirst_bench::testdata::read_to_string("per_scale/synthetic_flat_schema.json");
        let _: super::SchemaV2 = serde_json::from_str(&flat).expect("flat fixture must parse");
    }

    #[test]
    fn box_encoding_accepts_ltrb_alias_for_direct() {
        let dfl: BoxEncoding = serde_json::from_str("\"dfl\"").unwrap();
        assert_eq!(dfl, BoxEncoding::Dfl);

        let direct: BoxEncoding = serde_json::from_str("\"direct\"").unwrap();
        assert_eq!(direct, BoxEncoding::Direct);

        // yolo26 metadata uses "ltrb" — must deserialise to Direct.
        let ltrb: BoxEncoding = serde_json::from_str("\"ltrb\"").unwrap();
        assert_eq!(ltrb, BoxEncoding::Direct);
    }

    #[test]
    fn dtype_roundtrip() {
        for &d in DType::all() {
            let j = serde_json::to_string(&d).unwrap();
            let back: DType = serde_json::from_str(&j).unwrap();
            assert_eq!(back, d);
        }
    }

    #[test]
    fn dtype_is_numbered_and_named_by_the_tensor_dtype() {
        for &d in DType::all() {
            let t = d.to_tensor_dtype();
            assert_eq!(d.code(), t.code(), "{d:?}");
            assert_eq!(d.as_str(), t.as_str(), "{d:?}");
            assert_eq!(DType::from_code(t.code()), Some(d));
            assert_eq!(DType::from_tensor_dtype(t), Some(d));
            assert_eq!(
                serde_json::to_string(&d).unwrap(),
                format!("\"{}\"", t.as_str())
            );
        }
        // `u64` and `f64` are not model I/O dtypes.
        for t in [edgefirst_tensor::DType::U64, edgefirst_tensor::DType::F64] {
            assert_eq!(DType::from_tensor_dtype(t), None);
            assert_eq!(DType::from_code(t.code()), None);
            assert_eq!(DType::from_str_code(t.as_str()), None);
        }
        assert_eq!(DType::from_code(u32::MAX), None);
    }

    #[test]
    fn dtype_accepts_every_legacy_name() {
        let legacy = [
            ("int8", DType::Int8),
            ("uint8", DType::Uint8),
            ("int16", DType::Int16),
            ("uint16", DType::Uint16),
            ("int32", DType::Int32),
            ("uint32", DType::Uint32),
            ("float16", DType::Float16),
            ("float32", DType::Float32),
            ("int64", DType::Int64),
        ];
        assert_eq!(legacy.len(), DType::all().len());
        for (name, d) in legacy {
            assert_eq!(DType::from_str_code(name), Some(d), "{name}");
            let back: DType = serde_json::from_str(&format!("\"{name}\"")).unwrap();
            assert_eq!(back, d, "{name}");
            // Accepted on input, never produced on output.
            assert_ne!(d.as_str(), name);
        }
        assert_eq!(DType::accepted_names().count(), 2 * DType::all().len());
        assert!(serde_json::from_str::<DType>("\"float64\"").is_err());
        assert!(serde_json::from_str::<DType>("\"Int8\"").is_err());
    }

    #[test]
    fn schema_enums_take_their_codes_from_the_config_vocabularies() {
        for v in [
            DecoderVersion::Yolov5,
            DecoderVersion::Yolov8,
            DecoderVersion::Yolo11,
            DecoderVersion::Yolo26,
        ] {
            assert_eq!(v.code(), v.to_v1().code(), "{v:?}");
        }
        for m in [NmsMode::ClassAgnostic, NmsMode::ClassAware] {
            assert_eq!(m.code(), m.to_v1().code(), "{m:?}");
        }
        for &v in configs::DecoderType::all() {
            let k = DecoderKind::from_v1(v);
            assert_eq!(k.code(), v.code(), "{k:?}");
            assert_eq!(k.to_v1(), v, "{k:?}");
        }
    }

    #[test]
    fn dtype_widths() {
        assert_eq!(DType::Int8.size_bytes(), 1);
        assert_eq!(DType::Float16.size_bytes(), 2);
        assert_eq!(DType::Float32.size_bytes(), 4);
    }

    #[test]
    fn stride_accepts_scalar_or_pair() {
        let a: Stride = serde_json::from_str("8").unwrap();
        let b: Stride = serde_json::from_str("[8, 16]").unwrap();
        assert_eq!(a, Stride::Square(8));
        assert_eq!(b, Stride::Rect([8, 16]));
        assert_eq!(a.x(), 8);
        assert_eq!(a.y(), 8);
        assert_eq!(b.x(), 8);
        assert_eq!(b.y(), 16);
    }

    #[test]
    fn quantization_scalar_scale() {
        let j = r#"{"scale": 0.00392, "zero_point": 0, "dtype": "int8"}"#;
        let q: Quantization = serde_json::from_str(j).unwrap();
        assert!(q.is_per_tensor());
        assert!(q.is_symmetric());
        assert_eq!(q.scale_at(0), 0.00392);
        assert_eq!(q.scale_at(5), 0.00392);
        assert_eq!(q.zero_point_at(0), 0);
    }

    #[test]
    fn quantization_per_channel() {
        let j = r#"{"scale": [0.054, 0.089, 0.195], "axis": 0, "dtype": "int8"}"#;
        let q: Quantization = serde_json::from_str(j).unwrap();
        assert!(q.is_per_channel());
        assert!(q.is_symmetric());
        assert_eq!(q.axis, Some(0));
        assert_eq!(q.scale_at(0), 0.054);
        assert_eq!(q.scale_at(2), 0.195);
    }

    #[test]
    fn quantization_asymmetric_per_tensor() {
        let j = r#"{"scale": 0.176, "zero_point": 198, "dtype": "uint8"}"#;
        let q: Quantization = serde_json::from_str(j).unwrap();
        assert!(!q.is_symmetric());
        assert_eq!(q.zero_point_at(0), 198);
        assert_eq!(q.zero_point_at(10), 198);
    }

    #[test]
    fn quantization_symmetric_default_zero_point() {
        let j = r#"{"scale": 0.00392, "dtype": "int8"}"#;
        let q: Quantization = serde_json::from_str(j).unwrap();
        assert!(q.is_symmetric());
        assert_eq!(q.zero_point_at(0), 0);
    }

    #[test]
    fn quantization_to_tensor_per_tensor_asymmetric() {
        let q = Quantization {
            scale: vec![0.1],
            zero_point: Some(vec![-5]),
            axis: None,
            dtype: Some(DType::Int8),
        };
        let t: edgefirst_tensor::Quantization = (&q).try_into().unwrap();
        assert!(t.is_per_tensor());
        assert!(!t.is_symmetric());
        assert_eq!(t.scale(), &[0.1]);
        assert_eq!(t.zero_point(), Some(&[-5][..]));
    }

    #[test]
    fn quantization_to_tensor_per_tensor_symmetric() {
        let q = Quantization {
            scale: vec![0.05],
            zero_point: None,
            axis: None,
            dtype: Some(DType::Int8),
        };
        let t: edgefirst_tensor::Quantization = (&q).try_into().unwrap();
        assert!(t.is_per_tensor());
        assert!(t.is_symmetric());
    }

    #[test]
    fn quantization_to_tensor_per_channel_asymmetric() {
        let q = Quantization {
            scale: vec![0.1, 0.2, 0.3],
            zero_point: Some(vec![-1, 0, 1]),
            axis: Some(2),
            dtype: Some(DType::Int8),
        };
        let t: edgefirst_tensor::Quantization = (&q).try_into().unwrap();
        assert!(t.is_per_channel());
        assert_eq!(t.axis(), Some(2));
        assert_eq!(t.scale().len(), 3);
        assert_eq!(t.zero_point().map(|z| z.len()), Some(3));
    }

    #[test]
    fn quantization_to_tensor_per_channel_symmetric() {
        let q = Quantization {
            scale: vec![0.054, 0.089, 0.195],
            zero_point: None,
            axis: Some(0),
            dtype: Some(DType::Int8),
        };
        let t: edgefirst_tensor::Quantization = (&q).try_into().unwrap();
        assert!(t.is_per_channel());
        assert!(t.is_symmetric());
        assert_eq!(t.axis(), Some(0));
    }

    #[test]
    fn quantization_to_tensor_per_channel_missing_axis_errors() {
        let q = Quantization {
            scale: vec![0.1, 0.2, 0.3],
            zero_point: None,
            axis: None,
            dtype: None,
        };
        let err = edgefirst_tensor::Quantization::try_from(&q).unwrap_err();
        // The field matters: the per-channel-without-axis arm is what should
        // reject this. Matching only on the variant also accepts the catch-all
        // "scale" arm, which would mean the arm above never ran.
        assert!(matches!(
            err,
            edgefirst_tensor::Error::QuantizationInvalid { field: "axis", .. }
        ));
    }

    /// Both redundant-axis arms map to per-tensor. Losing either one drops the
    /// conversion through to the catch-all and turns a valid configuration
    /// into an error.
    #[test]
    fn quantization_to_tensor_per_tensor_ignores_a_redundant_axis() {
        let q = Quantization {
            scale: vec![0.5],
            zero_point: Some(vec![3]),
            axis: Some(0),
            dtype: Some(DType::Int8),
        };
        let t: edgefirst_tensor::Quantization = (&q).try_into().unwrap();
        assert!(t.is_per_tensor());
        assert_eq!(t.scale(), &[0.5][..]);
        assert_eq!(t.zero_point(), Some(&[3][..]));
    }

    #[test]
    fn quantization_to_tensor_symmetric_ignores_a_redundant_axis() {
        let q = Quantization {
            scale: vec![0.5],
            zero_point: None,
            axis: Some(0),
            dtype: Some(DType::Int8),
        };
        let t: edgefirst_tensor::Quantization = (&q).try_into().unwrap();
        assert!(t.is_per_tensor());
        assert!(t.is_symmetric());
        assert_eq!(t.scale(), &[0.5][..]);
    }

    /// An empty scale is neither per-tensor nor per-channel, so it must reach
    /// the catch-all and name `scale`. Each of these reaches it down a
    /// different path: no axis, an axis, and an axis with zero points.
    #[test]
    fn quantization_to_tensor_empty_scale_errors_on_scale() {
        for (zero_point, axis) in [
            (None, None),
            (None, Some(0)),
            (Some(vec![]), Some(0)),
            (Some(vec![]), None),
        ] {
            let q = Quantization {
                scale: vec![],
                zero_point,
                axis,
                dtype: Some(DType::Int8),
            };
            let err = edgefirst_tensor::Quantization::try_from(&q).unwrap_err();
            assert!(
                matches!(
                    err,
                    edgefirst_tensor::Error::QuantizationInvalid { field: "scale", .. }
                ),
                "axis={axis:?} gave {err:?}"
            );
        }
    }

    /// One scale with two zero points is not per-tensor (the zero point is not
    /// a single element) and not per-channel (there is one scale), so it is
    /// the catch-all's job with or without an axis.
    #[test]
    fn quantization_to_tensor_single_scale_with_many_zero_points_errors_on_scale() {
        for axis in [None, Some(0)] {
            let q = Quantization {
                scale: vec![0.5],
                zero_point: Some(vec![1, 2]),
                axis,
                dtype: Some(DType::Int8),
            };
            let err = edgefirst_tensor::Quantization::try_from(&q).unwrap_err();
            assert!(
                matches!(
                    err,
                    edgefirst_tensor::Error::QuantizationInvalid { field: "scale", .. }
                ),
                "axis={axis:?} gave {err:?}"
            );
        }
    }

    #[test]
    fn per_channel_quantization_is_not_per_tensor() {
        let q = Quantization {
            scale: vec![0.1, 0.2, 0.3],
            zero_point: None,
            axis: Some(0),
            dtype: Some(DType::Int8),
        };
        assert!(q.is_per_channel());
        assert!(!q.is_per_tensor());

        let per_tensor = Quantization {
            scale: vec![0.1],
            zero_point: None,
            axis: None,
            dtype: Some(DType::Int8),
        };
        assert!(per_tensor.is_per_tensor());
        assert!(!per_tensor.is_per_channel());
    }

    /// A single zero point applies to every channel; a per-channel list is
    /// indexed. Treating the list as if it had one element would return
    /// channel 0's zero point for every channel.
    #[test]
    fn zero_point_at_indexes_per_channel_zero_points() {
        let per_channel = Quantization {
            scale: vec![0.1, 0.2, 0.3],
            zero_point: Some(vec![10, 20, 30]),
            axis: Some(0),
            dtype: Some(DType::Int8),
        };
        assert_eq!(per_channel.zero_point_at(0), 10);
        assert_eq!(per_channel.zero_point_at(1), 20);
        assert_eq!(per_channel.zero_point_at(2), 30);
        // Out of range falls back to 0 rather than panicking.
        assert_eq!(per_channel.zero_point_at(3), 0);

        let shared = Quantization {
            scale: vec![0.1, 0.2, 0.3],
            zero_point: Some(vec![7]),
            axis: Some(0),
            dtype: Some(DType::Int8),
        };
        assert_eq!(shared.zero_point_at(0), 7);
        assert_eq!(shared.zero_point_at(2), 7);

        let symmetric = Quantization {
            scale: vec![0.1],
            zero_point: None,
            axis: None,
            dtype: Some(DType::Int8),
        };
        assert_eq!(symmetric.zero_point_at(0), 0);
    }

    #[test]
    fn logical_output_flat_tflite_boxes() {
        // Example 3 from the spec: TFLite YOLOv8 detection, flat boxes
        let j = r#"{
          "name": "boxes", "type": "boxes",
          "shape": [1, 64, 8400],
          "dshape": [{"batch": 1}, {"num_features": 64}, {"num_boxes": 8400}],
          "dtype": "int8",
          "quantization": {"scale": 0.00392, "zero_point": 0, "dtype": "int8"},
          "decoder": "ultralytics",
          "encoding": "dfl",
          "normalized": true
        }"#;
        let lo: LogicalOutput = serde_json::from_str(j).unwrap();
        assert_eq!(lo.type_, Some(LogicalType::Boxes));
        assert_eq!(lo.encoding, Some(BoxEncoding::Dfl));
        assert_eq!(lo.normalized, Some(true));
        assert!(!lo.is_split());
        assert_eq!(lo.dtype, Some(DType::Int8));
    }

    #[test]
    fn logical_output_hailo_per_scale_split() {
        // Example 5 from the spec: Hailo YOLOv8 boxes, per-scale split
        let j = r#"{
          "name": "boxes", "type": "boxes",
          "shape": [1, 64, 8400],
          "encoding": "dfl", "decoder": "ultralytics", "normalized": true,
          "outputs": [
            {
              "name": "boxes_0", "type": "boxes",
              "stride": 8, "scale_index": 0,
              "shape": [1, 80, 80, 64],
              "dshape": [{"batch": 1}, {"height": 80}, {"width": 80}, {"num_features": 64}],
              "dtype": "uint8",
              "quantization": {"scale": 0.0234, "zero_point": 128, "dtype": "uint8"}
            }
          ]
        }"#;
        let lo: LogicalOutput = serde_json::from_str(j).unwrap();
        assert!(lo.is_split());
        assert_eq!(lo.outputs.len(), 1);
        let child = &lo.outputs[0];
        assert_eq!(child.name, "boxes_0");
        assert_eq!(child.type_, Some(PhysicalType::Boxes));
        assert_eq!(child.stride, Some(Stride::Square(8)));
        assert_eq!(child.scale_index, Some(0));
        assert_eq!(child.dtype, DType::Uint8);
    }

    #[test]
    fn logical_output_ara2_xy_wh_channel_split() {
        // Example 4 from the spec: ARA-2 boxes split into xy/wh
        let j = r#"{
          "name": "boxes", "type": "boxes",
          "shape": [1, 4, 8400, 1],
          "encoding": "direct", "decoder": "ultralytics", "normalized": true,
          "outputs": [
            {
              "name": "_model_22_Div_1_output_0", "type": "boxes_xy",
              "shape": [1, 2, 8400, 1],
              "dshape": [{"batch": 1}, {"box_coords": 2}, {"num_boxes": 8400}, {"padding": 1}],
              "dtype": "int16",
              "quantization": {"scale": 3.129e-5, "zero_point": 0, "dtype": "int16"}
            },
            {
              "name": "_model_22_Sub_1_output_0", "type": "boxes_wh",
              "shape": [1, 2, 8400, 1],
              "dshape": [{"batch": 1}, {"box_coords": 2}, {"num_boxes": 8400}, {"padding": 1}],
              "dtype": "int16",
              "quantization": {"scale": 3.149e-5, "zero_point": 0, "dtype": "int16"}
            }
          ]
        }"#;
        let lo: LogicalOutput = serde_json::from_str(j).unwrap();
        assert_eq!(lo.encoding, Some(BoxEncoding::Direct));
        assert_eq!(lo.outputs.len(), 2);
        assert_eq!(lo.outputs[0].type_, Some(PhysicalType::BoxesXy));
        assert_eq!(lo.outputs[1].type_, Some(PhysicalType::BoxesWh));
        assert!(lo.outputs[0].stride.is_none());
        assert!(lo.outputs[1].stride.is_none());
    }

    #[test]
    fn logical_output_hailo_scores_sigmoid_applied() {
        let j = r#"{
          "name": "scores", "type": "scores",
          "shape": [1, 80, 8400],
          "decoder": "ultralytics", "score_format": "per_class",
          "outputs": [
            {
              "name": "scores_0", "type": "scores",
              "stride": 8, "scale_index": 0,
              "shape": [1, 80, 80, 80],
              "dshape": [{"batch": 1}, {"height": 80}, {"width": 80}, {"num_classes": 80}],
              "dtype": "uint8",
              "quantization": {"scale": 0.003922, "dtype": "uint8"},
              "activation_applied": "sigmoid"
            }
          ]
        }"#;
        let lo: LogicalOutput = serde_json::from_str(j).unwrap();
        assert_eq!(lo.score_format, Some(ScoreFormat::PerClass));
        let child = &lo.outputs[0];
        assert_eq!(child.activation_applied, Some(Activation::Sigmoid));
        assert!(child.activation_required.is_none());
    }

    #[test]
    fn yolo26_end_to_end_detections() {
        let j = r#"{
          "schema_version": 2,
          "decoder_version": "yolo26",
          "outputs": [{
            "name": "output0", "type": "detections",
            "shape": [1, 100, 6],
            "dshape": [{"batch": 1}, {"num_boxes": 100}, {"num_features": 6}],
            "dtype": "int8",
            "quantization": {"scale": 0.0078, "zero_point": 0, "dtype": "int8"},
            "normalized": false,
            "decoder": "ultralytics"
          }]
        }"#;
        let s: SchemaV2 = serde_json::from_str(j).unwrap();
        assert_eq!(s.decoder_version, Some(DecoderVersion::Yolo26));
        assert!(s.decoder_version.unwrap().is_end_to_end());
        assert_eq!(s.outputs[0].type_, Some(LogicalType::Detections));
        assert_eq!(s.outputs[0].normalized, Some(false));
        assert!(s.nms.is_none());
    }

    #[test]
    fn modelpack_anchor_detection_with_rect_stride() {
        let j = r#"{
          "schema_version": 2,
          "outputs": [{
            "name": "output_0", "type": "detection",
            "shape": [1, 40, 40, 54],
            "dshape": [{"batch": 1}, {"height": 40}, {"width": 40}, {"num_anchors_x_features": 54}],
            "dtype": "uint8",
            "quantization": {"scale": 0.176, "zero_point": 198, "dtype": "uint8"},
            "decoder": "modelpack",
            "encoding": "anchor",
            "stride": [16, 16],
            "anchors": [[0.054, 0.065], [0.089, 0.139], [0.195, 0.196]]
          }]
        }"#;
        let s: SchemaV2 = serde_json::from_str(j).unwrap();
        let lo = &s.outputs[0];
        assert_eq!(lo.encoding, Some(BoxEncoding::Anchor));
        assert_eq!(lo.stride, Some(Stride::Rect([16, 16])));
        assert_eq!(lo.anchors.as_ref().map(|a| a.len()), Some(3));
    }

    #[test]
    fn yolov5_obj_x_class_objectness_logical() {
        let j = r#"{
          "name": "objectness", "type": "objectness",
          "shape": [1, 3, 8400],
          "decoder": "ultralytics",
          "outputs": [{
            "name": "objectness_0", "type": "objectness",
            "stride": 8, "scale_index": 0,
            "shape": [1, 80, 80, 3],
            "dshape": [{"batch": 1}, {"height": 80}, {"width": 80}, {"num_features": 3}],
            "dtype": "uint8",
            "quantization": {"scale": 0.0039, "zero_point": 0, "dtype": "uint8"},
            "activation_applied": "sigmoid"
          }]
        }"#;
        let lo: LogicalOutput = serde_json::from_str(j).unwrap();
        assert_eq!(lo.type_, Some(LogicalType::Objectness));
        assert_eq!(lo.outputs[0].activation_applied, Some(Activation::Sigmoid));
    }

    #[test]
    fn direct_protos_no_decoder() {
        // protos are consumed directly — no `decoder` field
        let j = r#"{
          "name": "protos", "type": "protos",
          "shape": [1, 32, 160, 160],
          "dshape": [{"batch": 1}, {"num_protos": 32}, {"height": 160}, {"width": 160}],
          "dtype": "uint8",
          "quantization": {"scale": 0.0203, "zero_point": 45, "dtype": "uint8"},
          "stride": 4
        }"#;
        let lo: LogicalOutput = serde_json::from_str(j).unwrap();
        assert_eq!(lo.type_, Some(LogicalType::Protos));
        assert!(lo.decoder.is_none());
        assert_eq!(lo.stride, Some(Stride::Square(4)));
    }

    #[test]
    fn full_yolov8_tflite_flat_detection() {
        // Example 3: complete two-output YOLOv8 detection schema
        let j = r#"{
          "schema_version": 2,
          "decoder_version": "yolov8",
          "nms": "class_agnostic",
          "input": { "shape": [1, 640, 640, 3], "cameraadaptor": "rgb" },
          "outputs": [
            {
              "name": "boxes", "type": "boxes",
              "shape": [1, 64, 8400],
              "dshape": [{"batch": 1}, {"num_features": 64}, {"num_boxes": 8400}],
              "dtype": "int8",
              "quantization": {"scale": 0.00392, "zero_point": 0, "dtype": "int8"},
              "decoder": "ultralytics",
              "encoding": "dfl",
              "normalized": true
            },
            {
              "name": "scores", "type": "scores",
              "shape": [1, 80, 8400],
              "dshape": [{"batch": 1}, {"num_classes": 80}, {"num_boxes": 8400}],
              "dtype": "int8",
              "quantization": {"scale": 0.00392, "zero_point": 0, "dtype": "int8"},
              "decoder": "ultralytics",
              "score_format": "per_class"
            }
          ]
        }"#;
        let s: SchemaV2 = serde_json::from_str(j).unwrap();
        assert_eq!(s.schema_version, 2);
        assert_eq!(s.decoder_version, Some(DecoderVersion::Yolov8));
        assert_eq!(s.nms, Some(NmsMode::ClassAgnostic));
        assert_eq!(s.input.as_ref().unwrap().shape, vec![1, 640, 640, 3]);
        assert_eq!(s.outputs.len(), 2);
    }

    #[test]
    fn schema_unknown_version_parses_without_validation() {
        // Parser accepts any u32; the decoder is responsible for rejecting
        // unsupported versions with a useful error.
        let j = r#"{"schema_version": 99, "outputs": []}"#;
        let s: SchemaV2 = serde_json::from_str(j).unwrap();
        assert_eq!(s.schema_version, 99);
    }

    #[test]
    fn serde_roundtrip_preserves_fields() {
        let original = SchemaV2 {
            schema_version: 2,
            input: Some(InputSpec {
                shape: vec![1, 3, 640, 640],
                dshape: vec![],
                cameraadaptor: Some("rgb".into()),
                preprocessing: None,
            }),
            outputs: vec![LogicalOutput {
                name: Some("boxes".into()),
                type_: Some(LogicalType::Boxes),
                shape: vec![1, 4, 8400],
                dshape: vec![],
                decoder: Some(DecoderKind::Ultralytics),
                encoding: Some(BoxEncoding::Direct),
                score_format: None,
                normalized: Some(true),
                anchors: None,
                stride: None,
                dtype: Some(DType::Float32),
                quantization: None,
                outputs: vec![],
                activation_applied: None,
                activation_required: None,
                semantic: Default::default(),
            }],
            nms: Some(NmsMode::ClassAgnostic),
            nms_multi_label: None,
            decoder_version: Some(DecoderVersion::Yolov8),
        };
        let j = serde_json::to_string(&original).unwrap();
        let parsed: SchemaV2 = serde_json::from_str(&j).unwrap();
        assert_eq!(parsed, original);
    }

    // ─── v1 → v2 shim tests ─────────────────────────────────

    #[test]
    fn parse_v1_yaml_yolov8_seg_testdata() {
        let yaml = edgefirst_bench::testdata::read_to_string("yolov8_seg.yaml");
        let schema = SchemaV2::parse_yaml(&yaml).expect("parse v1 yaml");
        assert_eq!(schema.schema_version, 2);
        assert_eq!(schema.outputs.len(), 2);
        // First output: Detection [1, 116, 8400]
        let det = &schema.outputs[0];
        assert_eq!(det.type_, Some(LogicalType::Detection));
        assert_eq!(det.shape, vec![1, 116, 8400]);
        assert_eq!(det.decoder, Some(DecoderKind::Ultralytics));
        assert_eq!(det.encoding, Some(BoxEncoding::Direct));
        let q = det.quantization.as_ref().unwrap();
        assert_eq!(q.scale.len(), 1);
        assert!((q.scale[0] - 0.021_287_762).abs() < 1e-6);
        assert_eq!(q.zero_point, Some(vec![31]));
        // Second output: Protos [1, 160, 160, 32]
        let protos = &schema.outputs[1];
        assert_eq!(protos.type_, Some(LogicalType::Protos));
        assert_eq!(protos.shape, vec![1, 160, 160, 32]);
    }

    #[test]
    fn parse_v1_json_modelpack_split_testdata() {
        let json = edgefirst_bench::testdata::read_to_string("modelpack_split.json");
        let schema = SchemaV2::parse_json(&json).expect("parse v1 json");
        assert_eq!(schema.schema_version, 2);
        assert_eq!(schema.outputs.len(), 2);
        // Both are ModelPack anchor detection with anchors
        for out in &schema.outputs {
            assert_eq!(out.type_, Some(LogicalType::Detection));
            assert_eq!(out.decoder, Some(DecoderKind::ModelPack));
            assert_eq!(out.encoding, Some(BoxEncoding::Anchor));
            assert_eq!(out.anchors.as_ref().map(|a| a.len()), Some(3));
        }
    }

    #[test]
    fn parse_v2_json_direct_when_schema_version_present() {
        let j = r#"{
          "schema_version": 2,
          "outputs": [{
            "name": "boxes", "type": "boxes",
            "shape": [1, 4, 8400],
            "dshape": [{"batch": 1}, {"box_coords": 4}, {"num_boxes": 8400}],
            "dtype": "float32",
            "decoder": "ultralytics",
            "encoding": "direct",
            "normalized": true
          }]
        }"#;
        let schema = SchemaV2::parse_json(j).unwrap();
        assert_eq!(schema.schema_version, 2);
        assert_eq!(schema.outputs[0].type_, Some(LogicalType::Boxes));
    }

    #[test]
    fn parse_rejects_future_schema_version() {
        let j = r#"{"schema_version": 99, "outputs": []}"#;
        let err = SchemaV2::parse_json(j).unwrap_err();
        matches!(err, DecoderError::NotSupported(_));
    }

    #[test]
    fn parse_absent_schema_version_treats_as_v1() {
        // No schema_version field — classic v1 yolov8 split
        let j = r#"{
          "outputs": [
            {
              "type": "boxes", "decoder": "ultralytics",
              "shape": [1, 4, 8400],
              "quantization": [0.00392, 0]
            },
            {
              "type": "scores", "decoder": "ultralytics",
              "shape": [1, 80, 8400],
              "quantization": [0.00392, 0]
            }
          ]
        }"#;
        let schema = SchemaV2::parse_json(j).expect("v1 legacy parse");
        assert_eq!(schema.schema_version, 2); // converted
        assert_eq!(schema.outputs.len(), 2);
        assert_eq!(schema.outputs[0].type_, Some(LogicalType::Boxes));
        assert_eq!(schema.outputs[1].type_, Some(LogicalType::Scores));
        // default score_format assumed on v1→v2
        assert_eq!(schema.outputs[1].score_format, Some(ScoreFormat::PerClass));
    }

    #[test]
    fn from_v1_preserves_nms_and_decoder_version() {
        let v1 = ConfigOutputs {
            outputs: vec![ConfigOutput::Boxes(crate::configs::Boxes {
                decoder: crate::configs::DecoderType::Ultralytics,
                quantization: Some(crate::configs::QuantTuple(0.01, 5)),
                shape: vec![1, 4, 8400],
                dshape: vec![],
                normalized: Some(true),
            })],
            nms: Some(crate::configs::Nms::ClassAware),
            nms_multi_label: None,
            decoder_version: Some(crate::configs::DecoderVersion::Yolo11),
        };
        let v2 = SchemaV2::from_v1(&v1).unwrap();
        assert_eq!(v2.nms, Some(NmsMode::ClassAware));
        assert_eq!(v2.decoder_version, Some(DecoderVersion::Yolo11));
        assert_eq!(v2.outputs[0].normalized, Some(true));
        let q = v2.outputs[0].quantization.as_ref().unwrap();
        assert_eq!(q.scale, vec![0.01]);
        assert_eq!(q.zero_point, Some(vec![5]));
        assert_eq!(q.dtype, None); // v1 did not carry dtype
    }

    /// Outputs declared without a `type` field must parse successfully
    /// and round-trip to JSON without introducing a synthetic type.
    /// The metadata v2 spec lists `type` as required on both logical
    /// and physical levels, but the HAL tolerates typeless logical
    /// outputs as "additional" (auxiliary / diagnostic) tensors that
    /// do not participate in decoder dispatch.
    #[test]
    fn typeless_logical_output_parses_and_roundtrips() {
        let j = r#"{
            "schema_version": 2,
            "outputs": [
                {
                    "name": "extra_telemetry",
                    "shape": [1, 16]
                },
                {
                    "name": "boxes",
                    "type": "boxes",
                    "shape": [1, 4, 8400]
                }
            ]
        }"#;
        let schema: SchemaV2 = serde_json::from_str(j).unwrap();
        assert_eq!(schema.outputs.len(), 2);
        assert_eq!(schema.outputs[0].type_, None);
        assert_eq!(schema.outputs[0].name.as_deref(), Some("extra_telemetry"));
        assert_eq!(schema.outputs[1].type_, Some(LogicalType::Boxes));

        // Typeless output must not serialize a `type` field.
        let round = serde_json::to_string(&schema).unwrap();
        let first_obj = round
            .split("\"outputs\":[")
            .nth(1)
            .and_then(|s| s.split("}").next())
            .expect("outputs array");
        assert!(
            !first_obj.contains("\"type\""),
            "typeless output must not serialize a `type` field, got: {first_obj}"
        );
    }

    /// Typeless logical outputs are filtered out of the legacy
    /// ConfigOutputs — they carry no decoder role and the legacy
    /// builder can't represent them. A schema with typeless extras
    /// plus a recognised `boxes` role must lower to a legacy config
    /// containing only the `boxes` entry.
    #[test]
    fn typeless_outputs_filtered_from_legacy_config() {
        let schema = SchemaV2 {
            schema_version: 2,
            input: None,
            outputs: vec![
                LogicalOutput {
                    name: Some("diagnostic_histogram".into()),
                    type_: None,
                    shape: vec![1, 256],
                    dshape: vec![],
                    decoder: None,
                    encoding: None,
                    score_format: None,
                    normalized: None,
                    anchors: None,
                    stride: None,
                    dtype: None,
                    quantization: None,
                    outputs: vec![],
                    activation_applied: None,
                    activation_required: None,
                    semantic: Default::default(),
                },
                LogicalOutput {
                    name: Some("boxes".into()),
                    type_: Some(LogicalType::Boxes),
                    shape: vec![1, 4, 8400],
                    dshape: vec![],
                    decoder: Some(DecoderKind::Ultralytics),
                    encoding: Some(BoxEncoding::Direct),
                    score_format: None,
                    normalized: Some(true),
                    anchors: None,
                    stride: None,
                    dtype: None,
                    quantization: None,
                    outputs: vec![],
                    activation_applied: None,
                    activation_required: None,
                    semantic: Default::default(),
                },
            ],
            nms: None,
            nms_multi_label: None,
            decoder_version: None,
        };
        let legacy = schema.to_legacy_config_outputs().unwrap();
        assert_eq!(
            legacy.outputs.len(),
            1,
            "typeless output must be filtered from legacy config"
        );
        assert!(
            matches!(legacy.outputs[0], ConfigOutput::Boxes(_)),
            "only the typed `boxes` output should survive lowering"
        );
    }

    /// A schema that contains no typed outputs (all typeless) lowers
    /// to an empty legacy config. The decoder builder then surfaces
    /// its own "No outputs found in config" error — meaningful,
    /// decoder-centric, not a serde-level "missing field type".
    #[test]
    fn all_typeless_schema_produces_empty_legacy_config() {
        let schema = SchemaV2 {
            schema_version: 2,
            input: None,
            outputs: vec![LogicalOutput {
                name: Some("aux".into()),
                type_: None,
                shape: vec![1, 8],
                dshape: vec![],
                decoder: None,
                encoding: None,
                score_format: None,
                normalized: None,
                anchors: None,
                stride: None,
                dtype: None,
                quantization: None,
                outputs: vec![],
                activation_applied: None,
                activation_required: None,
                semantic: Default::default(),
            }],
            nms: None,
            nms_multi_label: None,
            decoder_version: None,
        };
        let legacy = schema.to_legacy_config_outputs().unwrap();
        assert!(legacy.outputs.is_empty());
    }

    /// Physical children may also omit `type`. The schema parses, the
    /// output round-trips without a synthetic `type` field, and the
    /// uniqueness check doesn't flag a typeless child sharing shape
    /// with a typed sibling (the type disambiguator is absent, but we
    /// don't bind typeless children by type anyway).
    #[test]
    fn typeless_physical_child_parses_and_skips_uniqueness() {
        let j = r#"{
            "name": "boxes",
            "type": "boxes",
            "shape": [1, 8400, 4],
            "outputs": [
                {
                    "name": "boxes_xy",
                    "type": "boxes_xy",
                    "shape": [1, 8400, 2],
                    "dtype": "float32"
                },
                {
                    "name": "aux_user_managed",
                    "shape": [1, 8400, 2],
                    "dtype": "float32"
                }
            ]
        }"#;
        let lo: LogicalOutput = serde_json::from_str(j).unwrap();
        assert_eq!(lo.outputs.len(), 2);
        assert_eq!(lo.outputs[0].type_, Some(PhysicalType::BoxesXy));
        assert_eq!(lo.outputs[1].type_, None);

        // Wrap in a minimal schema so we can call validate().
        // BoxesXy and the typeless child share shape `[1, 8400, 2]`;
        // the uniqueness check must not treat this as a conflict.
        let schema = SchemaV2 {
            schema_version: 2,
            input: None,
            outputs: vec![lo],
            nms: None,
            nms_multi_label: None,
            decoder_version: None,
        };
        schema.validate().expect(
            "typed + typeless children with equal shape must not trigger \
             uniqueness error",
        );

        // Serialization skips `type` on the typeless child.
        let s = serde_json::to_string(&schema).unwrap();
        assert!(
            s.contains("\"aux_user_managed\""),
            "typeless child must survive round-trip: {s}"
        );
        // Locate the typeless child's JSON object and confirm no `type` key.
        let aux_obj = s
            .split("\"aux_user_managed\"")
            .nth(1)
            .and_then(|s| s.split('}').next())
            .unwrap_or("");
        assert!(
            !aux_obj.contains("\"type\""),
            "typeless child must not serialize `type`, got: {aux_obj}"
        );
    }

    #[test]
    fn from_v1_modelpack_anchor_detection_maps_encoding() {
        let v1 = ConfigOutputs {
            outputs: vec![ConfigOutput::Detection(crate::configs::Detection {
                anchors: Some(vec![[0.1, 0.2], [0.3, 0.4]]),
                decoder: crate::configs::DecoderType::ModelPack,
                quantization: Some(crate::configs::QuantTuple(0.176, 198)),
                shape: vec![1, 40, 40, 54],
                dshape: vec![],
                normalized: None,
            })],
            nms: None,
            nms_multi_label: None,
            decoder_version: None,
        };
        let v2 = SchemaV2::from_v1(&v1).unwrap();
        assert_eq!(v2.outputs[0].encoding, Some(BoxEncoding::Anchor));
        assert_eq!(v2.outputs[0].decoder, Some(DecoderKind::ModelPack));
        assert_eq!(v2.outputs[0].anchors.as_ref().map(|a| a.len()), Some(2));
    }

    // ─── validate() tests ──────────────────────────────────

    #[test]
    fn validate_accepts_flat_v2_yolov8_detection() {
        let j = r#"{
          "schema_version": 2,
          "outputs": [
            {"name":"boxes","type":"boxes","shape":[1,64,8400],
             "dtype":"int8","decoder":"ultralytics","encoding":"dfl"},
            {"name":"scores","type":"scores","shape":[1,80,8400],
             "dtype":"int8","decoder":"ultralytics","score_format":"per_class"}
          ]
        }"#;
        SchemaV2::parse_json(j).unwrap().validate().unwrap();
    }

    #[test]
    fn validate_rejects_unnamed_physical_child() {
        let j = r#"{
          "schema_version": 2,
          "outputs": [{
            "name":"boxes","type":"boxes","shape":[1,64,8400],
            "encoding":"dfl","decoder":"ultralytics",
            "outputs": [{
              "name":"","type":"boxes","stride":8,
              "shape":[1,80,80,64],"dtype":"uint8"
            }]
          }]
        }"#;
        let err = SchemaV2::parse_json(j).unwrap().validate().unwrap_err();
        let msg = format!("{err}");
        assert!(msg.contains("missing `name`"), "got: {msg}");
    }

    #[test]
    fn validate_rejects_duplicate_physical_shapes() {
        let j = r#"{
          "schema_version": 2,
          "outputs": [{
            "name":"boxes","type":"boxes","shape":[1,64,8400],
            "encoding":"dfl","decoder":"ultralytics",
            "outputs": [
              {"name":"a","type":"boxes","stride":8,"shape":[1,80,80,64],"dtype":"uint8"},
              {"name":"b","type":"boxes","stride":16,"shape":[1,80,80,64],"dtype":"uint8"}
            ]
          }]
        }"#;
        let err = SchemaV2::parse_json(j).unwrap().validate().unwrap_err();
        let msg = format!("{err}");
        assert!(msg.contains("share shape"), "got: {msg}");
    }

    #[test]
    fn validate_rejects_mixed_decomposition() {
        // one child carries stride, the other does not — ill-defined merge
        let j = r#"{
          "schema_version": 2,
          "outputs": [{
            "name":"boxes","type":"boxes","shape":[1,4,8400,1],
            "encoding":"direct","decoder":"ultralytics",
            "outputs": [
              {"name":"xy","type":"boxes_xy","shape":[1,2,8400,1],"dtype":"int16"},
              {"name":"p0","type":"boxes","stride":8,"shape":[1,80,80,64],"dtype":"uint8"}
            ]
          }]
        }"#;
        let err = SchemaV2::parse_json(j).unwrap().validate().unwrap_err();
        let msg = format!("{err}");
        assert!(msg.contains("uniform"), "got: {msg}");
    }

    #[test]
    fn validate_rejects_dfl_boxes_feature_not_divisible_by_4() {
        let j = r#"{
          "schema_version": 2,
          "outputs": [{
            "name":"boxes","type":"boxes","shape":[1,63,8400],
            "encoding":"dfl","decoder":"ultralytics",
            "outputs": [{
              "name":"b0","type":"boxes","stride":8,
              "shape":[1,80,80,63],
              "dshape":[{"batch":1},{"height":80},{"width":80},{"num_features":63}],
              "dtype":"uint8"
            }]
          }]
        }"#;
        let err = SchemaV2::parse_json(j).unwrap().validate().unwrap_err();
        let msg = format!("{err}");
        assert!(msg.contains("not"), "got: {msg}");
        assert!(msg.contains("divisible by 4"), "got: {msg}");
    }

    #[test]
    fn validate_accepts_hailo_per_scale_yolov8() {
        let j = r#"{
          "schema_version": 2,
          "outputs": [{
            "name":"boxes","type":"boxes","shape":[1,64,8400],
            "encoding":"dfl","decoder":"ultralytics","normalized":true,
            "outputs": [
              {"name":"b0","type":"boxes","stride":8,
               "shape":[1,80,80,64],
               "dshape":[{"batch":1},{"height":80},{"width":80},{"num_features":64}],
               "dtype":"uint8",
               "quantization":{"scale":0.0234,"zero_point":128,"dtype":"uint8"}},
              {"name":"b1","type":"boxes","stride":16,
               "shape":[1,40,40,64],
               "dshape":[{"batch":1},{"height":40},{"width":40},{"num_features":64}],
               "dtype":"uint8",
               "quantization":{"scale":0.0198,"zero_point":130,"dtype":"uint8"}},
              {"name":"b2","type":"boxes","stride":32,
               "shape":[1,20,20,64],
               "dshape":[{"batch":1},{"height":20},{"width":20},{"num_features":64}],
               "dtype":"uint8",
               "quantization":{"scale":0.0312,"zero_point":125,"dtype":"uint8"}}
            ]
          }]
        }"#;
        let s = SchemaV2::parse_json(j).unwrap();
        s.validate().unwrap();
    }

    #[test]
    fn validate_accepts_ara2_xy_wh() {
        let j = r#"{
          "schema_version": 2,
          "outputs": [{
            "name":"boxes","type":"boxes","shape":[1,4,8400,1],
            "encoding":"direct","decoder":"ultralytics","normalized":true,
            "outputs": [
              {"name":"xy","type":"boxes_xy","shape":[1,2,8400,1],
               "dshape":[{"batch":1},{"box_coords":2},{"num_boxes":8400},{"padding":1}],
               "dtype":"int16",
               "quantization":{"scale":3.1e-5,"zero_point":0,"dtype":"int16"}},
              {"name":"wh","type":"boxes_wh","shape":[1,2,8400,1],
               "dshape":[{"batch":1},{"box_coords":2},{"num_boxes":8400},{"padding":1}],
               "dtype":"int16",
               "quantization":{"scale":3.2e-5,"zero_point":0,"dtype":"int16"}}
            ]
          }]
        }"#;
        SchemaV2::parse_json(j).unwrap().validate().unwrap();
    }

    #[test]
    fn parse_file_auto_detects_json() {
        let tmp = std::env::temp_dir().join(format!("schema_v2_test_{}.json", std::process::id()));
        std::fs::write(&tmp, r#"{"schema_version":2,"outputs":[]}"#).unwrap();
        let s = SchemaV2::parse_file(&tmp).unwrap();
        assert_eq!(s.schema_version, 2);
        let _ = std::fs::remove_file(&tmp);
    }

    #[test]
    fn parse_file_auto_detects_yaml() {
        let tmp = std::env::temp_dir().join(format!("schema_v2_test_{}.yaml", std::process::id()));
        std::fs::write(&tmp, "schema_version: 2\noutputs: []\n").unwrap();
        let s = SchemaV2::parse_file(&tmp).unwrap();
        assert_eq!(s.schema_version, 2);
        let _ = std::fs::remove_file(&tmp);
    }

    // ─── Real ARA-2 DVM fixtures ────────────────────────────

    #[test]
    fn parse_real_ara2_int8_dvm_metadata() {
        let json = edgefirst_bench::testdata::read_to_string("ara2_int8_edgefirst.json");
        let schema = SchemaV2::parse_json(&json).expect("ARA-2 int8 parse");
        assert_eq!(schema.schema_version, 2);
        assert_eq!(schema.decoder_version, Some(DecoderVersion::Yolov8));
        assert_eq!(schema.nms, Some(NmsMode::ClassAgnostic));
        assert_eq!(schema.input.as_ref().unwrap().shape, vec![1, 3, 640, 640]);

        // Four logical outputs: boxes (split xy/wh), scores, mask_coefs, protos.
        assert_eq!(schema.outputs.len(), 4);
        let boxes = &schema.outputs[0];
        assert_eq!(boxes.type_, Some(LogicalType::Boxes));
        assert_eq!(boxes.encoding, Some(BoxEncoding::Direct));
        assert_eq!(boxes.normalized, Some(true));
        assert_eq!(boxes.shape, vec![1, 4, 8400, 1]); // 4D with padding
        assert_eq!(boxes.outputs.len(), 2);
        assert_eq!(boxes.outputs[0].type_, Some(PhysicalType::BoxesXy));
        assert_eq!(boxes.outputs[1].type_, Some(PhysicalType::BoxesWh));
        // xy quant: scale 0.004177791997790337, zp -122, int8
        let q_xy = boxes.outputs[0].quantization.as_ref().unwrap();
        assert_eq!(q_xy.dtype, Some(DType::Int8));
        assert!((q_xy.scale[0] - 0.004_177_792).abs() < 1e-6);
        assert_eq!(q_xy.zero_point_at(0), -122);

        let scores = &schema.outputs[1];
        assert_eq!(scores.type_, Some(LogicalType::Scores));
        assert_eq!(scores.score_format, Some(ScoreFormat::PerClass));
        assert_eq!(scores.shape, vec![1, 80, 8400, 1]);

        let mask_coefs = &schema.outputs[2];
        assert_eq!(mask_coefs.type_, Some(LogicalType::MaskCoefs));
        assert_eq!(mask_coefs.shape, vec![1, 32, 8400, 1]);

        let protos = &schema.outputs[3];
        assert_eq!(protos.type_, Some(LogicalType::Protos));
        assert_eq!(protos.shape, vec![1, 32, 160, 160]);

        // Schema-level validation passes.
        schema.validate().expect("ARA-2 int8 validate");
    }

    #[test]
    fn parse_real_ara2_int16_dvm_metadata() {
        let json = edgefirst_bench::testdata::read_to_string("ara2_int16_edgefirst.json");
        let schema = SchemaV2::parse_json(&json).expect("ARA-2 int16 parse");
        assert_eq!(schema.schema_version, 2);
        assert_eq!(schema.outputs.len(), 4);
        let boxes = &schema.outputs[0];
        assert_eq!(boxes.outputs.len(), 2);
        let q_xy = boxes.outputs[0].quantization.as_ref().unwrap();
        assert_eq!(q_xy.dtype, Some(DType::Int16));
        assert!((q_xy.scale[0] - 3.211_570_6e-5).abs() < 1e-10);
        assert_eq!(q_xy.zero_point_at(0), 0);
        // Mask coefs and protos too are INT16 in this build.
        let mc_q = schema.outputs[2].quantization.as_ref().unwrap();
        assert_eq!(mc_q.dtype, Some(DType::Int16));
        schema.validate().expect("ARA-2 int16 validate");
    }

    #[test]
    fn parse_yaml_with_explicit_schema_version_2() {
        let yaml = r#"
schema_version: 2
outputs:
  - name: scores
    type: scores
    shape: [1, 80, 8400]
    dtype: int8
    quantization:
      scale: 0.00392
      dtype: int8
    decoder: ultralytics
    score_format: per_class
"#;
        let schema = SchemaV2::parse_yaml(yaml).unwrap();
        assert_eq!(schema.schema_version, 2);
        assert_eq!(schema.outputs[0].score_format, Some(ScoreFormat::PerClass));
    }

    // ─── squeeze_padding_dims / to_legacy_config_outputs regressions ────

    #[test]
    fn squeeze_padding_dims_preserves_shape_when_dshape_absent() {
        // Empty dshape must pass shape through untouched. The previous
        // `zip` implementation silently truncated to `[]`, which made
        // every v2 logical output without named dims arrive at the legacy
        // verifier with `shape: []` and fail rank checks.
        let (shape, dshape) = squeeze_padding_dims(vec![1, 4, 8400], vec![]);
        assert_eq!(shape, vec![1, 4, 8400]);
        assert!(dshape.is_empty());
    }

    fn sample_logical(ty: LogicalType) -> LogicalOutput {
        LogicalOutput {
            name: Some("sample".into()),
            type_: Some(ty),
            shape: vec![1, 4, 100],
            dshape: vec![],
            decoder: None,
            encoding: None,
            score_format: None,
            normalized: Some(true),
            anchors: None,
            stride: None,
            dtype: None,
            quantization: None,
            outputs: vec![],
            activation_applied: None,
            activation_required: None,
            semantic: Default::default(),
        }
    }

    #[test]
    fn logical_to_legacy_maps_each_supported_type() {
        let cases = [
            (LogicalType::Boxes, "Boxes"),
            (LogicalType::Scores, "Scores"),
            (LogicalType::Protos, "Protos"),
            (LogicalType::MaskCoefs, "MaskCoefficients"),
            (LogicalType::Segmentation, "Segmentation"),
            (LogicalType::Masks, "Mask"),
            (LogicalType::Classes, "Classes"),
            (LogicalType::Detection, "Detection"),
            (LogicalType::Detections, "Detection"),
        ];
        for (ty, expected) in cases {
            let out = logical_to_legacy_config_output(&sample_logical(ty)).unwrap();
            let name = match &out {
                ConfigOutput::Boxes(_) => "Boxes",
                ConfigOutput::Scores(_) => "Scores",
                ConfigOutput::Protos(_) => "Protos",
                ConfigOutput::MaskCoefficients(_) => "MaskCoefficients",
                ConfigOutput::Segmentation(_) => "Segmentation",
                ConfigOutput::Mask(_) => "Mask",
                ConfigOutput::Classes(_) => "Classes",
                ConfigOutput::Detection(_) => "Detection",
            };
            assert_eq!(name, expected, "type {ty:?}");
        }
    }

    #[test]
    fn logical_to_legacy_rejects_objectness_and_landmarks() {
        for ty in [LogicalType::Objectness, LogicalType::Landmarks] {
            let err = logical_to_legacy_config_output(&sample_logical(ty)).unwrap_err();
            assert!(
                matches!(err, DecoderError::NotSupported(_)),
                "expected NotSupported for {ty:?}, got {err:?}"
            );
        }
    }

    #[test]
    fn logical_to_legacy_rejects_typeless_output() {
        let mut logical = sample_logical(LogicalType::Boxes);
        logical.type_ = None;
        let err = logical_to_legacy_config_output(&logical).unwrap_err();
        assert!(matches!(err, DecoderError::InvalidConfig(_)));
    }

    #[test]
    fn to_legacy_modelpack_boxes_preserves_padding_dim() {
        // Regression: ModelPack boxes with shape [1, N, 1, 4] (padding dim
        // present in dshape) were incorrectly squeezed to [1, N, 4] by
        // `logical_to_legacy_config_output`, triggering "Invalid ModelPack
        // Boxes shape [1, 1935, 4]". The ModelPack path must skip squeezing.
        let j = r#"{
          "schema_version": 2,
          "outputs": [
            {"name":"boxes","type":"boxes",
             "shape":[1,1935,1,4],
             "dshape":[{"batch":1},{"num_boxes":1935},{"padding":1},{"box_coords":4}],
             "decoder":"modelpack"}
          ]
        }"#;
        let schema = SchemaV2::parse_json(j).unwrap();
        let legacy = schema.to_legacy_config_outputs().expect("lowers cleanly");
        let boxes = match &legacy.outputs[0] {
            crate::ConfigOutput::Boxes(b) => b,
            other => panic!("expected Boxes, got {other:?}"),
        };
        // Must preserve the rank-4 shape — the padding dim must NOT be
        // squeezed for ModelPack outputs.
        assert_eq!(boxes.shape, vec![1, 1935, 1, 4]);
        assert_eq!(
            boxes.dshape,
            vec![
                (DimName::Batch, 1),
                (DimName::NumBoxes, 1935),
                (DimName::Padding, 1),
                (DimName::BoxCoords, 4),
            ]
        );
    }

    #[test]
    fn to_legacy_preserves_shape_for_v2_split_boxes_without_dshape() {
        // Regression: `Decoder({...v2 split boxes, shape:[1,4,8400], no dshape...})`
        // used to fail with `Invalid Yolo Split Boxes shape []` because
        // `squeeze_padding_dims` truncated shape when dshape was empty.
        let j = r#"{
          "schema_version": 2,
          "outputs": [
            {"name":"boxes","type":"boxes","shape":[1,4,8400],
             "dtype":"float32","decoder":"ultralytics","encoding":"direct"},
            {"name":"scores","type":"scores","shape":[1,80,8400],
             "dtype":"float32","decoder":"ultralytics","score_format":"per_class"}
          ]
        }"#;
        let schema = SchemaV2::parse_json(j).unwrap();
        let legacy = schema.to_legacy_config_outputs().expect("lowers cleanly");
        let boxes = match &legacy.outputs[0] {
            crate::ConfigOutput::Boxes(b) => b,
            other => panic!("expected Boxes, got {other:?}"),
        };
        assert_eq!(boxes.shape, vec![1, 4, 8400]);
        let scores = match &legacy.outputs[1] {
            crate::ConfigOutput::Scores(s) => s,
            other => panic!("expected Scores, got {other:?}"),
        };
        assert_eq!(scores.shape, vec![1, 80, 8400]);
    }

    const SEGFORMER_B1: &str = r#"{
      "schema_version": 2,
      "input": {
        "shape": [1, 3, 512, 672],
        "dshape": [{"batch": 1}, {"channels": 3}, {"height": 512}, {"width": 672}],
        "cameraadaptor": "rgb",
        "preprocessing": {
          "normalization": {"mean": [123.675, 116.28, 103.53], "std": [58.395, 57.12, 57.375]},
          "resize": "letterbox",
          "interpolation": "bilinear",
          "letterbox": {"placement": "topleft", "pad": [0.0, 0.0, 0.0], "pad_space": "normalized"}
        }
      },
      "outputs": [{
        "name": "logits", "type": "segmentation", "decoder": "semantic",
        "shape": [1, 150, 128, 168],
        "dshape": [{"batch": 1}, {"num_classes": 150}, {"height": 128}, {"width": 168}],
        "dtype": "float32", "stride": 4,
        "upsample": {"method": "bilinear", "align_corners": false},
        "decode_mode": "accurate"
      }]
    }"#;

    #[test]
    fn semantic_segformer_parses_and_validates() {
        let schema = SchemaV2::parse_json(SEGFORMER_B1).unwrap();
        schema.validate().unwrap();

        let pre = schema
            .input
            .as_ref()
            .unwrap()
            .preprocessing
            .as_ref()
            .unwrap();
        assert_eq!(pre.resize, Some(FitMode::Letterbox));
        assert_eq!(pre.interpolation, Some(Interpolation::Bilinear));
        let lb = pre.letterbox.as_ref().unwrap();
        assert_eq!(lb.placement, Some(LetterboxPlacement::TopLeft));
        assert_eq!(lb.pad_space, Some(PadSpace::Normalized));
        let (mean, std) = pre.normalization.as_ref().unwrap().mean_std(3).unwrap();
        assert_eq!(
            mean,
            edgefirst_tensor::Normalization::imagenet().mean().to_vec()
        );
        assert_eq!(
            std,
            edgefirst_tensor::Normalization::imagenet().std().to_vec()
        );

        let out = &schema.outputs[0];
        assert_eq!(out.decoder, Some(DecoderKind::Semantic));
        assert_eq!(out.stride, Some(Stride::Square(4)));
        assert_eq!(
            out.semantic.upsample,
            Some(Upsample {
                method: UpsampleMethod::Bilinear,
                align_corners: false
            })
        );
        assert_eq!(out.semantic.decode_mode, Some(DecodeMode::Accurate));
    }

    #[test]
    fn semantic_round_trips_with_flat_fields() {
        let schema = SchemaV2::parse_json(SEGFORMER_B1).unwrap();
        let value = serde_json::to_value(&schema).unwrap();
        let out = &value["outputs"][0];
        assert_eq!(out["decode_mode"], "accurate");
        assert_eq!(out["upsample"]["method"], "bilinear");
        assert!(out.get("semantic").is_none(), "fields must serialize flat");
        assert!(out.get("threshold").is_none(), "unset fields are omitted");
        let back: SchemaV2 = serde_json::from_value(value).unwrap();
        assert_eq!(back, schema);
    }

    #[test]
    fn semantic_decoder_is_not_lowered_to_legacy() {
        let schema = SchemaV2::parse_json(SEGFORMER_B1).unwrap();
        let err = schema.to_legacy_config_outputs().unwrap_err();
        assert!(matches!(err, DecoderError::NotSupported(_)), "{err:?}");
    }

    #[test]
    fn modelpack_segmentation_still_lowers_to_legacy() {
        let j = r#"{
          "schema_version": 2,
          "outputs": [{
            "name": "segmentation_output", "type": "segmentation",
            "shape": [1, 480, 640, 5],
            "dshape": [{"batch": 1}, {"height": 480}, {"width": 640}, {"num_classes": 5}],
            "dtype": "uint8",
            "quantization": {"scale": 0.00392, "zero_point": 0, "dtype": "uint8"},
            "decoder": "modelpack"
          }]
        }"#;
        let schema = SchemaV2::parse_json(j).unwrap();
        assert_eq!(schema.outputs[0].semantic, SemanticParams::default());
        let legacy = schema.to_legacy_config_outputs().unwrap();
        assert!(matches!(
            legacy.outputs[0],
            crate::ConfigOutput::Segmentation(_)
        ));
    }

    #[test]
    fn normalization_presets_resolve() {
        let cases = [
            (NormalizationPreset::Unsigned, 0.0, 255.0),
            (NormalizationPreset::Signed, 127.5, 127.5),
            (NormalizationPreset::Raw, 0.0, 1.0),
        ];
        for (preset, m, s) in cases {
            let (mean, std) = NormalizationConfig::Preset(preset).mean_std(4).unwrap();
            assert_eq!(mean, vec![m; 4], "{preset:?}");
            assert_eq!(std, vec![s; 4], "{preset:?}");
        }
        let imagenet = NormalizationConfig::Preset(NormalizationPreset::Imagenet);
        assert!(imagenet.mean_std(3).is_ok());
        assert!(imagenet.mean_std(1).is_err());
    }

    #[test]
    fn normalization_preset_parses_from_string() {
        for (text, preset) in [
            ("unsigned", NormalizationPreset::Unsigned),
            ("signed", NormalizationPreset::Signed),
            ("raw", NormalizationPreset::Raw),
            ("imagenet", NormalizationPreset::Imagenet),
        ] {
            let norm: NormalizationConfig =
                serde_json::from_value(serde_json::json!(text)).unwrap();
            assert_eq!(norm, NormalizationConfig::Preset(preset));
        }
        assert!(
            serde_json::from_value::<NormalizationConfig>(serde_json::json!("zscore")).is_err()
        );
    }

    #[test]
    fn mean_std_broadcasts_and_rejects_bad_input() {
        let one = NormalizationConfig::MeanStd {
            mean: vec![127.5],
            std: vec![127.5],
        };
        assert_eq!(one.mean_std(3).unwrap().0, vec![127.5; 3]);

        let mismatched = NormalizationConfig::MeanStd {
            mean: vec![0.0, 0.0],
            std: vec![1.0; 3],
        };
        assert!(mismatched.mean_std(3).is_err());

        let zero_std = NormalizationConfig::MeanStd {
            mean: vec![0.0; 3],
            std: vec![1.0, 0.0, 1.0],
        };
        assert!(zero_std.mean_std(3).is_err());
    }

    #[test]
    fn validate_rejects_bad_preprocessing() {
        let bad_pad = r#"{
          "schema_version": 2,
          "input": {"shape": [1, 3, 8, 8], "preprocessing": {
            "normalization": {"mean": [0, 0, 0], "std": [1, 1, 1]},
            "letterbox": {"pad": [0, 0]}
          }}
        }"#;
        assert!(SchemaV2::parse_json(bad_pad).unwrap().validate().is_err());

        let zero_std = r#"{
          "schema_version": 2,
          "input": {"shape": [1, 3, 8, 8], "preprocessing": {
            "normalization": {"mean": [0], "std": [0]}
          }}
        }"#;
        assert!(SchemaV2::parse_json(zero_std).unwrap().validate().is_err());
    }

    #[test]
    fn non_finite_mean_is_rejected() {
        for bad in [f32::NAN, f32::INFINITY] {
            let norm = NormalizationConfig::MeanStd {
                mean: vec![bad],
                std: vec![1.0],
            };
            assert!(norm.mean_std(3).is_err(), "{bad}");

            let mut schema =
                SchemaV2::parse_json(r#"{"schema_version": 2, "input": {"shape": [1, 3, 8, 8]}}"#)
                    .unwrap();
            schema.input.as_mut().unwrap().preprocessing = Some(Preprocessing {
                normalization: Some(norm),
                ..Default::default()
            });
            assert!(schema.validate().is_err(), "{bad}");
        }
    }

    fn validate_input(shape: &str, preprocessing: &str) -> DecoderResult<()> {
        let j = format!(
            r#"{{"schema_version": 2, "input": {{{shape}, "preprocessing": {preprocessing}}}}}"#
        );
        SchemaV2::parse_json(&j).unwrap().validate()
    }

    #[test]
    fn scalar_coefficients_broadcast_with_per_channel_pad() {
        let pre = r#"{"normalization": {"mean": [0], "std": [255]},
                      "letterbox": {"pad": [114, 114, 114]}}"#;
        validate_input(r#""shape": [1, 3, 512, 512]"#, pre).unwrap();
        validate_input(r#""shape": [1, 512, 512, 3]"#, pre).unwrap();
        // Unknown layout: the per-channel pad sets the channel count.
        validate_input(r#""shape": [1, 3, 4, 3]"#, pre).unwrap();
    }

    #[test]
    fn coefficients_must_match_input_channels() {
        let two = r#"{"normalization": {"mean": [0, 0], "std": [1, 1]}}"#;
        let nchw = r#""shape": [1, 3, 512, 512]"#;
        let named = r#""shape": [1, 512, 512, 3],
            "dshape": [{"batch": 1}, {"height": 512}, {"width": 512}, {"channels": 3}]"#;
        assert!(validate_input(nchw, two).is_err());
        assert!(validate_input(named, two).is_err());

        let pad_two = r#"{"normalization": "unsigned", "letterbox": {"pad": [0, 0]}}"#;
        assert!(validate_input(nchw, pad_two).is_err());

        let imagenet = r#"{"normalization": "imagenet"}"#;
        assert!(validate_input(r#""shape": [1, 1, 64, 64]"#, imagenet).is_err());
        validate_input(nchw, imagenet).unwrap();

        // Unknown layout: non-scalar vectors must agree with each other.
        let mixed = r#"{"normalization": {"mean": [0, 0, 0], "std": [1, 1]}}"#;
        assert!(validate_input(r#""shape": [1, 3, 4, 3]"#, mixed).is_err());
    }

    #[test]
    fn input_channels_resolve_from_dshape_or_shape() {
        let spec = |j: &str| serde_json::from_str::<InputSpec>(j).unwrap().channels();
        assert_eq!(spec(r#"{"shape": [1, 3, 512, 512]}"#), Some(3));
        assert_eq!(spec(r#"{"shape": [1, 512, 512, 4]}"#), Some(4));
        assert_eq!(spec(r#"{"shape": [1, 3, 4, 3]}"#), None);
        assert_eq!(spec(r#"{"shape": [1, 512, 512]}"#), None);
        assert_eq!(
            spec(
                r#"{"shape": [1, 3, 4, 3],
                    "dshape": [{"batch": 1}, {"channels": 3}, {"height": 4}, {"width": 3}]}"#
            ),
            Some(3)
        );
    }

    #[test]
    fn preprocessing_parses_from_yaml() {
        let y = r#"
schema_version: 2
input:
  shape: [1, 256, 256, 3]
  preprocessing:
    normalization: unsigned
    resize: stretch
"#;
        let schema = SchemaV2::parse_yaml(y).unwrap();
        let pre = schema.input.unwrap().preprocessing.unwrap();
        assert_eq!(
            pre.normalization,
            Some(NormalizationConfig::Preset(NormalizationPreset::Unsigned))
        );
        assert_eq!(pre.resize, Some(FitMode::Stretch));
        assert!(pre.letterbox.is_none());
    }

    #[test]
    fn class_map_masks_accept_int64() {
        let j = r#"{
          "schema_version": 2,
          "outputs": [{
            "name": "ArgMax", "type": "masks", "decoder": "semantic",
            "shape": [1, 513, 513],
            "dshape": [{"batch": 1}, {"height": 513}, {"width": 513}],
            "dtype": "int64"
          }]
        }"#;
        let schema = SchemaV2::parse_json(j).unwrap();
        schema.validate().unwrap();
        assert_eq!(schema.outputs[0].dtype, Some(DType::Int64));
        assert_eq!(DType::Int64.size_bytes(), 8);
        assert!(DType::Int64.is_integer());
    }

    #[test]
    fn single_channel_threshold_and_background_parse() {
        let j = r#"{
          "schema_version": 2,
          "outputs": [{
            "name": "segment", "type": "segmentation", "decoder": "semantic",
            "shape": [1, 256, 256, 1],
            "dshape": [{"batch": 1}, {"height": 256}, {"width": 256}, {"num_classes": 1}],
            "dtype": "float32", "activation_applied": "sigmoid",
            "threshold": 0.5, "background_index": 0
          }]
        }"#;
        let schema = SchemaV2::parse_json(j).unwrap();
        let out = &schema.outputs[0];
        assert_eq!(out.activation_applied, Some(Activation::Sigmoid));
        assert_eq!(out.semantic.threshold, Some(0.5));
        assert_eq!(out.semantic.background_index, Some(0));
    }

    #[test]
    fn reserved_mask_classification_parses_but_does_not_lower() {
        let j = r#"{
          "schema_version": 2,
          "outputs": [
            {"name": "class_queries_logits", "type": "class_logits",
             "shape": [1, 100, 151],
             "dshape": [{"batch": 1}, {"num_queries": 100}, {"num_classes": 151}],
             "dtype": "float32", "no_object_index": 150},
            {"name": "masks_queries_logits", "type": "mask_logits",
             "shape": [1, 100, 128, 128],
             "dshape": [{"batch": 1}, {"num_queries": 100}, {"height": 128}, {"width": 128}],
             "dtype": "float32", "stride": 4, "mask_activation": "sigmoid"}
          ]
        }"#;
        let schema = SchemaV2::parse_json(j).unwrap();
        schema.validate().unwrap();
        assert_eq!(schema.outputs[0].type_, Some(LogicalType::ClassLogits));
        assert_eq!(schema.outputs[0].dshape[1].0, DimName::NumQueries);
        assert_eq!(schema.outputs[0].semantic.no_object_index, Some(150));
        assert_eq!(
            schema.outputs[1].semantic.mask_activation,
            Some(MaskActivation::Sigmoid)
        );
        assert!(matches!(
            schema.to_legacy_config_outputs(),
            Err(DecoderError::NotSupported(_))
        ));
    }

    #[test]
    fn semantic_decoder_kind_shares_the_v1_code() {
        assert_eq!(
            DecoderKind::Semantic.to_v1(),
            configs::DecoderType::Semantic
        );
        let v: configs::DecoderType = serde_json::from_str("\"semantic\"").unwrap();
        assert_eq!(v, configs::DecoderType::Semantic);
    }
}