oxideav-av1 0.1.21

//! §7.11.3 Inter prediction process — sample-generation leaves and
//! supporting helpers per av1-spec p.257-265.
//!
//! This module covers the translational single-reference path of the
//! §7.11.3 inter prediction process:
//!
//! * §7.11.3.2 — [`rounding_variables`]: the
//!   `(InterRound0, InterRound1, InterPostRound)` rounding-shift
//!   derivation from `(BitDepth, isCompound)` per av1-spec p.259.
//!
//! * §7.11.3.3 — [`motion_vector_scaling`]: the
//!   `(startX, startY, stepX, stepY)` reference-frame sample-location
//!   derivation from `(plane, refIdx, x, y, mv)` per av1-spec
//!   p.260-261, returning the 10-fractional-bit reference-frame
//!   coordinate (`SCALE_SUBPEL_BITS = 10`).
//!
//! * §7.11.3.4 — [`block_inter_prediction`]: the 8-tap horizontal +
//!   vertical convolution kernel that turns `(ref[ plane ][..][..],
//!   startX, startY, stepX, stepY, w, h)` plus the chosen
//!   `interp_filter[0..1]` pair into the per-cell `pred[i][j]`
//!   intermediate samples. Per av1-spec p.262-265: the intermediate
//!   array is sized `intermediateHeight × w` with
//!   `intermediateHeight = ((h-1) * yStep + (1 << SCALE_SUBPEL_BITS) - 1) >> SCALE_SUBPEL_BITS + 8`;
//!   horizontal filter reads `ref[ Clip3(0, lastY, ...) ][ Clip3( 0,
//!   lastX, ...) ]` per (r, c, t) and rounds by
//!   `Round2(s, InterRound0)`; vertical filter reads
//!   `intermediate[ (p >> 10) + t ][ c ]` per (r, c, t) and rounds by
//!   `Round2(s, InterRound1)`.
//!
//! * [`SUBPEL_FILTERS`] — the `Subpel_Filters[ 6 ][ 16 ][ 8 ]`
//!   coefficient table verbatim from av1-spec p.263-265: indices
//!   `0..4` are the four 8-tap full-size filters (`EIGHTTAP`,
//!   `EIGHTTAP_SMOOTH`, `EIGHTTAP_SHARP`, `BILINEAR`); indices `4..6`
//!   are the small-block (`w <= 4` / `h <= 4`) 4-tap versions of
//!   `EIGHTTAP` and `EIGHTTAP_SMOOTH` per the small-block remap rule
//!   at the head of §7.11.3.4 (lines 14602-14608 of av1-spec.txt).
//!
//! * [`select_interp_filter_small_block`] — the small-block remap
//!   (`EIGHTTAP` / `EIGHTTAP_SHARP` → 4, `EIGHTTAP_SMOOTH` → 5) per
//!   av1-spec p.262 lines 14602-14608 and 14626-14632.
//!
//! ## Scope
//!
//! Translational single-ref MC + the §7.11.3.11-15 compound-mask
//! blend bodies + the §7.11.3.5-8 WARP MC kernel + the §7.11.3.9-10
//! OBMC overlap-blending leaves. With r193 the entire §7.11.3 inter
//! prediction sample-generation layer is in place; the §7.11.3.1
//! driver entry point that wires the kernels against `RefFrames[..]`
//! plane buffers + the per-block `motion_mode` arm dispatch is
//! deferred to the next arc.
//!
//! Round 193 adds the OBMC bodies:
//!
//! * §7.11.3.10 — [`overlap_blending`] (overlap-blend pixel kernel) —
//!   the `Round2( m * curr + (64 - m) * obmcPred, 6 )` site with the
//!   `pass`-driven mask-axis selection ([`OverlapPass::Above`] ⇒
//!   `m = mask[i]`, [`OverlapPass::Left`] ⇒ `m = mask[j]`).
//! * §7.11.3.9 — [`get_obmc_mask`] (length-to-table dispatch) +
//!   [`overlap_neighbour_predict_blend`] (the `predict_overlap` step-8
//!   wrapper). The mi-grid outer driver lives in the §7.11.3.1 wiring
//!   (next arc); this round provides the per-candidate post-MC blend.
//! * The five `Obmc_Mask_*` tables ([`OBMC_MASK_2`], [`OBMC_MASK_4`],
//!   [`OBMC_MASK_8`], [`OBMC_MASK_16`], [`OBMC_MASK_32`]) — verbatim
//!   from av1-spec p.277 lines 15406-15418.
//!
//! Round 192 adds the four WARP bodies:
//!
//! * §7.11.3.5 — [`block_warp`] (LOCALWARP / GLOBAL_GLOBALMV affine
//!   warp) — projects the (`srcX`, `srcY`) through the 6-element warp
//!   matrix, runs the two-pass 8-tap warped convolution against the
//!   reference plane via [`WARPED_FILTERS`], writes the 8×8
//!   sub-section into `pred`.
//! * §7.11.3.6 — [`setup_shear`] — derives `(α, β, γ, δ, warpValid)`
//!   from the warp matrix via [`resolve_divisor`] of `warpParams[2]`.
//! * §7.11.3.7 — [`resolve_divisor`] — `(divFactor, divShift)`
//!   fixed-point inverse via [`DIV_LUT`].
//! * §7.11.3.8 — [`warp_estimation`] — least-squares fit of
//!   `LocalWarpParams` from the §7.10.4 `find_warp_samples` cand
//!   list (`CandList[i] = (sy, sx, dy, dx)`).
//!
//! Round 191 adds the five compound bodies:
//!
//! * §7.11.3.11 — [`wedge_mask`] (COMPOUND_WEDGE) — generates the
//!   16 × 3-shape wedge mask table on first use via
//!   [`WedgeMaskCache`], then dispatches per `(bsize, wedge_sign,
//!   wedge_index)` to a 64 × 64 `MasterMask` slice.
//! * §7.11.3.12 — [`difference_weight_mask`] (COMPOUND_DIFFWTD) — the
//!   per-pixel `m = Clip3(0, 64, 38 + Abs(p0 - p1) / 16)` mask the
//!   `mask_type` toggle inverts.
//! * §7.11.3.13 — [`intra_mode_variant_mask`] (COMPOUND_INTRA) — the
//!   `Ii_Weights_1d[ MAX_SB_SIZE ]` (av1-spec p.283-284) smooth-mask
//!   driver with the four `II_*` interintra-mode sub-paths.
//! * §7.11.3.14 — [`mask_blend`] (compound blend with mask) — the
//!   `out = Clip1( Round2( m * p0 + (64 - m) * p1, 6 + InterPostRound ) )`
//!   inter-inter site and the `interintra` interintra site with the
//!   `(subX, subY)` chroma-subsample averaging.
//! * §7.11.3.15 — [`distance_weights`] (COMPOUND_DISTANCE) — the
//!   `(FwdWeight, BckWeight)` derivation from two `RefFrames[refList]`
//!   `OrderHints` deltas via [`Quant_Dist_Weight`] /
//!   [`Quant_Dist_Lookup`].
//!
//! And the §7.11.3.1 driver itself — once it lands, the
//! `block_inter_prediction` leaf is what the driver invokes on the
//! `useWarp == 0` branch, and the compound bodies are what the
//! driver invokes on the `isCompound == 1` / `IsInterIntra == 1` arms
//! after the §7.11.3.4 prediction has been formed.

// =====================================================================
// §3 constants used by §7.11.3 — from av1-spec.txt p.16-17.
// =====================================================================

/// `FILTER_BITS = 7` — number of bits used in Wiener filter
/// coefficients (av1-spec p.17 line 1312). Reused by §7.11.3 for the
/// `InterPostRound = 2 * FILTER_BITS - (InterRound0 + InterRound1)`
/// derivation in §7.11.3.2.
pub const FILTER_BITS: u32 = 7;

/// `SUBPEL_BITS = 4` — fractional precision of the §7.11.3.3 motion
/// vector after the §5.11 `Mvs[]` clamp (av1-spec p.16 line 1101).
pub const SUBPEL_BITS: u32 = 4;

/// `SUBPEL_MASK = (1 << SUBPEL_BITS) - 1 = 15` — mask isolating the
/// SUBPEL_BITS fractional component (av1-spec p.16 line 1104).
pub const SUBPEL_MASK: u32 = (1 << SUBPEL_BITS) - 1;

/// `SCALE_SUBPEL_BITS = 10` — fractional precision of the
/// reference-frame coordinate after §7.11.3.3 scaling. The
/// `(startX, startY, stepX, stepY)` outputs of
/// [`motion_vector_scaling`] all carry this many fractional bits
/// (av1-spec p.17 line 1106).
pub const SCALE_SUBPEL_BITS: u32 = 10;

/// `REF_SCALE_SHIFT = 14` — fractional precision of the per-plane
/// reference-frame size scaling factor (`xScale` / `yScale`) (av1-spec
/// p.16 line 1098).
pub const REF_SCALE_SHIFT: u32 = 14;

/// `EIGHTTAP = 0` — av1-spec §6.8.9 interpolation-filter ordinal
/// (av1-spec p.161 line 9158). Reproduced locally for the
/// [`select_interp_filter_small_block`] body and the
/// [`SUBPEL_FILTERS`] table indices.
pub const EIGHTTAP: u8 = 0;
/// `EIGHTTAP_SMOOTH = 1`.
pub const EIGHTTAP_SMOOTH: u8 = 1;
/// `EIGHTTAP_SHARP = 2`.
pub const EIGHTTAP_SHARP: u8 = 2;
/// `BILINEAR = 3`.
pub const BILINEAR: u8 = 3;
/// Sentinel `4` — the 4-tap small-block version of `EIGHTTAP` /
/// `EIGHTTAP_SHARP` per av1-spec p.262 line 14604 ("if interpFilter ==
/// EIGHTTAP || interpFilter == EIGHTTAP_SHARP, interpFilter = 4").
/// The full filter row sits in [`SUBPEL_FILTERS`] at index 4.
pub const EIGHTTAP_4TAP: u8 = 4;
/// Sentinel `5` — the 4-tap small-block version of `EIGHTTAP_SMOOTH`
/// per av1-spec p.262 line 14606. Lives at [`SUBPEL_FILTERS`] index 5.
pub const EIGHTTAP_SMOOTH_4TAP: u8 = 5;

// =====================================================================
// §7.11.3.2 — Rounding variables derivation process (av1-spec p.259).
// =====================================================================

/// §7.11.3.2 output: the three rounding-shift counts the §7.11.3.4
/// horizontal / vertical / post convolutions consume.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RoundingVars {
    /// `InterRound0` — bits to round after horizontal filtering.
    /// `3` for 8/10-bit content, `5` for 12-bit content.
    pub inter_round0: u32,
    /// `InterRound1` — bits to round after vertical filtering. Depends
    /// on both `isCompound` and `BitDepth`:
    /// * `isCompound == 1` ⇒ `7`.
    /// * `isCompound == 0, BitDepth != 12` ⇒ `11`.
    /// * `isCompound == 0, BitDepth == 12` ⇒ `9`.
    pub inter_round1: u32,
    /// `InterPostRound = 2 * FILTER_BITS - (InterRound0 + InterRound1)`
    /// — the post-prediction rounding shift used by the §7.11.3.1
    /// compound-blend Clip1-Round2 sites. (`FILTER_BITS = 7`.)
    pub inter_post_round: u32,
}

/// §7.11.3.2 (av1-spec p.259): derive the §7.11.3.4 / §7.11.3.1
/// rounding shifts from `(bit_depth, is_compound)`.
///
/// The spec body reads:
///
/// ```text
///   InterRound0 = 3
///   InterRound1 = isCompound ? 7 : 11
///   if (BitDepth == 12) InterRound0 += 2
///   if (BitDepth == 12 && !isCompound) InterRound1 -= 2
///   InterPostRound = 2 * FILTER_BITS - (InterRound0 + InterRound1)
/// ```
///
/// ## Arguments
///
/// * `bit_depth` — §5.5.2 frame `BitDepth` (`8`, `10`, or `12`).
/// * `is_compound` — §7.11.3.1 `isCompound = RefFrames[candRow][candCol][1] >
///   INTRA_FRAME` flag. `false` for single-reference inter blocks.
///
/// ## Returns
///
/// A [`RoundingVars`] carrying the three shifts. Returns
/// [`crate::Error::PartitionWalkOutOfRange`] for caller-bug
/// `bit_depth` outside `{8, 10, 12}`.
pub fn rounding_variables(bit_depth: u8, is_compound: bool) -> Result<RoundingVars, crate::Error> {
    if !matches!(bit_depth, 8 | 10 | 12) {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let mut inter_round0: u32 = 3;
    let mut inter_round1: u32 = if is_compound { 7 } else { 11 };
    if bit_depth == 12 {
        inter_round0 += 2;
        if !is_compound {
            inter_round1 -= 2;
        }
    }
    let inter_post_round = 2 * FILTER_BITS - (inter_round0 + inter_round1);
    Ok(RoundingVars {
        inter_round0,
        inter_round1,
        inter_post_round,
    })
}

// =====================================================================
// §7.11.3.3 — Motion vector scaling process (av1-spec p.260-261).
// =====================================================================

/// §7.11.3.3 output: the §7.11.3.4 `(startX, startY, stepX, stepY)`
/// reference-frame sample-location quadruple.
///
/// All four components carry `SCALE_SUBPEL_BITS = 10` fractional bits
/// — i.e. `startX = 1024` represents one luma sample of horizontal
/// offset into the reference frame.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MvScale {
    /// `startX` — left edge of the reference block in the reference
    /// frame's plane-coordinate system (10 fractional bits).
    pub start_x: i32,
    /// `startY` — top edge of the reference block in the reference
    /// frame's plane-coordinate system (10 fractional bits).
    pub start_y: i32,
    /// `stepX` — horizontal step per current-frame sample (10
    /// fractional bits). `1024` (= 1.0 in plane samples) for the
    /// `RefUpscaledWidth == FrameWidth` non-scaled case.
    pub step_x: i32,
    /// `stepY` — vertical step per current-frame sample (10 fractional
    /// bits). `1024` for the non-scaled case.
    pub step_y: i32,
}

/// §3 `Round2Signed(x, n)` — sign-preserving right-shift with bias-
/// half rounding. Mirrors the §3 definition at av1-spec.txt line 1568
/// — for negative inputs, `Round2Signed(x, n) = -Round2(-x, n)`.
#[inline]
pub(crate) fn round2_signed(x: i64, n: u32) -> i64 {
    if n == 0 {
        x
    } else if x >= 0 {
        (x + (1i64 << (n - 1))) >> n
    } else {
        -(((-x) + (1i64 << (n - 1))) >> n)
    }
}

/// §7.11.3.3 (av1-spec p.260-261): derive the
/// `(startX, startY, stepX, stepY)` reference-frame sample-location
/// quadruple for one (plane, refIdx, x, y, mv) input.
///
/// The spec body reads:
///
/// ```text
///   xScale = ( ( RefUpscaledWidth[refIdx]  << REF_SCALE_SHIFT ) + (FrameWidth  / 2) ) / FrameWidth
///   yScale = ( ( RefFrameHeight[refIdx]    << REF_SCALE_SHIFT ) + (FrameHeight / 2) ) / FrameHeight
///   subX, subY ← plane==0 ? (0,0) : (subsampling_x, subsampling_y)
///   halfSample = 1 << (SUBPEL_BITS - 1)
///   origX = (x << SUBPEL_BITS) + ((2 * mv[1]) >> subX) + halfSample
///   origY = (y << SUBPEL_BITS) + ((2 * mv[0]) >> subY) + halfSample
///   baseX = origX * xScale - (halfSample << REF_SCALE_SHIFT)
///   baseY = origY * yScale - (halfSample << REF_SCALE_SHIFT)
///   off   = (1 << (SCALE_SUBPEL_BITS - SUBPEL_BITS)) / 2
///   startX = Round2Signed(baseX, REF_SCALE_SHIFT + SUBPEL_BITS - SCALE_SUBPEL_BITS) + off
///   startY = Round2Signed(baseY, REF_SCALE_SHIFT + SUBPEL_BITS - SCALE_SUBPEL_BITS) + off
///   stepX  = Round2Signed(xScale, REF_SCALE_SHIFT - SCALE_SUBPEL_BITS)
///   stepY  = Round2Signed(yScale, REF_SCALE_SHIFT - SCALE_SUBPEL_BITS)
/// ```
///
/// ## Arguments
///
/// * `plane` — `0` (luma), `1` (Cb), `2` (Cr); selects (subX, subY).
/// * `subsampling_x` / `subsampling_y` — §5.5.2 chroma subsampling
///   (`0` for 4:4:4, `1` for 4:2:2 / 4:2:0).
/// * `frame_width` / `frame_height` — current frame dimensions
///   (`FrameWidth` / `FrameHeight` per §5.9.5), in LUMA samples for
///   EVERY plane — §7.11.3.3 computes `xScale` / `yScale` from the
///   luma extents regardless of `plane` (only the `mv` shift and the
///   caller's `x` / `y` are per-plane). A chroma-subsampled pair
///   silently skews the scale ratio whenever a luma extent is odd.
/// * `ref_upscaled_width` — reference frame `RefUpscaledWidth[refIdx]`
///   (the pre-superres width per §5.9.8), LUMA samples. Must equal
///   `FrameWidth` when no superres / resize is in effect.
/// * `ref_frame_height` — reference frame `RefFrameHeight[refIdx]`,
///   LUMA samples.
/// * `x` / `y` — current-frame top-left sample coordinate of the
///   prediction region.
/// * `mv` — `[mv_row, mv_col]` motion vector in §5.11 1/8-sample
///   precision (i.e. with `SUBPEL_BITS - 1` fractional bits because
///   the spec multiplies by `2` before the `>> subX` shift).
///
/// ## Returns
///
/// An [`MvScale`] carrying `(startX, startY, stepX, stepY)`. Returns
/// [`crate::Error::PartitionWalkOutOfRange`] for caller-bug arguments:
/// `plane > 2`, `subsampling_x > 1`, `subsampling_y > 1`,
/// `frame_width == 0` or `frame_height == 0`, `ref_upscaled_width ==
/// 0` or `ref_frame_height == 0`.
#[allow(clippy::too_many_arguments)]
pub fn motion_vector_scaling(
    plane: u8,
    subsampling_x: u8,
    subsampling_y: u8,
    frame_width: u32,
    frame_height: u32,
    ref_upscaled_width: u32,
    ref_frame_height: u32,
    x: i32,
    y: i32,
    mv: [i16; 2],
) -> Result<MvScale, crate::Error> {
    // ---------- caller-bug guards ----------
    if plane > 2 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if subsampling_x > 1 || subsampling_y > 1 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if frame_width == 0 || frame_height == 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if ref_upscaled_width == 0 || ref_frame_height == 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    // §7.11.3.3 scale factors. Use i64 so the `<< REF_SCALE_SHIFT`
    // does not overflow on the largest legal frame size
    // (`RefUpscaledWidth <= 2 * FrameWidth` per the §7.11.3.3
    // conformance gate, with FrameWidth up to 65536).
    let x_scale: i64 = (((ref_upscaled_width as i64) << REF_SCALE_SHIFT)
        + (frame_width as i64) / 2)
        / (frame_width as i64);
    let y_scale: i64 = (((ref_frame_height as i64) << REF_SCALE_SHIFT) + (frame_height as i64) / 2)
        / (frame_height as i64);

    // §7.11.3.3 sub-sampling per-plane.
    let sub_x: u32 = if plane == 0 { 0 } else { subsampling_x as u32 };
    let sub_y: u32 = if plane == 0 { 0 } else { subsampling_y as u32 };

    // §7.11.3.3 origX / origY in 1/16-sample (SUBPEL_BITS=4) units.
    let half_sample: i64 = 1i64 << (SUBPEL_BITS - 1);
    let orig_x: i64 = ((x as i64) << SUBPEL_BITS) + ((2 * (mv[1] as i64)) >> sub_x) + half_sample;
    let orig_y: i64 = ((y as i64) << SUBPEL_BITS) + ((2 * (mv[0] as i64)) >> sub_y) + half_sample;

    // §7.11.3.3 baseX / baseY: reference-frame coordinate with
    // `REF_SCALE_SHIFT + SUBPEL_BITS = 18` fractional bits.
    let base_x: i64 = orig_x * x_scale - (half_sample << REF_SCALE_SHIFT);
    let base_y: i64 = orig_y * y_scale - (half_sample << REF_SCALE_SHIFT);

    // §7.11.3.3 off rounding offset for tap selection.
    let off: i64 = (1i64 << (SCALE_SUBPEL_BITS - SUBPEL_BITS)) / 2;

    // §7.11.3.3 Round2Signed by `REF_SCALE_SHIFT + SUBPEL_BITS -
    // SCALE_SUBPEL_BITS = 8` so the result carries
    // `SCALE_SUBPEL_BITS = 10` fractional bits.
    let shift = REF_SCALE_SHIFT + SUBPEL_BITS - SCALE_SUBPEL_BITS;
    let start_x = round2_signed(base_x, shift) + off;
    let start_y = round2_signed(base_y, shift) + off;
    let step_x = round2_signed(x_scale, REF_SCALE_SHIFT - SCALE_SUBPEL_BITS);
    let step_y = round2_signed(y_scale, REF_SCALE_SHIFT - SCALE_SUBPEL_BITS);

    Ok(MvScale {
        start_x: start_x as i32,
        start_y: start_y as i32,
        step_x: step_x as i32,
        step_y: step_y as i32,
    })
}

// =====================================================================
// §7.11.3.4 — Subpel_Filters table (av1-spec p.263-265).
// =====================================================================

/// `Subpel_Filters[ 6 ][ 16 ][ 8 ]` — the six 16-phase filter banks
/// the §7.11.3.4 horizontal + vertical convolutions consume.
///
/// Indexed `[interpFilter][phase][tap]` where:
///
/// * `interpFilter ∈ 0..6`:
///   - `0 = EIGHTTAP` (8-tap regular)
///   - `1 = EIGHTTAP_SMOOTH` (8-tap smooth)
///   - `2 = EIGHTTAP_SHARP` (8-tap sharp)
///   - `3 = BILINEAR` (8-tap; coefficients realize a 2-tap bilinear)
///   - `4 = EIGHTTAP_4TAP` (small-block 4-tap reduction of EIGHTTAP /
///     EIGHTTAP_SHARP — taps 0,1,6,7 are zero)
///   - `5 = EIGHTTAP_SMOOTH_4TAP` (small-block 4-tap reduction of
///     EIGHTTAP_SMOOTH — taps 0,1,6,7 are zero)
/// * `phase ∈ 0..16` (SUBPEL_MASK + 1): the fractional-position
///   index `(p >> 6) & SUBPEL_MASK` from §7.11.3.4.
/// * `tap ∈ 0..8`: the eight convolution taps; sum across `tap` of
///   `coef * ref_sample` is the §7.11.3.4 `s` accumulator before
///   `Round2(s, InterRound0)` (horizontal) or `Round2(s,
///   InterRound1)` (vertical).
///
/// All values are even per the §7.11.3.4 note (av1-spec p.265 line
/// 14786). The phase-0 row of every filter is `(0, 0, 0, 128, 0, 0,
/// 0, 0)` — i.e. a unit copy at the integer position.
///
/// Table transcribed verbatim from av1-spec p.263-265 (av1-spec.txt
/// lines 14655-14783).
#[rustfmt::skip]
pub const SUBPEL_FILTERS: [[[i32; 8]; 16]; 6] = [
    // [0] EIGHTTAP (av1-spec p.263 lines 14656-14673).
    [
        [  0,  0,   0, 128,   0,   0,  0,  0 ],
        [  0,  2,  -6, 126,   8,  -2,  0,  0 ],
        [  0,  2, -10, 122,  18,  -4,  0,  0 ],
        [  0,  2, -12, 116,  28,  -8,  2,  0 ],
        [  0,  2, -14, 110,  38, -10,  2,  0 ],
        [  0,  2, -14, 102,  48, -12,  2,  0 ],
        [  0,  2, -16,  94,  58, -12,  2,  0 ],
        [  0,  2, -14,  84,  66, -12,  2,  0 ],
        [  0,  2, -14,  76,  76, -14,  2,  0 ],
        [  0,  2, -12,  66,  84, -14,  2,  0 ],
        [  0,  2, -12,  58,  94, -16,  2,  0 ],
        [  0,  2, -12,  48, 102, -14,  2,  0 ],
        [  0,  2, -10,  38, 110, -14,  2,  0 ],
        [  0,  2,  -8,  28, 116, -12,  2,  0 ],
        [  0,  0,  -4,  18, 122, -10,  2,  0 ],
        [  0,  0,  -2,   8, 126,  -6,  2,  0 ],
    ],
    // [1] EIGHTTAP_SMOOTH (av1-spec p.263 lines 14675-14692).
    [
        [  0,  0,   0, 128,   0,   0,  0,  0 ],
        [  0,  2,  28,  62,  34,   2,  0,  0 ],
        [  0,  0,  26,  62,  36,   4,  0,  0 ],
        [  0,  0,  22,  62,  40,   4,  0,  0 ],
        [  0,  0,  20,  60,  42,   6,  0,  0 ],
        [  0,  0,  18,  58,  44,   8,  0,  0 ],
        [  0,  0,  16,  56,  46,  10,  0,  0 ],
        [  0, -2,  16,  54,  48,  12,  0,  0 ],
        [  0, -2,  14,  52,  52,  14, -2,  0 ],
        [  0,  0,  12,  48,  54,  16, -2,  0 ],
        [  0,  0,  10,  46,  56,  16,  0,  0 ],
        [  0,  0,   8,  44,  58,  18,  0,  0 ],
        [  0,  0,   6,  42,  60,  20,  0,  0 ],
        [  0,  0,   4,  40,  62,  22,  0,  0 ],
        [  0,  0,   4,  36,  62,  26,  0,  0 ],
        [  0,  0,   2,  34,  62,  28,  2,  0 ],
    ],
    // [2] EIGHTTAP_SHARP (av1-spec p.264 lines 14693-14718).
    [
        [  0,  0,   0, 128,   0,   0,  0,  0 ],
        [ -2,  2,  -6, 126,   8,  -2,  2,  0 ],
        [ -2,  6, -12, 124,  16,  -6,  4, -2 ],
        [ -2,  8, -18, 120,  26, -10,  6, -2 ],
        [ -4, 10, -22, 116,  38, -14,  6, -2 ],
        [ -4, 10, -22, 108,  48, -18,  8, -2 ],
        [ -4, 10, -24, 100,  60, -20,  8, -2 ],
        [ -4, 10, -24,  90,  70, -22, 10, -2 ],
        [ -4, 12, -24,  80,  80, -24, 12, -4 ],
        [ -2, 10, -22,  70,  90, -24, 10, -4 ],
        [ -2,  8, -20,  60, 100, -24, 10, -4 ],
        [ -2,  8, -18,  48, 108, -22, 10, -4 ],
        [ -2,  6, -14,  38, 116, -22, 10, -4 ],
        [ -2,  6, -10,  26, 120, -18,  8, -2 ],
        [ -2,  4,  -6,  16, 124, -12,  6, -2 ],
        [  0,  2,  -2,   8, 126,  -6,  2, -2 ],
    ],
    // [3] BILINEAR (av1-spec p.264 lines 14719-14736).
    [
        [  0,  0,   0, 128,   0,   0,  0,  0 ],
        [  0,  0,   0, 120,   8,   0,  0,  0 ],
        [  0,  0,   0, 112,  16,   0,  0,  0 ],
        [  0,  0,   0, 104,  24,   0,  0,  0 ],
        [  0,  0,   0,  96,  32,   0,  0,  0 ],
        [  0,  0,   0,  88,  40,   0,  0,  0 ],
        [  0,  0,   0,  80,  48,   0,  0,  0 ],
        [  0,  0,   0,  72,  56,   0,  0,  0 ],
        [  0,  0,   0,  64,  64,   0,  0,  0 ],
        [  0,  0,   0,  56,  72,   0,  0,  0 ],
        [  0,  0,   0,  48,  80,   0,  0,  0 ],
        [  0,  0,   0,  40,  88,   0,  0,  0 ],
        [  0,  0,   0,  32,  96,   0,  0,  0 ],
        [  0,  0,   0,  24, 104,   0,  0,  0 ],
        [  0,  0,   0,  16, 112,   0,  0,  0 ],
        [  0,  0,   0,   8, 120,   0,  0,  0 ],
    ],
    // [4] EIGHTTAP_4TAP (small-block reduction of EIGHTTAP — av1-spec
    // p.264-265 lines 14737-14754).
    [
        [  0,  0,   0, 128,   0,   0,  0,  0 ],
        [  0,  0,  -4, 126,   8,  -2,  0,  0 ],
        [  0,  0,  -8, 122,  18,  -4,  0,  0 ],
        [  0,  0, -10, 116,  28,  -6,  0,  0 ],
        [  0,  0, -12, 110,  38,  -8,  0,  0 ],
        [  0,  0, -12, 102,  48, -10,  0,  0 ],
        [  0,  0, -14,  94,  58, -10,  0,  0 ],
        [  0,  0, -12,  84,  66, -10,  0,  0 ],
        [  0,  0, -12,  76,  76, -12,  0,  0 ],
        [  0,  0, -10,  66,  84, -12,  0,  0 ],
        [  0,  0, -10,  58,  94, -14,  0,  0 ],
        [  0,  0, -10,  48, 102, -12,  0,  0 ],
        [  0,  0,  -8,  38, 110, -12,  0,  0 ],
        [  0,  0,  -6,  28, 116, -10,  0,  0 ],
        [  0,  0,  -4,  18, 122,  -8,  0,  0 ],
        [  0,  0,  -2,   8, 126,  -4,  0,  0 ],
    ],
    // [5] EIGHTTAP_SMOOTH_4TAP (small-block reduction of
    // EIGHTTAP_SMOOTH — av1-spec p.265 lines 14755-14781).
    [
        [  0,  0,   0, 128,   0,   0,  0,  0 ],
        [  0,  0,  30,  62,  34,   2,  0,  0 ],
        [  0,  0,  26,  62,  36,   4,  0,  0 ],
        [  0,  0,  22,  62,  40,   4,  0,  0 ],
        [  0,  0,  20,  60,  42,   6,  0,  0 ],
        [  0,  0,  18,  58,  44,   8,  0,  0 ],
        [  0,  0,  16,  56,  46,  10,  0,  0 ],
        [  0,  0,  14,  54,  48,  12,  0,  0 ],
        [  0,  0,  12,  52,  52,  12,  0,  0 ],
        [  0,  0,  12,  48,  54,  14,  0,  0 ],
        [  0,  0,  10,  46,  56,  16,  0,  0 ],
        [  0,  0,   8,  44,  58,  18,  0,  0 ],
        [  0,  0,   6,  42,  60,  20,  0,  0 ],
        [  0,  0,   4,  40,  62,  22,  0,  0 ],
        [  0,  0,   4,  36,  62,  26,  0,  0 ],
        [  0,  0,   2,  34,  62,  30,  0,  0 ],
    ],
];

/// §7.11.3.4 small-block filter remap (av1-spec p.262 lines
/// 14602-14608 / 14626-14632). On the horizontal pass, applied when
/// `w <= 4`; on the vertical pass, applied when `h <= 4`. The
/// `EIGHTTAP_4TAP` / `EIGHTTAP_SMOOTH_4TAP` substitutions select the
/// 4-tap small-block rows of [`SUBPEL_FILTERS`].
///
/// `interp_filter` values outside `0..=3` pass through unchanged —
/// the spec's two-branch `if` reads as "leave the input alone
/// otherwise" (no `SWITCHABLE` value reaches §7.11.3.4 because the
/// §5.11 reader resolves switchable to a concrete filter).
#[inline]
pub fn select_interp_filter_small_block(interp_filter: u8) -> u8 {
    match interp_filter {
        EIGHTTAP | EIGHTTAP_SHARP => EIGHTTAP_4TAP,
        EIGHTTAP_SMOOTH => EIGHTTAP_SMOOTH_4TAP,
        // BILINEAR + the two 4-tap rows already (idx 4, 5) pass
        // through. Out-of-range values likewise pass through; the
        // §7.11.3.4 caller validates.
        other => other,
    }
}

// =====================================================================
// §7.11.3.4 — Block inter prediction process (av1-spec p.261-265).
// =====================================================================

/// §3 `Round2(x, n)` integer form per av1-spec.txt line 1583. Used by
/// the §7.11.3.4 horizontal / vertical convolutions.
#[inline]
fn round2(x: i64, n: u32) -> i64 {
    if n == 0 {
        x
    } else {
        (x + (1i64 << (n - 1))) >> n
    }
}

/// §3 `Clip3(low, high, v)` for `i32` operands (av1-spec p.18 line
/// 1568). Used by the §7.11.3.4 reference-sample fetch's `Clip3(0,
/// lastY, ...)` / `Clip3(0, lastX, ...)` boundary clamp.
#[inline]
fn clip3_i32(low: i32, high: i32, v: i32) -> i32 {
    if v < low {
        low
    } else if v > high {
        high
    } else {
        v
    }
}

/// §7.11.3.4 (av1-spec p.261-265): the translational 8-tap horizontal
/// + vertical convolution kernel.
///
/// On the spec's translational `useWarp == 0` branch (the only
/// branch landed in this round), the §7.11.3.1 driver calls this
/// helper with the §7.11.3.3 `(startX, startY, stepX, stepY)`
/// quadruple plus the per-ref-list `interp_filter[0..1]` and the
/// reference plane's sample grid.
///
/// The kernel walks the spec's two ordered steps:
///
/// * Step 1 — horizontal filter populates `intermediate[r][c]` for
///   `r in 0..intermediateHeight`, `c in 0..w` per av1-spec p.262
///   lines 14609-14619, with `Round2(s, InterRound0)`.
/// * Step 2 — vertical filter populates `pred[r][c]` for
///   `r in 0..h`, `c in 0..w` per av1-spec p.262 lines 14633-14642,
///   with `Round2(s, InterRound1)`.
///
/// The §7.11.3.1 outer `Clip1( pred[0][i][j] )` is *not* applied
/// here: the spec applies it at the call site after the
/// compound-blend decision (see av1-spec p.258 lines 14402-14412).
/// Callers wanting the single-ref final samples can apply
/// `Clip1(pred[i][j])` (= `Clip3(0, (1 << BitDepth) - 1, pred[i][j])`)
/// to the returned buffer; see [`clip1_single_ref`].
///
/// ## Arguments
///
/// * `plane` — `0` (luma), `1` (Cb), `2` (Cr). Determines subsampling
///   for the `(lastX, lastY)` clamp.
/// * `subsampling_x` / `subsampling_y` — §5.5.2 chroma subsampling.
/// * `ref_plane` — the reference-frame sample grid for the chosen
///   `plane`, row-major (`ref_plane[ry * ref_stride + rx]`). Length
///   must be `>= ref_height * ref_stride`.
/// * `ref_stride` — row stride in samples of `ref_plane`. Must be
///   `>= lastX + 1` (the derived per-plane width).
/// * `ref_width` / `ref_height` — §7.11.3.4 `RefUpscaledWidth[ refIdx ]`
///   / `RefFrameHeight[ refIdx ]` in LUMA samples (pre-subsampling).
///   The per-plane clamp derives inside per av1-spec p.262 lines
///   14575-14577: `lastX = ((RefUpscaledWidth + subX) >> subX) - 1`,
///   `lastY = ((RefFrameHeight + subY) >> subY) - 1` — the parity of
///   an ODD luma extent is preserved, which a caller-side pre-folded
///   per-plane width cannot represent.
/// * `start_x` / `start_y` / `step_x` / `step_y` — §7.11.3.3 outputs.
/// * `w` / `h` — prediction region width / height in current-frame
///   samples.
/// * `interp_filter_x` — `InterpFilters[candRow][candCol][1]` per
///   av1-spec p.262 line 14601 (horizontal pass).
/// * `interp_filter_y` — `InterpFilters[candRow][candCol][0]` per
///   av1-spec p.262 line 14625 (vertical pass).
/// * `inter_round0` — `RoundingVars::inter_round0` (horizontal shift).
/// * `inter_round1` — `RoundingVars::inter_round1` (vertical shift).
/// * `pred` — output buffer, row-major; length must be `>= h * w`.
///   The helper writes `pred[r * w + c]` for `r in 0..h`, `c in 0..w`.
///
/// ## Returns
///
/// `Ok(())` on success. Returns
/// [`crate::Error::PartitionWalkOutOfRange`] for caller-bug arguments:
/// `plane > 2`, `subsampling_{x,y} > 1`, `ref_width == 0`,
/// `ref_height == 0`, `ref_stride < ref_width`, `ref_plane.len() <
/// ref_height * ref_stride`, `w == 0`, `h == 0`, `w > 256`, `h > 256`,
/// `step_x <= 0`, `step_y <= 0`, `interp_filter_x >= 6`,
/// `interp_filter_y >= 6`, `pred.len() < h * w`.
#[allow(clippy::too_many_arguments)]
pub fn block_inter_prediction(
    plane: u8,
    subsampling_x: u8,
    subsampling_y: u8,
    ref_plane: &[u16],
    ref_stride: usize,
    ref_width: u32,
    ref_height: u32,
    start_x: i32,
    start_y: i32,
    step_x: i32,
    step_y: i32,
    w: usize,
    h: usize,
    interp_filter_x: u8,
    interp_filter_y: u8,
    inter_round0: u32,
    inter_round1: u32,
    pred: &mut [i32],
) -> Result<(), crate::Error> {
    // ---------- caller-bug guards ----------
    if plane > 2 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if subsampling_x > 1 || subsampling_y > 1 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    // Stride / length guards run against the DERIVED per-plane
    // extents (`ref_width` / `ref_height` are luma-unit §7.11.3.4
    // `RefUpscaledWidth` / `RefFrameHeight`; see below).
    let guard_sub_x: u32 = if plane == 0 { 0 } else { subsampling_x as u32 };
    let guard_sub_y: u32 = if plane == 0 { 0 } else { subsampling_y as u32 };
    let plane_w = ((ref_width + guard_sub_x) >> guard_sub_x) as usize;
    let plane_h = ((ref_height + guard_sub_y) >> guard_sub_y) as usize;
    if ref_width == 0 || ref_height == 0 || ref_stride < plane_w {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if ref_plane.len() < plane_h * ref_stride {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if w == 0 || h == 0 || w > 256 || h > 256 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if step_x <= 0 || step_y <= 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let n_filters = SUBPEL_FILTERS.len() as u8;
    if interp_filter_x >= n_filters || interp_filter_y >= n_filters {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if pred.len() < h * w {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    // §7.11.3.4 (av1-spec p.262 lines 14575-14577).
    //
    //   lastX = ((RefUpscaledWidth + subX) >> subX) - 1
    //   lastY = ((RefFrameHeight   + subY) >> subY) - 1
    //
    // `ref_width` / `ref_height` arrive in LUMA samples
    // (`RefUpscaledWidth[ refIdx ]` / `RefFrameHeight[ refIdx ]`) and
    // the per-plane clamp derives HERE, spec-verbatim — a caller-side
    // pre-folded per-plane width loses the parity of an odd luma
    // extent, which shifts the whole §7.11.3.3 scale ratio on scaled
    // chroma (e.g. a 213-wide resized frame: chroma 107 could lift
    // back to 213 OR 214).
    let last_x: i32 = (plane_w as i32) - 1;
    let last_y: i32 = (plane_h as i32) - 1;

    // §7.11.3.4 (av1-spec p.262 line 14581).
    //
    //   intermediateHeight = (((h-1) * yStep + (1 << SCALE_SUBPEL_BITS) - 1)
    //                          >> SCALE_SUBPEL_BITS) + 8
    let intermediate_height: usize =
        ((((h as i64) - 1) * (step_y as i64) + (1i64 << SCALE_SUBPEL_BITS) - 1)
            >> SCALE_SUBPEL_BITS) as usize
            + 8;

    // §7.11.3.4 horizontal filter small-block remap (lines 14602-14608).
    let h_filter = if w <= 4 {
        select_interp_filter_small_block(interp_filter_x) as usize
    } else {
        interp_filter_x as usize
    };

    // §7.11.3.4 vertical filter small-block remap (lines 14626-14632).
    let v_filter = if h <= 4 {
        select_interp_filter_small_block(interp_filter_y) as usize
    } else {
        interp_filter_y as usize
    };

    // §7.11.3.4 intermediate buffer. The post-Round2 value fits in
    // ~14 bits for 8-bit content (sum of |coef| at one phase is at
    // most 384, times max sample 255 = 97920, Round2 by 3 = 12240
    // — well within i32). We use i32 for headroom across bit depths.
    let mut intermediate: Vec<i32> = vec![0i32; intermediate_height * w];

    // ---------- §7.11.3.4 step 1: horizontal filter ----------
    //
    //   for r in 0..intermediateHeight:
    //     for c in 0..w:
    //       s = 0
    //       p = x + xStep * c
    //       for t in 0..8:
    //         s += Subpel_Filters[hFilter][(p >> 6) & SUBPEL_MASK][t]
    //              * ref[Clip3(0, lastY, (y >> 10) + r - 3)]
    //                   [Clip3(0, lastX, (p >> 10) + t - 3)]
    //       intermediate[r][c] = Round2(s, InterRound0)
    //
    // (av1-spec p.262 lines 14609-14619.)
    let y_base = (start_y >> SCALE_SUBPEL_BITS) - 3;
    for r in 0..intermediate_height {
        let ry = clip3_i32(0, last_y, y_base + (r as i32)) as usize;
        let row_base = ry * ref_stride;
        for c in 0..w {
            let p: i32 = start_x + step_x * (c as i32);
            // §7.11.3.4 phase index `(p >> 6) & SUBPEL_MASK` —
            // `>> 6` reduces SCALE_SUBPEL_BITS=10 to SUBPEL_BITS=4
            // (10 - 4 = 6) and the mask isolates the 4-bit phase.
            let phase = ((p >> (SCALE_SUBPEL_BITS - SUBPEL_BITS)) as u32 & SUBPEL_MASK) as usize;
            let p_int = p >> SCALE_SUBPEL_BITS;
            let coeffs = &SUBPEL_FILTERS[h_filter][phase];
            let mut s: i64 = 0;
            for (t, coef) in coeffs.iter().enumerate() {
                let rx = clip3_i32(0, last_x, p_int + (t as i32) - 3) as usize;
                let sample = ref_plane[row_base + rx] as i64;
                s += (*coef as i64) * sample;
            }
            intermediate[r * w + c] = round2(s, inter_round0) as i32;
        }
    }

    // ---------- §7.11.3.4 step 2: vertical filter ----------
    //
    //   for r in 0..h:
    //     for c in 0..w:
    //       s = 0
    //       p = (y & 1023) + yStep * r
    //       for t in 0..8:
    //         s += Subpel_Filters[vFilter][(p >> 6) & SUBPEL_MASK][t]
    //              * intermediate[(p >> 10) + t][c]
    //       pred[r][c] = Round2(s, InterRound1)
    //
    // (av1-spec p.262 lines 14633-14642.)
    let y_frac_mask: i32 = (1i32 << SCALE_SUBPEL_BITS) - 1;
    for r in 0..h {
        let p: i32 = (start_y & y_frac_mask) + step_y * (r as i32);
        let phase = ((p >> (SCALE_SUBPEL_BITS - SUBPEL_BITS)) as u32 & SUBPEL_MASK) as usize;
        let p_int = (p >> SCALE_SUBPEL_BITS) as usize;
        let coeffs = &SUBPEL_FILTERS[v_filter][phase];
        for c in 0..w {
            let mut s: i64 = 0;
            for (t, coef) in coeffs.iter().enumerate() {
                let interp_row = p_int + t;
                // The intermediate-height derivation above guarantees
                // `p_int + t < intermediate_height` for every legal
                // (r, t) — `(h-1) * yStep < intermediateHeight - 7`
                // after applying the `+8` margin from line 14582.
                let v = intermediate[interp_row * w + c] as i64;
                s += (*coef as i64) * v;
            }
            pred[r * w + c] = round2(s, inter_round1) as i32;
        }
    }

    Ok(())
}

/// §7.11.3.1 single-ref post-prediction `Clip1` (av1-spec p.258 line
/// 14402): on the non-compound, non-interintra path, the spec writes
/// `CurrFrame[plane][y+i][x+j] = Clip1( preds[0][i][j] )`. This helper
/// applies that clip to the [`block_inter_prediction`] output for
/// callers who want sample-domain predictions.
///
/// `bit_depth` must be one of `{8, 10, 12}`; pred values are clipped
/// in-place to `[0, (1 << bit_depth) - 1]`.
pub fn clip1_single_ref(bit_depth: u8, pred: &[i32], out: &mut [u16]) -> Result<(), crate::Error> {
    if !matches!(bit_depth, 8 | 10 | 12) {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if out.len() < pred.len() {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let max = (1i32 << bit_depth) - 1;
    for (dst, src) in out.iter_mut().zip(pred.iter().copied()) {
        *dst = clip3_i32(0, max, src) as u16;
    }
    Ok(())
}

// =====================================================================
// §7.11.3.1 — Motion compensation driver (av1-spec p.257-258).
// =====================================================================
//
// The §7.11.3.1 process composes the §7.11.3.2 rounding-variables
// derivation, the §7.11.3.3 motion-vector scaling, and (per `useWarp`)
// either the §7.11.3.4 8-tap translational kernel or the §7.11.3.5-8
// warp kernel into one prediction for a `w × h` region of one plane,
// then applies the §7.11.3.1 final-clip / compound-blend step and
// (when `motion_mode == OBMC`) hands off to §7.11.3.9-10 for the
// overlap blend.
//
// r194 landed the minimum end-to-end path: single-reference
// translational MC (`is_compound == false`, `motion_mode ==
// MOTION_MODE_SIMPLE`, `IsInterIntra == false`) — i.e. the §7.11.3.1
// steps 1, 4, 5 (refList=0), 8, 9, 10, 13, then the
// `isCompound == 0 && IsInterIntra == 0` final-clip arm of the
// "inter predicted samples are then derived" step (av1-spec p.258
// line 14402).
//
// r201 wires the §7.11.3.1 step-14 compound arm: when `is_compound ==
// true`, the driver iterates `refList ∈ {0, 1}`, runs the same §7.11.3.3
// + §7.11.3.4 pipeline twice (one per ref), then dispatches on
// `compound_type` per av1-spec p.258 lines 14400-14412:
//
//   * `COMPOUND_AVERAGE` (line 14405) — `Clip1(Round2(preds[0] +
//     preds[1], 1 + InterPostRound))` per pixel.
//   * `COMPOUND_DISTANCE` (line 14408) — `Clip1(Round2(FwdWeight *
//     preds[0] + BckWeight * preds[1], 4 + InterPostRound))` per pixel
//     using `(FwdWeight, BckWeight)` from §7.11.3.15.
//   * `COMPOUND_WEDGE` / `COMPOUND_DIFFWTD` / `COMPOUND_INTRA` (line
//     14412) — `mask_blend(preds, plane, x, y, w, h)` with the
//     §7.11.3.11 / §7.11.3.12 / §7.11.3.13 mask. The mask is computed
//     once at `plane == 0` (spec line 14386-14393 condition) and reused
//     for chroma via [`mask_blend`]'s `(sub_x, sub_y)` downsampling.
//     The driver does not compute the mask itself — the caller supplies
//     the already-derived luma-grid mask through `CompoundParams`.
//
// The remaining `motion_mode == WARPED_CAUSAL` / `motion_mode == OBMC`
// arms surface dedicated [`crate::Error`] variants — the caller can
// therefore narrow the call site once each arm lands.
//
// Steps mapped to this driver:
//
// * Step 1  → [`rounding_variables`]
// * Steps 2,3,6,7 → WARP / global-warp arm — `motion_mode ==
//   MOTION_MODE_WARPED_CAUSAL` short-circuits at
//   `Error::PredictInterWarpUnsupported`.
// * Step 4  → `refList = 0` (the compound path also runs refList=1).
// * Step 5  → caller supplies `ref_frame[refList]` through the
//   `RefPlane` argument array.
// * Step 8  → caller-supplied `mv[refList]`.
// * Step 9  → caller-supplied `ref_idx[refList]`. We do not validate
//   the `use_intrabc` arm here — its `RefFrameWidth[-1] = FrameWidth`
//   etc. is the caller's responsibility (the kernel only consumes
//   already-resolved `ref_width` / `ref_height` / `ref_upscaled_width`).
// * Step 10 → [`motion_vector_scaling`]
// * Step 11 → not driver-side (`use_intrabc` ref-dim override is
//   caller responsibility, same rationale as step 9).
// * Step 12 → WARP arm — short-circuits as above.
// * Step 13 → [`block_inter_prediction`] (the §7.11.3.4 leaf).
// * Step 14 → `is_compound == 1` repeats steps 5-13 for `refList = 1`
//   into a second `preds[1]` buffer, then dispatches the
//   `compound_type` arm of the "inter predicted samples are then
//   derived" step.
// * "Mask" prep / "inter predicted samples are then derived" —
//   `isCompound == 0 && IsInterIntra == 0` arm:
//   `CurrFrame[plane][y+i][x+j] = Clip1( preds[0][i][j] )`. We write
//   into a caller-supplied flat `pred_out: &mut [u16]` per-block
//   buffer; integrating the per-`CurrFrame[plane]` merge is the
//   walker's responsibility (it owns the per-plane buffer; see
//   [`crate::PartitionWalker::curr_frame`]). The compound arm writes
//   into the same `pred_out` buffer with the §7.11.3.11-15 combined
//   output.
// * §7.11.3.1 post-step `motion_mode == OBMC` — runs the §7.11.3.9
//   `overlapped_motion_compensation` mi-grid walk (above-pass +
//   left-pass) against the caller-supplied [`ObmcParams`] context,
//   blending each qualifying neighbour's translational MC into the
//   in-place `pred_out` buffer via §7.11.3.10
//   [`overlap_neighbour_predict_blend`].

/// §7.11.3.1 per-`refList` MV / ref descriptor (av1-spec p.257
/// step 5-10): the per-list inputs the driver consumes once for
/// `refList == 0` on the single-ref path, twice on the compound
/// path.
///
/// Lives in one place rather than fanned out across
/// [`predict_inter`]'s argument list so adding the compound arm in a
/// future arc is a one-call-site change.
#[derive(Debug, Clone, Copy)]
pub struct PredictInterRef<'a> {
    /// §7.11.3.1 step 5 — `RefFrames[candRow][candCol][refList]`
    /// resolved to a per-plane sample buffer. Row-major flat layout
    /// with `ref_stride` column stride. Per-plane sample values are
    /// the spec's `RefFrames[][][..]` values clipped to `BitDepth`
    /// (i.e. `0..=(1 << bit_depth) - 1`).
    pub ref_plane: &'a [u16],
    /// Column stride of `ref_plane` (`>= ref_width`).
    pub ref_stride: usize,
    /// §7.11.3.3 `RefUpscaledWidth[refIdx]` — pre-superres ref
    /// width in LUMA samples (r405: NOT per-plane — §7.11.3.3 derives
    /// `xScale` from the luma extents for every plane, and a
    /// pre-folded chroma width loses the parity of an odd luma
    /// extent). Equal to `ref_width` when superres / resize is not
    /// in effect.
    pub ref_upscaled_width: u32,
    /// §7.11.3.4 clamp width in LUMA samples (the §7.20 stores hold
    /// planes at the upscaled extent, so this equals
    /// `ref_upscaled_width` for stored references). The §7.11.3.4
    /// leaf derives the per-plane `lastX` internally.
    pub ref_width: u32,
    /// §7.11.3.3 `RefFrameHeight[refIdx]` in LUMA samples.
    pub ref_height: u32,
    /// §7.11.3.1 step 8 — `Mvs[candRow][candCol][refList]` in
    /// 1/8-luma-sample precision per §5.11 (the [`motion_vector_scaling`]
    /// body multiplies by 2 before the chroma `>> subX` shift).
    /// Layout: `[mv_row, mv_col]` per av1-spec.
    pub mv: [i16; 2],
}

/// §7.11.3.1 step-14 compound-combine descriptor (av1-spec p.258 lines
/// 14384-14412): selects one of the five `compound_type` combine arms
/// and carries the per-arm side data the §7.11.3.11-15 leaves consume.
///
/// The driver receives this as `Some(_)` when `is_compound == true`
/// and `None` (or ignored) on the single-ref path. Per av1-spec p.258
/// line 14386-14393, the §7.11.3.11 / §7.11.3.12 / §7.11.3.13 mask is
/// computed once at `plane == 0` and **reused** for chroma planes
/// (downsampled by [`mask_blend`]'s `(sub_x, sub_y)` argument). The
/// caller is responsible for computing the mask once at `plane == 0`
/// and passing the same buffer on subsequent `plane == 1` / `plane == 2`
/// invocations — the driver does not cache it across calls.
///
/// `Copy` / `Clone` are intentionally *not* derived: the
/// [`CompoundParams::Diffwtd`] arm carries a `&mut [u8]` persistent
/// luma-grid mask buffer (the §7.11.3.12 mask the driver derives from
/// the two `preds[]` at `plane == 0` and reuses verbatim for the chroma
/// planes per av1-spec p.258 line 14392's `plane == 0` guard), which is
/// not copyable. The value is consumed once per [`predict_inter`] call.
#[derive(Debug)]
pub enum CompoundParams<'a> {
    /// `COMPOUND_AVERAGE` (av1-spec p.258 line 14405) — `Clip1(Round2(
    /// preds[0] + preds[1], 1 + InterPostRound))` per pixel. No mask /
    /// weights needed.
    Average,
    /// `COMPOUND_DISTANCE` (av1-spec p.258 line 14408) — `Clip1(Round2(
    /// FwdWeight * preds[0] + BckWeight * preds[1], 4 + InterPostRound))`
    /// per pixel, using `(FwdWeight, BckWeight)` from the §7.11.3.15
    /// `distance_weights` body.
    Distance(DistanceWeights),
    /// `COMPOUND_WEDGE` (av1-spec p.258 line 14412 via §7.11.3.11 +
    /// §7.11.3.14) — wedge-mask blend. The mask is the §7.11.3.11
    /// output filled at `plane == 0` (luma grid) and reused across
    /// planes via [`mask_blend`]'s `(sub_x, sub_y)` downsampling.
    /// `mask_stride` is the row stride of `mask`; `0` selects the
    /// natural `2*w` (when `sub_x == 1`) or `w` row stride.
    Wedge {
        /// Luma-grid wedge mask (filled by [`wedge_mask`]).
        mask: &'a [u8],
        /// Row stride of `mask` in `u8`s; `0` selects the default.
        mask_stride: usize,
    },
    /// `COMPOUND_DIFFWTD` (av1-spec p.258 line 14412 via §7.11.3.12 +
    /// §7.11.3.14) — difference-weight mask blend. Unlike the wedge /
    /// intra arms, the §7.11.3.12 mask is a function of the two
    /// `preds[]` themselves, so it cannot be supplied by the caller
    /// ahead of motion compensation. The driver derives it *internally*
    /// from the actual `pred0` / `pred1` it forms, at `plane == 0` only
    /// (av1-spec p.258 line 14392: "Otherwise if compound_type is equal
    /// to COMPOUND_DIFFWTD and plane is equal to 0, the difference
    /// weight mask process … is invoked"). The luma-grid mask then
    /// persists for the chroma planes, which reuse it through
    /// [`mask_blend`]'s `(sub_x, sub_y)` downsampling.
    Diffwtd {
        /// §5.11.29 `mask_type` bit (`0` = `DIFFWTD_38`, `1` =
        /// `DIFFWTD_38_INV`) — the §7.11.3.12 `mask_type` toggle that
        /// inverts the per-pixel weight (`Mask = 64 - m`).
        mask_type: u8,
        /// Persistent luma-grid mask buffer, length `>= block_w *
        /// block_h` (the *luma* block extent). The driver writes the
        /// §7.11.3.12 result here on the `plane == 0` call and reads it
        /// back on the chroma calls. The caller owns this buffer across
        /// the per-plane [`predict_inter`] invocations for one block and
        /// must pass the *same* buffer each time so the chroma planes see
        /// the luma-derived mask (the driver does not cache it).
        mask: &'a mut [u8],
    },
    /// `COMPOUND_INTRA` (av1-spec p.258 line 14412 via §7.11.3.13 +
    /// §7.11.3.14) — inter-intra-variant mask blend (also reached on
    /// the `IsInterIntra == 0 && compound_type == COMPOUND_INTRA`
    /// compound path per p.258 lines 14389-14390). The mask is the
    /// §7.11.3.13 output from [`intra_mode_variant_mask`].
    Intra {
        /// Mask buffer (filled by [`intra_mode_variant_mask`]).
        mask: &'a [u8],
        /// Row stride of `mask` in `u8`s; `0` selects the default.
        mask_stride: usize,
    },
}

/// §7.11.3.1 inter-intra blend descriptor (av1-spec p.258 lines
/// 14384-14412 + §7.11.3.14) — the `IsInterIntra == 1` arm's side data.
///
/// On an inter-intra block `isCompound == 0` (`RefFrame[1] ==
/// INTRA_FRAME`): the §7.11.3.1 driver forms a *single* inter prediction
/// `preds[0]` from `refs[0]`, then blends it against the intra prediction
/// the §7.11.2 process already wrote into the destination buffer
/// (`pred1 = CurrFrame[plane][y+dstY][x+dstX]` per av1-spec p.284 line
/// 15786) through the §7.11.3.14 inter-intra blend body
/// ([`mask_blend_interintra`]).
///
/// This descriptor carries the §5.11.28 `interintra_mode` that selects
/// the §7.11.3.13 [`intra_mode_variant_mask`] variant, plus the optional
/// `wedge_interintra == 1` sub-arm payload:
///
/// * **Non-wedge** (`wedge == None`, `wedge_interintra == 0`). The mask
///   is the §7.11.3.13 [`intra_mode_variant_mask`] output for
///   `interintra_mode`; §7.11.3.14 reads it directly at `Mask[y][x]`
///   (the `(interintra && !wedge_interintra)` branch, av1-spec p.284
///   line 15773) so no chroma downsampling is needed.
/// * **Wedge** (`wedge == Some(_)`, `wedge_interintra == 1`). The mask
///   is the §7.11.3.11 luma-grid wedge mask (`wedge_index`, `wedge_sign
///   == 0` per av1-spec p.79 line 4965), built once at `plane == 0` and
///   read with `(subX, subY)` averaging for the chroma planes
///   (av1-spec p.284 line 15773's predicate does **not** short-circuit
///   when `wedge_interintra == 1`). `interintra_mode` still selects the
///   §7.11.2 *intra* prediction the caller writes into `dst`, but the
///   §7.11.3.13 mask is not used on this arm.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct InterIntraParams<'a> {
    /// §5.11.28 `interintra_mode` (`II_DC_PRED` / `II_V_PRED` /
    /// `II_H_PRED` / `II_SMOOTH_PRED`, i.e. `0..=3`) — selects the
    /// §7.11.3.13 [`intra_mode_variant_mask`] variant whose per-plane
    /// `w × h` `Mask` the §7.11.3.14 body blends with on the non-wedge
    /// arm. (On the wedge arm the §7.11.3.13 mask is unused; only the
    /// §7.11.2 intra prediction it ultimately drives matters.)
    pub interintra_mode: u8,
    /// `Some(_)` selects the §7.11.3.11 wedge sub-arm
    /// (`wedge_interintra == 1`); `None` selects the §7.11.3.13
    /// intra-variant sub-arm (`wedge_interintra == 0`).
    pub wedge: Option<WedgeInterIntraInfo<'a>>,
}

/// §7.11.3.11 wedge sub-arm payload for [`InterIntraParams`]
/// (`wedge_interintra == 1`).
///
/// The §7.11.3.1 mask-prep step builds the §7.11.3.11 wedge mask only at
/// `plane == 0` (av1-spec p.258 line 14386), so the caller fills a single
/// *luma-grid* mask via [`wedge_mask`] and reuses it across the per-plane
/// [`predict_inter`] calls for one block; the chroma planes read it
/// through [`mask_blend_interintra`]'s `(sub_x, sub_y)` averaging.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct WedgeInterIntraInfo<'a> {
    /// Luma-grid wedge mask (filled by [`wedge_mask`] with
    /// `wedge_sign == 0`, the value §5.11.28 fixes for the interintra
    /// arm). Native extent is the *luma* block `block_w × block_h`.
    pub mask: &'a [u8],
    /// Row stride of `mask` in `u8`s; `0` selects the natural stride
    /// (`block_w` at the luma plane, `2*w` at a `sub_x == 1` chroma
    /// plane).
    pub mask_stride: usize,
}

/// §7.11.3.1 driver — translational single-reference MC arm.
///
/// Composes [`rounding_variables`] (§7.11.3.2),
/// [`motion_vector_scaling`] (§7.11.3.3), and
/// [`block_inter_prediction`] (§7.11.3.4) into one `w × h`
/// prediction per the av1-spec p.257-258 process, then applies the
/// §7.11.3.1 single-ref final-clip (`CurrFrame[plane][y+i][x+j] =
/// Clip1( preds[0][i][j] )`, av1-spec p.258 line 14402).
///
/// ## Implemented (r194 single-ref + r201 compound)
///
/// * Step 1 — `rounding_variables(bit_depth, is_compound)`.
/// * Step 4 — `refList = 0` (single-ref + compound) plus the step-14
///   `refList = 1` repeat on the compound arm.
/// * Steps 8-10 — `motion_vector_scaling(plane, subsampling_*,
///   frame_*, ref_upscaled_width, ref_frame_height, x, y, mv)`.
/// * Step 13 — `block_inter_prediction(plane, subsampling_*,
///   ref_plane, ref_stride, ref_width, ref_height, startX, startY,
///   stepX, stepY, w, h, interp_filter_x, interp_filter_y,
///   InterRound0, InterRound1, pred)`.
/// * "inter predicted samples are then derived" arms (av1-spec p.258
///   lines 14400-14412):
///   * `isCompound == 0 && IsInterIntra == 0` — single-ref final-clip
///     `Clip1(pred[i*w+j])` via [`clip1_single_ref`].
///   * `COMPOUND_AVERAGE` — `Clip1(Round2(preds[0] + preds[1],
///     1 + InterPostRound))` per pixel.
///   * `COMPOUND_DISTANCE` — `Clip1(Round2(FwdWeight * preds[0] +
///     BckWeight * preds[1], 4 + InterPostRound))` via
///     [`compound_distance_blend`].
///   * `COMPOUND_WEDGE` / `COMPOUND_DIFFWTD` / `COMPOUND_INTRA` —
///     [`mask_blend`] with the caller-supplied luma-grid mask (the
///     mask is computed once at `plane == 0` and reused for chroma per
///     spec line 14386-14393's `plane == 0` guard, with the per-plane
///     downsampling handled inside `mask_blend` via `(sub_x, sub_y)`).
///
/// ## Stubbed arms
///
/// Post-r203 every motion mode (SIMPLE, WARPED_CAUSAL, OBMC, plus
/// compound) has driver-side wiring. The remaining caller-bug
/// guards surface [`crate::Error::PartitionWalkOutOfRange`] when a
/// caller signals a motion mode without supplying its required
/// context bundle (WARPED_CAUSAL without `WarpDriverParams`, OBMC
/// without `ObmcParams`).
///
/// ## Arguments
///
/// * `plane` — 0 (Y) / 1 (Cb) / 2 (Cr).
/// * `x` / `y` — top-left sample coordinate of the prediction region
///   in the per-plane current-frame space.
/// * `w` / `h` — prediction region extent in per-plane samples.
/// * `motion_mode` — §5.11.27 `motion_mode` ordinal
///   ([`crate::MOTION_MODE_SIMPLE`] / `MOTION_MODE_OBMC` /
///   `MOTION_MODE_WARPED_CAUSAL`). r194 supports `SIMPLE` only.
/// * `is_compound` — §7.11.3.1 `isCompound`. When `true`, `refs` must
///   contain at least 2 entries and `compound` must be `Some(_)`.
/// * `is_inter_intra` — §5.11.33 `IsInterIntra` (`RefFrame[1] ==
///   INTRA_FRAME`). When `true`, `is_compound` must be `false` and
///   `inter_intra` must be `Some(_)`; the driver forms a single inter
///   prediction from `refs[0]` and blends it with the §7.11.2 intra
///   prediction the caller already wrote into `pred_out` (the §7.11.3.14
///   inter-intra body, [`mask_blend_interintra`]). Both interintra
///   sub-arms are wired: `InterIntraParams.wedge == None` selects the
///   non-wedge (`COMPOUND_INTRA`, §7.11.3.13) mask; `Some(_)` selects
///   the `wedge_interintra == 1` (`COMPOUND_WEDGE`, §7.11.3.11) mask.
/// * `inter_intra` — `Some(InterIntraParams)` on the inter-intra arm
///   (`is_inter_intra == true`); must be `None` otherwise. Carries the
///   §5.11.28 `interintra_mode` and the optional `wedge` sub-arm mask.
/// * `bit_depth` — §5.5.2 frame `BitDepth` (8 / 10 / 12).
/// * `subsampling_x` / `subsampling_y` — §5.5.2 chroma subsampling.
/// * `frame_width` / `frame_height` — §5.9.5 current-frame
///   dimensions in luma samples (the `motion_vector_scaling` body
///   reduces to per-plane internally).
/// * `interp_filter_x` / `interp_filter_y` — §5.11.x
///   `InterpFilters[plane][0..1]` ordinals (`EIGHTTAP` /
///   `EIGHTTAP_SMOOTH` / `EIGHTTAP_SHARP` / `BILINEAR`). The
///   §7.11.3.4 small-block remap is applied inside the leaf.
/// * `refs` — per-list `(ref_plane, ref_stride, mv, ref_dims)`
///   bundles. On the single-ref path `refs.len() >= 1` (only
///   `refs[0]` is consulted); on the compound path `refs.len() >= 2`.
/// * `compound` — `Some(CompoundParams)` on the compound arm
///   (`is_compound == true`); must be `None` on the single-ref arm.
///   See [`CompoundParams`] for the per-`compound_type` payloads.
/// * `pred_out` — flat `w * h` row-major output buffer
///   (`pred_out[i*w + j]`). Receives the §7.11.3.1 single-ref
///   `Clip1(preds[0][i][j])` on the single-ref arm, or the
///   §7.11.3.11-15 combined output on the compound arm.
///
/// ## Returns
///
/// `Ok(())` on success (all four motion modes wired post-r203).
/// Returns `Error::PartitionWalkOutOfRange` for caller-bug arguments:
/// `plane > 2`, `subsampling_{x,y} > 1`, `bit_depth ∉ {8, 10, 12}`,
/// `frame_{width,height} == 0`, `w == 0 || h == 0 || w > 256 ||
/// h > 256`, `refs.is_empty()`, `refs.len() < 2` on the compound
/// path, missing/spurious `compound` argument, missing/spurious
/// `inter_intra` argument, `is_compound && is_inter_intra`, an
/// out-of-range `interintra_mode`, `pred_out.len() <
/// w * h`, missing `warp` on the WARPED_CAUSAL arm, missing `obmc`
/// on the OBMC arm, or any sub-condition the `motion_vector_scaling` /
/// `block_inter_prediction` / `clip1_single_ref` / `mask_blend` /
/// `mask_blend_interintra` / `intra_mode_variant_mask` /
/// `compound_distance_blend` leaves reject.
/// §7.11.3.1 step 5-13 per-`refList` body (av1-spec p.257 lines
/// 14315-14374) — produce the `preds[refList][i][j]` `i32` prediction
/// array for one reference. Used twice on the compound arm.
///
/// Drives [`motion_vector_scaling`] (§7.11.3.3) → [`block_inter_prediction`]
/// (§7.11.3.4) with the same `(plane, subsampling_*, frame_*,
/// interp_filter_*, inter_round0, inter_round1)` shared across refs.
///
/// Allocates the `w * h` `i32` buffer fallibly (returns
/// `Error::PartitionWalkOutOfRange` on alloc failure).
#[allow(clippy::too_many_arguments)]
fn predict_inter_per_ref(
    r: &PredictInterRef<'_>,
    plane: u8,
    x: i32,
    y: i32,
    w: usize,
    h: usize,
    subsampling_x: u8,
    subsampling_y: u8,
    frame_width: u32,
    frame_height: u32,
    interp_filter_x: u8,
    interp_filter_y: u8,
    inter_round0: u32,
    inter_round1: u32,
) -> Result<Vec<i32>, crate::Error> {
    let mvs = motion_vector_scaling(
        plane,
        subsampling_x,
        subsampling_y,
        frame_width,
        frame_height,
        r.ref_upscaled_width,
        r.ref_height,
        x,
        y,
        r.mv,
    )?;

    let mut pred: Vec<i32> = Vec::new();
    if pred.try_reserve_exact(w * h).is_err() {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    pred.resize(w * h, 0);

    block_inter_prediction(
        plane,
        subsampling_x,
        subsampling_y,
        r.ref_plane,
        r.ref_stride,
        r.ref_width,
        r.ref_height,
        mvs.start_x,
        mvs.start_y,
        mvs.step_x,
        mvs.step_y,
        w,
        h,
        interp_filter_x,
        interp_filter_y,
        inter_round0,
        inter_round1,
        &mut pred,
    )?;
    Ok(pred)
}

/// §7.11.3.1 step-14 compound combine (av1-spec p.258 lines 14400-14412)
/// — dispatch on `CompoundParams` to apply one of the five §7.11.3.11-15
/// blend mechanisms and write the result into `pred_out`.
///
/// * `COMPOUND_AVERAGE` is inlined here (the §7.11.3.1 body itself
///   carries it — no separate leaf).
/// * `COMPOUND_DISTANCE` routes to [`compound_distance_blend`].
/// * `COMPOUND_WEDGE` / `COMPOUND_DIFFWTD` / `COMPOUND_INTRA` route to
///   [`mask_blend`] with the caller-supplied luma-grid mask.
#[allow(clippy::too_many_arguments)]
fn predict_inter_compound_blend(
    plane: u8,
    bit_depth: u8,
    inter_post_round: u32,
    subsampling_x: u8,
    subsampling_y: u8,
    w: usize,
    h: usize,
    pred0: &[i32],
    pred1: &[i32],
    params: CompoundParams<'_>,
    pred_out: &mut [u16],
) -> Result<(), crate::Error> {
    match params {
        CompoundParams::Average => {
            // av1-spec p.258 line 14405:
            //   CurrFrame[plane][y+i][x+j] =
            //       Clip1(Round2(preds[0][i][j] + preds[1][i][j],
            //                    1 + InterPostRound))
            let max: i32 = (1i32 << bit_depth) - 1;
            let shift: u32 = 1 + inter_post_round;
            for i in 0..h {
                for j in 0..w {
                    let acc = pred0[i * w + j] as i64 + pred1[i * w + j] as i64;
                    let rounded = round2(acc, shift) as i32;
                    pred_out[i * w + j] = clip3_i32(0, max, rounded) as u16;
                }
            }
            Ok(())
        }
        CompoundParams::Distance(weights) => compound_distance_blend(
            bit_depth,
            inter_post_round,
            weights,
            pred0,
            pred1,
            w,
            h,
            pred_out,
        ),
        CompoundParams::Wedge { mask, mask_stride }
        | CompoundParams::Intra { mask, mask_stride } => mask_blend(
            bit_depth,
            inter_post_round,
            subsampling_x,
            subsampling_y,
            pred0,
            pred1,
            w,
            h,
            mask,
            mask_stride,
            pred_out,
        ),
        CompoundParams::Diffwtd { mask_type, mask } => {
            // av1-spec p.258 lines 14392-14393: the §7.11.3.12 mask is
            // derived from the two `preds[]` at `plane == 0` only and
            // then reused verbatim for the chroma planes (the `Mask`
            // array persists across the per-plane invocations). The
            // luma grid is `(w << sub_x) × (h << sub_y)`; on the luma
            // plane that is exactly `w × h` so the §7.11.3.12 output
            // sizing matches `pred0` / `pred1` directly.
            let luma_w = w << subsampling_x;
            let luma_h = h << subsampling_y;
            if plane == 0 {
                // The §7.11.3.12 process consumes the *luma* `preds[]`
                // (here `pred0` / `pred1`, which are luma-grid on the
                // `plane == 0` call) and fills the persistent `Mask`
                // array on the luma grid.
                if mask.len() < luma_w * luma_h {
                    return Err(crate::Error::PartitionWalkOutOfRange);
                }
                difference_weight_mask(
                    bit_depth,
                    inter_post_round,
                    mask_type,
                    pred0,
                    pred1,
                    luma_w,
                    luma_h,
                    mask,
                )?;
            }
            // §7.11.3.14: blend the current plane's `preds[]` through
            // the (luma-grid) `Mask`, downsampling for chroma via the
            // `(sub_x, sub_y)` arm. The luma-grid row stride is `luma_w`.
            mask_blend(
                bit_depth,
                inter_post_round,
                subsampling_x,
                subsampling_y,
                pred0,
                pred1,
                w,
                h,
                mask,
                luma_w,
                pred_out,
            )
        }
    }
}

/// §7.11.3.1 step-2/3/6/7 useWarp-derivation inputs (av1-spec p.257
/// lines 14308-14349) — the per-block warp context [`predict_inter`]
/// consumes once on its WARP arm to decide between LOCALWARP
/// (`useWarp == 1`) and GLOBAL_GLOBALMV (`useWarp == 2`) dispatch.
///
/// The driver receives this as `Some(_)` whenever
/// `motion_mode == MOTION_MODE_WARPED_CAUSAL` (= spec LOCALWARP) or
/// the §5.11.x cascade has already decided
/// `YMode ∈ {GLOBALMV, GLOBAL_GLOBALMV}` against a `GmType[refFrame] >
/// TRANSLATION` reference. A caller-supplied `None` keeps the prior
/// translational-only path — the driver behaves exactly as the r194
/// / r201 SIMPLE / compound arms do when `motion_mode ==
/// MOTION_MODE_SIMPLE` and no global-warp gating fires.
///
/// Step-by-step the driver consumes:
///
/// * **Step 2** — `motion_mode == LOCALWARP` ⇒ the §7.11.3.8
///   `warp_estimation` is invoked at the caller site; the result is
///   plumbed in via `local_warp_params` / `local_valid`.
/// * **Step 3** — `plane == 0 && motion_mode == LOCALWARP &&
///   LocalValid == 1` ⇒ the §7.11.3.6 `setup_shear` is re-validated
///   on `LocalWarpParams`; failure flips `local_valid` to false. The
///   driver performs this check internally on `plane == 0`.
/// * **Step 6** — `YMode ∈ {GLOBALMV, GLOBAL_GLOBALMV} && GmType[
///   refFrame] > TRANSLATION` ⇒ §7.11.3.6 `setup_shear` on
///   `gm_params[refFrame]` produces `globalValid`. The driver
///   performs this internally per-`refList`.
/// * **Step 7** — the `useWarp` decision tree (`w < 8 || h < 8` ⇒ 0;
///   `force_integer_mv` ⇒ 0; LOCALWARP + LocalValid ⇒ 1;
///   GLOBALMV-class + `GmType > TRANSLATION` + `!is_scaled` +
///   globalValid ⇒ 2; else 0).
///
/// Per-`refList` fields (`y_mode`, `gm_type`, `gm_params`,
/// `ref_is_scaled`) are indexed by `refList ∈ {0, 1}` matching the
/// `refs[refList]` array `predict_inter` consumes. On the single-ref
/// arm only `[0]` is consulted.
///
/// The §5.11.27 LOCALWARP arm is luma-only; for chroma planes
/// `predict_inter` re-uses the luma-derived `LocalValid` directly
/// (step 3's `plane == 0` gate means chroma never re-runs
/// `setup_shear`, but the same `LocalValid` bit propagates).
#[derive(Debug, Clone, Copy)]
pub struct WarpDriverParams {
    /// §5.11.x `YMode` per-refList — used for the step-7 `useWarp
    /// = 2` global-warp gate (`YMode ∈ {GLOBALMV,
    /// GLOBAL_GLOBALMV}`). Indexed by `refList`; only
    /// `[0]` is consulted on the single-ref path.
    pub y_mode: [u8; 2],
    /// §5.9.x `GmType[refFrame]` per-refList — the `IDENTITY` /
    /// `TRANSLATION` / `ROTZOOM` / `AFFINE` discriminant of the
    /// per-ref global-motion model. The step-7 `useWarp = 2` gate
    /// requires `gm_type > TRANSLATION`.
    pub gm_type: [u8; 2],
    /// §5.9.x `gm_params[refFrame][0..6]` per-refList — the affine
    /// matrix for the GLOBAL_GLOBALMV `useWarp == 2` arm; consumed by
    /// `block_warp` when the step-7 derivation lands on global warp.
    pub gm_params: [[i32; 6]; 2],
    /// §7.11.3.8 `LocalWarpParams[0..6]` — the per-block warp matrix
    /// produced by `warp_estimation`; consumed by `block_warp` when
    /// `useWarp == 1`. Only meaningful when `local_valid == true`.
    /// Shared across `refList` since LOCALWARP is single-reference
    /// only (`isCompound == 0` on the LOCALWARP cascade per §5.11.27).
    pub local_warp_params: [i32; 6],
    /// §7.11.3.8 `LocalValid` bit — `true` when `warp_estimation`'s
    /// least-squares fit produced a non-singular `A` matrix. False
    /// flips the step-7 LOCALWARP arm to `useWarp = 0` (translational
    /// fallback).
    pub local_valid: bool,
    /// §5.11.27 `is_scaled(refFrame)` per-refList — `true` when the
    /// ref frame's `(xScale, yScale) != (noScale, noScale)`. Step-7
    /// `useWarp = 2` requires `is_scaled == false` per av1-spec p.257
    /// line 14345.
    pub ref_is_scaled: [bool; 2],
    /// §5.9.x `force_integer_mv` frame flag — when `true`, step-7
    /// forces `useWarp = 0` regardless of motion mode. (`true` only
    /// on intra frames or when explicitly signalled per av1-spec
    /// §5.9.5.)
    pub force_integer_mv: bool,
}

/// §7.11.3.9 `predict_overlap` per-neighbour candidate (av1-spec p.275
/// lines 15301-15346 + p.276 lines 15349-15376) — one qualifying mi-grid
/// neighbour the OBMC post-step blends into the current block's
/// prediction. The caller pre-resolves the spec's `RefFrames[candRow]
/// [candCol][0] > INTRA_FRAME` gate, the `Mvs[candRow][candCol][0]`
/// motion vector, and the `ref_frame_idx[..]` → ref-frame buffer
/// indirection into a single self-contained bundle so the driver can
/// run §7.11.3.9 steps 1-8 without re-entering the §7 mi-grid state
/// (which is only partially modelled in `oxideav-av1`).
///
/// The driver still owns the §7.11.3.9 outer `(x4, y4, step4, nLimit)`
/// iteration — the caller supplies the *ordered* sequence of
/// qualifying neighbours along one axis (above-row or left-col) and
/// their `step4` advances. The driver consumes them in order, capped
/// at `nLimit = Min(4, Mi_{Width,Height}_Log2[MiSize])` per the spec.
///
/// `step4 = Clip3( 2, 16, Num_4x4_Blocks_{Wide,High}[ candSz ] )` per
/// av1-spec p.275 line 15313 / 15336. The caller is responsible for
/// the Clip3.
#[derive(Debug, Clone, Copy)]
pub struct ObmcNeighbour<'a> {
    /// §7.11.3.9 step 5 `refIdx` → spec `RefFrames[candRow][candCol]
    /// [0]` resolved into a ref-frame plane bundle. The bundle's
    /// `ref_plane` / `ref_stride` / `ref_upscaled_width` / `ref_width`
    /// / `ref_height` fields match the same `(plane, subsampling_*)`
    /// the §7.11.3.1 driver was invoked with (the caller does the
    /// per-plane resolution).
    ///
    /// The `mv` field carries `Mvs[candRow][candCol][0]` per av1-spec
    /// p.276 line 15359.
    pub bundle: PredictInterRef<'a>,
    /// `step4 = Clip3( 2, 16, Num_4x4_Blocks_{Wide,High}[ candSz ] )`
    /// per av1-spec p.275 lines 15313 / 15336 — how many 4×4 mi cells
    /// this neighbour spans along the walk axis. The driver advances
    /// `x4 += step4` (above-pass) or `y4 += step4` (left-pass) after
    /// consuming the neighbour.
    pub step4: u8,
    /// The CANDIDATE cell's horizontal interpolation filter —
    /// §7.11.3.9 step 6 invokes §7.11.3.4 with `candRow, candCol`, so
    /// the overlap prediction reads `InterpFilters[ candRow ][
    /// candCol ][ 1 ]` (the neighbour's own filter, not the OBMC
    /// block's). r394 dual-filter fix.
    pub interp_filter_x: u8,
    /// The candidate cell's vertical filter — `InterpFilters[ candRow
    /// ][ candCol ][ 0 ]` per §7.11.3.4.
    pub interp_filter_y: u8,
    /// The §7.11.3.9 axis position (`x4` on the above-pass, `y4` on
    /// the left-pass, in mi units) at which this candidate's
    /// `predict_overlap` fires — `predX = ( x4 * 4 ) >> subX` /
    /// `predY = ( y4 * 4 ) >> subY` read it. The walk position is NOT
    /// reconstructible from the qualifying list alone: a skipped
    /// candidate (`RefFrames[ cand ][ 0 ] <= INTRA_FRAME`) still
    /// advances `x4` / `y4` by ITS OWN `step4` without appearing here
    /// (r394 fix — the driver previously re-walked positions assuming
    /// every visited slot qualified, misplacing every overlap region
    /// after a skipped intra candidate).
    pub axis_pos4: u16,
}

/// §7.11.3.9 OBMC mi-grid context — caller-resolved neighbour lists
/// and the `(MiRow, MiCol, MiSize, AvailU, AvailL)` block context the
/// outer `(x4, y4)` walk needs.
///
/// The driver consumes this whenever `motion_mode == MOTION_MODE_OBMC`
/// (av1-spec p.258 line 14414). On `motion_mode != MOTION_MODE_OBMC`
/// the param is ignored (the caller may pass `None`). On
/// `motion_mode == MOTION_MODE_OBMC` the param **must** be `Some(_)`
/// (the driver returns `Error::PartitionWalkOutOfRange` otherwise —
/// caller bug).
///
/// ## Field semantics
///
/// * `mi_row` / `mi_col` / `mi_cols` / `mi_rows` — §5.9.5 mi-grid
///   coordinates of the current block + frame dimensions. Used for the
///   `x4 < Min(MiCols, MiCol + w4)` / `y4 < Min(MiRows, MiRow + h4)`
///   loop bound (av1-spec p.275 lines 15309 / 15332).
/// * `mi_width_log2` / `mi_height_log2` — `Mi_Width_Log2[ MiSize ]` /
///   `Mi_Height_Log2[ MiSize ]`. Used for `nLimit = Min(4, …)` per
///   av1-spec p.275 lines 15308 / 15331.
/// * `avail_u` / `avail_l` — §5.11.18 `AvailU` / `AvailL` for the
///   current block. The above-pass is gated by `avail_u`, the
///   left-pass by `avail_l` (av1-spec p.275 lines 15301 / 15325).
/// * `plane_residual_size_ge_block_8x8` — `get_plane_residual_size(
///   MiSize, plane ) >= BLOCK_8X8` (av1-spec p.275 line 15302). The
///   above-pass is additionally gated by this; the left-pass is
///   gated by the spec's "small block" carve-out (line 15283: "For
///   small blocks, only the left neighbor will be used"). The left
///   pass therefore runs whenever `avail_l == true` regardless.
/// * `above_neighbours` / `left_neighbours` — ordered slices of the
///   per-axis qualifying neighbour candidates (already-filtered for
///   the §7.11.3.9 `RefFrames[..][0] > INTRA_FRAME` gate). Empty
///   slice = no qualifying neighbour on that axis = no overlap blend
///   contribution.
#[derive(Debug, Clone, Copy)]
pub struct ObmcParams<'a, 'n> {
    /// §5.9.5 `MiRow` of the current block (luma mi-grid).
    pub mi_row: u32,
    /// §5.9.5 `MiCol` of the current block (luma mi-grid).
    pub mi_col: u32,
    /// §5.9.5 `MiCols` of the current frame.
    pub mi_cols: u32,
    /// §5.9.5 `MiRows` of the current frame.
    pub mi_rows: u32,
    /// §3 `Mi_Width_Log2[ MiSize ]` of the current block.
    pub mi_width_log2: u8,
    /// §3 `Mi_Height_Log2[ MiSize ]` of the current block.
    pub mi_height_log2: u8,
    /// §5.11.18 `AvailU` for the current block.
    pub avail_u: bool,
    /// §5.11.18 `AvailL` for the current block.
    pub avail_l: bool,
    /// §7.11.3.9 above-pass gate: `get_plane_residual_size( MiSize,
    /// plane ) >= BLOCK_8X8` (av1-spec p.275 line 15302). The
    /// left-pass is unconditional on this per the "small blocks → left
    /// neighbour only" carve-out (av1-spec p.275 line 15283).
    pub plane_residual_size_ge_block_8x8: bool,
    /// §7.11.3.9 above-pass qualifying neighbour list (ordered along
    /// `x4` ascending). Each entry's `step4` is the `Clip3(2, 16,
    /// Num_4x4_Blocks_Wide[ candSz ])` advance for the slot it
    /// occupies.
    pub above_neighbours: &'n [ObmcNeighbour<'a>],
    /// §7.11.3.9 left-pass qualifying neighbour list (ordered along
    /// `y4` ascending). Each entry's `step4` is the `Clip3(2, 16,
    /// Num_4x4_Blocks_High[ candSz ])` advance for the slot it
    /// occupies.
    pub left_neighbours: &'n [ObmcNeighbour<'a>],
}

/// §7.11.3.1 step-7 output: which `block_warp` matrix to apply for
/// one `refList`. `Translational` indicates `useWarp == 0` (fall
/// through to the existing §7.11.3.4 8-tap kernel).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum UseWarpDecision {
    /// `useWarp == 0` per av1-spec p.257 line 14332/14334/14349.
    Translational,
    /// `useWarp == 1` per av1-spec p.257 line 14336 — invoke
    /// `block_warp` with `LocalWarpParams`.
    Local,
    /// `useWarp == 2` per av1-spec p.257 line 14339 — invoke
    /// `block_warp` with `gm_params[refFrame]`.
    Global,
}

/// §7.11.3.1 step-7 derivation (av1-spec p.257 lines 14330-14349) —
/// pick `useWarp ∈ {0, 1, 2}` for one `refList`.
///
/// The bundle of step-7 conditions is exactly:
///
/// 1. `w < 8 || h < 8` → 0.
/// 2. `force_integer_mv == 1` → 0.
/// 3. `motion_mode == LOCALWARP && LocalValid == 1` → 1.
/// 4. `YMode ∈ {GLOBALMV, GLOBAL_GLOBALMV} && GmType[refFrame] >
///    TRANSLATION && !is_scaled(refFrame) && globalValid == 1` → 2.
/// 5. otherwise → 0.
///
/// `global_valid` is the §7.11.3.6 `warpValid` re-derived from
/// `gm_params[refFrame]` at the call site (per av1-spec p.257
/// step 6). When the gate (YMode + GmType) doesn't fire, the
/// caller does not need to run §7.11.3.6 and may pass `false`
/// — the gate short-circuits before consulting `global_valid`.
#[allow(clippy::too_many_arguments)]
fn derive_use_warp(
    w: usize,
    h: usize,
    motion_mode: u8,
    y_mode: u8,
    gm_type: u8,
    ref_is_scaled: bool,
    local_valid: bool,
    global_valid: bool,
    force_integer_mv: bool,
) -> UseWarpDecision {
    // Step-7 ◦ 1 — w/h < 8.
    if w < 8 || h < 8 {
        return UseWarpDecision::Translational;
    }
    // Step-7 ◦ 2 — force_integer_mv.
    if force_integer_mv {
        return UseWarpDecision::Translational;
    }
    // Step-7 ◦ 3 — LOCALWARP + LocalValid.
    if motion_mode == crate::cdf::MOTION_MODE_WARPED_CAUSAL && local_valid {
        return UseWarpDecision::Local;
    }
    // Step-7 ◦ 4 — global-warp gate (the four-AND of YMode in
    // {GLOBALMV, GLOBAL_GLOBALMV}, GmType > TRANSLATION,
    // !is_scaled, globalValid).
    let y_is_global = matches!(
        y_mode,
        crate::cdf::MODE_GLOBALMV | crate::cdf::MODE_GLOBAL_GLOBALMV
    );
    let gm_is_warp = (gm_type as i32) > crate::cdf::GM_TYPE_TRANSLATION;
    if y_is_global && gm_is_warp && !ref_is_scaled && global_valid {
        return UseWarpDecision::Global;
    }
    // Step-7 ◦ 5 — fall-through.
    UseWarpDecision::Translational
}

/// §7.11.3.1 step-12 per-`refList` warp body (av1-spec p.257 lines
/// 14368-14370) — drives `block_warp` once per 8×8 sub-block of the
/// `w × h` prediction region and returns the `w * h` `i32`
/// pre-`Clip1` prediction matching what `predict_inter_per_ref`
/// would have produced on the translational arm.
///
/// `warp_params` is `LocalWarpParams` (when `use_warp ==
/// USE_WARP_LOCAL`) or `gm_params[refFrame]` (when `use_warp ==
/// USE_WARP_GLOBAL`); the caller picks per the step-7 derivation.
#[allow(clippy::too_many_arguments)]
fn predict_inter_per_ref_warp(
    r: &PredictInterRef<'_>,
    use_warp: u8,
    plane: u8,
    x: i32,
    y: i32,
    w: usize,
    h: usize,
    subsampling_x: u8,
    subsampling_y: u8,
    warp_params: [i32; 6],
    inter_round0: u32,
    inter_round1: u32,
) -> Result<Vec<i32>, crate::Error> {
    let mut pred: Vec<i32> = Vec::new();
    if pred.try_reserve_exact(w * h).is_err() {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    pred.resize(w * h, 0);

    // av1-spec p.257 line 14369: "i8 = 0..((h-1) >> 3) and for j8 =
    // 0..((w-1) >> 3)". The inclusive upper bound expressed as
    // `(dim - 1) >> 3` matches `dim.div_ceil(8) - 1`; the §7.11.3.1
    // step-7 ◦ 1 gate guarantees `w >= 8 && h >= 8` here so both
    // loops run at least once.
    let i_blocks = h.div_ceil(8);
    let j_blocks = w.div_ceil(8);
    // [`PredictInterRef`] carries LUMA-unit reference dimensions
    // (r405 contract) — exactly what §7.11.3.5 / [`block_warp`] takes;
    // it re-derives the per-plane `lastX` / `lastY` internally. (The
    // r390 chroma-warp fix lifted the then-per-plane fields back to
    // luma here; the lift is gone now that the fields ARE luma.)
    for i8b in 0..i_blocks {
        for j8b in 0..j_blocks {
            block_warp(
                use_warp,
                plane,
                subsampling_x,
                subsampling_y,
                x,
                y,
                i8b as i32,
                j8b as i32,
                w,
                h,
                r.ref_plane,
                r.ref_stride,
                r.ref_upscaled_width,
                r.ref_height,
                warp_params,
                inter_round0,
                inter_round1,
                /* pred_stride */ w,
                &mut pred,
            )?;
        }
    }
    Ok(pred)
}

/// §7.11.3.1 step-5/8/9/10/12/13 per-`refList` dispatch — pick the
/// translational kernel ([`predict_inter_per_ref`]) or the warp kernel
/// ([`predict_inter_per_ref_warp`]) based on the step-7 `useWarp`
/// derivation and run it once for one reference.
///
/// `effective_local_valid` is the §7.11.3.1 step-3 output (the
/// caller-supplied `WarpDriverParams::local_valid` after the
/// `plane == 0` re-check against `setup_shear(LocalWarpParams)`).
#[allow(clippy::too_many_arguments)]
fn predict_inter_one_ref(
    r: &PredictInterRef<'_>,
    ref_list: usize,
    plane: u8,
    x: i32,
    y: i32,
    w: usize,
    h: usize,
    motion_mode: u8,
    subsampling_x: u8,
    subsampling_y: u8,
    frame_width: u32,
    frame_height: u32,
    interp_filter_x: u8,
    interp_filter_y: u8,
    inter_round0: u32,
    inter_round1: u32,
    warp: Option<&WarpDriverParams>,
    effective_local_valid: bool,
) -> Result<Vec<i32>, crate::Error> {
    // ---------- §7.11.3.1 step 6/7 — derive useWarp ----------
    //
    // Step 6 invokes §7.11.3.6 setup_shear on `gm_params[refFrame]`
    // and assigns warpValid → globalValid; we run it lazily (only
    // when YMode + GmType clear the rest of the step-7 gate, since
    // the call costs an inverse-divisor that's pointless otherwise).
    let decision = if let Some(wp) = warp {
        let y_mode = wp.y_mode[ref_list];
        let gm_type = wp.gm_type[ref_list];
        let ref_is_scaled = wp.ref_is_scaled[ref_list];
        let y_is_global = matches!(
            y_mode,
            crate::cdf::MODE_GLOBALMV | crate::cdf::MODE_GLOBAL_GLOBALMV
        );
        let gm_is_warp = (gm_type as i32) > crate::cdf::GM_TYPE_TRANSLATION;
        // Step 6 — only run setup_shear when the gate would consult
        // globalValid. The other arms of step-7 either short-circuit
        // before consulting it (`w/h < 8`, `force_integer_mv`,
        // LOCALWARP+LocalValid) or short-circuit before the AND chain
        // (`!(y_is_global && gm_is_warp)`).
        let global_valid = if y_is_global && gm_is_warp && !ref_is_scaled {
            matches!(setup_shear(wp.gm_params[ref_list]), Some(s) if s.warp_valid)
        } else {
            false
        };
        derive_use_warp(
            w,
            h,
            motion_mode,
            y_mode,
            gm_type,
            ref_is_scaled,
            effective_local_valid,
            global_valid,
            wp.force_integer_mv,
        )
    } else {
        UseWarpDecision::Translational
    };

    // ---------- §7.11.3.1 step 12 / 13 — dispatch ----------
    match decision {
        UseWarpDecision::Translational => predict_inter_per_ref(
            r,
            plane,
            x,
            y,
            w,
            h,
            subsampling_x,
            subsampling_y,
            frame_width,
            frame_height,
            interp_filter_x,
            interp_filter_y,
            inter_round0,
            inter_round1,
        ),
        UseWarpDecision::Local => {
            // av1-spec p.257 step-7 ◦ 3: LOCALWARP. `warp.is_some()`
            // is guaranteed by `derive_use_warp` returning `Local`
            // only when LocalValid && motion_mode == LOCALWARP, both
            // of which require a non-None `warp`.
            let wp = warp.expect("Local requires WarpDriverParams");
            predict_inter_per_ref_warp(
                r,
                USE_WARP_LOCAL,
                plane,
                x,
                y,
                w,
                h,
                subsampling_x,
                subsampling_y,
                wp.local_warp_params,
                inter_round0,
                inter_round1,
            )
        }
        UseWarpDecision::Global => {
            let wp = warp.expect("Global requires WarpDriverParams");
            predict_inter_per_ref_warp(
                r,
                USE_WARP_GLOBAL,
                plane,
                x,
                y,
                w,
                h,
                subsampling_x,
                subsampling_y,
                wp.gm_params[ref_list],
                inter_round0,
                inter_round1,
            )
        }
    }
}

/// §7.11.3.9 OBMC mi-grid neighbour walk + per-candidate
/// `predict_overlap` (av1-spec p.275-276) — single-axis driver shared
/// between the above-pass (`pass = OverlapPass::Above`) and the
/// left-pass (`pass = OverlapPass::Left`).
///
/// Iterates the caller-supplied ordered neighbour list, tracks the
/// `x4` (above) or `y4` (left) advance per spec line 15321 / 15344,
/// honours the `nCount < nLimit && x4 < Min(MiCols, MiCol + w4)`
/// (above) or `nCount < nLimit && y4 < Min(MiRows, MiRow + h4)`
/// (left) loop condition (av1-spec p.275 lines 15309 / 15332), and
/// runs §7.11.3.9 steps 1-8 for each qualifying neighbour:
///
/// * Steps 1, 2 — `mv` and `refIdx` are pre-resolved into the
///   neighbour's `PredictInterRef` bundle by the caller.
/// * Steps 3, 4 — `predX = (x4 * 4) >> subX`, `predY = (y4 * 4) >>
///   subY` (the §7.11.3.9 plane-relative coordinates).
/// * Steps 5, 6 — `motion_vector_scaling` + `block_inter_prediction`
///   are run via [`predict_inter_per_ref`] for the neighbour MV
///   against `predW × predH`.
/// * Step 7 — `clip1_single_ref` on the i32 prediction → u16 obmc_pred.
/// * Step 8 — `overlap_neighbour_predict_blend` against the in-place
///   `pred_out` buffer at the buffer-relative coordinates
///   `(predX - x_block_plane, predY - y_block_plane)`.
///
/// `pred_w_for_neighbour` / `pred_h_for_neighbour` encode the
/// pass-specific `predW` / `predH` derivation:
///
/// * Above-pass (av1-spec p.275 lines 15316-15317):
///   * `predW = Min(w, (step4 * MI_SIZE) >> subX)`.
///   * `predH = Min(h >> 1, 32 >> subY)`.
///   * `mask_length = predH`.
/// * Left-pass (av1-spec p.275 lines 15339-15340):
///   * `predW = Min(w >> 1, 32 >> subX)`.
///   * `predH = Min(h, (step4 * MI_SIZE) >> subY)`.
///   * `mask_length = predW`.
///
/// The walker passes `pred_out` as a `(h, w)` buffer with stride `w`
/// — i.e. exactly the per-block buffer `predict_inter` was given.
/// Pred-region coordinates are translated from plane-absolute
/// (`x_block_plane = (MiCol * MI_SIZE) >> subX`, similarly for y) to
/// buffer-relative before the §7.11.3.10 blend.
#[allow(clippy::too_many_arguments)]
fn obmc_walk_axis(
    pass: OverlapPass,
    plane: u8,
    block_x_plane: i32,
    block_y_plane: i32,
    block_w: usize,
    block_h: usize,
    mi_row: u32,
    mi_col: u32,
    mi_cols: u32,
    mi_rows: u32,
    mi_width_log2: u8,
    mi_height_log2: u8,
    subsampling_x: u8,
    subsampling_y: u8,
    frame_width: u32,
    frame_height: u32,
    inter_round0: u32,
    inter_round1: u32,
    bit_depth: u8,
    neighbours: &[ObmcNeighbour<'_>],
    pred_out: &mut [u16],
) -> Result<(), crate::Error> {
    let mi_size: u32 = crate::cdf::MI_SIZE as u32;
    let sub_x = subsampling_x as u32;
    let sub_y = subsampling_y as u32;

    // §7.11.3.9 outer-loop bounds:
    //
    //   Above-pass:  w4 = Num_4x4_Blocks_Wide[ MiSize ];
    //                nLimit = Min(4, Mi_Width_Log2[ MiSize ]);
    //                x4 walks MiCol → Min(MiCols, MiCol + w4).
    //   Left-pass:   h4 = Num_4x4_Blocks_High[ MiSize ];
    //                nLimit = Min(4, Mi_Height_Log2[ MiSize ]);
    //                y4 walks MiRow → Min(MiRows, MiRow + h4).
    //
    // `Num_4x4_Blocks_{Wide,High}[ MiSize ]` = `1 << Mi_{Width,
    // Height}_Log2[ MiSize ]` per §3 (av1-spec p.20).
    let (axis_limit_log2, frame_limit, axis_start, axis_block_extent) = match pass {
        OverlapPass::Above => {
            let w4 = 1u32 << (mi_width_log2 as u32);
            (
                mi_width_log2,
                mi_cols.min(mi_col.saturating_add(w4)),
                mi_col,
                w4,
            )
        }
        OverlapPass::Left => {
            let h4 = 1u32 << (mi_height_log2 as u32);
            (
                mi_height_log2,
                mi_rows.min(mi_row.saturating_add(h4)),
                mi_row,
                h4,
            )
        }
    };
    let _ = axis_block_extent;
    let n_limit: u32 = 4.min(axis_limit_log2 as u32);

    let mut n_count: u32 = 0;

    for cand in neighbours {
        // The caller resolved the §7.11.3.9 walk (including skipped
        // non-qualifying candidates, which advance the axis position
        // without appearing in the list); each surfaced neighbour
        // carries the `x4` / `y4` it fires at. The `nLimit` and
        // frame-edge guards still bound a caller-bug oversupply.
        if n_count >= n_limit {
            break;
        }
        let axis_pos: u32 = cand.axis_pos4 as u32;
        if axis_pos < axis_start || axis_pos >= frame_limit {
            return Err(crate::Error::PartitionWalkOutOfRange);
        }
        // §7.11.3.9 step4 = Clip3(2, 16, Num_4x4_Blocks_{Wide,High}[
        // candSz]). The caller already applied the Clip3.
        let step4: u32 = cand.step4 as u32;
        if !(2..=16).contains(&step4) {
            return Err(crate::Error::PartitionWalkOutOfRange);
        }
        // The spec increments `nCount` only for the qualifying
        // branch (`RefFrames[..][0] > INTRA_FRAME`); we honour that
        // by counting only neighbours the caller surfaces (they
        // pre-filter the gate).
        n_count = n_count.saturating_add(1);

        // §7.11.3.9 step 3 / 4 — predX, predY in plane coordinates.
        let (pred_x_plane, pred_y_plane): (u32, u32) = match pass {
            OverlapPass::Above => {
                let px = (axis_pos.saturating_mul(4)) >> sub_x;
                let py = (mi_row.saturating_mul(4)) >> sub_y;
                (px, py)
            }
            OverlapPass::Left => {
                let px = (mi_col.saturating_mul(4)) >> sub_x;
                let py = (axis_pos.saturating_mul(4)) >> sub_y;
                (px, py)
            }
        };

        // av1-spec p.275 lines 15316-15317 (Above) / 15339-15340 (Left).
        let (pred_w, pred_h, mask_length) = match pass {
            OverlapPass::Above => {
                let pw = block_w.min(((step4 * mi_size) >> sub_x) as usize);
                let ph = (block_h >> 1).min((32u32 >> sub_y) as usize);
                (pw, ph, ph)
            }
            OverlapPass::Left => {
                let pw = (block_w >> 1).min((32u32 >> sub_x) as usize);
                let ph = block_h.min(((step4 * mi_size) >> sub_y) as usize);
                (pw, ph, pw)
            }
        };

        // Buffer-relative offsets. `block_x_plane` / `block_y_plane`
        // are the prediction region top-left in plane coords (= `(x,
        // y)` the §7.11.3.1 driver was invoked with). The neighbour's
        // overlap region must land entirely inside the (block_w,
        // block_h) buffer — if it doesn't (caller-bug: wrong MiRow /
        // MiCol vs. (x, y), or a step4 that pushes past the block
        // edge), clamp pred_w/pred_h to what fits and skip if there's
        // no overlap left.
        if pred_w == 0 || pred_h == 0 {
            continue;
        }
        let off_x = (pred_x_plane as i64) - (block_x_plane as i64);
        let off_y = (pred_y_plane as i64) - (block_y_plane as i64);
        if off_x < 0 || off_y < 0 {
            return Err(crate::Error::PartitionWalkOutOfRange);
        }
        let off_x = off_x as usize;
        let off_y = off_y as usize;
        if off_x >= block_w || off_y >= block_h {
            return Err(crate::Error::PartitionWalkOutOfRange);
        }
        let fit_w = pred_w.min(block_w - off_x);
        let fit_h = pred_h.min(block_h - off_y);
        if fit_w == 0 || fit_h == 0 {
            continue;
        }

        // §7.11.3.9 steps 5/6 — run the translational MC kernel for
        // the neighbour MV / refIdx at this `(predX, predY)` against
        // a `pred_w × pred_h` (fitted) region.
        // §7.11.3.9 step 6 → §7.11.3.4 with (candRow, candCol): the
        // overlap MC uses the NEIGHBOUR's `InterpFilters[ cand ][ dir ]`
        // pair, not the OBMC block's own (r394 dual-filter fix).
        let obmc_pred_i32 = predict_inter_per_ref(
            &cand.bundle,
            plane,
            pred_x_plane as i32,
            pred_y_plane as i32,
            fit_w,
            fit_h,
            subsampling_x,
            subsampling_y,
            frame_width,
            frame_height,
            cand.interp_filter_x,
            cand.interp_filter_y,
            inter_round0,
            inter_round1,
        )?;

        // §7.11.3.9 step 7 — Clip1 on the i32 prediction.
        let mut obmc_pred_u16 = vec![0u16; fit_w * fit_h];
        clip1_single_ref(bit_depth, &obmc_pred_i32, &mut obmc_pred_u16)?;

        // §7.11.3.9 step 8 — overlap blend against the per-block
        // buffer treated as a `(block_h, block_w)` plane window.
        overlap_neighbour_predict_blend(
            pred_out,
            /* curr_stride */ block_w,
            /* pred_x */ off_x,
            /* pred_y */ off_y,
            fit_w,
            fit_h,
            pass,
            &obmc_pred_u16,
            /* obmc_stride */ fit_w,
            mask_length,
        )?;
    }
    Ok(())
}

#[allow(clippy::too_many_arguments)]
pub fn predict_inter(
    plane: u8,
    x: i32,
    y: i32,
    w: usize,
    h: usize,
    motion_mode: u8,
    is_compound: bool,
    is_inter_intra: bool,
    bit_depth: u8,
    subsampling_x: u8,
    subsampling_y: u8,
    frame_width: u32,
    frame_height: u32,
    interp_filter_x: u8,
    interp_filter_y: u8,
    refs: &[PredictInterRef<'_>],
    compound: Option<CompoundParams<'_>>,
    inter_intra: Option<InterIntraParams<'_>>,
    warp: Option<&WarpDriverParams>,
    obmc: Option<&ObmcParams<'_, '_>>,
    pred_out: &mut [u16],
) -> Result<(), crate::Error> {
    // ---------- caller-bug guards ----------
    if plane > 2 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if subsampling_x > 1 || subsampling_y > 1 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if !matches!(bit_depth, 8 | 10 | 12) {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if frame_width == 0 || frame_height == 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if w == 0 || h == 0 || w > 256 || h > 256 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if pred_out.len() < w * h {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if refs.is_empty() {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    // The compound arm reads `refs[1]`; the single-ref arm rejects a
    // spurious `compound = Some(_)` to keep the contract bidirectional.
    if is_compound {
        if refs.len() < 2 {
            return Err(crate::Error::PartitionWalkOutOfRange);
        }
        if compound.is_none() {
            return Err(crate::Error::PartitionWalkOutOfRange);
        }
    } else if compound.is_some() {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    // ---------- §7.11.3.1 IsInterIntra contract ----------
    //
    // av1-spec p.258 line 14301: `isCompound = RefFrames[..][1] >
    // INTRA_FRAME`. An inter-intra block has `RefFrame[1] ==
    // INTRA_FRAME`, so `isCompound == 0` — the two arms are mutually
    // exclusive. The inter-intra arm forms a single inter prediction
    // (`refs[0]`) and blends it with the in-place intra prediction, so
    // it requires `is_compound == false` and the [`InterIntraParams`]
    // side data; a caller that signals one without the other is a bug.
    //
    // Both interintra sub-arms are wired. `InterIntraParams.wedge`
    // selects: `None` ⇒ the non-wedge `COMPOUND_INTRA` path (§7.11.3.13
    // intra-variant mask, read directly at `Mask[y][x]`); `Some(_)` ⇒
    // the `wedge_interintra == 1` path (§7.11.3.11 luma-grid wedge mask,
    // read with `(subX, subY)` averaging for the chroma planes).
    if is_inter_intra {
        if is_compound {
            return Err(crate::Error::PartitionWalkOutOfRange);
        }
        if inter_intra.is_none() {
            return Err(crate::Error::PartitionWalkOutOfRange);
        }
        if inter_intra
            .map(|ii| ii.interintra_mode > II_SMOOTH_PRED)
            .unwrap_or(false)
        {
            return Err(crate::Error::PartitionWalkOutOfRange);
        }
    } else if inter_intra.is_some() {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    // ---------- §7.11.3.1 step 2/3/6/7 — WARP context plumbing ----
    //
    // The WARP arm (av1-spec p.257 lines 14308-14349, p.258 line
    // 14368) requires the caller to supply step-2/3/6/7 useWarp
    // derivation inputs through [`WarpDriverParams`]. A caller that
    // passes `warp = None` runs the translational-only path
    // unchanged — equivalent to the r194/r201 behaviour for
    // `motion_mode == MOTION_MODE_SIMPLE` blocks. A caller that
    // sets `motion_mode == MOTION_MODE_WARPED_CAUSAL` (= spec
    // LOCALWARP) but supplies `warp = None` is a caller bug.
    if motion_mode == crate::cdf::MOTION_MODE_WARPED_CAUSAL && warp.is_none() {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    // ---------- §7.11.3.1 post-step — OBMC caller-bug guard ------
    //
    // av1-spec p.258 line 14414 invokes §7.11.3.9 (overlapped motion
    // compensation) only on `motion_mode == OBMC`. The neighbour
    // mi-grid walk needs `ObmcParams` (above/left neighbour lists +
    // MiRow/MiCol context); a caller that signals OBMC without
    // supplying the bundle is a caller bug.
    if motion_mode == crate::cdf::MOTION_MODE_OBMC && obmc.is_none() {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    // ---------- §7.11.3.1 step 1 — rounding variables -----------
    let rv = rounding_variables(bit_depth, is_compound)?;

    // ---------- §7.11.3.1 step 3 (luma) — LocalValid re-derivation -
    //
    // av1-spec p.257 line 14311: "If plane is equal to 0 and
    // motion_mode is equal to LOCALWARP and LocalValid is equal to
    // 1, the setup shear process specified in section 7.11.3.6 is
    // invoked with LocalWarpParams as input, and the output
    // warpValid is assigned to LocalValid (the other outputs are
    // discarded)."
    //
    // We perform this gate per-frame at the caller surface (the
    // shear validity is purely a function of `LocalWarpParams`, so
    // running it once at `plane == 0` is bit-equivalent to running
    // it for every plane). Re-check here so a caller that derives
    // `local_valid` from the §7.11.3.8 fit without re-checking
    // §7.11.3.6 doesn't sneak past the spec's two-step validity.
    let mut effective_local_valid: bool = warp.is_some_and(|w| w.local_valid);
    if let Some(wp) = warp {
        if motion_mode == crate::cdf::MOTION_MODE_WARPED_CAUSAL && wp.local_valid {
            match setup_shear(wp.local_warp_params) {
                Some(s) if s.warp_valid => {}
                _ => effective_local_valid = false,
            }
        }
    }

    // ---------- §7.11.3.1 step 4-13 — refList = 0 ----------
    //
    // Steps 5,8,9 are subsumed into the caller-supplied `refs[refList]`
    // bundle. Step 10 = `motion_vector_scaling`. Step 13 =
    // `block_inter_prediction` against the
    // `(startX, startY, stepX, stepY)` quadruple — or, on the WARP
    // arm, step 12 = `block_warp` per 8×8 sub-section. The compound
    // arm (step 14) repeats the same body for `refList = 1`.
    let pred0 = predict_inter_one_ref(
        &refs[0],
        /* ref_list */ 0,
        plane,
        x,
        y,
        w,
        h,
        motion_mode,
        subsampling_x,
        subsampling_y,
        frame_width,
        frame_height,
        interp_filter_x,
        interp_filter_y,
        rv.inter_round0,
        rv.inter_round1,
        warp,
        effective_local_valid,
    )?;

    // ---------- §7.11.3.1 step 14 + final blend ----------
    //
    // av1-spec p.258 lines 14400-14412:
    //   * `isCompound == 0 && IsInterIntra == 0` ⇒ `CurrFrame =
    //     Clip1(preds[0])` (single-ref final-clip).
    //   * `COMPOUND_AVERAGE` ⇒ `Clip1(Round2(preds[0] + preds[1],
    //     1 + InterPostRound))`.
    //   * `COMPOUND_DISTANCE` ⇒ `Clip1(Round2(FwdWeight * preds[0] +
    //     BckWeight * preds[1], 4 + InterPostRound))`.
    //   * `COMPOUND_WEDGE` / `COMPOUND_DIFFWTD` / `COMPOUND_INTRA` ⇒
    //     `mask_blend(preds, plane, x, y, w, h)`.
    //
    // The inter-intra branch (`IsInterIntra == 1`, `isCompound == 0`)
    // takes the §7.11.3.14 inter-intra body instead: `preds[0]` is the
    // single inter prediction (pre-clip), `pred1` is the in-place intra
    // prediction already in `pred_out`. The mask is the §7.11.3.13
    // intra-variant mask on the non-wedge arm, or the §7.11.3.11
    // luma-grid wedge mask on the `wedge_interintra == 1` arm. It is
    // handled below the compound/single-ref split because it consumes
    // `pred_out` on entry.
    //
    // SAFETY: the `is_inter_intra` guards above returned
    // `PartitionWalkOutOfRange` unless `inter_intra.is_some()`.
    if is_inter_intra {
        let ii = inter_intra.expect("inter_intra checked above");
        // `pred_out` holds the §7.11.2 intra prediction on entry
        // (`pred1 = CurrFrame[plane][y+dstY][x+dstX]`); the blend reads
        // it as `pred1` and overwrites it with the blended sample.
        match ii.wedge {
            None => {
                // av1-spec p.258 line 14389-14390 + p.284 lines
                // 15772-15787: the non-wedge interintra mask is the
                // §7.11.3.13 per-plane `w × h` intra-variant mask; the
                // §7.11.3.14 body reads it at `Mask[y][x]` directly via
                // the `(interintra && !wedge_interintra)` predicate, so
                // no chroma downsampling is applied (`sub_x = sub_y = 0`).
                let mut mask = vec![0u8; w * h];
                intra_mode_variant_mask(ii.interintra_mode, w, h, &mut mask)?;
                mask_blend_interintra(
                    bit_depth,
                    rv.inter_post_round,
                    /* sub_x */ 0,
                    /* sub_y */ 0,
                    &pred0,
                    w,
                    h,
                    &mask,
                    /* mask_stride */ 0,
                    pred_out,
                )?;
            }
            Some(wi) => {
                // av1-spec p.258 line 14386 + p.80 line 5017: the
                // wedge interintra arm sets `compound_type ==
                // COMPOUND_WEDGE`, so the mask is the §7.11.3.11
                // luma-grid wedge mask the caller built once at
                // `plane == 0`. The §7.11.3.14 body reads it with the
                // current plane's `(subX, subY)` averaging (av1-spec
                // p.284 line 15772-15781) — the
                // `(interintra && !wedge_interintra)` short-circuit does
                // not fire here.
                mask_blend_interintra(
                    bit_depth,
                    rv.inter_post_round,
                    subsampling_x,
                    subsampling_y,
                    &pred0,
                    w,
                    h,
                    wi.mask,
                    wi.mask_stride,
                    pred_out,
                )?;
            }
        }
    } else if is_compound {
        // step 14: build preds[1] from refs[1] with the same pipeline.
        let pred1 = predict_inter_one_ref(
            &refs[1],
            /* ref_list */ 1,
            plane,
            x,
            y,
            w,
            h,
            motion_mode,
            subsampling_x,
            subsampling_y,
            frame_width,
            frame_height,
            interp_filter_x,
            interp_filter_y,
            rv.inter_round0,
            rv.inter_round1,
            warp,
            effective_local_valid,
        )?;
        // SAFETY: the `is_compound` arm guarded `compound.is_some()`
        // above, so `unwrap` cannot panic.
        let cp = compound.expect("compound checked above");
        predict_inter_compound_blend(
            plane,
            bit_depth,
            rv.inter_post_round,
            subsampling_x,
            subsampling_y,
            w,
            h,
            &pred0,
            &pred1,
            cp,
            pred_out,
        )?;
    } else {
        // av1-spec p.258 line 14402: `CurrFrame[plane][y + i][x + j] =
        // Clip1( preds[0][i][j] )` for `(i, j) ∈ [0, h) × [0, w)`.
        // We write into the caller-supplied per-block buffer; the merge
        // into [`crate::PartitionWalker::curr_frame`] is the walker's
        // responsibility (it owns the per-plane buffer and the (x, y)
        // offsetting).
        clip1_single_ref(bit_depth, &pred0, pred_out)?;
    }

    // ---------- §7.11.3.1 post-step — OBMC overlap blend ---------
    //
    // av1-spec p.258 line 14414: "If motion_mode is equal to OBMC,
    // the overlapped motion compensation in section 7.11.3.9 is
    // invoked with plane, w, h as inputs."
    //
    // The blend runs *after* the translational MC has already been
    // written into `pred_out` — the §7.11.3.10 kernel modifies
    // `CurrFrame[plane][predY + i][predX + j]` in place. We treat
    // the per-block `pred_out` buffer as a `(h, w)` window of
    // `CurrFrame[plane]` with origin at plane coords `(x, y)`; the
    // §7.11.3.9 outer walk produces plane-absolute `(predX, predY)`
    // coordinates we translate to buffer-relative inside
    // [`obmc_walk_axis`].
    //
    // Above-pass first (gated by `AvailU &&
    // get_plane_residual_size(MiSize, plane) >= BLOCK_8X8`), then
    // left-pass (gated by `AvailL` only — the spec carves out small
    // blocks so that only the left neighbour is used per av1-spec
    // p.275 line 15283).
    if motion_mode == crate::cdf::MOTION_MODE_OBMC {
        // SAFETY: the OBMC caller-bug guard above returned
        // `PartitionWalkOutOfRange` if `obmc.is_none()`, so this
        // unwrap cannot panic.
        let op = obmc.expect("OBMC requires ObmcParams (guarded above)");

        // av1-spec p.275 line 15301: `if (AvailU)` outer gate +
        // line 15302: `if (get_plane_residual_size(MiSize, plane) >=
        // BLOCK_8X8)` inner gate for the above-pass.
        if op.avail_u && op.plane_residual_size_ge_block_8x8 {
            obmc_walk_axis(
                OverlapPass::Above,
                plane,
                x,
                y,
                w,
                h,
                op.mi_row,
                op.mi_col,
                op.mi_cols,
                op.mi_rows,
                op.mi_width_log2,
                op.mi_height_log2,
                subsampling_x,
                subsampling_y,
                frame_width,
                frame_height,
                rv.inter_round0,
                rv.inter_round1,
                bit_depth,
                op.above_neighbours,
                pred_out,
            )?;
        }
        // av1-spec p.275 line 15325: `if (AvailL)` outer gate for the
        // left-pass. Unlike the above-pass there is no
        // `get_plane_residual_size >= BLOCK_8X8` gate — the spec's
        // line 15283 carve-out ("For small blocks, only the left
        // neighbor will be used") is precisely the asymmetry.
        if op.avail_l {
            obmc_walk_axis(
                OverlapPass::Left,
                plane,
                x,
                y,
                w,
                h,
                op.mi_row,
                op.mi_col,
                op.mi_cols,
                op.mi_rows,
                op.mi_width_log2,
                op.mi_height_log2,
                subsampling_x,
                subsampling_y,
                frame_width,
                frame_height,
                rv.inter_round0,
                rv.inter_round1,
                bit_depth,
                op.left_neighbours,
                pred_out,
            )?;
        }
    }

    Ok(())
}

// =====================================================================
// §7.11.3.11-15 — Compound mask / blend bodies (av1-spec p.278-285).
// =====================================================================
//
// The §7.11.3.1 driver (av1-spec p.257-258) consumes one of five
// compound mechanisms (`COMPOUND_AVERAGE` / `COMPOUND_WEDGE` /
// `COMPOUND_DIFFWTD` / `COMPOUND_INTRA` / `COMPOUND_DISTANCE`) to
// combine two inter predictions, plus the interintra blend for
// `IsInterIntra == 1` blocks.
//
// `COMPOUND_AVERAGE` and the `is_compound == 0 && IsInterIntra == 0`
// single-ref path fold into the inline final-clip step of §7.11.3.1
// itself (av1-spec p.258 lines 14402-14410) and don't need a mask
// array. The remaining four mechanisms produce a per-pixel mask via
// §7.11.3.11 (wedge_mask) / §7.11.3.12 (difference_weight_mask) /
// §7.11.3.13 (intra_mode_variant_mask), and the §7.11.3.14
// (mask_blend) and §7.11.3.15 (distance_weights) helpers below apply
// that mask to the two preds.

// ---------------------------------------------------------------------
// §3 constants used by §7.11.3.11-15 (av1-spec p.7-18).
// ---------------------------------------------------------------------

/// `MASK_MASTER_SIZE = 64` (av1-spec p.18 line 1234) — side length of
/// the §7.11.3.11 `MasterMask` square. The 16 wedge variants per
/// block-shape are read out of one of three master masks (oblique 63°,
/// oblique 27°, and vertical/horizontal pairs derived from them) at
/// `(yoff, xoff)` offsets the §7.11.3.11 `get_wedge_xoff` /
/// `get_wedge_yoff` helpers compute from `(bsize, wedge)`.
pub const MASK_MASTER_SIZE: usize = 64;

/// `MAX_SB_SIZE = 128` (av1-spec p.11 line 915) — maximum superblock
/// side length in luma samples. §7.11.3.13 uses it as the `sizeScale =
/// MAX_SB_SIZE / Max(h, w)` divisor + the `Ii_Weights_1d` table length.
pub const MAX_SB_SIZE: usize = 128;

/// `MAX_FRAME_DISTANCE = 31` (av1-spec p.16 line 1348) — saturation
/// value for the §7.11.3.15 `dist[0]` / `dist[1]` per-list distances,
/// also the second column of the `Quant_Dist_Weight[3]` row that
/// pegs the "out of range" branch of the per-`i` comparison.
pub const MAX_FRAME_DISTANCE: i32 = 31;

// ---------------------------------------------------------------------
// §3 (av1-spec p.10 lines 887-893) compound-type constants — reproduced
// locally for the §7.11.3.11-14 dispatchers. Identical to the
// `compound_type` ordinals tabled at av1-spec p.185.
// ---------------------------------------------------------------------

/// `COMPOUND_WEDGE = 0` (av1-spec p.185 table) — the
/// wedge-blended compound mode driven by §7.11.3.11.
pub const COMPOUND_WEDGE: u8 = 0;
/// `COMPOUND_DIFFWTD = 1` (av1-spec p.185 table) — the
/// difference-weighted compound mode driven by §7.11.3.12.
pub const COMPOUND_DIFFWTD: u8 = 1;
/// `COMPOUND_AVERAGE = 2` (av1-spec p.185 table) — the plain mean
/// compound mode (no mask; folded into §7.11.3.1).
pub const COMPOUND_AVERAGE: u8 = 2;
/// `COMPOUND_INTRA = 3` (av1-spec p.185 table) — the inter-intra
/// blended compound mode driven by §7.11.3.13.
pub const COMPOUND_INTRA: u8 = 3;
/// `COMPOUND_DISTANCE = 4` (av1-spec p.185 table) — the
/// distance-weighted compound mode driven by §7.11.3.15.
pub const COMPOUND_DISTANCE: u8 = 4;

// ---------------------------------------------------------------------
// §3 (av1-spec p.185 table) inter-intra mode constants used by
// §7.11.3.13.
// ---------------------------------------------------------------------

/// `II_DC_PRED = 0` (av1-spec p.185) — interintra DC variant; the
/// §7.11.3.13 body emits a uniform `Mask[i][j] = 32` (50/50 blend).
pub const II_DC_PRED: u8 = 0;
/// `II_V_PRED = 1` (av1-spec p.185) — interintra V variant; the
/// §7.11.3.13 body picks the row-driven `Ii_Weights_1d[ i * sizeScale ]`.
pub const II_V_PRED: u8 = 1;
/// `II_H_PRED = 2` (av1-spec p.185) — interintra H variant; the
/// §7.11.3.13 body picks the column-driven `Ii_Weights_1d[ j *
/// sizeScale ]`.
pub const II_H_PRED: u8 = 2;
/// `II_SMOOTH_PRED = 3` (av1-spec p.185) — interintra SMOOTH variant;
/// the §7.11.3.13 body picks the diagonal-driven
/// `Ii_Weights_1d[ Min(i, j) * sizeScale ]`.
pub const II_SMOOTH_PRED: u8 = 3;

// =====================================================================
// §7.11.3.11 — Wedge mask process (av1-spec p.278-282).
// =====================================================================

/// `WEDGE_HORIZONTAL = 0` (av1-spec p.282 table) — `MasterMask`
/// direction ordinal for the horizontal split.
pub const WEDGE_HORIZONTAL: u8 = 0;
/// `WEDGE_VERTICAL = 1` (av1-spec p.282 table) — `MasterMask` direction
/// ordinal for the vertical split.
pub const WEDGE_VERTICAL: u8 = 1;
/// `WEDGE_OBLIQUE27 = 2` (av1-spec p.282 table) — `MasterMask`
/// direction ordinal for the shallow 27° split.
pub const WEDGE_OBLIQUE27: u8 = 2;
/// `WEDGE_OBLIQUE63 = 3` (av1-spec p.282 table) — `MasterMask`
/// direction ordinal for the steep 63° split.
pub const WEDGE_OBLIQUE63: u8 = 3;
/// `WEDGE_OBLIQUE117 = 4` (av1-spec p.282 table) — `MasterMask`
/// direction ordinal for the 117° split (mirror of 63°).
pub const WEDGE_OBLIQUE117: u8 = 4;
/// `WEDGE_OBLIQUE153 = 5` (av1-spec p.282 table) — `MasterMask`
/// direction ordinal for the 153° split (mirror of 27°).
pub const WEDGE_OBLIQUE153: u8 = 5;

/// `WEDGE_DIRECTIONS = 6` — the six wedge directions enumerated above.
pub const WEDGE_DIRECTIONS: usize = 6;

/// `Wedge_Master_Oblique_Odd[ MASK_MASTER_SIZE ]` (av1-spec p.280
/// lines 15550-15555). The 1d driver for odd rows of the
/// `WEDGE_OBLIQUE63` master mask.
#[rustfmt::skip]
pub const WEDGE_MASTER_OBLIQUE_ODD: [u8; MASK_MASTER_SIZE] = [
     0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,
     0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  1,  2,  6, 18,
    37, 53, 60, 63, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64,
    64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64,
];

/// `Wedge_Master_Oblique_Even[ MASK_MASTER_SIZE ]` (av1-spec p.280
/// lines 15557-15562). The 1d driver for even rows of the
/// `WEDGE_OBLIQUE63` master mask.
#[rustfmt::skip]
pub const WEDGE_MASTER_OBLIQUE_EVEN: [u8; MASK_MASTER_SIZE] = [
     0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,
     0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  1,  4, 11, 27,
    46, 58, 62, 63, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64,
    64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64,
];

/// `Wedge_Master_Vertical[ MASK_MASTER_SIZE ]` (av1-spec p.280 lines
/// 15564-15569). The 1d driver shared by both rows of the
/// `WEDGE_VERTICAL` master mask.
#[rustfmt::skip]
pub const WEDGE_MASTER_VERTICAL: [u8; MASK_MASTER_SIZE] = [
     0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,
     0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  2,  7, 21,
    43, 57, 62, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64,
    64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64, 64,
];

/// `Wedge_Codebook[ 3 ][ 16 ][ 3 ]` (av1-spec p.281-282 lines
/// 15605-15645). Indexed by `[block_shape][wedge_index]` to yield the
/// `(direction, xoff_eighths, yoff_eighths)` triple, where the
/// `xoff`/`yoff` are in units of eighths-of-a-block (so the
/// §7.11.3.11 wrapper computes the per-pixel offset as
/// `MASK_MASTER_SIZE / 2 - ((codebook_off * block_dim) >> 3)`).
///
/// Block-shape ordinals (from `block_shape(bsize)` per av1-spec p.281
/// lines 15582-15591):
///
/// * `0` — `h4 > w4` (tall block — e.g. `BLOCK_8X16`, `BLOCK_16X32`).
/// * `1` — `h4 < w4` (wide block — e.g. `BLOCK_16X8`).
/// * `2` — `h4 == w4` (square block — e.g. `BLOCK_8X8`).
#[rustfmt::skip]
pub const WEDGE_CODEBOOK: [[[u8; 3]; 16]; 3] = [
    // [0] block_shape == 0 (tall: h4 > w4).
    [
        [WEDGE_OBLIQUE27,  4, 4], [WEDGE_OBLIQUE63,  4, 4],
        [WEDGE_OBLIQUE117, 4, 4], [WEDGE_OBLIQUE153, 4, 4],
        [WEDGE_HORIZONTAL, 4, 2], [WEDGE_HORIZONTAL, 4, 4],
        [WEDGE_HORIZONTAL, 4, 6], [WEDGE_VERTICAL,   4, 4],
        [WEDGE_OBLIQUE27,  4, 2], [WEDGE_OBLIQUE27,  4, 6],
        [WEDGE_OBLIQUE153, 4, 2], [WEDGE_OBLIQUE153, 4, 6],
        [WEDGE_OBLIQUE63,  2, 4], [WEDGE_OBLIQUE63,  6, 4],
        [WEDGE_OBLIQUE117, 2, 4], [WEDGE_OBLIQUE117, 6, 4],
    ],
    // [1] block_shape == 1 (wide: h4 < w4).
    [
        [WEDGE_OBLIQUE27,  4, 4], [WEDGE_OBLIQUE63,  4, 4],
        [WEDGE_OBLIQUE117, 4, 4], [WEDGE_OBLIQUE153, 4, 4],
        [WEDGE_VERTICAL,   2, 4], [WEDGE_VERTICAL,   4, 4],
        [WEDGE_VERTICAL,   6, 4], [WEDGE_HORIZONTAL, 4, 4],
        [WEDGE_OBLIQUE27,  4, 2], [WEDGE_OBLIQUE27,  4, 6],
        [WEDGE_OBLIQUE153, 4, 2], [WEDGE_OBLIQUE153, 4, 6],
        [WEDGE_OBLIQUE63,  2, 4], [WEDGE_OBLIQUE63,  6, 4],
        [WEDGE_OBLIQUE117, 2, 4], [WEDGE_OBLIQUE117, 6, 4],
    ],
    // [2] block_shape == 2 (square: h4 == w4).
    [
        [WEDGE_OBLIQUE27,  4, 4], [WEDGE_OBLIQUE63,  4, 4],
        [WEDGE_OBLIQUE117, 4, 4], [WEDGE_OBLIQUE153, 4, 4],
        [WEDGE_HORIZONTAL, 4, 2], [WEDGE_HORIZONTAL, 4, 6],
        [WEDGE_VERTICAL,   2, 4], [WEDGE_VERTICAL,   6, 4],
        [WEDGE_OBLIQUE27,  4, 2], [WEDGE_OBLIQUE27,  4, 6],
        [WEDGE_OBLIQUE153, 4, 2], [WEDGE_OBLIQUE153, 4, 6],
        [WEDGE_OBLIQUE63,  2, 4], [WEDGE_OBLIQUE63,  6, 4],
        [WEDGE_OBLIQUE117, 2, 4], [WEDGE_OBLIQUE117, 6, 4],
    ],
];

/// `Wedge_Bits[ BLOCK_SIZES ]` (av1-spec p.409 lines 22414-22417) —
/// number of bits used to signal a wedge index for each block size
/// (`0` ⇒ wedge is forbidden, `4` ⇒ 16 wedge indices). Wedge masks
/// are defined only for block sizes whose entry is non-zero.
#[rustfmt::skip]
pub const WEDGE_BITS: [u8; 22] = [
    0, 0, 0, 4, 4, 4, 4, 4, 4, 4, 0,
    0, 0, 0, 0, 0, 0, 0, 4, 4, 0, 0,
];

/// `block_shape(bsize)` (av1-spec p.281 lines 15582-15591) — returns
/// the wedge-codebook outer dimension for `bsize` based on the
/// `(Num_4x4_Blocks_Wide, Num_4x4_Blocks_High)` shape relation.
///
/// Returns `0` for tall blocks (`h4 > w4`), `1` for wide blocks
/// (`h4 < w4`), `2` for square blocks (`h4 == w4`).
#[inline]
#[must_use]
pub fn block_shape(num_4x4_wide: u32, num_4x4_high: u32) -> u8 {
    if num_4x4_high > num_4x4_wide {
        0
    } else if num_4x4_high < num_4x4_wide {
        1
    } else {
        2
    }
}

/// §7.11.3.11 (av1-spec p.279 lines 15485-15544) `MasterMask` — the
/// six 64 × 64 master mask grids that `wedge_mask` slices into.
///
/// Stored row-major; `index[direction * MASK_MASTER_SIZE *
/// MASK_MASTER_SIZE + i * MASK_MASTER_SIZE + j]`. Built once on first
/// use via [`master_mask_table`] (the spec's
/// `initialise_wedge_mask_table` first loop, p.279 lines 15486-15508).
fn build_master_mask() -> Box<[u8; WEDGE_DIRECTIONS * MASK_MASTER_SIZE * MASK_MASTER_SIZE]> {
    let master =
        vec![0u8; WEDGE_DIRECTIONS * MASK_MASTER_SIZE * MASK_MASTER_SIZE].into_boxed_slice();
    let mut m: Box<[u8; WEDGE_DIRECTIONS * MASK_MASTER_SIZE * MASK_MASTER_SIZE]> =
        master.try_into().expect("len matches");
    let w = MASK_MASTER_SIZE;
    let h = MASK_MASTER_SIZE;

    // ---------- First loop: OBLIQUE63 + VERTICAL (av1-spec p.279
    // lines 15488-15499). ----------
    //
    //   for ( j = 0; j < w; j++ ) {
    //       shift = MASK_MASTER_SIZE / 4
    //       for ( i = 0; i < h; i += 2 ) {
    //           MasterMask[OBLIQUE63][i  ][j] =
    //               Wedge_Master_Oblique_Even[ Clip3(0, MMS-1, j-shift) ]
    //           shift -= 1
    //           MasterMask[OBLIQUE63][i+1][j] =
    //               Wedge_Master_Oblique_Odd [ Clip3(0, MMS-1, j-shift) ]
    //           MasterMask[VERTICAL ][i  ][j] = Wedge_Master_Vertical[j]
    //           MasterMask[VERTICAL ][i+1][j] = Wedge_Master_Vertical[j]
    //       }
    //   }
    for j in 0..w {
        let mut shift: i32 = (MASK_MASTER_SIZE / 4) as i32;
        let mut i = 0usize;
        while i < h {
            let idx_even = clip3_i32(0, (MASK_MASTER_SIZE - 1) as i32, j as i32 - shift) as usize;
            m[idx3(WEDGE_OBLIQUE63 as usize, i, j)] = WEDGE_MASTER_OBLIQUE_EVEN[idx_even];
            shift -= 1;
            let idx_odd = clip3_i32(0, (MASK_MASTER_SIZE - 1) as i32, j as i32 - shift) as usize;
            m[idx3(WEDGE_OBLIQUE63 as usize, i + 1, j)] = WEDGE_MASTER_OBLIQUE_ODD[idx_odd];
            m[idx3(WEDGE_VERTICAL as usize, i, j)] = WEDGE_MASTER_VERTICAL[j];
            m[idx3(WEDGE_VERTICAL as usize, i + 1, j)] = WEDGE_MASTER_VERTICAL[j];
            i += 2;
        }
    }

    // ---------- Second loop: derive OBLIQUE27, OBLIQUE117,
    // OBLIQUE153, HORIZONTAL from OBLIQUE63 + VERTICAL (av1-spec
    // p.279 lines 15500-15508). ----------
    //
    //   for ( i = 0; i < h; i++ ) {
    //       for ( j = 0; j < w; j++ ) {
    //           msk = MasterMask[OBLIQUE63][i][j]
    //           MasterMask[OBLIQUE27 ][j         ][i        ] = msk
    //           MasterMask[OBLIQUE117][i         ][w-1-j    ] = 64 - msk
    //           MasterMask[OBLIQUE153][w-1-j     ][i        ] = 64 - msk
    //           MasterMask[HORIZONTAL][j         ][i        ] =
    //               MasterMask[VERTICAL ][i][j]
    //       }
    //   }
    for i in 0..h {
        for j in 0..w {
            let msk = m[idx3(WEDGE_OBLIQUE63 as usize, i, j)];
            m[idx3(WEDGE_OBLIQUE27 as usize, j, i)] = msk;
            m[idx3(WEDGE_OBLIQUE117 as usize, i, w - 1 - j)] = 64 - msk;
            m[idx3(WEDGE_OBLIQUE153 as usize, w - 1 - j, i)] = 64 - msk;
            m[idx3(WEDGE_HORIZONTAL as usize, j, i)] = m[idx3(WEDGE_VERTICAL as usize, i, j)];
        }
    }

    m
}

#[inline(always)]
const fn idx3(dir: usize, i: usize, j: usize) -> usize {
    dir * MASK_MASTER_SIZE * MASK_MASTER_SIZE + i * MASK_MASTER_SIZE + j
}

/// Lazily-built §7.11.3.11 `MasterMask` table. The first call to
/// [`wedge_mask`] (or [`master_mask_table`]) triggers
/// [`build_master_mask`]; subsequent calls return the cached
/// reference. ~24 KiB (6 × 64 × 64 = 24576 bytes).
static MASTER_MASK_CACHE: std::sync::OnceLock<
    Box<[u8; WEDGE_DIRECTIONS * MASK_MASTER_SIZE * MASK_MASTER_SIZE]>,
> = std::sync::OnceLock::new();

/// Returns the cached `MasterMask` table, building it on first call.
///
/// The table contents are the §7.11.3.11 spec body's `MasterMask[6]
/// [64][64]` array after the `initialise_wedge_mask_table` first loop
/// (av1-spec p.279 lines 15485-15508).
#[must_use]
pub fn master_mask_table() -> &'static [u8; WEDGE_DIRECTIONS * MASK_MASTER_SIZE * MASK_MASTER_SIZE]
{
    MASTER_MASK_CACHE.get_or_init(build_master_mask)
}

/// §7.11.3.11 (av1-spec p.278-282) — populate `mask[ i * w + j ]` for
/// `i in 0..h`, `j in 0..w` with the per-pixel `WedgeMasks[ bsize ][
/// wedge_sign ][ wedge_index ][ i ][ j ]` value.
///
/// The spec body lifts a single per-`(bsize, wedge_index)` slice out
/// of the `MasterMask` table at `(yoff, xoff)`:
///
/// ```text
///   xoff = MASK_MASTER_SIZE / 2 - ((get_wedge_xoff(bsize, wedge) * w) >> 3)
///   yoff = MASK_MASTER_SIZE / 2 - ((get_wedge_yoff(bsize, wedge) * h) >> 3)
/// ```
///
/// The `flipSign` adjustment (av1-spec p.280 lines 15517-15531)
/// inverts the mask sense when the slice's tap-traced average is
/// below `32`: `WedgeMasks[bsize][flipSign][wedge][i][j] = master[..]`
/// and `WedgeMasks[bsize][!flipSign][wedge][i][j] = 64 - master[..]`.
/// `wedge_sign == flipSign` therefore returns the raw master slice;
/// `wedge_sign != flipSign` returns the inverted slice.
///
/// ## Arguments
///
/// * `mi_size` — `BLOCK_SIZES` index (`0..22`); must have
///   `WEDGE_BITS[mi_size] > 0` (the spec enumerates the 9 wedge-eligible
///   block sizes as `BLOCK_8X8`, `BLOCK_8X16`, `BLOCK_16X8`,
///   `BLOCK_16X16`, `BLOCK_16X32`, `BLOCK_32X16`, `BLOCK_32X32`,
///   `BLOCK_8X32`, `BLOCK_32X8`).
/// * `num_4x4_wide` / `num_4x4_high` — `Num_4x4_Blocks_Wide` /
///   `Num_4x4_Blocks_High` for `mi_size` (used by [`block_shape`] +
///   the `xoff`/`yoff` derivation). The width / height in luma
///   samples is `4 * num_4x4_*`.
/// * `wedge_index` — in `0..16` (`WEDGE_TYPES`); the codebook ordinal
///   read by §5.11.28 or §5.11.29.
/// * `wedge_sign` — `0` or `1`; the §5.11.29 sign bit (always `0` on
///   the inter-intra wedge path per §5.11.28).
/// * `mask` — output buffer with length `>= w * h` where `w = 4 *
///   num_4x4_wide` and `h = 4 * num_4x4_high`.
///
/// ## Returns
///
/// `Ok(())` on success, [`crate::Error::PartitionWalkOutOfRange`] for
/// caller-bug arguments (out-of-range `mi_size`, `num_4x4_*`,
/// `wedge_index`, `wedge_sign`, or `mask.len() < w*h`, or a `mi_size`
/// with `WEDGE_BITS[mi_size] == 0`).
pub fn wedge_mask(
    mi_size: usize,
    num_4x4_wide: u32,
    num_4x4_high: u32,
    wedge_index: u8,
    wedge_sign: u8,
    mask: &mut [u8],
) -> Result<(), crate::Error> {
    if mi_size >= WEDGE_BITS.len() {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if WEDGE_BITS[mi_size] == 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if wedge_index >= 16 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if wedge_sign > 1 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if num_4x4_wide == 0 || num_4x4_high == 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let w: usize = (num_4x4_wide as usize) * 4;
    let h: usize = (num_4x4_high as usize) * 4;
    // The 9 wedge-eligible block sizes max out at BLOCK_32X32 (32×32);
    // 8×32 / 32×8 are 32 in one axis. Guard against caller-bug giant
    // sizes that would walk off the 64×64 master mask.
    if w > MASK_MASTER_SIZE || h > MASK_MASTER_SIZE {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if mask.len() < w * h {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    let shape = block_shape(num_4x4_wide, num_4x4_high) as usize;
    let entry = &WEDGE_CODEBOOK[shape][wedge_index as usize];
    let dir = entry[0] as usize;
    let xoff_codebook = entry[1] as i32;
    let yoff_codebook = entry[2] as i32;
    let xoff: i32 = (MASK_MASTER_SIZE as i32) / 2 - ((xoff_codebook * (w as i32)) >> 3);
    let yoff: i32 = (MASK_MASTER_SIZE as i32) / 2 - ((yoff_codebook * (h as i32)) >> 3);

    // §7.11.3.11 (av1-spec p.279 lines 15517-15523) — average-of-edge
    // sum over the first row + first column to determine the flipSign
    // for this `(bsize, wedge)` slot.
    let master = master_mask_table();
    let mut sum: i64 = 0;
    for i in 0..w {
        sum += master[idx3(dir, yoff as usize, (xoff + i as i32) as usize)] as i64;
    }
    for i in 1..h {
        sum += master[idx3(dir, (yoff + i as i32) as usize, xoff as usize)] as i64;
    }
    let avg = (sum + ((w + h - 1) as i64) / 2) / ((w + h - 1) as i64);
    let flip_sign: u8 = if avg < 32 { 1 } else { 0 };

    // §7.11.3.11 (av1-spec p.279 lines 15524-15531) — `WedgeMasks[
    // bsize ][ flipSign ][ wedge ][ i ][ j ] = MasterMask[ dir ][
    // yoff+i ][ xoff+j ]` and `WedgeMasks[ bsize ][ !flipSign ][...]
    // = 64 - MasterMask[...]`. The wedge_sign argument selects which
    // of the two stored variants to materialize.
    let invert = wedge_sign != flip_sign;
    for i in 0..h {
        for j in 0..w {
            let raw = master[idx3(dir, (yoff + i as i32) as usize, (xoff + j as i32) as usize)];
            mask[i * w + j] = if invert { 64 - raw } else { raw };
        }
    }
    Ok(())
}

// =====================================================================
// §7.11.3.12 — Difference weight mask process (av1-spec p.282-283).
// =====================================================================

/// §7.11.3.12 (av1-spec p.282-283) — fill `mask[ i * w + j ]` with the
/// per-pixel `m = Clip3(0, 64, 38 + diff/16)` value driven by the
/// inter-pred sample difference, with the `mask_type` toggle
/// inverting the sense (`Mask = 64 - m` when `mask_type != 0`).
///
/// The spec body reads:
///
/// ```text
///   for ( i = 0; i < h; i++ ) {
///       for ( j = 0; j < w; j++ ) {
///           diff = Abs(preds[0][i][j] - preds[1][i][j])
///           diff = Round2(diff, (BitDepth - 8) + InterPostRound)
///           m = Clip3(0, 64, 38 + diff / 16)
///           Mask[i][j] = mask_type ? (64 - m) : m
///       }
///   }
/// ```
///
/// ## Arguments
///
/// * `bit_depth` — `8`, `10`, or `12`.
/// * `inter_post_round` — `RoundingVars::inter_post_round` from
///   §7.11.3.2; the `(BitDepth - 8) + InterPostRound` total shift on
///   the diff is `1 + 4 = 5` for 10-bit compound, `4 + 2 = 6` for
///   12-bit compound, `4` for 8-bit compound.
/// * `mask_type` — `0` (`DIFFWTD_38`) or `1` (`DIFFWTD_38_INV`); the
///   §5.11.29 `mask_type` bit.
/// * `preds0` / `preds1` — the two §7.11.3.4-produced per-pixel
///   prediction arrays, each `w * h` `i32` values.
/// * `w` / `h` — region width / height in samples.
/// * `mask` — output, length `>= w * h`.
///
/// ## Returns
///
/// `Ok(())` on success. [`crate::Error::PartitionWalkOutOfRange`] for
/// caller-bug arguments (invalid `bit_depth`, `mask_type > 1`,
/// `w == 0`, `h == 0`, slice-length undershoot).
#[allow(clippy::too_many_arguments)]
pub fn difference_weight_mask(
    bit_depth: u8,
    inter_post_round: u32,
    mask_type: u8,
    preds0: &[i32],
    preds1: &[i32],
    w: usize,
    h: usize,
    mask: &mut [u8],
) -> Result<(), crate::Error> {
    if !matches!(bit_depth, 8 | 10 | 12) {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if mask_type > 1 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if w == 0 || h == 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let n = w * h;
    if preds0.len() < n || preds1.len() < n || mask.len() < n {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let shift: u32 = (bit_depth as u32 - 8) + inter_post_round;
    for i in 0..h {
        for j in 0..w {
            let p0 = preds0[i * w + j] as i64;
            let p1 = preds1[i * w + j] as i64;
            let diff = (p0 - p1).unsigned_abs() as i64;
            let scaled = round2(diff, shift);
            let m = clip3_i32(0, 64, 38 + (scaled / 16) as i32) as u8;
            mask[i * w + j] = if mask_type != 0 { 64 - m } else { m };
        }
    }
    Ok(())
}

// =====================================================================
// §7.11.3.13 — Intra mode variant mask process (av1-spec p.283-284).
// =====================================================================

/// `Ii_Weights_1d[ MAX_SB_SIZE ]` (av1-spec p.283-284 lines
/// 15727-15735). The 128-entry 1d driver §7.11.3.13 indexes via
/// `i * sizeScale` (II_V_PRED), `j * sizeScale` (II_H_PRED), or
/// `Min(i,j) * sizeScale` (II_SMOOTH_PRED). Values are monotonically
/// non-increasing from `60` (idx 0) down to `1` (idx 113..=127),
/// reflecting the smooth-mask falloff with distance from the
/// edge.
#[rustfmt::skip]
pub const II_WEIGHTS_1D: [u8; MAX_SB_SIZE] = [
    60, 58, 56, 54, 52, 50, 48, 47, 45, 44, 42, 41, 39, 38, 37, 35, 34, 33, 32,
    31, 30, 29, 28, 27, 26, 25, 24, 23, 22, 22, 21, 20, 19, 19, 18, 18, 17, 16,
    16, 15, 15, 14, 14, 13, 13, 12, 12, 12, 11, 11, 10, 10, 10,  9,  9,  9,  8,
     8,  8,  8,  7,  7,  7,  7,  6,  6,  6,  6,  6,  5,  5,  5,  5,  5,  4,  4,
     4,  4,  4,  4,  4,  4,  3,  3,  3,  3,  3,  3,  3,  3,  3,  2,  2,  2,  2,
     2,  2,  2,  2,  2,  2,  2,  2,  2,  2,  2,  1,  1,  1,  1,  1,  1,  1,  1,
     1,  1,  1,  1,  1,  1,  1,  1,  1,  1,  1,  1,  1,  1,
];

/// §7.11.3.13 (av1-spec p.283-284) — fill `mask[ i * w + j ]` with the
/// `interintra_mode`-driven smooth-mask weights for the inter-intra
/// blend.
///
/// The spec body reads:
///
/// ```text
///   sizeScale = MAX_SB_SIZE / Max( h, w )
///   for ( i = 0; i < h; i++ ) {
///       for ( j = 0; j < w; j++ ) {
///           if ( interintra_mode == II_V_PRED )
///               Mask[i][j] = Ii_Weights_1d[ i * sizeScale ]
///           else if ( interintra_mode == II_H_PRED )
///               Mask[i][j] = Ii_Weights_1d[ j * sizeScale ]
///           else if ( interintra_mode == II_SMOOTH_PRED )
///               Mask[i][j] = Ii_Weights_1d[ Min(i, j) * sizeScale ]
///           else
///               Mask[i][j] = 32
///       }
///   }
/// ```
///
/// ## Arguments
///
/// * `interintra_mode` — `0..4` per §5.11.28 (`II_DC_PRED`,
///   `II_V_PRED`, `II_H_PRED`, `II_SMOOTH_PRED`).
/// * `w` / `h` — region width / height in samples. `Max(w, h)` must
///   divide `MAX_SB_SIZE = 128` (true for all `BLOCK_SIZES` that
///   support inter-intra: 8, 16, 32 are factors of 128).
/// * `mask` — output, length `>= w * h`.
///
/// ## Returns
///
/// `Ok(())` on success. [`crate::Error::PartitionWalkOutOfRange`] for
/// caller-bug arguments.
pub fn intra_mode_variant_mask(
    interintra_mode: u8,
    w: usize,
    h: usize,
    mask: &mut [u8],
) -> Result<(), crate::Error> {
    if interintra_mode > II_SMOOTH_PRED {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if w == 0 || h == 0 || w > MAX_SB_SIZE || h > MAX_SB_SIZE {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if mask.len() < w * h {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let larger = w.max(h);
    let size_scale: usize = MAX_SB_SIZE / larger;
    for i in 0..h {
        for j in 0..w {
            let m = match interintra_mode {
                II_V_PRED => II_WEIGHTS_1D[i * size_scale],
                II_H_PRED => II_WEIGHTS_1D[j * size_scale],
                II_SMOOTH_PRED => II_WEIGHTS_1D[i.min(j) * size_scale],
                // II_DC_PRED ⇒ 50/50 blend
                _ => 32,
            };
            mask[i * w + j] = m;
        }
    }
    Ok(())
}

// =====================================================================
// §7.11.3.14 — Mask blend process (av1-spec p.284-285).
// =====================================================================

/// §7.11.3.14 (av1-spec p.284-285) — inter-inter mask blend for the
/// `IsInterIntra == 0 && compound_type ∈ {COMPOUND_WEDGE,
/// COMPOUND_DIFFWTD, COMPOUND_INTRA}` arm of §7.11.3.1.
///
/// Combines `preds[0]` and `preds[1]` per-pixel via the mask:
///
/// ```text
///   m as derived per (subX, subY) from Mask
///   out[y][x] = Clip1( Round2( m * preds[0][y][x] + (64 - m) * preds[1][y][x],
///                              6 + InterPostRound ) )
/// ```
///
/// The `(subX, subY)` argument selects how the per-luma-pixel mask is
/// down-sampled for chroma planes (av1-spec p.284 lines 15771-15783):
///
/// * `(0, 0)` ⇒ `m = Mask[y][x]` (luma, or chroma when
///   `subsampling_{x,y} == 0`).
/// * `(1, 0)` ⇒ `m = Round2(Mask[y][2x] + Mask[y][2x+1], 1)`.
/// * `(0, 1)` ⇒ `m = Round2(Mask[2y][x] + Mask[2y+1][x], 1)`.
/// * `(1, 1)` ⇒ `m = Round2(Mask[2y][2x] + Mask[2y][2x+1] +
///                Mask[2y+1][2x] + Mask[2y+1][2x+1], 2)`.
///
/// ## Arguments
///
/// * `bit_depth` — `8`, `10`, or `12`; sets the `Clip1` upper bound.
/// * `inter_post_round` — `RoundingVars::inter_post_round`.
/// * `sub_x` / `sub_y` — `0` (luma, or chroma without subsampling) or
///   `1` (chroma with subsampling on that axis).
/// * `preds0` / `preds1` — the two §7.11.3.4 prediction buffers
///   sized `w * h` for the *current plane*.
/// * `w` / `h` — output region width / height in the current-plane
///   sample grid.
/// * `mask` — the §7.11.3.11/12/13 luma-grid mask buffer. Its layout
///   depends on `(sub_x, sub_y)`:
///   * `(0, 0)` ⇒ length `>= w * h`, row stride `w`.
///   * `(1, 0)` ⇒ length `>= 2*w * h`, row stride `2*w`.
///   * `(0, 1)` ⇒ length `>= w * 2*h`, row stride `w`.
///   * `(1, 1)` ⇒ length `>= 2*w * 2*h`, row stride `2*w`.
/// * `mask_stride` — row stride of `mask` in u8s (typically `2*w` when
///   `sub_x == 1`, else `w`). Pass `0` to use the default
///   derived-from-`(sub_x, w)` stride.
/// * `out` — output sample buffer, length `>= w * h`.
///
/// ## Returns
///
/// `Ok(())` on success. [`crate::Error::PartitionWalkOutOfRange`] for
/// caller-bug arguments.
#[allow(clippy::too_many_arguments)]
pub fn mask_blend(
    bit_depth: u8,
    inter_post_round: u32,
    sub_x: u8,
    sub_y: u8,
    preds0: &[i32],
    preds1: &[i32],
    w: usize,
    h: usize,
    mask: &[u8],
    mask_stride: usize,
    out: &mut [u16],
) -> Result<(), crate::Error> {
    if !matches!(bit_depth, 8 | 10 | 12) {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if sub_x > 1 || sub_y > 1 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if w == 0 || h == 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let n = w * h;
    if preds0.len() < n || preds1.len() < n || out.len() < n {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    // The mask grid lives on the luma plane; its native width is
    // `2*w` when sub_x==1 and `w` otherwise; same for height with
    // sub_y. mask_stride defaults to the natural row stride when 0.
    let mask_w = if sub_x == 1 { 2 * w } else { w };
    let mask_h = if sub_y == 1 { 2 * h } else { h };
    let stride = if mask_stride == 0 {
        mask_w
    } else {
        mask_stride
    };
    if stride < mask_w {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if mask.len() < stride * (mask_h - 1) + mask_w {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    let shift: u32 = 6 + inter_post_round;
    let max: i32 = (1i32 << bit_depth) - 1;
    for y in 0..h {
        for x in 0..w {
            let m: i32 = match (sub_x, sub_y) {
                (0, 0) => mask[y * stride + x] as i32,
                (1, 0) => round2(
                    mask[y * stride + 2 * x] as i64 + mask[y * stride + 2 * x + 1] as i64,
                    1,
                ) as i32,
                (0, 1) => round2(
                    mask[2 * y * stride + x] as i64 + mask[(2 * y + 1) * stride + x] as i64,
                    1,
                ) as i32,
                _ => round2(
                    mask[2 * y * stride + 2 * x] as i64
                        + mask[2 * y * stride + 2 * x + 1] as i64
                        + mask[(2 * y + 1) * stride + 2 * x] as i64
                        + mask[(2 * y + 1) * stride + 2 * x + 1] as i64,
                    2,
                ) as i32,
            };
            let p0 = preds0[y * w + x] as i64;
            let p1 = preds1[y * w + x] as i64;
            let acc = (m as i64) * p0 + ((64 - m) as i64) * p1;
            let blended = round2(acc, shift) as i32;
            out[y * w + x] = clip3_i32(0, max, blended) as u16;
        }
    }
    Ok(())
}

/// §7.11.3.14 (av1-spec p.284-285) — interintra mask blend for the
/// `IsInterIntra == 1` arm of §7.11.3.1.
///
/// Combines `preds[0]` (the inter prediction in pre-Clip form) and
/// the in-place intra prediction already written to `dst` per:
///
/// ```text
///   pred0 = Clip1( Round2( preds[0][y][x], InterPostRound ) )
///   pred1 = CurrFrame[plane][y+dstY][x+dstX]
///   CurrFrame[plane][y+dstY][x+dstX] =
///       Round2( m * pred1 + (64 - m) * pred0, 6 )
/// ```
///
/// Two §7.11.3.14 interintra sub-arms are distinguished by the mask's
/// downsampling regime (av1-spec p.284 line 15773's
/// `(!subX && !subY) || (interintra && !wedge_interintra)` predicate):
///
/// * **Non-wedge** (`COMPOUND_INTRA`, `wedge_interintra == 0`). The
///   §7.11.3.13 driver produces a per-plane mask sized to the current
///   plane already, so the `(interintra && !wedge_interintra)` clause
///   forces `m = Mask[y][x]` on every plane — no chroma averaging.
///   Reached with `sub_x == 0 && sub_y == 0` (the natural call shape).
/// * **Wedge** (`wedge_interintra == 1`, which sets `compound_type ==
///   COMPOUND_WEDGE` per av1-spec p.80 line 5017). The §7.11.3.11 wedge
///   mask is built once on the *luma* grid (the §7.11.3.1 mask-prep step
///   invokes it only at `plane == 0`, av1-spec p.258 line 14386), so the
///   chroma planes read it through the same subsampling-average branches
///   the inter-inter masks use. The `(interintra && !wedge_interintra)`
///   exception does **not** fire here, so `(subX, subY)` selects the
///   1-D / 2-D `Round2` averaging.
///
/// This function realises both: a non-subsampled call (`sub_x == 0 &&
/// sub_y == 0`) reads `Mask[y][x]` directly (covering the non-wedge arm
/// and the luma plane of the wedge arm); a subsampled call applies the
/// matching §7.11.3.14 averaging over the luma-grid mask (covering the
/// chroma planes of the wedge arm).
///
/// ## Arguments
///
/// * `bit_depth` — `8`, `10`, or `12`.
/// * `inter_post_round` — `RoundingVars::inter_post_round`.
/// * `sub_x` / `sub_y` — `0` / `1` chroma subsampling of the current
///   plane (always `0` on the non-wedge arm and on the luma plane).
/// * `preds0` — the inter prediction (pre-Clip), length `>= w * h`.
/// * `w` / `h` — output region width / height in current-plane samples.
/// * `mask` — the blending mask. On the non-subsampled call it is the
///   per-plane `w × h` grid; on the subsampled call it is the luma-grid
///   wedge mask whose native extent is `2*w` × `h` (`sub_x == 1`),
///   `w` × `2*h` (`sub_y == 1`), or `2*w` × `2*h` (both).
/// * `mask_stride` — row stride of `mask` in `u8`s; `0` selects the
///   natural stride (`2*w` when `sub_x == 1`, else `w`).
/// * `dst` — the in-place destination; on entry holds the §7.11.2
///   intra prediction (i.e. `CurrFrame[plane][y+dstY][x+dstX]`); on
///   exit holds the blended sample.
///
/// ## Returns
///
/// `Ok(())` on success. [`crate::Error::PartitionWalkOutOfRange`] for
/// caller-bug arguments (invalid `bit_depth`, `sub_* > 1`, zero extent,
/// slice-length / stride undershoot).
#[allow(clippy::too_many_arguments)]
pub fn mask_blend_interintra(
    bit_depth: u8,
    inter_post_round: u32,
    sub_x: u8,
    sub_y: u8,
    preds0: &[i32],
    w: usize,
    h: usize,
    mask: &[u8],
    mask_stride: usize,
    dst: &mut [u16],
) -> Result<(), crate::Error> {
    if !matches!(bit_depth, 8 | 10 | 12) {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if sub_x > 1 || sub_y > 1 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if w == 0 || h == 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let n = w * h;
    if preds0.len() < n || dst.len() < n {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    // The luma-grid mask's native extent depends on the current plane's
    // subsampling; `mask_stride == 0` selects the natural row stride.
    let mask_w = if sub_x == 1 { 2 * w } else { w };
    let mask_h = if sub_y == 1 { 2 * h } else { h };
    let stride = if mask_stride == 0 {
        mask_w
    } else {
        mask_stride
    };
    if stride < mask_w {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if mask.len() < stride * (mask_h - 1) + mask_w {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let max: i32 = (1i32 << bit_depth) - 1;
    for y in 0..h {
        for x in 0..w {
            // av1-spec p.284 lines 15772-15781: the wedge interintra
            // mask is the luma-grid wedge mask, so `(subX, subY)`
            // selects the same 1-D / 2-D `Round2` averaging the
            // inter-inter masks use; the non-wedge arm always reaches
            // the `m = Mask[y][x]` branch via `sub_x == 0 && sub_y == 0`.
            let m: i64 = match (sub_x, sub_y) {
                (0, 0) => mask[y * stride + x] as i64,
                (1, 0) => round2(
                    mask[y * stride + 2 * x] as i64 + mask[y * stride + 2 * x + 1] as i64,
                    1,
                ),
                (0, 1) => round2(
                    mask[2 * y * stride + x] as i64 + mask[(2 * y + 1) * stride + x] as i64,
                    1,
                ),
                _ => round2(
                    mask[2 * y * stride + 2 * x] as i64
                        + mask[2 * y * stride + 2 * x + 1] as i64
                        + mask[(2 * y + 1) * stride + 2 * x] as i64
                        + mask[(2 * y + 1) * stride + 2 * x + 1] as i64,
                    2,
                ),
            };
            let raw_pred0 = preds0[y * w + x] as i64;
            // pred0 = Clip1( Round2( preds[0][y][x], InterPostRound ) )
            let clipped = clip3_i32(0, max, round2(raw_pred0, inter_post_round) as i32) as i64;
            let pred1 = dst[y * w + x] as i64;
            let blended = round2(m * pred1 + (64 - m) * clipped, 6) as i32;
            dst[y * w + x] = clip3_i32(0, max, blended) as u16;
        }
    }
    Ok(())
}

// =====================================================================
// §7.11.3.15 — Distance weights process (av1-spec p.285).
// =====================================================================

/// `Quant_Dist_Weight[ 4 ][ 2 ]` (av1-spec p.285 line 15845) — the
/// per-`i` `(c0, c1)` pair the §7.11.3.15 search-loop compares against
/// `(d0, d1)`. The four rows realise progressively-asymmetric weight
/// ratios.
pub const QUANT_DIST_WEIGHT: [[i32; 2]; 4] = [[2, 3], [2, 5], [2, 7], [1, MAX_FRAME_DISTANCE]];

/// `Quant_Dist_Lookup[ 4 ][ 2 ]` (av1-spec p.285 line 15849) — the
/// `(fwd, bck)` weight pairs the §7.11.3.15 search-loop falls back to
/// after deciding `i` (and `(d0, d1)` ordering). Sums to `16` in
/// every row.
pub const QUANT_DIST_LOOKUP: [[i32; 2]; 4] = [[9, 7], [11, 5], [12, 4], [13, 3]];

/// §5.9.3 `get_relative_dist(a, b)` (av1-spec p.41-42) — the sign-
/// extending order-hint subtraction used by §7.11.3.15. Returns
/// `0` when `order_hint_bits == 0` (i.e. `enable_order_hint == 0`);
/// otherwise sign-extends the difference through the `OrderHintBits`-
/// bit signed range.
///
/// ## Arguments
///
/// * `a` / `b` — the two order hints to subtract.
/// * `order_hint_bits` — `OrderHintBits` from §5.5.1 (`0..=8`); `0`
///   when `enable_order_hint == 0`.
///
/// ## Returns
///
/// The sign-extended `(a - b)` in `-(1 << (OrderHintBits-1)) ..
/// (1 << (OrderHintBits-1)) - 1`, or `0` when `order_hint_bits == 0`.
#[inline]
#[must_use]
pub fn get_relative_dist(a: i32, b: i32, order_hint_bits: u32) -> i32 {
    if order_hint_bits == 0 {
        return 0;
    }
    let diff: i32 = a - b;
    let m: i32 = 1 << (order_hint_bits - 1);
    (diff & (m - 1)) - (diff & m)
}

/// §7.11.3.15 output: the `(FwdWeight, BckWeight)` pair the
/// §7.11.3.1 `COMPOUND_DISTANCE` blend combines `preds[0]` and
/// `preds[1]` with: `Clip1( Round2( FwdWeight * preds[0] + BckWeight
/// * preds[1], 4 + InterPostRound ) )`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DistanceWeights {
    /// `FwdWeight` applied to `preds[0]`. In `3..=13`.
    pub fwd_weight: i32,
    /// `BckWeight` applied to `preds[1]`. In `3..=13`. Always sums to
    /// `16` with `fwd_weight`.
    pub bck_weight: i32,
}

/// §7.11.3.15 (av1-spec p.285) — derive `(FwdWeight, BckWeight)` from
/// the two reference frames' `OrderHints[]` deltas relative to the
/// current frame's `OrderHint`.
///
/// The spec body computes:
///
/// ```text
///   for ( refList = 0; refList < 2; refList++ )
///     h = OrderHints[ RefFrames[candRow][candCol][refList] ]
///     dist[refList] = Clip3(0, MAX_FRAME_DISTANCE,
///                           Abs( get_relative_dist(h, OrderHint) ))
///   d0 = dist[1]
///   d1 = dist[0]
///   order = d0 <= d1
///   if ( d0 == 0 || d1 == 0 )
///     FwdWeight = Quant_Dist_Lookup[3][order]
///     BckWeight = Quant_Dist_Lookup[3][1 - order]
///   else
///     for ( i = 0; i < 3; i++ )
///       c0 = Quant_Dist_Weight[i][order]
///       c1 = Quant_Dist_Weight[i][1 - order]
///       if ( order  && d0 * c0 > d1 * c1 ) break
///       if ( !order && d0 * c0 < d1 * c1 ) break
///     FwdWeight = Quant_Dist_Lookup[i][order]
///     BckWeight = Quant_Dist_Lookup[i][1 - order]
/// ```
///
/// ## Arguments
///
/// * `order_hint_bits` — `OrderHintBits` from §5.5.1.
/// * `current_order_hint` — `OrderHint` of the frame being decoded.
/// * `order_hint_ref0` / `order_hint_ref1` — `OrderHints[ RefFrames[
///   candRow ][ candCol ][ 0 ] ]` and `[ 1 ]`.
///
/// ## Returns
///
/// `DistanceWeights { fwd_weight, bck_weight }`. The two always sum
/// to `16`, by construction of [`QUANT_DIST_LOOKUP`].
pub fn distance_weights(
    order_hint_bits: u32,
    current_order_hint: i32,
    order_hint_ref0: i32,
    order_hint_ref1: i32,
) -> DistanceWeights {
    // Per-list distance: Abs(get_relative_dist), saturated to
    // [0, MAX_FRAME_DISTANCE].
    let dist0 = clip3_i32(
        0,
        MAX_FRAME_DISTANCE,
        get_relative_dist(order_hint_ref0, current_order_hint, order_hint_bits).abs(),
    );
    let dist1 = clip3_i32(
        0,
        MAX_FRAME_DISTANCE,
        get_relative_dist(order_hint_ref1, current_order_hint, order_hint_bits).abs(),
    );
    // d0 = dist[1], d1 = dist[0] per the spec body — note the swap.
    let d0 = dist1;
    let d1 = dist0;
    let order_bool = d0 <= d1;
    let order: usize = if order_bool { 1 } else { 0 };
    let other: usize = 1 - order;

    if d0 == 0 || d1 == 0 {
        return DistanceWeights {
            fwd_weight: QUANT_DIST_LOOKUP[3][order],
            bck_weight: QUANT_DIST_LOOKUP[3][other],
        };
    }

    // The spec body's `for (i = 0; i < 3; i++)` loop falls through to
    // `i = 3` if no break fires.
    let mut chosen_i = 3usize;
    for (i, row) in QUANT_DIST_WEIGHT.iter().enumerate().take(3) {
        let c0 = row[order];
        let c1 = row[other];
        let lhs = d0 * c0;
        let rhs = d1 * c1;
        let break_now = if order_bool { lhs > rhs } else { lhs < rhs };
        if break_now {
            chosen_i = i;
            break;
        }
    }
    DistanceWeights {
        fwd_weight: QUANT_DIST_LOOKUP[chosen_i][order],
        bck_weight: QUANT_DIST_LOOKUP[chosen_i][other],
    }
}

/// Apply a `COMPOUND_DISTANCE` blend per av1-spec p.258 line 14408 —
/// `CurrFrame[plane][y+i][x+j] = Clip1( Round2( FwdWeight * preds[0]
/// + BckWeight * preds[1], 4 + InterPostRound ) )`.
///
/// Convenience wrapper combining [`distance_weights`] output with the
/// per-pixel blend. Caller-bug-checked against the same argument set
/// as [`mask_blend`].
#[allow(clippy::too_many_arguments)]
pub fn compound_distance_blend(
    bit_depth: u8,
    inter_post_round: u32,
    weights: DistanceWeights,
    preds0: &[i32],
    preds1: &[i32],
    w: usize,
    h: usize,
    out: &mut [u16],
) -> Result<(), crate::Error> {
    if !matches!(bit_depth, 8 | 10 | 12) {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if w == 0 || h == 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let n = w * h;
    if preds0.len() < n || preds1.len() < n || out.len() < n {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let max: i32 = (1i32 << bit_depth) - 1;
    let shift: u32 = 4 + inter_post_round;
    for y in 0..h {
        for x in 0..w {
            let acc = (weights.fwd_weight as i64) * (preds0[y * w + x] as i64)
                + (weights.bck_weight as i64) * (preds1[y * w + x] as i64);
            let rounded = round2(acc, shift) as i32;
            out[y * w + x] = clip3_i32(0, max, rounded) as u16;
        }
    }
    Ok(())
}

// =====================================================================
// §7.11.3.5-8 — Warp motion compensation (av1-spec p.266-274).
// =====================================================================
//
// The §7.11.3.1 driver dispatches to `block_warp` (§7.11.3.5) on the
// `useWarp == 1` (LOCALWARP) and `useWarp == 2` (GLOBAL_GLOBALMV) arms.
// This module lands the four sub-sections of the WARP family — the
// `block_warp` MC kernel itself, the `setup_shear` derivation of the
// `(alpha, beta, gamma, delta)` shear coefficients, the
// `resolve_divisor` fixed-point inverse helper, and the
// `warp_estimation` least-squares fit that derives `LocalWarpParams`
// from the §7.10.4 `CandList` of neighbour MV samples (the
// `find_warp_samples` output landed in r175).

/// `WARPEDMODEL_PREC_BITS = 16` (av1-spec p.16 line 1160) — internal
/// precision of warped motion model coefficients. Re-exported here for
/// the warp kernel's local arithmetic; matches the existing
/// [`crate::uncompressed_header_tail::WARPEDMODEL_PREC_BITS`] /
/// [`crate::cdf::WARPEDMODEL_PREC_BITS`] siblings.
pub const WARP_WARPEDMODEL_PREC_BITS: u32 = 16;

/// `WARP_PARAM_REDUCE_BITS = 6` (av1-spec p.18 line 1357) — rounding
/// bit-width applied to the shear-coefficient inputs of `setup_shear`.
pub const WARP_PARAM_REDUCE_BITS: u32 = 6;

/// `DIV_LUT_PREC_BITS = 14` (av1-spec p.17 line 1191) — fractional-bit
/// precision of each `Div_Lut` entry.
pub const DIV_LUT_PREC_BITS: u32 = 14;

/// `DIV_LUT_BITS = 8` (av1-spec p.17 line 1194) — fractional-bit width
/// of the `f` lookup index in `resolve_divisor`.
pub const DIV_LUT_BITS: u32 = 8;

/// `DIV_LUT_NUM = 257` (av1-spec p.17 line 1197) — number of entries
/// in the `Div_Lut` table.
pub const DIV_LUT_NUM: usize = 257;

/// `LS_MV_MAX = 256` (av1-spec p.18 line 1210) — per-axis clamp on
/// each `(sx - dx)` / `(sy - dy)` neighbour-MV-difference that
/// participates in the §7.11.3.8 least-squares accumulation.
pub const LS_MV_MAX: i32 = 256;

/// `WARPEDMODEL_TRANS_CLAMP = 1 << 23` (av1-spec p.18 line 1213) —
/// clamp on the translation components (`LocalWarpParams[0]` /
/// `LocalWarpParams[1]`) emitted by §7.11.3.8.
pub const WARPEDMODEL_TRANS_CLAMP: i32 = 1 << 23;

/// `WARPEDMODEL_NONDIAGAFFINE_CLAMP = 1 << 13` (av1-spec p.18 line
/// 1216) — clamp on the off-diagonal affine entries
/// (`LocalWarpParams[3]` / `LocalWarpParams[4]`) emitted by
/// §7.11.3.8's `nondiag`, and the offset clamp for the on-diagonal
/// entries (`LocalWarpParams[2]` / `LocalWarpParams[5]`) emitted by
/// `diag`.
pub const WARPEDMODEL_NONDIAGAFFINE_CLAMP: i32 = 1 << 13;

/// `WARPEDPIXEL_PREC_SHIFTS = 1 << 6 = 64` (av1-spec p.18 line 1219)
/// — number of phases used in `Warped_Filters`. The `offs` index in
/// §7.11.3.5 is computed as `Round2(sx, WARPEDDIFF_PREC_BITS) +
/// WARPEDPIXEL_PREC_SHIFTS` and ranges across `0..(3 * WPS + 1)`.
pub const WARPEDPIXEL_PREC_SHIFTS: usize = 1 << 6;

/// `WARPEDDIFF_PREC_BITS = 10` (av1-spec p.18 line 1221) — extra bits
/// of precision in the warped-filter input `(sx, sy)` differentials
/// over the integer phase resolution.
pub const WARPEDDIFF_PREC_BITS: u32 = 10;

/// `Warped_Filters[ WARPEDPIXEL_PREC_SHIFTS * 3 + 1 ][ 8 ]` —
/// per-phase warped 8-tap filter coefficients. Transcribed verbatim
/// from av1-spec p.268-270 (av1-spec.txt lines 14919-15036).
///
/// The table covers `193 = 3*64 + 1` phases. Each row is the 8-tap
/// kernel applied to the reference samples surrounding the integer
/// position. The phase index `offs` is derived in §7.11.3.5 from
/// `(sx, sy) = sx4 + alpha*i2 + beta*i1` / similar via
/// `Round2(sx, WARPEDDIFF_PREC_BITS) + WARPEDPIXEL_PREC_SHIFTS`. The
/// `+ WARPEDPIXEL_PREC_SHIFTS` shift centres the table around index
/// 64 (the integer-position row at `{0,0,0,128,0,0,0,0}` analogue).
#[rustfmt::skip]
pub const WARPED_FILTERS: [[i32; 8]; WARPEDPIXEL_PREC_SHIFTS * 3 + 1] = [
    [   0,    0,  127,    1,    0,    0,    0,    0],
    [   0,   -1,  127,    2,    0,    0,    0,    0],
    [   1,   -3,  127,    4,   -1,    0,    0,    0],
    [   1,   -4,  126,    6,   -2,    1,    0,    0],
    [   1,   -5,  126,    8,   -3,    1,    0,    0],
    [   1,   -6,  125,   11,   -4,    1,    0,    0],
    [   1,   -7,  124,   13,   -4,    1,    0,    0],
    [   2,   -8,  123,   15,   -5,    1,    0,    0],
    [   2,   -9,  122,   18,   -6,    1,    0,    0],
    [   2,  -10,  121,   20,   -6,    1,    0,    0],
    [   2,  -11,  120,   22,   -7,    2,    0,    0],
    [   2,  -12,  119,   25,   -8,    2,    0,    0],
    [   3,  -13,  117,   27,   -8,    2,    0,    0],
    [   3,  -13,  116,   29,   -9,    2,    0,    0],
    [   3,  -14,  114,   32,  -10,    3,    0,    0],
    [   3,  -15,  113,   35,  -10,    2,    0,    0],
    [   3,  -15,  111,   37,  -11,    3,    0,    0],
    [   3,  -16,  109,   40,  -11,    3,    0,    0],
    [   3,  -16,  108,   42,  -12,    3,    0,    0],
    [   4,  -17,  106,   45,  -13,    3,    0,    0],
    [   4,  -17,  104,   47,  -13,    3,    0,    0],
    [   4,  -17,  102,   50,  -14,    3,    0,    0],
    [   4,  -17,  100,   52,  -14,    3,    0,    0],
    [   4,  -18,   98,   55,  -15,    4,    0,    0],
    [   4,  -18,   96,   58,  -15,    3,    0,    0],
    [   4,  -18,   94,   60,  -16,    4,    0,    0],
    [   4,  -18,   91,   63,  -16,    4,    0,    0],
    [   4,  -18,   89,   65,  -16,    4,    0,    0],
    [   4,  -18,   87,   68,  -17,    4,    0,    0],
    [   4,  -18,   85,   70,  -17,    4,    0,    0],
    [   4,  -18,   82,   73,  -17,    4,    0,    0],
    [   4,  -18,   80,   75,  -17,    4,    0,    0],
    [   4,  -18,   78,   78,  -18,    4,    0,    0],
    [   4,  -17,   75,   80,  -18,    4,    0,    0],
    [   4,  -17,   73,   82,  -18,    4,    0,    0],
    [   4,  -17,   70,   85,  -18,    4,    0,    0],
    [   4,  -17,   68,   87,  -18,    4,    0,    0],
    [   4,  -16,   65,   89,  -18,    4,    0,    0],
    [   4,  -16,   63,   91,  -18,    4,    0,    0],
    [   4,  -16,   60,   94,  -18,    4,    0,    0],
    [   3,  -15,   58,   96,  -18,    4,    0,    0],
    [   4,  -15,   55,   98,  -18,    4,    0,    0],
    [   3,  -14,   52,  100,  -17,    4,    0,    0],
    [   3,  -14,   50,  102,  -17,    4,    0,    0],
    [   3,  -13,   47,  104,  -17,    4,    0,    0],
    [   3,  -13,   45,  106,  -17,    4,    0,    0],
    [   3,  -12,   42,  108,  -16,    3,    0,    0],
    [   3,  -11,   40,  109,  -16,    3,    0,    0],
    [   3,  -11,   37,  111,  -15,    3,    0,    0],
    [   2,  -10,   35,  113,  -15,    3,    0,    0],
    [   3,  -10,   32,  114,  -14,    3,    0,    0],
    [   2,   -9,   29,  116,  -13,    3,    0,    0],
    [   2,   -8,   27,  117,  -13,    3,    0,    0],
    [   2,   -8,   25,  119,  -12,    2,    0,    0],
    [   2,   -7,   22,  120,  -11,    2,    0,    0],
    [   1,   -6,   20,  121,  -10,    2,    0,    0],
    [   1,   -6,   18,  122,   -9,    2,    0,    0],
    [   1,   -5,   15,  123,   -8,    2,    0,    0],
    [   1,   -4,   13,  124,   -7,    1,    0,    0],
    [   1,   -4,   11,  125,   -6,    1,    0,    0],
    [   1,   -3,    8,  126,   -5,    1,    0,    0],
    [   1,   -2,    6,  126,   -4,    1,    0,    0],
    [   0,   -1,    4,  127,   -3,    1,    0,    0],
    [   0,    0,    2,  127,   -1,    0,    0,    0],
    [   0,    0,    0,  127,    1,    0,    0,    0],
    [   0,    0,   -1,  127,    2,    0,    0,    0],
    [   0,    1,   -3,  127,    4,   -2,    1,    0],
    [   0,    1,   -5,  127,    6,   -2,    1,    0],
    [   0,    2,   -6,  126,    8,   -3,    1,    0],
    [  -1,    2,   -7,  126,   11,   -4,    2,   -1],
    [  -1,    3,   -8,  125,   13,   -5,    2,   -1],
    [  -1,    3,  -10,  124,   16,   -6,    3,   -1],
    [  -1,    4,  -11,  123,   18,   -7,    3,   -1],
    [  -1,    4,  -12,  122,   20,   -7,    3,   -1],
    [  -1,    4,  -13,  121,   23,   -8,    3,   -1],
    [  -2,    5,  -14,  120,   25,   -9,    4,   -1],
    [  -1,    5,  -15,  119,   27,  -10,    4,   -1],
    [  -1,    5,  -16,  118,   30,  -11,    4,   -1],
    [  -2,    6,  -17,  116,   33,  -12,    5,   -1],
    [  -2,    6,  -17,  114,   35,  -12,    5,   -1],
    [  -2,    6,  -18,  113,   38,  -13,    5,   -1],
    [  -2,    7,  -19,  111,   41,  -14,    6,   -2],
    [  -2,    7,  -19,  110,   43,  -15,    6,   -2],
    [  -2,    7,  -20,  108,   46,  -15,    6,   -2],
    [  -2,    7,  -20,  106,   49,  -16,    6,   -2],
    [  -2,    7,  -21,  104,   51,  -16,    7,   -2],
    [  -2,    7,  -21,  102,   54,  -17,    7,   -2],
    [  -2,    8,  -21,  100,   56,  -18,    7,   -2],
    [  -2,    8,  -22,   98,   59,  -18,    7,   -2],
    [  -2,    8,  -22,   96,   62,  -19,    7,   -2],
    [  -2,    8,  -22,   94,   64,  -19,    7,   -2],
    [  -2,    8,  -22,   91,   67,  -20,    8,   -2],
    [  -2,    8,  -22,   89,   69,  -20,    8,   -2],
    [  -2,    8,  -22,   87,   72,  -21,    8,   -2],
    [  -2,    8,  -21,   84,   74,  -21,    8,   -2],
    [  -2,    8,  -22,   82,   77,  -21,    8,   -2],
    [  -2,    8,  -21,   79,   79,  -21,    8,   -2],
    [  -2,    8,  -21,   77,   82,  -22,    8,   -2],
    [  -2,    8,  -21,   74,   84,  -21,    8,   -2],
    [  -2,    8,  -21,   72,   87,  -22,    8,   -2],
    [  -2,    8,  -20,   69,   89,  -22,    8,   -2],
    [  -2,    8,  -20,   67,   91,  -22,    8,   -2],
    [  -2,    7,  -19,   64,   94,  -22,    8,   -2],
    [  -2,    7,  -19,   62,   96,  -22,    8,   -2],
    [  -2,    7,  -18,   59,   98,  -22,    8,   -2],
    [  -2,    7,  -18,   56,  100,  -21,    8,   -2],
    [  -2,    7,  -17,   54,  102,  -21,    7,   -2],
    [  -2,    7,  -16,   51,  104,  -21,    7,   -2],
    [  -2,    6,  -16,   49,  106,  -20,    7,   -2],
    [  -2,    6,  -15,   46,  108,  -20,    7,   -2],
    [  -2,    6,  -15,   43,  110,  -19,    7,   -2],
    [  -2,    6,  -14,   41,  111,  -19,    7,   -2],
    [  -1,    5,  -13,   38,  113,  -18,    6,   -2],
    [  -1,    5,  -12,   35,  114,  -17,    6,   -2],
    [  -1,    5,  -12,   33,  116,  -17,    6,   -2],
    [  -1,    4,  -11,   30,  118,  -16,    5,   -1],
    [  -1,    4,  -10,   27,  119,  -15,    5,   -1],
    [  -1,    4,   -9,   25,  120,  -14,    5,   -2],
    [  -1,    3,   -8,   23,  121,  -13,    4,   -1],
    [  -1,    3,   -7,   20,  122,  -12,    4,   -1],
    [  -1,    3,   -7,   18,  123,  -11,    4,   -1],
    [  -1,    3,   -6,   16,  124,  -10,    3,   -1],
    [  -1,    2,   -5,   13,  125,   -8,    3,   -1],
    [  -1,    2,   -4,   11,  126,   -7,    2,   -1],
    [   0,    1,   -3,    8,  126,   -6,    2,    0],
    [   0,    1,   -2,    6,  127,   -5,    1,    0],
    [   0,    1,   -2,    4,  127,   -3,    1,    0],
    [   0,    0,    0,    2,  127,   -1,    0,    0],
    [   0,    0,    0,    1,  127,    0,    0,    0],
    [   0,    0,    0,   -1,  127,    2,    0,    0],
    [   0,    0,    1,   -3,  127,    4,   -1,    0],
    [   0,    0,    1,   -4,  126,    6,   -2,    1],
    [   0,    0,    1,   -5,  126,    8,   -3,    1],
    [   0,    0,    1,   -6,  125,   11,   -4,    1],
    [   0,    0,    1,   -7,  124,   13,   -4,    1],
    [   0,    0,    2,   -8,  123,   15,   -5,    1],
    [   0,    0,    2,   -9,  122,   18,   -6,    1],
    [   0,    0,    2,  -10,  121,   20,   -6,    1],
    [   0,    0,    2,  -11,  120,   22,   -7,    2],
    [   0,    0,    2,  -12,  119,   25,   -8,    2],
    [   0,    0,    3,  -13,  117,   27,   -8,    2],
    [   0,    0,    3,  -13,  116,   29,   -9,    2],
    [   0,    0,    3,  -14,  114,   32,  -10,    3],
    [   0,    0,    3,  -15,  113,   35,  -10,    2],
    [   0,    0,    3,  -15,  111,   37,  -11,    3],
    [   0,    0,    3,  -16,  109,   40,  -11,    3],
    [   0,    0,    3,  -16,  108,   42,  -12,    3],
    [   0,    0,    4,  -17,  106,   45,  -13,    3],
    [   0,    0,    4,  -17,  104,   47,  -13,    3],
    [   0,    0,    4,  -17,  102,   50,  -14,    3],
    [   0,    0,    4,  -17,  100,   52,  -14,    3],
    [   0,    0,    4,  -18,   98,   55,  -15,    4],
    [   0,    0,    4,  -18,   96,   58,  -15,    3],
    [   0,    0,    4,  -18,   94,   60,  -16,    4],
    [   0,    0,    4,  -18,   91,   63,  -16,    4],
    [   0,    0,    4,  -18,   89,   65,  -16,    4],
    [   0,    0,    4,  -18,   87,   68,  -17,    4],
    [   0,    0,    4,  -18,   85,   70,  -17,    4],
    [   0,    0,    4,  -18,   82,   73,  -17,    4],
    [   0,    0,    4,  -18,   80,   75,  -17,    4],
    [   0,    0,    4,  -18,   78,   78,  -18,    4],
    [   0,    0,    4,  -17,   75,   80,  -18,    4],
    [   0,    0,    4,  -17,   73,   82,  -18,    4],
    [   0,    0,    4,  -17,   70,   85,  -18,    4],
    [   0,    0,    4,  -17,   68,   87,  -18,    4],
    [   0,    0,    4,  -16,   65,   89,  -18,    4],
    [   0,    0,    4,  -16,   63,   91,  -18,    4],
    [   0,    0,    4,  -16,   60,   94,  -18,    4],
    [   0,    0,    3,  -15,   58,   96,  -18,    4],
    [   0,    0,    4,  -15,   55,   98,  -18,    4],
    [   0,    0,    3,  -14,   52,  100,  -17,    4],
    [   0,    0,    3,  -14,   50,  102,  -17,    4],
    [   0,    0,    3,  -13,   47,  104,  -17,    4],
    [   0,    0,    3,  -13,   45,  106,  -17,    4],
    [   0,    0,    3,  -12,   42,  108,  -16,    3],
    [   0,    0,    3,  -11,   40,  109,  -16,    3],
    [   0,    0,    3,  -11,   37,  111,  -15,    3],
    [   0,    0,    2,  -10,   35,  113,  -15,    3],
    [   0,    0,    3,  -10,   32,  114,  -14,    3],
    [   0,    0,    2,   -9,   29,  116,  -13,    3],
    [   0,    0,    2,   -8,   27,  117,  -13,    3],
    [   0,    0,    2,   -8,   25,  119,  -12,    2],
    [   0,    0,    2,   -7,   22,  120,  -11,    2],
    [   0,    0,    1,   -6,   20,  121,  -10,    2],
    [   0,    0,    1,   -6,   18,  122,   -9,    2],
    [   0,    0,    1,   -5,   15,  123,   -8,    2],
    [   0,    0,    1,   -4,   13,  124,   -7,    1],
    [   0,    0,    1,   -4,   11,  125,   -6,    1],
    [   0,    0,    1,   -3,    8,  126,   -5,    1],
    [   0,    0,    1,   -2,    6,  126,   -4,    1],
    [   0,    0,    0,   -1,    4,  127,   -3,    1],
    [   0,    0,    0,    0,    2,  127,   -1,    0],
    [   0,    0,    0,    0,    2,  127,   -1,    0],
];

/// `Div_Lut[ DIV_LUT_NUM ]` (av1-spec p.272 lines 15117-15140) —
/// 257-entry inverse lookup table consumed by `resolve_divisor`.
/// Entries are unsigned 16-bit; `Div_Lut[0] = 16384 = 1 <<
/// DIV_LUT_PREC_BITS` represents the unit fraction at the smallest
/// non-zero index, and the table decays monotonically to
/// `Div_Lut[256] = 8192 = 1 << (DIV_LUT_PREC_BITS - 1)`.
#[rustfmt::skip]
pub const DIV_LUT: [i32; DIV_LUT_NUM] = [
    16384, 16320, 16257, 16194, 16132, 16070, 16009, 15948,
    15888, 15828, 15768, 15709, 15650, 15592, 15534, 15477,
    15420, 15364, 15308, 15252, 15197, 15142, 15087, 15033,
    14980, 14926, 14873, 14821, 14769, 14717, 14665, 14614,
    14564, 14513, 14463, 14413, 14364, 14315, 14266, 14218,
    14170, 14122, 14075, 14028, 13981, 13935, 13888, 13843,
    13797, 13752, 13707, 13662, 13618, 13574, 13530, 13487,
    13443, 13400, 13358, 13315, 13273, 13231, 13190, 13148,
    13107, 13066, 13026, 12985, 12945, 12906, 12866, 12827,
    12788, 12749, 12710, 12672, 12633, 12596, 12558, 12520,
    12483, 12446, 12409, 12373, 12336, 12300, 12264, 12228,
    12193, 12157, 12122, 12087, 12053, 12018, 11984, 11950,
    11916, 11882, 11848, 11815, 11782, 11749, 11716, 11683,
    11651, 11619, 11586, 11555, 11523, 11491, 11460, 11429,
    11398, 11367, 11336, 11305, 11275, 11245, 11215, 11185,
    11155, 11125, 11096, 11067, 11038, 11009, 10980, 10951,
    10923, 10894, 10866, 10838, 10810, 10782, 10755, 10727,
    10700, 10673, 10645, 10618, 10592, 10565, 10538, 10512,
    10486, 10460, 10434, 10408, 10382, 10356, 10331, 10305,
    10280, 10255, 10230, 10205, 10180, 10156, 10131, 10107,
    10082, 10058, 10034, 10010,  9986,  9963,  9939,  9916,
     9892,  9869,  9846,  9823,  9800,  9777,  9754,  9732,
     9709,  9687,  9664,  9642,  9620,  9598,  9576,  9554,
     9533,  9511,  9489,  9468,  9447,  9425,  9404,  9383,
     9362,  9341,  9321,  9300,  9279,  9259,  9239,  9218,
     9198,  9178,  9158,  9138,  9118,  9098,  9079,  9059,
     9039,  9020,  9001,  8981,  8962,  8943,  8924,  8905,
     8886,  8867,  8849,  8830,  8812,  8793,  8775,  8756,
     8738,  8720,  8702,  8684,  8666,  8648,  8630,  8613,
     8595,  8577,  8560,  8542,  8525,  8508,  8490,  8473,
     8456,  8439,  8422,  8405,  8389,  8372,  8355,  8339,
     8322,  8306,  8289,  8273,  8257,  8240,  8224,  8208,
     8192,
];

/// §7.11.3.7 output: `(divFactor, divShift)` — fixed-point
/// approximation of `1 / d` such that
/// `Round2Signed(v * divFactor, divShift) ≈ v / d`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Divisor {
    /// `divFactor` — fixed-point multiplier read out of [`DIV_LUT`].
    /// Negated when the input `d` is negative.
    pub div_factor: i32,
    /// `divShift = n + DIV_LUT_PREC_BITS` (right shift to apply after
    /// multiplying by [`Divisor::div_factor`]).
    pub div_shift: u32,
}

/// §7.11.3.7 (av1-spec p.271): derive `(divFactor, divShift)` for the
/// approximate division `v / d` consumed by §7.11.3.6 and §7.11.3.8.
///
/// Returns `None` when `d == 0` (caller-bug guard — the spec body is
/// only invoked after §7.11.3.8 has already checked `det != 0`, and
/// §7.11.3.6 is only invoked with `warpParams[2]` whose
/// implementation domain excludes zero).
///
/// Spec body:
///
/// ```text
///   n = FloorLog2(Abs(d))
///   e = Abs(d) - (1 << n)
///   if (n > DIV_LUT_BITS) f = Round2(e, n - DIV_LUT_BITS)
///   else                   f = e << (DIV_LUT_BITS - n)
///   divShift = n + DIV_LUT_PREC_BITS
///   divFactor = (d < 0) ? -Div_Lut[f] : Div_Lut[f]
/// ```
#[must_use]
pub fn resolve_divisor(d: i32) -> Option<Divisor> {
    if d == 0 {
        return None;
    }
    let abs_d: u32 = d.unsigned_abs();
    // §3 `FloorLog2(x) = floor(log2(x))` (av1-spec.txt line 1574).
    // `abs_d > 0` because `d != 0`, so `leading_zeros < 32`.
    let n: u32 = 31 - abs_d.leading_zeros();
    let e: i32 = (abs_d as i32) - (1i32 << n);
    let f: usize = if n > DIV_LUT_BITS {
        // Round2(e, n - DIV_LUT_BITS).
        let shift = n - DIV_LUT_BITS;
        (((e as i64) + (1i64 << (shift - 1))) >> shift) as usize
    } else {
        // e << (DIV_LUT_BITS - n).
        ((e as i64) << (DIV_LUT_BITS - n)) as usize
    };
    // f indexes [0, DIV_LUT_NUM); the §7.11.3.7 derivation guarantees
    // f <= 256. Defensive clamp keeps a buggy caller from indexing OOB.
    let f = f.min(DIV_LUT_NUM - 1);
    let factor = DIV_LUT[f];
    Some(Divisor {
        div_factor: if d < 0 { -factor } else { factor },
        div_shift: n + DIV_LUT_PREC_BITS,
    })
}

/// §7.11.3.6 output: the `(warpValid, alpha, beta, gamma, delta)` quad
/// the §7.11.3.5 `block_warp` invokes as its inner shear coefficients.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ShearParams {
    /// `warpValid` — `1` when the four-shear factorisation is well-
    /// conditioned per the §7.11.3.6 final two bounds, `0` otherwise.
    /// §7.11.3.5 only invokes `setup_shear` on warpParams the upstream
    /// §5.11.27 dispatcher already proved valid, but the bit is
    /// returned so callers can re-check.
    pub warp_valid: bool,
    /// `alpha` — horizontal shear of the warp matrix's `(2)` entry,
    /// reduced through `WARP_PARAM_REDUCE_BITS`.
    pub alpha: i32,
    /// `beta` — vertical shear coupling into the horizontal phase
    /// (the `(3)` entry, reduced).
    pub beta: i32,
    /// `gamma` — horizontal shear coupling into the vertical phase
    /// (derived from `warpParams[4]` × inverse of `warpParams[2]`).
    pub gamma: i32,
    /// `delta` — vertical shear of the warp matrix's `(5)` entry,
    /// reduced and with the `(warpParams[3] * warpParams[4])`
    /// cross-term subtracted.
    pub delta: i32,
}

/// §3 `Clip3(low, high, v)` for `i32` — local re-export. (`clip3_i32`
/// in this module is private; the warp body reuses it.)
#[inline]
fn warp_clip3_i32(low: i32, high: i32, v: i32) -> i32 {
    if v < low {
        low
    } else if v > high {
        high
    } else {
        v
    }
}

/// §7.11.3.6 (av1-spec p.270-271): derive the shear quadruple
/// `(alpha, beta, gamma, delta)` plus the `warpValid` bit from a
/// 6-element `warpParams` matrix.
///
/// `warp_params` is the row-major `[a0, a1, a2, a3, a4, a5]` matrix
/// per the §5.11.x storage convention — `a0` / `a1` are translation,
/// `a2` / `a5` are the on-diagonal affine entries (with `1 <<
/// WARPEDMODEL_PREC_BITS` as the identity offset), `a3` / `a4` are
/// the off-diagonal affine entries.
///
/// Spec body:
///
/// ```text
///   alpha0 = Clip3(-32768, 32767, warpParams[2] - (1 << 16))
///   beta0  = Clip3(-32768, 32767, warpParams[3])
///   (divFactor, divShift) = resolve_divisor(warpParams[2])
///   v = warpParams[4] << 16
///   gamma0 = Clip3(-32768, 32767, Round2Signed(v * divFactor, divShift))
///   w = warpParams[3] * warpParams[4]
///   delta0 = Clip3(-32768, 32767,
///                  warpParams[5] - Round2Signed(w * divFactor, divShift) - (1 << 16))
///   {alpha,beta,gamma,delta} = Round2Signed(_0, 6) << 6
///   warpValid = 1 unless
///     4*|alpha| + 7*|beta|  >= 1<<16  or
///     4*|gamma| + 4*|delta| >= 1<<16
/// ```
///
/// Returns `None` when `warpParams[2] == 0` (caller-bug — divisor
/// fails). The spec ordering of the validity check is honoured:
/// `warp_valid = false` propagates back to §7.11.3.5 callers that
/// want to bail.
#[must_use]
pub fn setup_shear(warp_params: [i32; 6]) -> Option<ShearParams> {
    let alpha0 = warp_clip3_i32(
        -32_768,
        32_767,
        warp_params[2] - (1i32 << WARP_WARPEDMODEL_PREC_BITS),
    );
    let beta0 = warp_clip3_i32(-32_768, 32_767, warp_params[3]);

    let div = resolve_divisor(warp_params[2])?;
    let v: i64 = (warp_params[4] as i64) << WARP_WARPEDMODEL_PREC_BITS;
    let gamma_raw = round2_signed(v.saturating_mul(div.div_factor as i64), div.div_shift) as i32;
    let gamma0 = warp_clip3_i32(-32_768, 32_767, gamma_raw);

    let w: i64 = (warp_params[3] as i64) * (warp_params[4] as i64);
    let delta_correction =
        round2_signed(w.saturating_mul(div.div_factor as i64), div.div_shift) as i32;
    let delta_raw = warp_params[5]
        .wrapping_sub(delta_correction)
        .wrapping_sub(1i32 << WARP_WARPEDMODEL_PREC_BITS);
    let delta0 = warp_clip3_i32(-32_768, 32_767, delta_raw);

    let reduce = |x: i32| -> i32 {
        (round2_signed(x as i64, WARP_PARAM_REDUCE_BITS) as i32) << WARP_PARAM_REDUCE_BITS
    };
    let alpha = reduce(alpha0);
    let beta = reduce(beta0);
    let gamma = reduce(gamma0);
    let delta = reduce(delta0);

    // §7.11.3.6 final bound — the two-shear factorisation is only
    // valid when the off-axis combination stays under `(1 << 16)`.
    let bound = 1i32 << WARP_WARPEDMODEL_PREC_BITS;
    let warp_valid =
        4 * alpha.abs() + 7 * beta.abs() < bound && 4 * gamma.abs() + 4 * delta.abs() < bound;

    Some(ShearParams {
        warp_valid,
        alpha,
        beta,
        gamma,
        delta,
    })
}

/// `LEAST_SQUARES_SAMPLES_MAX = 8` (av1-spec p.18 line 1207) — upper
/// bound on the §7.10.4 `CandList` length consumed by §7.11.3.8.
pub const LEAST_SQUARES_SAMPLES_MAX: usize = 8;

/// §7.11.3.8 input candidate: a single `(sy, sx, dy, dx)` quad from
/// the §7.10.4 `CandList` (source y / x = neighbour position, dest y
/// / x = neighbour position + neighbour MV in 1/8-sample precision).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct WarpSampleCand {
    /// `CandList[i][0]` — source y in 1/8-sample units.
    pub sy: i32,
    /// `CandList[i][1]` — source x in 1/8-sample units.
    pub sx: i32,
    /// `CandList[i][2]` — destination y in 1/8-sample units.
    pub dy: i32,
    /// `CandList[i][3]` — destination x in 1/8-sample units.
    pub dx: i32,
}

/// §7.11.3.8 output: the `(LocalValid, LocalWarpParams)` pair the
/// §5.11.27 dispatcher consults before flipping to the LOCALWARP arm.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct LocalWarp {
    /// `LocalValid` — `false` when `det == 0` (degenerate fit).
    pub local_valid: bool,
    /// `LocalWarpParams[0..6]` — the affine model derived from the
    /// least-squares fit. Only meaningful when `local_valid == true`.
    pub local_warp_params: [i32; 6],
}

/// §3 `ls_product(a, b) = ((a * b) >> 2) + (a + b)` (av1-spec p.273
/// line 15194). The §7.11.3.8 accumulator helper.
#[inline]
fn ls_product(a: i32, b: i32) -> i64 {
    (((a as i64) * (b as i64)) >> 2) + (a as i64) + (b as i64)
}

/// §7.11.3.8 (av1-spec p.273-274): least-squares-fit `LocalWarpParams`
/// from a list of `(sy, sx, dy, dx)` candidates produced by the
/// §7.10.4 `find_warp_samples` walker.
///
/// ## Arguments
///
/// * `cand_list` — slice of [`WarpSampleCand`], length `NumSamples`
///   (`<= LEAST_SQUARES_SAMPLES_MAX = 8`).
/// * `mi_row` / `mi_col` — current-block §5.11.4 4×4-MI grid position.
/// * `block_w4` / `block_h4` — current-block size in 4×4 units
///   (`Num_4x4_Blocks_Wide[MiSize]` / `Num_4x4_Blocks_High[MiSize]`).
/// * `mv` — current-block `Mv[0]` (`[row, col]` in 1/8-sample units).
///
/// ## Returns
///
/// A [`LocalWarp`] with `local_valid == false` when the matrix `A`'s
/// determinant is zero (degenerate fit; §5.11.27 forces the
/// dispatcher's `motion_mode` decision elsewhere in that case).
#[allow(clippy::too_many_arguments)]
#[must_use]
pub fn warp_estimation(
    cand_list: &[WarpSampleCand],
    mi_row: i32,
    mi_col: i32,
    block_w4: i32,
    block_h4: i32,
    mv: [i16; 2],
) -> LocalWarp {
    // The cand list is bounded by the §7.10.4 add_sample cap; a
    // longer slice is harmless to walk but is a caller bug — silently
    // truncate to the documented bound.
    let n = cand_list.len().min(LEAST_SQUARES_SAMPLES_MAX);
    let cand = &cand_list[..n];

    // §7.11.3.8 midpoint & translation origin.
    let mid_y: i32 = mi_row * 4 + block_h4 * 2 - 1;
    let mid_x: i32 = mi_col * 4 + block_w4 * 2 - 1;
    let suy: i32 = mid_y * 8;
    let sux: i32 = mid_x * 8;
    let duy: i32 = suy.wrapping_add(mv[0] as i32);
    let dux: i32 = sux.wrapping_add(mv[1] as i32);

    // Accumulators — i64 because each `ls_product` term can hit
    // ~`LS_MV_MAX^2 / 4 = 16384`, summed over up to 8 cands plus the
    // `+8` / `+4` per-iteration bias.
    let mut a00: i64 = 0;
    let mut a01: i64 = 0;
    let mut a11: i64 = 0;
    let mut bx0: i64 = 0;
    let mut bx1: i64 = 0;
    let mut by0: i64 = 0;
    let mut by1: i64 = 0;

    for c in cand {
        let sy = c.sy.wrapping_sub(suy);
        let sx = c.sx.wrapping_sub(sux);
        let dy = c.dy.wrapping_sub(duy);
        let dx = c.dx.wrapping_sub(dux);
        if (sx - dx).abs() < LS_MV_MAX && (sy - dy).abs() < LS_MV_MAX {
            a00 += ls_product(sx, sx) + 8;
            a01 += ls_product(sx, sy) + 4;
            a11 += ls_product(sy, sy) + 8;
            bx0 += ls_product(sx, dx) + 8;
            bx1 += ls_product(sy, dx) + 4;
            by0 += ls_product(sx, dy) + 4;
            by1 += ls_product(sy, dy) + 8;
        }
    }

    // §7.11.3.8 det = A[0][0] * A[1][1] - A[0][1]^2.
    let det: i64 = a00.saturating_mul(a11) - a01.saturating_mul(a01);

    if det == 0 {
        return LocalWarp {
            local_valid: false,
            local_warp_params: [0; 6],
        };
    }
    // det fits in i64; truncating to i32 follows the spec's
    // `resolve_divisor` signature (`d` is the spec's `int` type;
    // implementations clamp to i32 silently because the §7.10.4
    // candidate count + LS_MV_MAX cap bound `|det|` below `2^62`,
    // but the divisor body itself only consumes `FloorLog2(Abs(d))`).
    // Use i64 path for the divisor body to honour the spec literally
    // without losing precision.
    let abs_det: u64 = det.unsigned_abs();
    let n_bits: u32 = 63 - abs_det.leading_zeros();
    let e: i64 = (abs_det as i64) - (1i64 << n_bits);
    let f: usize = if n_bits > DIV_LUT_BITS {
        let shift = n_bits - DIV_LUT_BITS;
        let half = 1i64 << (shift - 1);
        ((e + half) >> shift) as usize
    } else {
        (e << (DIV_LUT_BITS - n_bits)) as usize
    };
    let f = f.min(DIV_LUT_NUM - 1);
    let mut div_factor: i64 = DIV_LUT[f] as i64;
    if det < 0 {
        div_factor = -div_factor;
    }
    let mut div_shift: i32 = (n_bits + DIV_LUT_PREC_BITS) as i32;

    // §7.11.3.8 divShift adjustment for the `WARPEDMODEL_PREC_BITS`
    // headroom built into the diag/nondiag clamps.
    div_shift -= WARP_WARPEDMODEL_PREC_BITS as i32;
    if div_shift < 0 {
        div_factor <<= (-div_shift) as u32;
        div_shift = 0;
    }
    let div_shift_u: u32 = div_shift as u32;

    let nondiag_clamp_lo = -WARPEDMODEL_NONDIAGAFFINE_CLAMP + 1;
    let nondiag_clamp_hi = WARPEDMODEL_NONDIAGAFFINE_CLAMP - 1;
    let diag_one: i32 = 1i32 << WARP_WARPEDMODEL_PREC_BITS;
    let diag_clamp_lo = diag_one - WARPEDMODEL_NONDIAGAFFINE_CLAMP + 1;
    let diag_clamp_hi = diag_one + WARPEDMODEL_NONDIAGAFFINE_CLAMP - 1;

    let diag = |v: i64| -> i32 {
        let raw = round2_signed(v.saturating_mul(div_factor), div_shift_u);
        warp_clip3_i32(diag_clamp_lo, diag_clamp_hi, raw as i32)
    };
    let nondiag = |v: i64| -> i32 {
        let raw = round2_signed(v.saturating_mul(div_factor), div_shift_u);
        warp_clip3_i32(nondiag_clamp_lo, nondiag_clamp_hi, raw as i32)
    };

    let mut params = [0i32; 6];
    params[2] = diag(a11 * bx0 - a01 * bx1);
    params[3] = nondiag(-a01 * bx0 + a00 * bx1);
    params[4] = nondiag(a11 * by0 - a01 * by1);
    params[5] = diag(-a01 * by0 + a00 * by1);

    let mvx: i32 = mv[1] as i32;
    let mvy: i32 = mv[0] as i32;
    let shift_3: u32 = WARP_WARPEDMODEL_PREC_BITS - 3;
    let vx: i64 = (mvx as i64) * (1i64 << shift_3)
        - ((mid_x as i64) * ((params[2] - diag_one) as i64) + (mid_y as i64) * (params[3] as i64));
    let vy: i64 = (mvy as i64) * (1i64 << shift_3)
        - ((mid_x as i64) * (params[4] as i64) + (mid_y as i64) * ((params[5] - diag_one) as i64));
    let vx_clamped = if vx < -(WARPEDMODEL_TRANS_CLAMP as i64) {
        -WARPEDMODEL_TRANS_CLAMP
    } else if vx > (WARPEDMODEL_TRANS_CLAMP as i64) - 1 {
        WARPEDMODEL_TRANS_CLAMP - 1
    } else {
        vx as i32
    };
    let vy_clamped = if vy < -(WARPEDMODEL_TRANS_CLAMP as i64) {
        -WARPEDMODEL_TRANS_CLAMP
    } else if vy > (WARPEDMODEL_TRANS_CLAMP as i64) - 1 {
        WARPEDMODEL_TRANS_CLAMP - 1
    } else {
        vy as i32
    };
    params[0] = vx_clamped;
    params[1] = vy_clamped;

    LocalWarp {
        local_valid: true,
        local_warp_params: params,
    }
}

/// §7.11.3.5 `useWarp` value indicating LOCALWARP — the warp matrix
/// is the per-block `LocalWarpParams` derived by §7.11.3.8.
pub const USE_WARP_LOCAL: u8 = 1;
/// §7.11.3.5 `useWarp` value indicating GLOBAL_GLOBALMV — the warp
/// matrix is `gm_params[RefFrame[refList]]`.
pub const USE_WARP_GLOBAL: u8 = 2;

/// §7.11.3.5 (av1-spec p.266-270): apply the affine warp to a single
/// 8×8 sub-section of the prediction block (clipped to the residual
/// area `(w - j8*8, h - i8*8)`).
///
/// The §7.11.3.1 driver invokes this once per 8×8 sub-section of the
/// current block (`i8 in 0..h/8`, `j8 in 0..w/8`) and concatenates
/// the results into the full `pred` array.
///
/// ## Arguments
///
/// * `use_warp` — `USE_WARP_LOCAL` (1) or `USE_WARP_GLOBAL` (2). The
///   argument is preserved on the call surface even though both
///   branches consume the same `warp_params` matrix; callers use it
///   to select which matrix to pass.
/// * `plane` — 0 (luma), 1 (Cb), 2 (Cr) — drives the (subX, subY)
///   sub-sampling for the (lastX, lastY, srcX, srcY) derivation.
/// * `subsampling_x` / `subsampling_y` — §5.5.2 sub-sampling flags.
/// * `x` / `y` — top-left sample of the current block in the
///   current-frame plane grid.
/// * `i8b` / `j8b` — 8-sample offsets into the current block of the
///   sub-section being filled (`pred[i8b*8 + ...][j8b*8 + ...]`).
/// * `w` / `h` — current-block dimensions in samples.
/// * `ref_plane` — reference frame's sample grid for `plane`, row-
///   major.
/// * `ref_stride` — row stride of `ref_plane`.
/// * `ref_upscaled_width` / `ref_frame_height` — pre-sub-sample
///   dimensions of the reference frame (the §7.11.3.5 (lastX, lastY)
///   derivation re-applies the sub-sampling internally).
/// * `warp_params` — the 6-entry affine matrix (LocalWarpParams or
///   gm_params[refFrame] depending on use_warp).
/// * `inter_round0` / `inter_round1` — `RoundingVars` per §7.11.3.2.
/// * `pred_stride` — row stride of the `pred` output buffer (≥ w).
/// * `pred` — output buffer, row-major, length ≥ h * pred_stride.
///   `pred[(i8b*8 + i)*pred_stride + (j8b*8 + j)]` is written for
///   `i in 0..min(8, h - i8b*8)`, `j in 0..min(8, w - j8b*8)`.
///
/// ## Returns
///
/// `Ok(())` on success. Returns
/// [`crate::Error::PartitionWalkOutOfRange`] for caller-bug arguments
/// (plane > 2, subsampling > 1, ref dims = 0, w/h = 0, w/h > 128,
/// i8b*8 >= h, j8b*8 >= w, ref_stride < per-plane ref_upscaled_width,
/// pred_stride < w, pred too short, use_warp not in {1, 2}).
#[allow(clippy::too_many_arguments)]
pub fn block_warp(
    use_warp: u8,
    plane: u8,
    subsampling_x: u8,
    subsampling_y: u8,
    x: i32,
    y: i32,
    i8b: i32,
    j8b: i32,
    w: usize,
    h: usize,
    ref_plane: &[u16],
    ref_stride: usize,
    ref_upscaled_width: u32,
    ref_frame_height: u32,
    warp_params: [i32; 6],
    inter_round0: u32,
    inter_round1: u32,
    pred_stride: usize,
    pred: &mut [i32],
) -> Result<(), crate::Error> {
    if !matches!(use_warp, USE_WARP_LOCAL | USE_WARP_GLOBAL) {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if plane > 2 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if subsampling_x > 1 || subsampling_y > 1 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if w == 0 || h == 0 || w > 128 || h > 128 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if i8b < 0 || j8b < 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if (i8b as usize) * 8 >= h || (j8b as usize) * 8 >= w {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if ref_upscaled_width == 0 || ref_frame_height == 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if pred_stride < w {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if pred.len() < h * pred_stride {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    let sub_x: u32 = if plane == 0 { 0 } else { subsampling_x as u32 };
    let sub_y: u32 = if plane == 0 { 0 } else { subsampling_y as u32 };

    // §7.11.3.5 ref-plane bounds, sub-sampled.
    let last_x: i32 = (((ref_upscaled_width as i32) + (sub_x as i32)) >> sub_x) - 1;
    let last_y: i32 = (((ref_frame_height as i32) + (sub_y as i32)) >> sub_y) - 1;
    if (last_x as usize) >= ref_stride {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if ref_plane.len() < ((last_y as usize) + 1) * ref_stride {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    // §7.11.3.5 (srcX, srcY) in the luma grid then projected.
    let src_x: i32 = (x + j8b * 8 + 4) << sub_x;
    let src_y: i32 = (y + i8b * 8 + 4) << sub_y;

    let dst_x: i64 = (warp_params[2] as i64) * (src_x as i64)
        + (warp_params[3] as i64) * (src_y as i64)
        + (warp_params[0] as i64);
    let dst_y: i64 = (warp_params[4] as i64) * (src_x as i64)
        + (warp_params[5] as i64) * (src_y as i64)
        + (warp_params[1] as i64);

    let shear = setup_shear(warp_params).ok_or(crate::Error::PartitionWalkOutOfRange)?;
    let alpha = shear.alpha as i64;
    let beta = shear.beta as i64;
    let gamma = shear.gamma as i64;
    let delta = shear.delta as i64;

    // §7.11.3.5 (x4, y4, ix4, sx4, iy4, sy4) — per-plane sub-sampled
    // affine coordinate at the sub-section's centre.
    let prec_mask: i64 = (1i64 << WARP_WARPEDMODEL_PREC_BITS) - 1;
    let x4: i64 = dst_x >> (sub_x as i64);
    let y4: i64 = dst_y >> (sub_y as i64);
    let ix4: i32 = (x4 >> WARP_WARPEDMODEL_PREC_BITS) as i32;
    let sx4: i64 = x4 & prec_mask;
    let iy4: i32 = (y4 >> WARP_WARPEDMODEL_PREC_BITS) as i32;
    let sy4: i64 = y4 & prec_mask;

    // §7.11.3.5 horizontal pass — `intermediate[15][8]` for the
    // 15-row × 8-col sub-section needed by the vertical 8-tap.
    const INTER_ROWS: usize = 15;
    const INTER_COLS: usize = 8;
    let mut intermediate = [[0i32; INTER_COLS]; INTER_ROWS];

    for i1 in -7i32..8 {
        for i2 in -4i32..4 {
            let sx: i64 = sx4 + alpha * (i2 as i64) + beta * (i1 as i64);
            // §7.11.3.5 `offs = Round2(sx, WARPEDDIFF_PREC_BITS) +
            // WARPEDPIXEL_PREC_SHIFTS` — plain Round2 (the §3
            // arithmetic-shift form), NOT Round2Signed: for negative
            // `sx` the two differ by one, selecting the adjacent
            // filter phase (r408 fix — warp blocks whose shear walks
            // `sx` negative produced isolated ±1 sample diffs).
            let offs_signed: i64 =
                round2(sx, WARPEDDIFF_PREC_BITS) + (WARPEDPIXEL_PREC_SHIFTS as i64);
            // §7.11.3.5 filter-table index is non-negative in
            // well-formed inputs but a buggy caller could produce
            // an out-of-range index; clamp to keep the indexing safe.
            let offs = warp_clip3_i32(
                0,
                (WARPEDPIXEL_PREC_SHIFTS * 3) as i32,
                offs_signed.max(i32::MIN as i64).min(i32::MAX as i64) as i32,
            ) as usize;
            let ry = warp_clip3_i32(0, last_y, iy4 + i1) as usize;
            let base = ry * ref_stride;
            let mut s: i64 = 0;
            for (i3, coef) in WARPED_FILTERS[offs].iter().enumerate() {
                let rx = warp_clip3_i32(0, last_x, ix4 + i2 - 3 + (i3 as i32)) as usize;
                s += (*coef as i64) * (ref_plane[base + rx] as i64);
            }
            // §7.11.3.5 `intermediate[..] = Round2(s, InterRound0)` —
            // plain Round2 (negative sums round toward -∞ + carry).
            intermediate[(i1 + 7) as usize][(i2 + 4) as usize] = round2(s, inter_round0) as i32;
        }
    }

    // §7.11.3.5 vertical pass — write the (≤8×≤8) sub-section into
    // pred at offsets (i8b*8 + i1 + 4, j8b*8 + i2 + 4).
    let h_remaining: i32 = (h as i32) - i8b * 8 - 4;
    let w_remaining: i32 = (w as i32) - j8b * 8 - 4;
    let i_limit: i32 = h_remaining.min(4);
    let j_limit: i32 = w_remaining.min(4);

    for i1 in -4i32..i_limit {
        for i2 in -4i32..j_limit {
            let sy: i64 = sy4 + gamma * (i2 as i64) + delta * (i1 as i64);
            // §7.11.3.5: plain Round2, as on the horizontal pass.
            let offs_signed: i64 =
                round2(sy, WARPEDDIFF_PREC_BITS) + (WARPEDPIXEL_PREC_SHIFTS as i64);
            let offs = warp_clip3_i32(
                0,
                (WARPEDPIXEL_PREC_SHIFTS * 3) as i32,
                offs_signed.max(i32::MIN as i64).min(i32::MAX as i64) as i32,
            ) as usize;
            let mut s: i64 = 0;
            for (i3, coef) in WARPED_FILTERS[offs].iter().enumerate() {
                let inter_row = (i1 + (i3 as i32) + 4) as usize;
                // The (i1 + i3 + 4) ∈ [0, 14] for i1 ∈ [-4, 3],
                // i3 ∈ [0, 7]. INTER_ROWS = 15 ⇒ always in-bounds.
                let v = intermediate[inter_row][(i2 + 4) as usize] as i64;
                s += (*coef as i64) * v;
            }
            let row = (i8b as usize) * 8 + (i1 + 4) as usize;
            let col = (j8b as usize) * 8 + (i2 + 4) as usize;
            // §7.11.3.5 `pred[..] = Round2(s, InterRound1)` — plain Round2.
            pred[row * pred_stride + col] = round2(s, inter_round1) as i32;
        }
    }

    Ok(())
}

// =====================================================================
// §7.11.3.9 + §7.11.3.10 — Overlapped Motion Compensation (av1-spec
// p.275-278).
// =====================================================================
//
// OBMC is the inter-prediction post-process that blends the
// translational MC output of the current block with translational MC
// outputs of its above-row and left-column neighbours, weighted by a
// raised-cosine `Obmc_Mask_*` table whose length matches the overlap
// extent (predH for the above-pass vertical fall-off, predW for the
// left-pass horizontal fall-off).
//
// The dispatcher gate is `motion_mode == OBMC` per §5.11.27
// (read_motion_mode, av1-spec p.190 lines 10511-10526); §7.11.2.x
// invokes §7.11.3.9 with `(plane, w, h)` only on that branch.
//
// This module provides:
//
// * [`OBMC_MASK_2`] / [`OBMC_MASK_4`] / [`OBMC_MASK_8`] /
//   [`OBMC_MASK_16`] / [`OBMC_MASK_32`] — the five blending-weight
//   tables transcribed verbatim from av1-spec p.277.
// * [`get_obmc_mask`] — the §7.11.3.9 spec dispatch returning the
//   `Obmc_Mask_N` slice for `N in {2, 4, 8, 16, 32}`.
// * [`overlap_blending`] — §7.11.3.10's pixel blend
//   `Round2( m * curr + (64 - m) * obmcPred, 6 )` with the `pass`-
//   driven mask-axis selection (pass = 0 ⇒ `m = mask[i]` for vertical
//   above-pass fall-off, pass = 1 ⇒ `m = mask[j]` for horizontal
//   left-pass fall-off).
// * [`OverlapPass`] — `Above` / `Left` enum for callers; the spec
//   encodes the same two values as `pass ∈ {0, 1}`.
// * [`overlap_neighbour_predict_blend`] — the §7.11.3.9 "predict_overlap"
//   inner loop: given a single neighbour candidate's translational MC
//   output (already formed via [`block_inter_prediction`] +
//   [`clip1_single_ref`]) and its `(predX, predY, predW, predH, pass)`
//   tuple, applies the `get_obmc_mask` selection and runs the
//   [`overlap_blending`] step against the in-place current-frame plane
//   buffer. This is the spec-direct entry point for the §7.11.3.9
//   above/left passes when the caller has already iterated the
//   neighbour mi-grid and run translational MC for the neighbour MV.
//
// The §7.11.3.9 outer driver (which iterates `x4 += step4` along the
// top row + `y4 += step4` down the left column, capped at
// `nLimit = Min(4, Mi_{Width,Height}_Log2[ MiSize ])`, and chooses
// `predW`/`predH` per `(MiSize, plane)`) is wired in r203 inside
// [`predict_inter`]'s OBMC post-step arm via the [`obmc_walk_axis`]
// per-axis helper. The walker consumes a caller-resolved
// [`ObmcParams`] context (above/left ordered neighbour lists +
// MiRow/MiCol/MiSize block context + AvailU/AvailL gates) so the
// driver does not have to re-enter the §5.11.x mi-grid state that
// is only partially modelled in `oxideav-av1`.

/// `Obmc_Mask_2[2]` — the 2-tap OBMC blending weight table for an
/// overlap extent of 2 samples (av1-spec p.277 line 15406). The
/// blending weights are in `0..=64` (matching §7.11.3.10's
/// `Round2( m * curr + (64 - m) * obmcPred, 6 )` divisor of
/// `1 << 6 = 64`).
pub const OBMC_MASK_2: [u8; 2] = [45, 64];

/// `Obmc_Mask_4[4]` — the 4-tap OBMC blending weight table for an
/// overlap extent of 4 samples (av1-spec p.277 line 15408).
pub const OBMC_MASK_4: [u8; 4] = [39, 50, 59, 64];

/// `Obmc_Mask_8[8]` — the 8-tap OBMC blending weight table for an
/// overlap extent of 8 samples (av1-spec p.277 line 15410).
pub const OBMC_MASK_8: [u8; 8] = [36, 42, 48, 53, 57, 61, 64, 64];

/// `Obmc_Mask_16[16]` — the 16-tap OBMC blending weight table for an
/// overlap extent of 16 samples (av1-spec p.277 lines 15412-15413).
pub const OBMC_MASK_16: [u8; 16] = [
    34, 37, 40, 43, 46, 49, 52, 54, 56, 58, 60, 61, 64, 64, 64, 64,
];

/// `Obmc_Mask_32[32]` — the 32-tap OBMC blending weight table for an
/// overlap extent of 32 samples (av1-spec p.277 lines 15415-15418).
pub const OBMC_MASK_32: [u8; 32] = [
    33, 35, 36, 38, 40, 41, 43, 44, 45, 47, 48, 50, 51, 52, 53, 55, 56, 57, 58, 59, 60, 60, 61, 62,
    64, 64, 64, 64, 64, 64, 64, 64,
];

/// §7.11.3.9 `get_obmc_mask(length)` (av1-spec p.276 lines 15381-15393).
///
/// Returns the OBMC blending weight slice whose length matches the
/// overlap extent. The spec defines five tables for
/// `length ∈ {2, 4, 8, 16, 32}`; for any other length the spec's
/// `else` branch returns `Obmc_Mask_32`, so `length` values outside
/// the table set (e.g. `length = 1` or `length > 32`) fall through to
/// the 32-tap table.
///
/// In practice the §7.11.3.9 driver always calls this with
/// `length ∈ {min(h >> 1, 32 >> subY), min(w >> 1, 32 >> subX)}`,
/// which for the block sizes that admit OBMC
/// (Mi_{Width,Height}_Log2 ≥ 1, i.e. ≥ BLOCK_8X8) and the supported
/// chroma subsamplings always lands on `{2, 4, 8, 16, 32}`.
pub fn get_obmc_mask(length: usize) -> &'static [u8] {
    if length == 2 {
        &OBMC_MASK_2
    } else if length == 4 {
        &OBMC_MASK_4
    } else if length == 8 {
        &OBMC_MASK_8
    } else if length == 16 {
        &OBMC_MASK_16
    } else {
        &OBMC_MASK_32
    }
}

/// §7.11.3.9 `pass` parameter encoded as an enum.
///
/// `pass = 0` (`Above`) means the neighbour MV is from the above row,
/// the fall-off is vertical, and §7.11.3.10's `m` is `mask[i]` (row
/// index).
///
/// `pass = 1` (`Left`) means the neighbour MV is from the left
/// column, the fall-off is horizontal, and §7.11.3.10's `m` is
/// `mask[j]` (col index).
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum OverlapPass {
    /// Above-row neighbour (`pass = 0`); §7.11.3.10 uses `mask[i]`.
    Above,
    /// Left-column neighbour (`pass = 1`); §7.11.3.10 uses `mask[j]`.
    Left,
}

/// §7.11.3.10 (av1-spec p.277-278): the overlap-blending pixel kernel.
///
/// For `i in 0..predH`, `j in 0..predW`:
///
/// 1. `m` is selected from `mask` per `pass` (av1-spec p.278 lines
///    15442-15446):
///    * `pass == Above` (= spec `pass == 0`) ⇒ `m = mask[i]`.
///    * `pass == Left`  (= spec `pass == 1`) ⇒ `m = mask[j]`.
/// 2. `CurrFrame[plane][predY + i][predX + j]` is set to
///    `Round2( m * CurrFrame[plane][predY + i][predX + j]
///             + (64 - m) * obmc_pred[i][j], 6 )` (av1-spec p.278
///    lines 15448-15449).
///
/// The shift by 6 follows from the `Obmc_Mask_*` weights being in
/// `0..=64` so `m + (64 - m) = 64 = 1 << 6`.
///
/// ## Arguments
///
/// * `current_plane` — the current frame's plane samples, row-major;
///   `current_plane[(pred_y + i) * curr_stride + (pred_x + j)]` is
///   read and written in place for the blended region. `u16` matches
///   the §7.11.3.4 / §7.11.3.5 output domain (any of 8/10/12-bit
///   content fits in `u16`).
/// * `curr_stride` — row stride of `current_plane` in samples.
/// * `pred_x` / `pred_y` — top-left sample of the overlap region in
///   the `current_plane` grid (§7.11.3.9 step-3/4 `predX` / `predY`).
/// * `pred_w` / `pred_h` — width / height of the overlap region in
///   samples.
/// * `pass` — `Above` or `Left` per §7.11.3.10.
/// * `obmc_pred` — the neighbour-MV prediction samples for the overlap
///   region, row-major; `obmc_pred[i * obmc_stride + j]` is read for
///   `i in 0..pred_h`, `j in 0..pred_w`. These should be the output
///   of [`block_inter_prediction`] + [`clip1_single_ref`] (i.e. the
///   `Clip1` step at av1-spec p.276 line 15373 — predict_overlap
///   step 7).
/// * `obmc_stride` — row stride of `obmc_pred` (≥ `pred_w`).
/// * `mask` — the §7.11.3.9 `get_obmc_mask` output slice. `mask.len()`
///   must be `>= pred_h` when `pass == Above`, `>= pred_w` when
///   `pass == Left`.
///
/// ## Returns
///
/// `Ok(())` on success. Returns
/// [`crate::Error::PartitionWalkOutOfRange`] for caller-bug arguments:
/// `pred_w == 0`, `pred_h == 0`, `obmc_stride < pred_w`,
/// `curr_stride < pred_x + pred_w`, `obmc_pred` shorter than
/// `pred_h * obmc_stride`, `current_plane` shorter than
/// `(pred_y + pred_h) * curr_stride`, or `mask` shorter than the
/// pass-axis length (`pred_h` for `Above`, `pred_w` for `Left`).
#[allow(clippy::too_many_arguments)]
pub fn overlap_blending(
    current_plane: &mut [u16],
    curr_stride: usize,
    pred_x: usize,
    pred_y: usize,
    pred_w: usize,
    pred_h: usize,
    pass: OverlapPass,
    obmc_pred: &[u16],
    obmc_stride: usize,
    mask: &[u8],
) -> Result<(), crate::Error> {
    // ---------- caller-bug guards ----------
    if pred_w == 0 || pred_h == 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if obmc_stride < pred_w {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if curr_stride < pred_x.saturating_add(pred_w) {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    if obmc_pred.len() < pred_h * obmc_stride {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let needed_curr_rows = pred_y.saturating_add(pred_h);
    if current_plane.len() < needed_curr_rows.saturating_mul(curr_stride) {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let mask_axis_len = match pass {
        OverlapPass::Above => pred_h,
        OverlapPass::Left => pred_w,
    };
    if mask.len() < mask_axis_len {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    // ---------- §7.11.3.10 inner loop ----------
    //
    //   for i in 0..predH:
    //     for j in 0..predW:
    //       if pass == 0: m = mask[i]
    //       else:         m = mask[j]
    //       CurrFrame[plane][predY+i][predX+j] =
    //           Round2( m * CurrFrame[plane][predY+i][predX+j]
    //                   + (64 - m) * obmcPred[i][j], 6 )
    //
    // (av1-spec p.278 lines 15440-15449.)
    //
    // Split the pass match outside the inner loop: in the Above-pass
    // `m` only depends on `i` so it stays constant across `j`; in the
    // Left-pass `m` only depends on `j` so it's resolved per-column.
    match pass {
        OverlapPass::Above => {
            for (i, &mi) in mask.iter().enumerate().take(pred_h) {
                let m: u32 = mi as u32;
                let curr_row_base = (pred_y + i) * curr_stride;
                let obmc_row_base = i * obmc_stride;
                for j in 0..pred_w {
                    let curr_idx = curr_row_base + pred_x + j;
                    let obmc_idx = obmc_row_base + j;
                    let curr_sample = current_plane[curr_idx] as u32;
                    let obmc_sample = obmc_pred[obmc_idx] as u32;
                    // m ∈ [0, 64] so `64 - m` is non-negative; product
                    // fits in u32 for any bit depth ≤ 14 (64 * (1<<14)
                    // = 1<<20).
                    let blended = m * curr_sample + (64 - m) * obmc_sample;
                    // Round2(blended, 6) = (blended + (1 << 5)) >> 6.
                    current_plane[curr_idx] = ((blended + (1u32 << 5)) >> 6) as u16;
                }
            }
        }
        OverlapPass::Left => {
            for i in 0..pred_h {
                let curr_row_base = (pred_y + i) * curr_stride;
                let obmc_row_base = i * obmc_stride;
                for (j, &mj) in mask.iter().enumerate().take(pred_w) {
                    let m: u32 = mj as u32;
                    let curr_idx = curr_row_base + pred_x + j;
                    let obmc_idx = obmc_row_base + j;
                    let curr_sample = current_plane[curr_idx] as u32;
                    let obmc_sample = obmc_pred[obmc_idx] as u32;
                    let blended = m * curr_sample + (64 - m) * obmc_sample;
                    current_plane[curr_idx] = ((blended + (1u32 << 5)) >> 6) as u16;
                }
            }
        }
    }

    Ok(())
}

/// §7.11.3.9 `predict_overlap` step 8 wrapper (av1-spec p.276 lines
/// 15375-15376).
///
/// Wraps the [`get_obmc_mask`] → [`overlap_blending`] pipeline that
/// the spec's `predict_overlap` invokes once it has formed the
/// `obmcPred[i][j]` array for a single neighbour candidate. Callers
/// must:
///
/// 1. Have iterated the neighbour mi-grid (above row for `pass ==
///    Above`, left column for `pass == Left`) and chosen the candidate
///    cell `(candRow, candCol)` whose `RefFrames[..][0] > INTRA_FRAME`.
/// 2. Have formed `obmc_pred` via [`block_inter_prediction`] (with
///    the candidate's `Mvs[candRow][candCol][0]` and
///    `ref_frame_idx[..]`) followed by [`clip1_single_ref`] (the spec
///    explicitly applies `Clip1` at step 7 of `predict_overlap`).
/// 3. Have derived `(pred_x, pred_y, pred_w, pred_h)` per §7.11.3.9
///    `(x4, y4, step4)` walk:
///       * `predX = (x4 * 4) >> subX`
///       * `predY = (y4 * 4) >> subY`
///       * For `pass == Above`: `predW = min(w, (step4 * MI_SIZE) >>
///         subX)`, `predH = min(h >> 1, 32 >> subY)`,
///         `mask_length = predH`.
///       * For `pass == Left`: `predW = min(w >> 1, 32 >> subX)`,
///         `predH = min(h, (step4 * MI_SIZE) >> subY)`,
///         `mask_length = predW`.
///
/// The §7.11.3.9 outer mi-grid walk + the per-candidate step 1-7
/// translational MC are driven from [`predict_inter`]'s OBMC post-
/// step arm via the module-private `obmc_walk_axis` helper (r203);
/// see [`ObmcParams`] for the caller-resolved context bundle.
///
/// ## Arguments
///
/// Same as [`overlap_blending`], except `mask_length` is supplied
/// separately so the helper performs the [`get_obmc_mask`] lookup
/// itself (the spec applies the lookup inside `predict_overlap`'s
/// outer loop, not inside the inner blend).
///
/// ## Returns
///
/// `Ok(())` on success. Returns
/// [`crate::Error::PartitionWalkOutOfRange`] for the same caller-bug
/// conditions as [`overlap_blending`].
#[allow(clippy::too_many_arguments)]
pub fn overlap_neighbour_predict_blend(
    current_plane: &mut [u16],
    curr_stride: usize,
    pred_x: usize,
    pred_y: usize,
    pred_w: usize,
    pred_h: usize,
    pass: OverlapPass,
    obmc_pred: &[u16],
    obmc_stride: usize,
    mask_length: usize,
) -> Result<(), crate::Error> {
    let mask = get_obmc_mask(mask_length);
    overlap_blending(
        current_plane,
        curr_stride,
        pred_x,
        pred_y,
        pred_w,
        pred_h,
        pass,
        obmc_pred,
        obmc_stride,
        mask,
    )
}

// =====================================================================
// §7.11.3.1 — mode-info → CurrFrame reconstruction driver.
// =====================================================================
//
// `predict_inter` (above) closes the §7.11.3.1 prediction *arithmetic*:
// given a fully-resolved `PredictInterRef` (the spec's `RefFrames[
// candRow][candCol][refList]` already mapped to a per-plane sample
// buffer) it produces the `w × h` motion-compensated block into a
// caller-supplied scratch buffer. Two pieces of the §7.11.3 invocation
// context were left to "the walker" (see the module note at the head
// of this file, av1-spec p.258 line 14402):
//
//   1. §7.11.3.1 step 5 / §7.11.3.3 ref resolution — `refIdx =
//      ref_frame_idx[ refFrame - LAST_FRAME ]`, `ref = FrameStore[
//      refIdx ]` (av1-spec p.252 line 4942 / p.274 line 14812). The
//      decoded mode-info carries `RefFrame[refList]` as a small index
//      (`LAST_FRAME`..`ALTREF_FRAME`); the actual sample buffer lives
//      in the per-`refIdx` frame store.
//   2. The §7.11.3.1 final step `CurrFrame[plane][y+i][x+j] =
//      Clip1(preds[0][i][j])` (av1-spec p.258 line 14402) — stitching
//      the predicted block into the reconstructed plane at its plane
//      coordinates.
//
// `reconstruct_inter_block` composes both around `predict_inter` for
// the single forward-reference translational SIMPLE arm, so a caller
// holding decoded mode-info (`ref_frame` + `mv`) plus a frame store
// can drive an end-to-end block reconstruction without re-deriving the
// ref-buffer indirection or the CurrFrame merge by hand.

/// §7.11.3.1 single forward-reference mode-info descriptor — the
/// decoded `(RefFrame[0], Mvs[..][0])` pair the §7.11.3 inter
/// prediction process consumes for a translational SIMPLE block.
///
/// `ref_frame` is the spec's `RefFrame[ 0 ]` index in
/// `LAST_FRAME..=ALTREF_FRAME` (1..=7); `INTRA_FRAME` (0) is rejected
/// by [`reconstruct_inter_block`] since this driver is the inter arm.
/// `mv` is `Mvs[ candRow ][ candCol ][ 0 ]` in 1/8-luma-sample units,
/// laid out `[mv_row, mv_col]` per §5.11.
#[derive(Debug, Clone, Copy)]
pub struct InterModeInfo {
    /// §7.11.3.1 step 5 `RefFrame[ 0 ]` (1..=7, i.e.
    /// `LAST_FRAME..=ALTREF_FRAME`).
    pub ref_frame: u8,
    /// §7.11.3.1 step 8 `Mvs[ candRow ][ candCol ][ 0 ]` in
    /// 1/8-luma-sample units, `[mv_row, mv_col]`.
    pub mv: [i16; 2],
}

/// §7.11.3.3 per-`refIdx` reference-frame entry — one slot of the
/// decoder's `FrameStore`, with its dimensions already resolved to the
/// `(plane, subsampling_*)` the [`reconstruct_inter_block`] call is
/// being run for (the caller does the per-plane `>> subX` / `>> subY`
/// the same way [`PredictInterRef`] documents).
#[derive(Debug, Clone, Copy)]
pub struct RefFrameStoreEntry<'a> {
    /// `FrameStore[ refIdx ]` plane samples (row-major, `stride`
    /// columns).
    pub plane: &'a [u16],
    /// Column stride of `plane` (`>=` the PER-PLANE width — the
    /// stride stays in this plane's own sample units).
    pub stride: usize,
    /// §7.11.3.3 `RefUpscaledWidth[ refIdx ]` (LUMA samples — r405:
    /// the §7.11.3.3 scale ratio and the §7.11.3.4 / §7.11.3.5 clamps
    /// all take the luma extents and derive per-plane internally).
    pub upscaled_width: u32,
    /// §7.11.3.3 `RefFrameWidth[ refIdx ]` (LUMA samples).
    pub width: u32,
    /// §7.11.3.3 `RefFrameHeight[ refIdx ]` (LUMA samples).
    pub height: u32,
}

/// §7.11.3.1 single forward-reference translational reconstruction —
/// drives one decoded inter block from mode-info into a `CurrFrame`
/// plane.
///
/// This is the smallest end-to-end mode-info → reconstructed-plane
/// arc: it performs the §7.11.3.1 step-5 / §7.11.3.3 ref-buffer
/// resolution (`refIdx = ref_frame_idx[ ref_frame - LAST_FRAME ]`,
/// `ref = FrameStore[ refIdx ]`), runs [`predict_inter`] for the
/// SIMPLE single-ref translational arm (no warp / OBMC / compound /
/// inter-intra), then performs the §7.11.3.1 final step
/// `CurrFrame[plane][y+i][x+j] = Clip1(preds[0][i][j])` by copying the
/// predicted block into `curr_plane` at plane coordinates `(x, y)`.
///
/// Inputs (all from av1-spec §7.11.3):
///   * `mode_info` — decoded `(RefFrame[0], Mvs[..][0])`.
///   * `ref_frame_idx` — §6.8.2 `ref_frame_idx[ 0..REFS_PER_FRAME ]`
///     mapping each `RefFrame - LAST_FRAME` to a `FrameStore` slot.
///   * `frame_store` — the decoder's frame store, indexed by the
///     resolved `refIdx` (per-plane resolved, see
///     [`RefFrameStoreEntry`]).
///   * `(x, y, w, h)` — the §7.11.3.1 prediction region top-left and
///     size in `curr_plane` samples.
///   * `(plane, subsampling_x, subsampling_y, bit_depth, frame_width,
///     frame_height, interp_filter_x, interp_filter_y)` — the same
///     [`predict_inter`] context arguments.
///   * `curr_plane` / `curr_stride` — the `CurrFrame[plane]` buffer
///     and its column stride the predicted block is stitched into.
///
/// Returns [`crate::Error::PartitionWalkOutOfRange`] for caller-bug
/// arguments: an `INTRA_FRAME` (0) or out-of-range `ref_frame`, an
/// out-of-range resolved `refIdx`, a `curr_plane` too small for the
/// `(x, y, w, h)` write region, or anything [`predict_inter`] itself
/// rejects.
#[allow(clippy::too_many_arguments)]
pub fn reconstruct_inter_block(
    mode_info: InterModeInfo,
    ref_frame_idx: &[u8],
    frame_store: &[RefFrameStoreEntry<'_>],
    plane: u8,
    x: i32,
    y: i32,
    w: usize,
    h: usize,
    bit_depth: u8,
    subsampling_x: u8,
    subsampling_y: u8,
    frame_width: u32,
    frame_height: u32,
    interp_filter_x: u8,
    interp_filter_y: u8,
    curr_plane: &mut [u16],
    curr_stride: usize,
) -> Result<(), crate::Error> {
    // ---------- §7.11.3.1 step 5 — RefFrame[0] validity ----------
    //
    // This driver is the inter arm: `RefFrame[0]` must be a real
    // inter reference (`LAST_FRAME..=ALTREF_FRAME`, i.e. 1..=7).
    // INTRA_FRAME (0) and any value past ALTREF_FRAME is a caller bug.
    let ref_frame = mode_info.ref_frame as usize;
    if !(crate::uncompressed_header_tail::LAST_FRAME
        ..=crate::uncompressed_header_tail::ALTREF_FRAME)
        .contains(&ref_frame)
    {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    // ---------- §7.11.3.3 — refIdx = ref_frame_idx[ ref - LAST ] ---
    //
    // av1-spec p.252 line 4942 / p.274 line 14812: the small
    // `RefFrame` index selects a `ref_frame_idx[]` slot which in turn
    // names a `FrameStore[]` entry.
    let slot = ref_frame - crate::uncompressed_header_tail::LAST_FRAME;
    let ref_idx = *ref_frame_idx
        .get(slot)
        .ok_or(crate::Error::PartitionWalkOutOfRange)? as usize;
    let entry = frame_store
        .get(ref_idx)
        .ok_or(crate::Error::PartitionWalkOutOfRange)?;

    // ---------- §7.11.3.1 step 5 → PredictInterRef bundle ----------
    let refs = [PredictInterRef {
        ref_plane: entry.plane,
        ref_stride: entry.stride,
        ref_upscaled_width: entry.upscaled_width,
        ref_width: entry.width,
        ref_height: entry.height,
        mv: mode_info.mv,
    }];

    // ---------- §7.11.3.1 steps 1-13 — prediction into scratch -----
    let mut pred_out = vec![0u16; w * h];
    predict_inter(
        plane,
        x,
        y,
        w,
        h,
        crate::cdf::MOTION_MODE_SIMPLE,
        /* is_compound */ false,
        /* is_inter_intra */ false,
        bit_depth,
        subsampling_x,
        subsampling_y,
        frame_width,
        frame_height,
        interp_filter_x,
        interp_filter_y,
        &refs,
        /* compound */ None,
        /* inter_intra */ None,
        /* warp */ None,
        /* obmc */ None,
        &mut pred_out,
    )?;

    // ---------- §7.11.3.1 final step — CurrFrame[plane] stitch -----
    //
    // av1-spec p.258 line 14402: `CurrFrame[plane][y + i][x + j] =
    // Clip1(preds[0][i][j])`. `predict_inter` already applied the
    // `Clip1` (single-ref final-clip arm); here we copy the resulting
    // `w × h` block into the plane buffer at plane coords `(x, y)`.
    if x < 0 || y < 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let (px, py) = (x as usize, y as usize);
    // The write region must fit the supplied plane buffer.
    // §5.11.4 allows a leaf to OVERHANG the frame's bottom / right mi
    // edge (only its on-frame cells are grid-stamped). The §7.11.3.1
    // prediction still runs at the FULL block geometry — the wedge /
    // OBMC-band / small-block-filter derivations depend on
    // `Block_{Width,Height}` — but only the rows / columns inside the
    // plane are stitched back (r394: the previous full-fit guard
    // rejected every bottom-edge overhanging inter block).
    if curr_stride == 0 || px >= curr_stride {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let plane_rows = curr_plane.len() / curr_stride;
    if py >= plane_rows {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let fit_w = w.min(curr_stride - px);
    let fit_h = h.min(plane_rows - py);
    for i in 0..fit_h {
        let dst = (py + i) * curr_stride + px;
        let src = i * w;
        curr_plane[dst..dst + fit_w].copy_from_slice(&pred_out[src..src + fit_w]);
    }

    Ok(())
}

/// §7.11.3.1 single forward-reference **warped-motion** reconstruction —
/// drives one decoded `motion_mode == WARPED_CAUSAL` (LOCALWARP) /
/// global-warp inter block from mode-info into a `CurrFrame` plane.
///
/// This is the warp counterpart of [`reconstruct_inter_block`]: it
/// performs the same §7.11.3.1 step-5 / §7.11.3.3 ref-buffer resolution
/// (`refIdx = ref_frame_idx[ ref_frame - LAST_FRAME ]`,
/// `ref = FrameStore[ refIdx ]`), then runs [`predict_inter`] with
/// `motion_mode == MOTION_MODE_WARPED_CAUSAL` and the caller-supplied
/// [`WarpDriverParams`] so the §7.11.3.1 step-2/3/6/7 `useWarp`
/// derivation picks between the LOCALWARP (`useWarp == 1`) and
/// GLOBAL_GLOBALMV (`useWarp == 2`) §7.11.3.5 `block_warp` arms, and
/// finally stitches the predicted block into `curr_plane` at plane
/// coordinates `(x, y)` (`CurrFrame[plane][y+i][x+j] =
/// Clip1(preds[0][i][j])`, av1-spec p.258 line 14402 single-ref arm —
/// `predict_inter` applies the `Clip1`).
///
/// The `warp` bundle carries the §7.11.3.8 `LocalWarpParams` /
/// `LocalValid` the caller fitted from the §7.10.4 `find_warp_samples`
/// candidates (LOCALWARP arm), the per-ref `gm_type` / `gm_params`
/// global-motion model (GLOBAL_GLOBALMV arm), and the step-7 gating
/// flags (`y_mode`, `ref_is_scaled`, `force_integer_mv`). The
/// `useWarp` decision and the per-8×8 `block_warp` tiling happen inside
/// [`predict_inter`]; on `w < 8 || h < 8` or any step-7 fall-through to
/// `useWarp == 0` the driver predicts translationally, so this entry is
/// always safe to call for a `WARPED_CAUSAL` leaf even when the warp
/// gate does not actually fire (e.g. a sub-8×8 luma block, an invalid
/// local fit, or a chroma plane that the §5.11.27 LOCALWARP arm leaves
/// translational).
///
/// Returns [`crate::Error::PartitionWalkOutOfRange`] for the same
/// caller-bug arguments [`reconstruct_inter_block`] rejects (an
/// `INTRA_FRAME` / out-of-range `ref_frame`, an out-of-range resolved
/// `refIdx`, a `curr_plane` too small for the `(x, y, w, h)` write
/// region), plus anything [`predict_inter`]'s WARP arm itself rejects.
#[allow(clippy::too_many_arguments)]
pub fn reconstruct_inter_block_warp(
    mode_info: InterModeInfo,
    warp: &WarpDriverParams,
    ref_frame_idx: &[u8],
    frame_store: &[RefFrameStoreEntry<'_>],
    plane: u8,
    x: i32,
    y: i32,
    w: usize,
    h: usize,
    bit_depth: u8,
    subsampling_x: u8,
    subsampling_y: u8,
    frame_width: u32,
    frame_height: u32,
    interp_filter_x: u8,
    interp_filter_y: u8,
    curr_plane: &mut [u16],
    curr_stride: usize,
) -> Result<(), crate::Error> {
    // ---------- §7.11.3.1 step 5 — RefFrame[0] validity ----------
    let ref_frame = mode_info.ref_frame as usize;
    if !(crate::uncompressed_header_tail::LAST_FRAME
        ..=crate::uncompressed_header_tail::ALTREF_FRAME)
        .contains(&ref_frame)
    {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    // ---------- §7.11.3.3 — refIdx = ref_frame_idx[ ref - LAST ] ---
    let slot = ref_frame - crate::uncompressed_header_tail::LAST_FRAME;
    let ref_idx = *ref_frame_idx
        .get(slot)
        .ok_or(crate::Error::PartitionWalkOutOfRange)? as usize;
    let entry = frame_store
        .get(ref_idx)
        .ok_or(crate::Error::PartitionWalkOutOfRange)?;

    // ---------- §7.11.3.1 step 5 → PredictInterRef bundle ----------
    let refs = [PredictInterRef {
        ref_plane: entry.plane,
        ref_stride: entry.stride,
        ref_upscaled_width: entry.upscaled_width,
        ref_width: entry.width,
        ref_height: entry.height,
        mv: mode_info.mv,
    }];

    // ---------- §7.11.3.1 steps 1-13 — WARP prediction into scratch ---
    let mut pred_out = vec![0u16; w * h];
    predict_inter(
        plane,
        x,
        y,
        w,
        h,
        crate::cdf::MOTION_MODE_WARPED_CAUSAL,
        /* is_compound */ false,
        /* is_inter_intra */ false,
        bit_depth,
        subsampling_x,
        subsampling_y,
        frame_width,
        frame_height,
        interp_filter_x,
        interp_filter_y,
        &refs,
        /* compound */ None,
        /* inter_intra */ None,
        Some(warp),
        /* obmc */ None,
        &mut pred_out,
    )?;

    // ---------- §7.11.3.1 final step — CurrFrame[plane] stitch -----
    if x < 0 || y < 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let (px, py) = (x as usize, y as usize);
    // §5.11.4 allows a leaf to OVERHANG the frame's bottom / right mi
    // edge (only its on-frame cells are grid-stamped). The §7.11.3.1
    // prediction still runs at the FULL block geometry — the wedge /
    // OBMC-band / small-block-filter derivations depend on
    // `Block_{Width,Height}` — but only the rows / columns inside the
    // plane are stitched back (r394: the previous full-fit guard
    // rejected every bottom-edge overhanging inter block).
    if curr_stride == 0 || px >= curr_stride {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let plane_rows = curr_plane.len() / curr_stride;
    if py >= plane_rows {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let fit_w = w.min(curr_stride - px);
    let fit_h = h.min(plane_rows - py);
    for i in 0..fit_h {
        let dst = (py + i) * curr_stride + px;
        let src = i * w;
        curr_plane[dst..dst + fit_w].copy_from_slice(&pred_out[src..src + fit_w]);
    }

    Ok(())
}

/// §7.11.3.1 single forward-reference **OBMC** (overlapped block motion
/// compensation) reconstruction — drives one decoded `motion_mode ==
/// OBMC` inter block from mode-info into a `CurrFrame` plane
/// (av1-spec p.258 line 14414 invokes §7.11.3.9 only on `motion_mode ==
/// OBMC`).
///
/// This is the OBMC counterpart of [`reconstruct_inter_block`] /
/// [`reconstruct_inter_block_warp`]: it performs the same §7.11.3.1
/// step-5 / §7.11.3.3 ref-buffer resolution (`refIdx = ref_frame_idx[
/// ref_frame - LAST_FRAME ]`, `ref = FrameStore[ refIdx ]`) for the
/// block's own forward MV, then runs [`predict_inter`] with
/// `motion_mode == MOTION_MODE_OBMC` and the caller-supplied
/// [`ObmcParams`] bundle so the §7.11.3.9 above-pass / left-pass
/// neighbour walk blends each qualifying neighbour's translational
/// prediction (§7.11.3.10 `overlap_blending`) into the block's own
/// prediction in place, and finally stitches the blended block into
/// `curr_plane` at plane coordinates `(x, y)`
/// (`CurrFrame[plane][y+i][x+j] = Clip1(preds[0][i][j])`, av1-spec
/// p.258 line 14402 single-ref arm — [`predict_inter`] applies the
/// `Clip1`).
///
/// The block's own §7.11.3.1 step-5/-8 prediction (the `MOTION_MODE_OBMC`
/// block is single-reference and translational for its own MV) is formed
/// first; the §7.11.3.9 post-step then overlays the neighbour
/// contributions. The `obmc` bundle carries the §7.11.3.9 above/left
/// neighbour candidate lists the caller resolved from the §6.10.4
/// `RefFrames[]` / `Mvs[]` / `MiSizes[]` mi-grid plus the block's
/// `(MiRow, MiCol, MiSize, AvailU, AvailL)` context (see [`ObmcParams`]).
/// Empty neighbour lists (no qualifying above / left neighbour) make the
/// blend a no-op for that axis, so this entry is always safe to call for
/// an `OBMC` leaf even when no neighbour actually overlaps.
///
/// Returns [`crate::Error::PartitionWalkOutOfRange`] for the same
/// caller-bug arguments [`reconstruct_inter_block`] rejects (an
/// `INTRA_FRAME` / out-of-range `ref_frame`, an out-of-range resolved
/// `refIdx`, a `curr_plane` too small for the `(x, y, w, h)` write
/// region), plus anything [`predict_inter`]'s OBMC arm itself rejects.
#[allow(clippy::too_many_arguments)]
pub fn reconstruct_inter_block_obmc(
    mode_info: InterModeInfo,
    obmc: &ObmcParams<'_, '_>,
    ref_frame_idx: &[u8],
    frame_store: &[RefFrameStoreEntry<'_>],
    plane: u8,
    x: i32,
    y: i32,
    w: usize,
    h: usize,
    bit_depth: u8,
    subsampling_x: u8,
    subsampling_y: u8,
    frame_width: u32,
    frame_height: u32,
    interp_filter_x: u8,
    interp_filter_y: u8,
    curr_plane: &mut [u16],
    curr_stride: usize,
) -> Result<(), crate::Error> {
    // ---------- §7.11.3.1 step 5 — RefFrame[0] validity ----------
    let ref_frame = mode_info.ref_frame as usize;
    if !(crate::uncompressed_header_tail::LAST_FRAME
        ..=crate::uncompressed_header_tail::ALTREF_FRAME)
        .contains(&ref_frame)
    {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    // ---------- §7.11.3.3 — refIdx = ref_frame_idx[ ref - LAST ] ---
    let slot = ref_frame - crate::uncompressed_header_tail::LAST_FRAME;
    let ref_idx = *ref_frame_idx
        .get(slot)
        .ok_or(crate::Error::PartitionWalkOutOfRange)? as usize;
    let entry = frame_store
        .get(ref_idx)
        .ok_or(crate::Error::PartitionWalkOutOfRange)?;

    // ---------- §7.11.3.1 step 5 → PredictInterRef bundle ----------
    let refs = [PredictInterRef {
        ref_plane: entry.plane,
        ref_stride: entry.stride,
        ref_upscaled_width: entry.upscaled_width,
        ref_width: entry.width,
        ref_height: entry.height,
        mv: mode_info.mv,
    }];

    // ---------- §7.11.3.1 steps 1-13 + §7.11.3.9-10 OBMC post-step ---
    let mut pred_out = vec![0u16; w * h];
    predict_inter(
        plane,
        x,
        y,
        w,
        h,
        crate::cdf::MOTION_MODE_OBMC,
        /* is_compound */ false,
        /* is_inter_intra */ false,
        bit_depth,
        subsampling_x,
        subsampling_y,
        frame_width,
        frame_height,
        interp_filter_x,
        interp_filter_y,
        &refs,
        /* compound */ None,
        /* inter_intra */ None,
        /* warp */ None,
        Some(obmc),
        &mut pred_out,
    )?;

    // ---------- §7.11.3.1 final step — CurrFrame[plane] stitch -----
    if x < 0 || y < 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let (px, py) = (x as usize, y as usize);
    // §5.11.4 allows a leaf to OVERHANG the frame's bottom / right mi
    // edge (only its on-frame cells are grid-stamped). The §7.11.3.1
    // prediction still runs at the FULL block geometry — the wedge /
    // OBMC-band / small-block-filter derivations depend on
    // `Block_{Width,Height}` — but only the rows / columns inside the
    // plane are stitched back (r394: the previous full-fit guard
    // rejected every bottom-edge overhanging inter block).
    if curr_stride == 0 || px >= curr_stride {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let plane_rows = curr_plane.len() / curr_stride;
    if py >= plane_rows {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let fit_w = w.min(curr_stride - px);
    let fit_h = h.min(plane_rows - py);
    for i in 0..fit_h {
        let dst = (py + i) * curr_stride + px;
        let src = i * w;
        curr_plane[dst..dst + fit_w].copy_from_slice(&pred_out[src..src + fit_w]);
    }

    Ok(())
}

/// §7.11.3.1 compound two-reference mode-info descriptor — the decoded
/// `(RefFrame[0], RefFrame[1], Mvs[..][0], Mvs[..][1])` quad plus the
/// `compound_type` that selects the §7.11.3.1 step-14 combine arm
/// (av1-spec p.258 lines 14400-14412).
///
/// Both `ref_frame_0` and `ref_frame_1` are spec `RefFrame[ refList ]`
/// indices in `LAST_FRAME..=ALTREF_FRAME` (1..=7) — i.e. a real
/// bidirectional compound block (`RefFrame[1] >= LAST_FRAME`). The
/// inter-intra arm (`RefFrame[1] == INTRA_FRAME`) and the single-ref
/// arm (`RefFrame[1] == NONE`) are *not* compound and use
/// [`reconstruct_inter_block`] / the intra path instead.
///
/// `compound_type` is the §5.11.x decoded ordinal restricted here to the
/// four combine arms [`COMPOUND_AVERAGE`] / [`COMPOUND_DISTANCE`] /
/// [`COMPOUND_WEDGE`] / [`COMPOUND_DIFFWTD`]. `COMPOUND_AVERAGE` /
/// `COMPOUND_DISTANCE` need no mask; their output is fully derivable from
/// the two MVs, the two references, and (for `COMPOUND_DISTANCE`) the
/// §7.11.3.15 order-hint distance weights. `COMPOUND_WEDGE` additionally
/// reads the §5.11.29 `(wedge_index, wedge_sign)` carried in [`wedge`],
/// from which [`reconstruct_inter_block_compound`] regenerates the
/// §7.11.3.11 luma-grid wedge mask deterministically (the mask is a pure
/// function of `(MiSize, wedge_index, wedge_sign)`, with no
/// prediction-dependent side-data). `COMPOUND_DIFFWTD` carries only the
/// §5.11.29 [`mask_type`] toggle; its §7.11.3.12 mask is derived inside
/// the driver from the two formed `preds[]` (at `plane == 0`) into the
/// caller-supplied persistent luma-grid `diffwtd_mask` buffer. The
/// remaining prediction-derived mask arm [`COMPOUND_INTRA`] — whose
/// §7.11.3.13 mask the interintra driver owns — is still rejected.
///
/// [`wedge`]: CompoundInterModeInfo::wedge
/// [`mask_type`]: CompoundInterModeInfo::mask_type
#[derive(Debug, Clone, Copy)]
pub struct CompoundInterModeInfo {
    /// §7.11.3.1 step 5 `RefFrame[ 0 ]` (1..=7).
    pub ref_frame_0: u8,
    /// §7.11.3.1 step 5 `RefFrame[ 1 ]` (1..=7 — compound second ref).
    pub ref_frame_1: u8,
    /// §7.11.3.1 step 8 `Mvs[ candRow ][ candCol ][ 0 ]`, `[mv_row,
    /// mv_col]` in 1/8-luma-sample units.
    pub mv0: [i16; 2],
    /// §7.11.3.1 step 8 `Mvs[ candRow ][ candCol ][ 1 ]`.
    pub mv1: [i16; 2],
    /// §5.11.x decoded `compound_type` ordinal — must be
    /// [`COMPOUND_AVERAGE`], [`COMPOUND_DISTANCE`], or [`COMPOUND_WEDGE`].
    pub compound_type: u8,
    /// §7.11.3.11 wedge-mask side data — `Some(_)` **required** when
    /// `compound_type == COMPOUND_WEDGE`, ignored otherwise. Carries the
    /// `MiSize` (luma block size — the §7.11.3.11 `WedgeMasks[MiSize]`
    /// index) plus the §5.11.29 `(wedge_index, wedge_sign)` codebook
    /// selectors. A `COMPOUND_WEDGE` leaf with `wedge == None` is a
    /// caller bug ([`crate::Error::PartitionWalkOutOfRange`]).
    pub wedge: Option<WedgeModeInfo>,
    /// §5.11.29 `mask_type` bit — meaningful only on the
    /// [`COMPOUND_DIFFWTD`] arm (`0` = `DIFFWTD_38`, `1` =
    /// `DIFFWTD_38_INV`); ignored on every other `compound_type`. Drives
    /// the §7.11.3.12 per-pixel weight inversion.
    pub mask_type: u8,
}

/// §7.11.3.11 wedge-mask side data for a [`COMPOUND_WEDGE`] compound
/// leaf — the decoded selectors [`reconstruct_inter_block_compound`]
/// hands to [`wedge_mask`] to regenerate the luma-grid mask.
///
/// The mask is computed once on the luma grid (`MiSize`-sized) and
/// reused across chroma planes via [`mask_blend`]'s `(sub_x, sub_y)`
/// downsampling (av1-spec p.258 line 14386: the §7.11.3.11 process runs
/// only `if plane == 0`). The `mi_size` here is the **luma** block size,
/// so the wedge mask is always luma-sized regardless of which plane the
/// reconstruction driver is currently filling.
#[derive(Debug, Clone, Copy)]
pub struct WedgeModeInfo {
    /// `MiSize` — the luma `BLOCK_SIZES` index of the compound leaf;
    /// must have `WEDGE_BITS[mi_size] > 0` (one of the 9 wedge-eligible
    /// block sizes).
    pub mi_size: usize,
    /// §5.11.29 `wedge_index` — codebook ordinal in `0..16`.
    pub wedge_index: u8,
    /// §5.11.29 `wedge_sign` — `0` or `1`.
    pub wedge_sign: u8,
}

/// §7.11.3.15 order-hint context the [`COMPOUND_DISTANCE`] combine arm
/// derives `(FwdWeight, BckWeight)` from. Carries the current frame's
/// `OrderHint`, the `OrderHints[]` of the two references, and
/// `OrderHintBits` — the exact [`distance_weights`] inputs.
///
/// Ignored on the [`COMPOUND_AVERAGE`] arm (which needs no weights), so
/// a caller driving only `COMPOUND_AVERAGE` leaves may pass any value.
#[derive(Debug, Clone, Copy)]
pub struct CompoundOrderHintContext {
    /// §5.5.1 `OrderHintBits`.
    pub order_hint_bits: u32,
    /// §5.9.2 `OrderHint` of the frame being decoded.
    pub current_order_hint: i32,
    /// `OrderHints[ RefFrame[ 0 ] ]`.
    pub order_hint_ref0: i32,
    /// `OrderHints[ RefFrame[ 1 ] ]`.
    pub order_hint_ref1: i32,
}

/// §7.11.3.1 compound two-reference reconstruction — drives one decoded
/// compound inter block (`RefFrame[1] >= LAST_FRAME`) from mode-info
/// into a `CurrFrame` plane, for the [`COMPOUND_AVERAGE`] /
/// [`COMPOUND_DISTANCE`] mask-free arms, the [`COMPOUND_WEDGE`]
/// regenerable-mask arm, and the [`COMPOUND_DIFFWTD`] arm (whose
/// §7.11.3.12 mask is derived inside [`predict_inter`] from the two
/// formed `preds[]`).
///
/// The [`COMPOUND_DIFFWTD`] arm requires the caller to pass a persistent
/// luma-grid `diffwtd_mask` buffer (length `>= Block_Width[MiSize] *
/// Block_Height[MiSize]`): the driver fills it from the §7.11.3.12 mask
/// process on the `plane == 0` call and reuses it on the chroma calls
/// (av1-spec p.258 line 14392). The caller therefore owns this buffer
/// across the per-plane invocations for one block and passes the *same*
/// buffer each time. `diffwtd_mask` is ignored on the other arms.
///
/// This is the compound sibling of [`reconstruct_inter_block`]: it
/// resolves *both* references through the §7.11.3.3 `refIdx =
/// ref_frame_idx[ RefFrame − LAST_FRAME ]` ⇒ `FrameStore[ refIdx ]`
/// indirection, runs [`predict_inter`] with `is_compound == true` (which
/// forms `preds[0]` / `preds[1]` and applies the step-14 combine +
/// final `Clip1` into the scratch buffer), then stitches the result
/// into `curr_plane` at plane coordinates `(x, y)` (av1-spec p.258 line
/// 14402, identical to the single-ref stitch).
///
/// For [`COMPOUND_DISTANCE`] the §7.11.3.15 `(FwdWeight, BckWeight)` are
/// derived from `order_hints` via [`distance_weights`]; for
/// [`COMPOUND_AVERAGE`] `order_hints` is unused. For [`COMPOUND_WEDGE`]
/// the §7.11.3.11 luma-grid mask is regenerated once via [`wedge_mask`]
/// from `mode_info.wedge` (the decoded `(MiSize, wedge_index,
/// wedge_sign)`), then handed to [`predict_inter`] as
/// [`CompoundParams::Wedge`] with `mask_stride` set to the luma block
/// width so the per-plane `(sub_x, sub_y)` downsampling inside
/// [`mask_blend`] addresses it correctly on chroma planes.
///
/// Returns [`crate::Error::PartitionWalkOutOfRange`] for caller-bug
/// arguments: either `RefFrame` `INTRA_FRAME` (0) or out of range, an
/// out-of-range resolved `refIdx`, a `compound_type` other than
/// `COMPOUND_AVERAGE` / `COMPOUND_DISTANCE` / `COMPOUND_WEDGE` /
/// `COMPOUND_DIFFWTD`, a `COMPOUND_WEDGE` leaf with `wedge == None` or
/// wedge selectors [`wedge_mask`] rejects, a `COMPOUND_DIFFWTD` leaf
/// without a `diffwtd_mask` buffer (or one too small for the luma grid),
/// a `curr_plane` too small for the `(x, y, w, h)` write region, or
/// anything [`predict_inter`] itself rejects.
#[allow(clippy::too_many_arguments)]
pub fn reconstruct_inter_block_compound(
    mode_info: CompoundInterModeInfo,
    order_hints: CompoundOrderHintContext,
    ref_frame_idx: &[u8],
    frame_store: &[RefFrameStoreEntry<'_>],
    plane: u8,
    x: i32,
    y: i32,
    w: usize,
    h: usize,
    bit_depth: u8,
    subsampling_x: u8,
    subsampling_y: u8,
    frame_width: u32,
    frame_height: u32,
    interp_filter_x: u8,
    interp_filter_y: u8,
    diffwtd_mask: Option<&mut [u8]>,
    // §7.11.3.1 step-7 warp context for the GLOBAL_GLOBALMV /
    // GLOBALMV-class compound arm (`useWarp = 2` fires per refList
    // when `GmType[ RefFrame[ refList ] ] > TRANSLATION` — §5.11.27
    // forces `motion_mode = SIMPLE` on this block class, so the
    // compound driver is its only route). `None` keeps the
    // translational-only path.
    warp: Option<&WarpDriverParams>,
    curr_plane: &mut [u16],
    curr_stride: usize,
) -> Result<(), crate::Error> {
    // ---------- compound_type gate ----------
    //
    // This driver covers the two mask-free combine arms, the wedge arm
    // (whose mask is a pure function of the decoded `(MiSize,
    // wedge_index, wedge_sign)` carried in `mode_info.wedge`, so it can
    // be regenerated here before prediction), and the diff-weight arm
    // (whose §7.11.3.12 mask the §7.11.3.1 driver derives internally from
    // the two `preds[]` at `plane == 0` and persists for chroma via the
    // caller-supplied `diffwtd_mask` buffer). The intra-variant mask arm
    // is left to a later driver (caller bug to route it here).
    if !matches!(
        mode_info.compound_type,
        COMPOUND_AVERAGE | COMPOUND_DISTANCE | COMPOUND_WEDGE | COMPOUND_DIFFWTD
    ) {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    // The DIFFWTD arm needs a persistent luma-grid mask buffer to carry
    // the §7.11.3.12 mask from the `plane == 0` derivation to the chroma
    // planes (av1-spec p.258 line 14392). A DIFFWTD leaf routed here
    // without one is a caller bug; conversely a `diffwtd_mask` supplied
    // on a non-DIFFWTD arm is harmlessly ignored.
    if mode_info.compound_type == COMPOUND_DIFFWTD && diffwtd_mask.is_none() {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    // ---------- §7.11.3.3 — resolve each RefFrame[refList] -----------
    //
    // av1-spec p.252 line 4942 / p.274 line 14812: each small
    // `RefFrame` index selects a `ref_frame_idx[]` slot naming a
    // `FrameStore[]` entry. Both list-0 and list-1 references must be
    // real inter references (`LAST_FRAME..=ALTREF_FRAME`).
    let resolve = |rf: u8| -> Result<&RefFrameStoreEntry<'_>, crate::Error> {
        let rf = rf as usize;
        if !(crate::uncompressed_header_tail::LAST_FRAME
            ..=crate::uncompressed_header_tail::ALTREF_FRAME)
            .contains(&rf)
        {
            return Err(crate::Error::PartitionWalkOutOfRange);
        }
        let slot = rf - crate::uncompressed_header_tail::LAST_FRAME;
        let ref_idx = *ref_frame_idx
            .get(slot)
            .ok_or(crate::Error::PartitionWalkOutOfRange)? as usize;
        frame_store
            .get(ref_idx)
            .ok_or(crate::Error::PartitionWalkOutOfRange)
    };
    let entry0 = resolve(mode_info.ref_frame_0)?;
    let entry1 = resolve(mode_info.ref_frame_1)?;

    // ---------- §7.11.3.1 step 5 / step 14 → two-ref bundle ----------
    let refs = [
        PredictInterRef {
            ref_plane: entry0.plane,
            ref_stride: entry0.stride,
            ref_upscaled_width: entry0.upscaled_width,
            ref_width: entry0.width,
            ref_height: entry0.height,
            mv: mode_info.mv0,
        },
        PredictInterRef {
            ref_plane: entry1.plane,
            ref_stride: entry1.stride,
            ref_upscaled_width: entry1.upscaled_width,
            ref_width: entry1.width,
            ref_height: entry1.height,
            mv: mode_info.mv1,
        },
    ];

    // ---------- §7.11.3.1 step-14 combine descriptor ----------
    //
    // `COMPOUND_DISTANCE` derives `(FwdWeight, BckWeight)` from the
    // §7.11.3.15 order-hint distances; `COMPOUND_AVERAGE` needs none;
    // `COMPOUND_WEDGE` regenerates the §7.11.3.11 luma-grid mask from
    // the decoded `(MiSize, wedge_index, wedge_sign)`.
    //
    // The wedge mask buffer must outlive the `predict_inter` call, so
    // it is materialized here (`None` / unused on the non-wedge arms).
    // The §7.11.3.11 mask lives on the *luma* grid: its width / height
    // are `Block_Width[MiSize]` / `Block_Height[MiSize]` regardless of
    // which plane is being filled; `mask_blend`'s `(sub_x, sub_y)`
    // downsampling addresses it for chroma, with the luma block width as
    // the row stride.
    let wedge_mask_buf: Option<(Vec<u8>, usize)> = if mode_info.compound_type == COMPOUND_WEDGE {
        let wedge = mode_info
            .wedge
            .ok_or(crate::Error::PartitionWalkOutOfRange)?;
        if wedge.mi_size >= crate::cdf::BLOCK_SIZES {
            return Err(crate::Error::PartitionWalkOutOfRange);
        }
        let n4w = crate::cdf::num_4x4_blocks_wide(wedge.mi_size) as u32;
        let n4h = crate::cdf::num_4x4_blocks_high(wedge.mi_size) as u32;
        let luma_w = crate::cdf::block_width(wedge.mi_size);
        let luma_h = crate::cdf::block_height(wedge.mi_size);
        let mut buf = vec![0u8; luma_w * luma_h];
        wedge_mask(
            wedge.mi_size,
            n4w,
            n4h,
            wedge.wedge_index,
            wedge.wedge_sign,
            &mut buf,
        )?;
        Some((buf, luma_w))
    } else {
        None
    };
    let compound = match mode_info.compound_type {
        COMPOUND_DISTANCE => {
            let weights = distance_weights(
                order_hints.order_hint_bits,
                order_hints.current_order_hint,
                order_hints.order_hint_ref0,
                order_hints.order_hint_ref1,
            );
            CompoundParams::Distance(weights)
        }
        COMPOUND_WEDGE => {
            // SAFETY: the WEDGE branch above populated `wedge_mask_buf`
            // (or already returned the caller-bug error).
            let (mask, luma_w) = wedge_mask_buf
                .as_ref()
                .expect("WEDGE arm materialized the mask above");
            CompoundParams::Wedge {
                mask,
                mask_stride: *luma_w,
            }
        }
        COMPOUND_DIFFWTD => {
            // The §7.11.3.12 mask is derived by the driver from the two
            // `preds[]` (at `plane == 0`); we only forward the §5.11.29
            // `mask_type` toggle plus the persistent luma-grid buffer the
            // gate above guaranteed is `Some(_)`.
            let mask = diffwtd_mask.expect("DIFFWTD arm requires diffwtd_mask (gated above)");
            CompoundParams::Diffwtd {
                mask_type: mode_info.mask_type,
                mask,
            }
        }
        // COMPOUND_AVERAGE (the gate above rejected every other type).
        _ => CompoundParams::Average,
    };

    // ---------- §7.11.3.1 steps 1-14 — compound prediction ----------
    let mut pred_out = vec![0u16; w * h];
    predict_inter(
        plane,
        x,
        y,
        w,
        h,
        crate::cdf::MOTION_MODE_SIMPLE,
        /* is_compound */ true,
        /* is_inter_intra */ false,
        bit_depth,
        subsampling_x,
        subsampling_y,
        frame_width,
        frame_height,
        interp_filter_x,
        interp_filter_y,
        &refs,
        Some(compound),
        /* inter_intra */ None,
        warp,
        /* obmc */ None,
        &mut pred_out,
    )?;

    // ---------- §7.11.3.1 final step — CurrFrame[plane] stitch -------
    //
    // av1-spec p.258 line 14402: `CurrFrame[plane][y + i][x + j] =
    // <combined>`. `predict_inter` already applied the step-14 combine
    // + `Clip1` into `pred_out`; here we copy the `w × h` block into the
    // plane buffer at plane coords `(x, y)` (same stitch as the
    // single-ref arm).
    if x < 0 || y < 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let (px, py) = (x as usize, y as usize);
    // §5.11.4 allows a leaf to OVERHANG the frame's bottom / right mi
    // edge (only its on-frame cells are grid-stamped). The §7.11.3.1
    // prediction still runs at the FULL block geometry — the wedge /
    // OBMC-band / small-block-filter derivations depend on
    // `Block_{Width,Height}` — but only the rows / columns inside the
    // plane are stitched back (r394: the previous full-fit guard
    // rejected every bottom-edge overhanging inter block).
    if curr_stride == 0 || px >= curr_stride {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let plane_rows = curr_plane.len() / curr_stride;
    if py >= plane_rows {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let fit_w = w.min(curr_stride - px);
    let fit_h = h.min(plane_rows - py);
    for i in 0..fit_h {
        let dst = (py + i) * curr_stride + px;
        let src = i * w;
        curr_plane[dst..dst + fit_w].copy_from_slice(&pred_out[src..src + fit_w]);
    }

    Ok(())
}

/// §7.11.3.1 inter-intra mode-info descriptor — the decoded
/// `(RefFrame[0], Mvs[..][0])` pair for an inter-intra block
/// (`RefFrame[1] == INTRA_FRAME`, so `isCompound == 0`) plus the
/// §5.11.28 `interintra_mode` and the optional `wedge_interintra == 1`
/// sub-arm selectors.
///
/// `ref_frame_0` is the single inter reference (`LAST_FRAME..=ALTREF_FRAME`,
/// 1..=7) — the inter-intra block forms exactly one inter prediction from
/// it; the second operand of the §7.11.3.14 blend is the §7.11.2 intra
/// prediction the caller already wrote into `CurrFrame[plane]` (av1-spec
/// p.83 lines 5141-5163: `predict_intra` runs *before* `predict_inter`
/// on the `IsInterIntra` arm, and p.284 line 15786: `pred1 =
/// CurrFrame[plane][y+dstY][x+dstX]`).
///
/// `interintra_mode` is the §5.11.28 ordinal (`II_DC_PRED` / `II_V_PRED`
/// / `II_H_PRED` / `II_SMOOTH_PRED`, 0..=3) that selects the §7.11.3.13
/// [`intra_mode_variant_mask`] variant on the non-wedge sub-arm. When
/// [`wedge`] is `None` the §7.11.3.13 mask is used directly at
/// `Mask[y][x]` (the non-wedge `COMPOUND_INTRA` arm); when `Some(_)` the
/// §7.11.3.11 luma-grid wedge mask is used instead (`wedge_interintra ==
/// 1` ⇒ `compound_type == COMPOUND_WEDGE`, av1-spec p.80 line 5017), with
/// [`reconstruct_inter_block_interintra`] regenerating it from the decoded
/// `(MiSize, wedge_index)` (and `wedge_sign == 0`, fixed by §5.11.28
/// p.79 line 4965).
///
/// [`wedge`]: InterIntraModeInfo::wedge
#[derive(Debug, Clone, Copy)]
pub struct InterIntraModeInfo {
    /// §7.11.3.1 step 5 `RefFrame[ 0 ]` (1..=7) — the single inter
    /// reference.
    pub ref_frame: u8,
    /// §7.11.3.1 step 8 `Mvs[ candRow ][ candCol ][ 0 ]`, `[mv_row,
    /// mv_col]` in 1/8-luma-sample units.
    pub mv: [i16; 2],
    /// §5.11.28 `interintra_mode` (0..=3).
    pub interintra_mode: u8,
    /// §7.11.3.11 wedge selectors — `Some(_)` selects the
    /// `wedge_interintra == 1` sub-arm (the §7.11.3.11 luma-grid wedge
    /// mask, regenerated from `(MiSize, wedge_index)` with `wedge_sign ==
    /// 0`); `None` selects the §7.11.3.13 intra-variant sub-arm
    /// (`wedge_interintra == 0`).
    pub wedge: Option<InterIntraWedgeModeInfo>,
}

/// §7.11.3.11 wedge selectors for an inter-intra `wedge_interintra == 1`
/// leaf — the decoded `(MiSize, wedge_index)` from which
/// [`reconstruct_inter_block_interintra`] regenerates the luma-grid mask
/// via [`wedge_mask`].
///
/// `wedge_sign` is **not** carried: §5.11.28 (av1-spec p.79 line 4965)
/// fixes `wedge_sign = 0` for the interintra arm, so the driver always
/// passes `0`. The `mi_size` is the *luma* block size (the §7.11.3.11
/// `WedgeMasks[MiSize]` index); the mask is luma-grid and reused for
/// chroma via the persistent buffer the driver fills at `plane == 0`.
#[derive(Debug, Clone, Copy)]
pub struct InterIntraWedgeModeInfo {
    /// `MiSize` — the luma `BLOCK_SIZES` index; must have
    /// `WEDGE_BITS[mi_size] > 0`.
    pub mi_size: usize,
    /// §5.11.28 `wedge_index` — codebook ordinal in `0..16`.
    pub wedge_index: u8,
}

/// §7.11.3.1 inter-intra reconstruction — drives one decoded inter-intra
/// block (`RefFrame[1] == INTRA_FRAME`, `isCompound == 0`) from mode-info
/// into a `CurrFrame` plane.
///
/// This is the inter-intra sibling of [`reconstruct_inter_block`] /
/// [`reconstruct_inter_block_compound`]. Unlike those two, the second
/// blend operand is **not** another inter prediction: it is the §7.11.2
/// intra prediction already present in `curr_plane` at plane coordinates
/// `(x, y)` (av1-spec p.83 lines 5141-5163 run `predict_intra` first;
/// p.284 line 15786 reads it as `pred1 = CurrFrame[plane][y+dstY]
/// [x+dstX]`). The caller is therefore responsible for having written the
/// intra prediction into `curr_plane` for this leaf *before* invoking this
/// driver — the §5.11.33 ordering [`reconstruct_inter_frame`] documents.
///
/// The driver:
///   * resolves the single inter `RefFrame[0]` through the §7.11.3.3
///     `refIdx = ref_frame_idx[ RefFrame − LAST_FRAME ]` ⇒
///     `FrameStore[ refIdx ]` indirection (identical to
///     [`reconstruct_inter_block`]);
///   * seeds a `w × h` scratch buffer with the in-place intra prediction
///     read from `curr_plane` at `(x, y)`;
///   * runs [`predict_inter`] with `is_inter_intra == true`, which forms
///     `preds[0]` from `refs[0]` and blends it into the scratch buffer
///     through the §7.11.3.14 inter-intra body — the §7.11.3.13
///     intra-variant mask on the non-wedge arm (`wedge == None`), or the
///     §7.11.3.11 luma-grid wedge mask on the `wedge_interintra == 1` arm;
///   * stitches the blended `w × h` block back into `curr_plane` at
///     `(x, y)`.
///
/// On the wedge arm the §7.11.3.11 mask is luma-grid (built once at
/// `plane == 0` per av1-spec p.258 line 14386); the caller passes a
/// persistent `wedge_mask_buf` buffer (length `>= Block_Width[MiSize] *
/// Block_Height[MiSize]`) so it survives the per-plane invocations for one
/// block — the driver fills it on the `plane == 0` call and reuses it for
/// chroma (with `mask_blend_interintra`'s `(sub_x, sub_y)` downsampling).
/// `wedge_mask_buf` is ignored on the non-wedge arm.
///
/// Returns [`crate::Error::PartitionWalkOutOfRange`] for caller-bug
/// arguments: an `INTRA_FRAME` (0) or out-of-range `ref_frame`, an
/// out-of-range resolved `refIdx`, an out-of-range `interintra_mode`, a
/// wedge leaf with `wedge == Some(_)` but `wedge_mask_buf == None` (or a
/// buffer too small for the luma grid) or wedge selectors [`wedge_mask`]
/// rejects, a `curr_plane` too small for the `(x, y, w, h)` write region,
/// or anything [`predict_inter`] itself rejects.
#[allow(clippy::too_many_arguments)]
pub fn reconstruct_inter_block_interintra(
    mode_info: InterIntraModeInfo,
    ref_frame_idx: &[u8],
    frame_store: &[RefFrameStoreEntry<'_>],
    plane: u8,
    x: i32,
    y: i32,
    w: usize,
    h: usize,
    bit_depth: u8,
    subsampling_x: u8,
    subsampling_y: u8,
    frame_width: u32,
    frame_height: u32,
    interp_filter_x: u8,
    interp_filter_y: u8,
    wedge_mask_buf: Option<&mut [u8]>,
    warp: Option<&WarpDriverParams>,
    curr_plane: &mut [u16],
    curr_stride: usize,
) -> Result<(), crate::Error> {
    // ---------- §7.11.3.1 step 5 — RefFrame[0] validity ----------
    //
    // Like the single-ref arm, `RefFrame[0]` must be a real inter
    // reference (`LAST_FRAME..=ALTREF_FRAME`). The inter-intra block's
    // second reference is `INTRA_FRAME`, supplied as the in-place intra
    // prediction rather than a `RefFrame` index, so it never appears here.
    let ref_frame = mode_info.ref_frame as usize;
    if !(crate::uncompressed_header_tail::LAST_FRAME
        ..=crate::uncompressed_header_tail::ALTREF_FRAME)
        .contains(&ref_frame)
    {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }

    // ---------- §7.11.3.3 — refIdx = ref_frame_idx[ ref - LAST ] ----
    let slot = ref_frame - crate::uncompressed_header_tail::LAST_FRAME;
    let ref_idx = *ref_frame_idx
        .get(slot)
        .ok_or(crate::Error::PartitionWalkOutOfRange)? as usize;
    let entry = frame_store
        .get(ref_idx)
        .ok_or(crate::Error::PartitionWalkOutOfRange)?;

    let refs = [PredictInterRef {
        ref_plane: entry.plane,
        ref_stride: entry.stride,
        ref_upscaled_width: entry.upscaled_width,
        ref_width: entry.width,
        ref_height: entry.height,
        mv: mode_info.mv,
    }];

    // ---------- §7.11.3.1 final-write region bounds ----------
    //
    // Validate the `(x, y, w, h)` write region against `curr_plane`
    // *before* reading the intra seed out of it (the read and the
    // write-back share the region).
    if x < 0 || y < 0 {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let (px, py) = (x as usize, y as usize);
    // §5.11.4 allows a leaf to OVERHANG the frame's bottom / right mi
    // edge (only its on-frame cells are grid-stamped). The §7.11.3.1
    // prediction still runs at the FULL block geometry — the wedge /
    // OBMC-band / small-block-filter derivations depend on
    // `Block_{Width,Height}` — but only the rows / columns inside the
    // plane are stitched back (r394: the previous full-fit guard
    // rejected every bottom-edge overhanging inter block).
    if curr_stride == 0 || px >= curr_stride {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let plane_rows = curr_plane.len() / curr_stride;
    if py >= plane_rows {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let fit_w = w.min(curr_stride - px);
    let fit_h = h.min(plane_rows - py);

    // ---------- §7.11.3.14 step — seed scratch with intra pred -------
    //
    // av1-spec p.284 line 15786: `pred1 = CurrFrame[plane][y+dstY]
    // [x+dstX]` — the §7.11.3.14 body reads the in-place intra prediction
    // as the second blend operand. We copy that `w × h` window out of
    // `curr_plane` into the scratch buffer `predict_inter` consumes (it
    // overwrites the scratch with the blended sample in place).
    let mut pred_out = vec![0u16; w * h];
    // Seed only the in-plane window (an overhanging block's off-plane
    // rows / columns have no intra prediction to read; the §7.11.3.14
    // blend is pointwise, so the kept samples are unaffected by the
    // zero padding).
    for i in 0..fit_h {
        let src = (py + i) * curr_stride + px;
        let dst = i * w;
        pred_out[dst..dst + fit_w].copy_from_slice(&curr_plane[src..src + fit_w]);
    }

    // ---------- §7.11.3.11 wedge-mask regeneration (wedge arm) -------
    //
    // av1-spec p.258 line 14386: the §7.11.3.11 wedge mask is built only
    // at `plane == 0`, then reused (downsampled) for chroma. The caller
    // owns the persistent `wedge_mask_buf` across the per-plane calls; we
    // fill it on the luma call and read it (unchanged) on the chroma
    // calls. `wedge_sign == 0` is fixed by §5.11.28 (p.79 line 4965).
    let wedge_params: Option<InterIntraParams<'_>> = match mode_info.wedge {
        None => Some(InterIntraParams {
            interintra_mode: mode_info.interintra_mode,
            wedge: None,
        }),
        Some(wi) => {
            let buf = wedge_mask_buf.ok_or(crate::Error::PartitionWalkOutOfRange)?;
            if wi.mi_size >= crate::cdf::BLOCK_SIZES {
                return Err(crate::Error::PartitionWalkOutOfRange);
            }
            let luma_w = crate::cdf::block_width(wi.mi_size);
            let luma_h = crate::cdf::block_height(wi.mi_size);
            if buf.len() < luma_w * luma_h {
                return Err(crate::Error::PartitionWalkOutOfRange);
            }
            // Fill the luma-grid mask only at `plane == 0`; the chroma
            // planes reuse the buffer the caller carried over.
            if plane == 0 {
                let n4w = crate::cdf::num_4x4_blocks_wide(wi.mi_size) as u32;
                let n4h = crate::cdf::num_4x4_blocks_high(wi.mi_size) as u32;
                wedge_mask(
                    wi.mi_size,
                    n4w,
                    n4h,
                    wi.wedge_index,
                    /* wedge_sign */ 0,
                    &mut buf[..luma_w * luma_h],
                )?;
            }
            Some(InterIntraParams {
                interintra_mode: mode_info.interintra_mode,
                wedge: Some(WedgeInterIntraInfo {
                    mask: &buf[..luma_w * luma_h],
                    mask_stride: luma_w,
                }),
            })
        }
    };

    // ---------- §7.11.3.1 steps 1-13 + §7.11.3.14 blend ----------
    predict_inter(
        plane,
        x,
        y,
        w,
        h,
        crate::cdf::MOTION_MODE_SIMPLE,
        /* is_compound */ false,
        /* is_inter_intra */ true,
        bit_depth,
        subsampling_x,
        subsampling_y,
        frame_width,
        frame_height,
        interp_filter_x,
        interp_filter_y,
        &refs,
        /* compound */ None,
        wedge_params,
        warp,
        /* obmc */ None,
        &mut pred_out,
    )?;

    // ---------- §7.11.3.1 final step — CurrFrame[plane] stitch -----
    //
    // The §7.11.3.14 body wrote the blended `w × h` result into
    // `pred_out`; copy it back into `curr_plane` at `(x, y)`.
    for i in 0..fit_h {
        let dst = (py + i) * curr_stride + px;
        let src = i * w;
        curr_plane[dst..dst + fit_w].copy_from_slice(&pred_out[src..src + fit_w]);
    }

    Ok(())
}

/// One decoded §5.11.33 inter-intra leaf (`RefFrame[1] == INTRA_FRAME`,
/// `isCompound == 0`) at a known `(MiRow, MiCol)` origin — the per-block
/// state a single inter-intra reconstruction needs, independent of how it
/// was assembled.
///
/// This is the shared input to [`reconstruct_inter_intra_block`]: the
/// §5.11.33 frame-walk ([`reconstruct_inter_frame`]) builds it by reading
/// its `InterModeInfoGrid` slices at a leaf origin, while the §5.11.33
/// task-dispatcher path ([`reconstruct_inter_intra_from_dispatch`]) builds
/// it from the per-block mode-info the §5.11.23 reader already decoded.
/// Both then drive the one [`reconstruct_inter_block_interintra`] leaf —
/// so the two paths share a single reconstruction driver rather than each
/// re-deriving the per-plane invocation.
#[derive(Debug, Clone, Copy)]
pub struct InterIntraLeaf {
    /// §7.11.3.1 step 5 / step 8 inter side (`RefFrame[0]`, `Mvs[..][0]`)
    /// plus the §5.11.28 `interintra_mode` and optional wedge selectors.
    pub mode_info: InterIntraModeInfo,
    /// `MiSize` — the luma `BLOCK_SIZES` index. Drives the per-plane write
    /// region (`Block_Width/Height[MiSize] >> sub`) and the §7.11.3.11
    /// luma-grid wedge mask sizing.
    pub mi_size: usize,
    /// §7.11.3.1 leaf origin `MiRow` (mode-info units, luma grid).
    pub mi_row: u32,
    /// §7.11.3.1 leaf origin `MiCol` (mode-info units, luma grid).
    pub mi_col: u32,
    /// §7.11.3.2 horizontal interpolation filter ordinal
    /// (`InterpFilters[..][0]`).
    pub interp_filter_x: u8,
    /// §7.11.3.2 vertical interpolation filter ordinal
    /// (`InterpFilters[..][1]`).
    pub interp_filter_y: u8,
}

/// §5.11.33 inter-intra per-block reconstruction driver — runs the
/// §7.11.3.14 inter-intra blend for one decoded leaf across every plane.
///
/// This is the single per-block inter-intra driver the §5.11.33
/// frame-walk ([`reconstruct_inter_frame`]) and the §5.11.33
/// task-dispatcher bridge ([`reconstruct_inter_intra_from_dispatch`]) both
/// call. It mirrors the §5.11.33 plane loop exactly: for each plane it
/// derives `baseX = (MiCol >> subX) * MI_SIZE`, `baseY = (MiRow >> subY) *
/// MI_SIZE` (av1-spec p.82 lines 5135-5136), the write region `predW =
/// Block_Width[MiSize] >> subX`, `predH = Block_Height[MiSize] >> subY`
/// (lines 5166-5167), and invokes [`reconstruct_inter_block_interintra`]
/// to blend the §7.11.3.14 inter half against the §7.11.2 intra
/// prediction already present in that plane's `curr` buffer.
///
/// On the `wedge_interintra == 1` sub-arm the §7.11.3.11 luma-grid wedge
/// mask is regenerated once at `plane == 0` into a per-block scratch
/// buffer (sized to `Block_Width[MiSize] * Block_Height[MiSize]`, av1-spec
/// p.258 line 14386) and reused for the chroma planes.
///
/// **The caller must have written the §7.11.2 intra prediction into each
/// plane's `curr` buffer for this leaf's footprint before calling this
/// driver** (av1-spec p.83 lines 5141-5163 run `predict_intra` before
/// `predict_inter` on the `IsInterIntra` arm; p.284 line 15786 reads it
/// back as `pred1`). This driver supplies only the inter half of the
/// blend.
///
/// Returns [`crate::Error::PartitionWalkOutOfRange`] for an out-of-range
/// `MiSize`, or for anything [`reconstruct_inter_block_interintra`] itself
/// rejects.
pub fn reconstruct_inter_intra_block(
    leaf: &InterIntraLeaf,
    ref_frame_idx: &[u8],
    bit_depth: u8,
    warp: Option<&WarpDriverParams>,
    planes: &mut [PlaneReconContext<'_>],
) -> Result<(), crate::Error> {
    if leaf.mi_size >= crate::cdf::BLOCK_SIZES {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    // §7.11.3.11 persistent luma-grid wedge mask — filled by the driver at
    // `plane == 0` and reused for chroma (av1-spec p.258 line 14386).
    // Sized to the *luma* block; `None` on the non-wedge arm.
    let mut wedge_buf: Option<Vec<u8>> = if leaf.mode_info.wedge.is_some() {
        Some(vec![
            0u8;
            crate::cdf::block_width(leaf.mi_size)
                * crate::cdf::block_height(leaf.mi_size)
        ])
    } else {
        None
    };

    for ctx in planes.iter_mut() {
        let sub_x = if ctx.plane > 0 { ctx.subsampling_x } else { 0 };
        let sub_y = if ctx.plane > 0 { ctx.subsampling_y } else { 0 };
        let base_x = ((leaf.mi_col >> sub_x) * crate::cdf::MI_SIZE as u32) as i32;
        let base_y = ((leaf.mi_row >> sub_y) * crate::cdf::MI_SIZE as u32) as i32;
        let pred_w = crate::cdf::block_width(leaf.mi_size) >> sub_x;
        let pred_h = crate::cdf::block_height(leaf.mi_size) >> sub_y;

        reconstruct_inter_block_interintra(
            leaf.mode_info,
            ref_frame_idx,
            ctx.frame_store,
            ctx.plane,
            base_x,
            base_y,
            pred_w,
            pred_h,
            bit_depth,
            ctx.subsampling_x,
            ctx.subsampling_y,
            ctx.frame_width,
            ctx.frame_height,
            leaf.interp_filter_x,
            leaf.interp_filter_y,
            wedge_buf.as_deref_mut(),
            warp,
            ctx.curr,
            ctx.curr_stride,
        )?;
    }
    Ok(())
}

/// §5.11.33 task-dispatcher → inter-intra reconstruction bridge — threads
/// the [`crate::cdf::PartitionWalker::compute_prediction`] dispatcher's
/// emitted inter-intra task list into the shared
/// [`reconstruct_inter_intra_block`] driver.
///
/// The §5.11.33 dispatcher emits a [`crate::cdf::ComputePredictionReadout`]
/// whose `is_inter_intra == true` arm carries, per plane, the intra-half
/// [`crate::cdf::PlanePredictionTask`] (the §7.11.3.14 blend's intra
/// operand) ahead of that plane's inter tasks (av1-spec p.82-83 lines
/// 5140-5190 — the `IsInterIntra` and `is_inter` guards are sibling and
/// non-exclusive). The dispatcher works against the parser's running
/// mode-info state and has no `CurrFrame[plane]` buffers; this bridge
/// pairs that emitted readout with the pixel-level [`PlaneReconContext`]s
/// and the per-block inter side (`RefFrame[0]`, `Mvs[..][0]`, the §5.11.28
/// wedge selectors) the §5.11.23 reader decoded, then drives the **same**
/// per-block [`reconstruct_inter_intra_block`] leaf the §5.11.33 frame-walk
/// drives. The two paths therefore converge on one reconstruction driver.
///
/// `readout` is validated as a genuine inter-intra readout: its
/// `is_inter_intra` flag must be set and it must carry at least one task
/// per plane in `planes`. A readout that is not inter-intra, or whose plane
/// coverage does not match `planes`, is a caller bug
/// ([`crate::Error::PartitionWalkOutOfRange`]).
///
/// As with [`reconstruct_inter_intra_block`], the caller must already have
/// written the §7.11.2 intra prediction (the readout's intra-half tasks)
/// into each plane's `curr` buffer before calling this bridge.
pub fn reconstruct_inter_intra_from_dispatch(
    readout: &crate::cdf::ComputePredictionReadout,
    leaf: &InterIntraLeaf,
    ref_frame_idx: &[u8],
    bit_depth: u8,
    warp: Option<&WarpDriverParams>,
    planes: &mut [PlaneReconContext<'_>],
) -> Result<(), crate::Error> {
    // The dispatcher must have taken the §5.11.33 `IsInterIntra` arm.
    if !readout.is_inter_intra {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    // The readout must cover at least the planes we are reconstructing: the
    // §5.11.33 inter-intra arm emits one intra-half task per visited plane,
    // so `num_planes_visited` is the plane count the dispatcher saw. A
    // shorter coverage than the supplied `planes` is a caller bug (the two
    // paths disagree on `HasChroma`).
    if (readout.num_planes_visited as usize) < planes.len() {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    // Every plane we drive must carry its intra-half task in the readout
    // (the §7.11.3.14 blend's intra operand the caller wrote into `curr`).
    // The intra-half task's `mode` is the §5.11.33 `interintra_mode → mode`
    // translation; the leaf's `interintra_mode` must agree with it so the
    // dispatcher's emitted intra half and this bridge's inter half describe
    // the same block.
    let expected_intra_mode = match leaf.mode_info.interintra_mode {
        II_V_PRED => crate::cdf::V_PRED as u8,
        II_H_PRED => crate::cdf::H_PRED as u8,
        II_DC_PRED => crate::cdf::DC_PRED as u8,
        _ => crate::cdf::SMOOTH_PRED as u8,
    };
    for ctx in planes.iter() {
        let intra_half = readout
            .tasks
            .iter()
            .find(|t| t.plane == ctx.plane && t.mode == expected_intra_mode);
        if intra_half.is_none() {
            return Err(crate::Error::PartitionWalkOutOfRange);
        }
    }

    reconstruct_inter_intra_block(leaf, ref_frame_idx, bit_depth, warp, planes)
}

// =====================================================================
// r293 §5.11.33 predict() / §7.11.3 frame-level inter reconstruction
// =====================================================================
//
// `reconstruct_inter_block` (above) closes the per-block arc: one
// decoded `(RefFrame[0], Mvs[..][0])` pair through `predict_inter`
// into one `CurrFrame[plane]` write region. The §5.11.33 `predict()`
// body (av1-spec p.82-83, lines 5127-5191) is the loop that drives
// that arithmetic across the whole decoded mode-info grid: for every
// decoded leaf block it iterates the planes and, on the inter arm,
// runs `predict_inter` for each prediction sub-block.
//
//   for ( plane = 0; plane < 1 + HasChroma * 2; plane++ ) {
//       ...
//       baseX = (MiCol >> subX) * MI_SIZE
//       baseY = (MiRow >> subY) * MI_SIZE
//       if ( is_inter ) {
//           predW = Block_Width[ MiSize ] >> subX
//           predH = Block_Height[ MiSize ] >> subY
//           ...                                  // someUseIntra arm
//           for ( y = 0; y < num4x4H * 4; y += predH )
//               for ( x = 0; x < num4x4W * 4; x += predW )
//                   predict_inter( plane, baseX + x, baseY + y,
//                                  predW, predH, candRow + r, candCol + c )
//       }
//   }
//
// `reconstruct_inter_frame` walks the persisted mode-info grids the
// §5.11.5 decode walker stamps (`MiSizes[]` / `IsInters[]` /
// `RefFrames[][][0]` / `Mvs[][][0]` / `InterpFilters[][][0..2]`,
// exposed via the `PartitionWalker` accessors) and, for every inter
// leaf whose `RefFrame[1] == NONE` (single forward reference, the
// SIMPLE translational arm), runs the §5.11.33 per-plane `predict_inter`
// loop into the supplied `CurrFrame[plane]` buffers via
// `reconstruct_inter_block`.
//
// Scope (single-ref translational SIMPLE arm only — the same arm
// `reconstruct_inter_block` / `predict_inter` already cover):
//   * `RefFrame[1] == NONE` (no compound second reference); a
//     compound leaf (`RefFrame[1] >= LAST_FRAME`) is skipped, leaving
//     its CurrFrame region untouched for a later compound driver.
//   * `RefFrame[1] == INTRA_FRAME` (inter-intra) is likewise skipped.
//   * Intra leaves (`IsInters[origin] == 0`) are skipped — they are
//     the §7.11.2 intra-reconstruction arm's responsibility.
// On the single-ref arm `IsInterIntra` is false and `someUseIntra`
// is false (a single inter reference is never `INTRA_FRAME`), so the
// §5.11.33 inner loop reduces to one `predict_inter` per plane with
// `predW = Block_Width[MiSize] >> subX`, `predH = Block_Height[MiSize]
// >> subY` and the block origin `(baseX, baseY)` — exactly the
// `reconstruct_inter_block` write region.

/// Per-plane §7.11.3.3 reference state a [`crate::PartitionWalker`]
/// bridge needs to drive one inter-intra block's pixel reconstruction
/// against its own tracked `CurrFrame[plane]` buffers.
///
/// The §5.11.5 syntax walker owns the `CurrFrame[plane]` sample buffers
/// (it stamps the §7.11.2 intra prediction into them via the §7.12.3
/// step-3 merge), but it does **not** own the §7.11.3.3 frame store —
/// the per-reference decoded-picture buffer is decoder-level state one
/// layer above the per-tile parser. So the inter half of the
/// §7.11.3.14 inter-intra blend is supplied to the walker bridge
/// ([`crate::PartitionWalker::reconstruct_inter_intra_into_curr_frame`])
/// through this descriptor: per plane, the resolved `FrameStore` slice
/// plus the `(frame_width, frame_height)` extents (LUMA samples, r405)
/// and subsampling the inter prediction reads, matching
/// [`PlaneReconContext`].
#[derive(Debug, Clone, Copy)]
pub struct PlaneRefSpec<'a> {
    /// `0` (Y), `1` (Cb), `2` (Cr). Must match a plane the walker has
    /// a tracked `CurrFrame[plane]` buffer for.
    pub plane: u8,
    /// §6.4.2 `subsampling_x` for this plane (`0` for plane `0`).
    pub subsampling_x: u8,
    /// §6.4.2 `subsampling_y`.
    pub subsampling_y: u8,
    /// This plane's §7.11.3.3 `FrameStore` slice (indexed by the
    /// resolved `refIdx`), per-plane resolved like
    /// [`RefFrameStoreEntry`].
    pub frame_store: &'a [RefFrameStoreEntry<'a>],
    /// §7.11.3 `FrameWidth` in LUMA samples (r405: no longer
    /// per-plane — it feeds only the §7.11.3.3 scale ratio, which is
    /// luma-derived for every plane).
    pub frame_width: u32,
    /// §7.11.3 `FrameHeight` in LUMA samples.
    pub frame_height: u32,
}

/// §7.11.3 per-plane `CurrFrame[plane]` reconstruction target — one
/// plane's output buffer plus the §7.11.3.3 reference-frame store the
/// [`reconstruct_inter_frame`] walk resolves `RefFrame[0]` against for
/// this plane.
///
/// The `frame_store` plane BUFFERS and the `curr` buffer are in this
/// plane's own sample units; the DIMENSION fields (`frame_width` /
/// `frame_height` and the [`RefFrameStoreEntry`] extents) are LUMA
/// samples (r405) — the §7.11.3.3/.4/.5 leaves derive the per-plane
/// values internally, preserving odd-luma-extent parity.
#[derive(Debug)]
pub struct PlaneReconContext<'a> {
    /// `0` (Y), `1` (Cb), `2` (Cr).
    pub plane: u8,
    /// §6.4.2 `subsampling_x` for this plane's chroma down-shift
    /// (`0` for plane `0`, the sequence value for `1` / `2`).
    pub subsampling_x: u8,
    /// §6.4.2 `subsampling_y`.
    pub subsampling_y: u8,
    /// This plane's §7.11.3.3 `FrameStore` slice (indexed by the
    /// resolved `refIdx`); per-plane resolved like
    /// [`RefFrameStoreEntry`].
    pub frame_store: &'a [RefFrameStoreEntry<'a>],
    /// §7.11.3 `FrameWidth` in LUMA samples (r405: no longer
    /// per-plane — it feeds only the §7.11.3.3 scale ratio, which is
    /// luma-derived for every plane).
    pub frame_width: u32,
    /// §7.11.3 `FrameHeight` in LUMA samples.
    pub frame_height: u32,
    /// `CurrFrame[plane]` output buffer (row-major, `curr_stride`
    /// columns), large enough for `frame_height` rows.
    pub curr: &'a mut [u16],
    /// Column stride of `curr` (`>= frame_width`).
    pub curr_stride: usize,
}

/// §7.11.3 decoded mode-info grid view — the persisted
/// `PartitionWalker` grids [`reconstruct_inter_frame`] walks. Each
/// slice is row-major over the `mi_rows × mi_cols` mode-info grid; the
/// per-cell layout matches the `PartitionWalker` accessors
/// (`MiSizes[]` one `usize` per cell; `IsInters[]` one `u8`;
/// `RefFrames[][][0..2]` and `Mvs[][][0..2][0..2]` two slots per cell;
/// `InterpFilters[][][0..2]` two slots per cell).
#[derive(Debug)]
pub struct InterModeInfoGrid<'a> {
    /// `MiSizes[ r ][ c ]` — `mi_sizes()[ r * mi_cols + c ]`.
    pub mi_sizes: &'a [usize],
    /// `IsInters[ r ][ c ]` — `is_inters()[ r * mi_cols + c ]`.
    pub is_inters: &'a [u8],
    /// `RefFrames[ r ][ c ][ slot ]` — `ref_frames()[ (r * mi_cols +
    /// c) * 2 + slot ]`.
    pub ref_frames: &'a [i8],
    /// `Mvs[ r ][ c ][ list ][ comp ]` — `mvs()[ ((r * mi_cols + c) *
    /// 2 + list) * 2 + comp ]`.
    pub mvs: &'a [i16],
    /// `InterpFilters[ r ][ c ][ dir ]` — `interp_filters()[ (r *
    /// mi_cols + c) * 2 + dir ]`.
    pub interp_filters: &'a [u8],
    /// §5.11.x decoded `compound_type` ordinal per cell —
    /// `comp_types()[ r * mi_cols + c ]`. Read only at a compound
    /// leaf's origin (`RefFrame[1] >= LAST_FRAME`); ignored on
    /// single-ref / inter-intra / intra cells. The [`COMPOUND_AVERAGE`]
    /// / [`COMPOUND_DISTANCE`] mask-free arms, the [`COMPOUND_WEDGE`]
    /// regenerable-mask arm, and the [`COMPOUND_DIFFWTD`] arm (whose
    /// §7.11.3.12 mask the driver derives internally from the two
    /// `preds[]` at `plane == 0` and persists for chroma) are all driven.
    /// The [`COMPOUND_INTRA`] arm is skipped (its §7.11.3.13
    /// intra-variant mask belongs to the interintra driver).
    pub compound_types: &'a [u8],
    /// §5.11.29 `wedge_index` per cell — `wedge_index()[ r * mi_cols +
    /// c ]`. Read only at a [`COMPOUND_WEDGE`] compound leaf's origin
    /// (paired with `wedge_signs`); ignored on every other cell. Length
    /// must be at least `mi_rows * mi_cols`.
    pub wedge_indices: &'a [u8],
    /// §5.11.29 `wedge_sign` per cell — `wedge_sign()[ r * mi_cols +
    /// c ]`. Read only at a [`COMPOUND_WEDGE`] compound leaf's origin
    /// (paired with `wedge_indices`); ignored on every other cell.
    /// Length must be at least `mi_rows * mi_cols`.
    pub wedge_signs: &'a [u8],
    /// §5.11.29 `mask_type` per cell — `mask_type()[ r * mi_cols + c ]`.
    /// Read only at a [`COMPOUND_DIFFWTD`] compound leaf's origin (`0` =
    /// `DIFFWTD_38`, `1` = `DIFFWTD_38_INV`); ignored on every other
    /// cell. Length must be at least `mi_rows * mi_cols`.
    pub mask_types: &'a [u8],
    /// §5.11.28 `interintra_mode` per cell — `interintra_mode()[ r *
    /// mi_cols + c ]`. Read only at an inter-intra leaf's origin
    /// (`RefFrame[1] == INTRA_FRAME`, `0..=3`); ignored on every other
    /// cell. Length must be at least `mi_rows * mi_cols`.
    pub interintra_modes: &'a [u8],
    /// §5.11.28 `wedge_interintra` per cell — `wedge_interintra()[ r *
    /// mi_cols + c ]` (`0` = non-wedge §7.11.3.13 intra-variant mask, `1`
    /// = §7.11.3.11 luma-grid wedge mask). Read only at an inter-intra
    /// leaf's origin; ignored elsewhere. Length must be at least
    /// `mi_rows * mi_cols`.
    pub wedge_interintras: &'a [u8],
    /// §5.11.28 inter-intra `wedge_index` per cell —
    /// `wedge_index()[ r * mi_cols + c ]`. Read only at an inter-intra
    /// leaf's origin whose `wedge_interintras` cell is `1` (the
    /// `wedge_sign` is fixed at `0` for the interintra arm per §5.11.28,
    /// so it is not carried). Length must be at least `mi_rows *
    /// mi_cols`. (Distinct from the compound `wedge_indices` slice.)
    pub interintra_wedge_indices: &'a [u8],
    /// §7.11.3.15 order-hint context the [`COMPOUND_DISTANCE`] arm
    /// derives `(FwdWeight, BckWeight)` from. The `order_hint_ref0` /
    /// `order_hint_ref1` fields are re-resolved per compound leaf from
    /// the cell's two `RefFrames[]` against this grid's
    /// `order_hints_by_ref` table (so the single
    /// [`CompoundOrderHintContext`] value here is filled per leaf — see
    /// [`reconstruct_inter_frame`]).
    pub order_hint_bits: u32,
    /// §5.9.2 `OrderHint` of the frame being decoded.
    pub current_order_hint: i32,
    /// `OrderHints[ ref ]` for `ref` in `LAST_FRAME..=ALTREF_FRAME`
    /// (1..=7) — the per-reference output order hints the
    /// [`COMPOUND_DISTANCE`] arm reads via each compound leaf's
    /// `RefFrame[ refList ]`. Indexed by the raw `RefFrame` value
    /// (slot 0 unused); length must be at least `ALTREF_FRAME + 1`.
    pub order_hints_by_ref: &'a [i32],
    /// `MiRows`.
    pub mi_rows: u32,
    /// `MiCols`.
    pub mi_cols: u32,
    /// §7.11.3 `BitDepth`.
    pub bit_depth: u8,
    /// §5.11.27 warped-motion context — `Some(_)` enables the
    /// `motion_mode == WARPED_CAUSAL` arm of the single-reference walk;
    /// `None` (the default) drives every single-ref leaf translationally
    /// (the pre-r338 behaviour). When `Some(_)`, the per-cell
    /// `motion_modes` ordinal selects between the SIMPLE translational
    /// path ([`reconstruct_inter_block`]) and the §7.11.3.5 warp path
    /// ([`reconstruct_inter_block_warp`]). See [`GridWarpContext`].
    pub warp: Option<GridWarpContext<'a>>,
    /// §5.11.27 OBMC context — `Some(_)` enables the `motion_mode ==
    /// OBMC` arm of the single-reference walk; `None` (the default)
    /// drives every non-warp single-ref leaf translationally (the
    /// pre-r378 behaviour). When `Some(_)`, a single-ref leaf whose
    /// per-cell `motion_modes` ordinal is `OBMC` is dispatched to
    /// [`reconstruct_inter_block_obmc`] with the §7.11.3.9 above / left
    /// neighbour lists resolved from this grid's own `mi_sizes` /
    /// `ref_frames` / `mvs` slices. See [`GridObmcContext`]. The warp arm
    /// is consulted first: a `WARPED_CAUSAL` leaf takes the warp path even
    /// when `obmc` is `Some(_)` (the two `motion_mode` ordinals are
    /// mutually exclusive at one cell, so the precedence is moot in
    /// practice).
    pub obmc: Option<GridObmcContext<'a>>,
}

/// §5.11.27 / §7.11.3.5-8 per-frame warped-motion context for
/// [`InterModeInfoGrid`] — the slices [`reconstruct_inter_frame`]'s
/// single-reference arm consults to dispatch a leaf's `motion_mode ==
/// WARPED_CAUSAL` to [`reconstruct_inter_block_warp`].
///
/// Like the grid's compound side-data (`wedge_indices` / `mask_types` /
/// …), the warp context carries the **already-resolved** decode output
/// rather than re-running the §5.11.27 `read_motion_mode` cascade or the
/// §7.10.4 `find_warp_samples` / §7.11.3.8 `warp_estimation` machinery
/// (which the mode-info grid does not model). The caller (the
/// `PartitionWalker` bridge) supplies the decoded `motion_mode` per cell
/// plus the per-cell LOCALWARP fit and the per-RefFrame global-motion
/// model; this walk assembles a [`WarpDriverParams`] per warped leaf and
/// hands it to the §7.11.3.5 driver.
#[derive(Debug, Clone, Copy)]
pub struct GridWarpContext<'a> {
    /// §5.11.27 decoded `motion_mode` ordinal per cell
    /// ([`crate::cdf::MOTION_MODE_SIMPLE`] / `MOTION_MODE_OBMC` /
    /// `MOTION_MODE_WARPED_CAUSAL`) — `motion_modes[ r * mi_cols + c ]`.
    /// Read only at a single-reference inter leaf's origin. A
    /// `WARPED_CAUSAL` value routes the leaf to
    /// [`reconstruct_inter_block_warp`]; every other value (including
    /// `OBMC`, whose §7.11.3.9 neighbour walk this single-ref arm does
    /// not yet drive) takes the translational
    /// [`reconstruct_inter_block`] path. Length must be at least
    /// `mi_rows * mi_cols`.
    pub motion_modes: &'a [u8],
    /// §7.11.3.8 `LocalWarpParams[ 0..6 ]` per cell —
    /// `local_warp_params[ (r * mi_cols + c) * 6 + k ]`. The least-squares
    /// affine fit the §7.10.4 / §7.11.3.8 decode produced for this leaf's
    /// LOCALWARP arm. Read only at a `WARPED_CAUSAL` single-ref leaf's
    /// origin (`plane == 0`; the §5.11.27 LOCALWARP arm is luma-only).
    /// Length must be at least `mi_rows * mi_cols * 6`.
    pub local_warp_params: &'a [i32],
    /// §7.11.3.8 `LocalValid` bit per cell —
    /// `local_warp_valid[ r * mi_cols + c ]` (`0` / `1`). `false` flips
    /// the §7.11.3.1 step-7 LOCALWARP arm to `useWarp = 0`
    /// (translational fallback). Length must be at least
    /// `mi_rows * mi_cols`.
    pub local_warp_valid: &'a [u8],
    /// §5.11.x decoded `YMode` per cell — `y_modes[ r * mi_cols + c ]`.
    /// The §7.11.3.1 step-7 global-warp gate (`useWarp = 2`) requires
    /// `YMode ∈ {GLOBALMV, GLOBAL_GLOBALMV}`. Read only at a single-ref
    /// inter leaf's origin. Length must be at least `mi_rows * mi_cols`.
    pub y_modes: &'a [u8],
    /// §5.9.24 `GmType[ ref ]` for `ref` in `INTRA_FRAME..=ALTREF_FRAME`
    /// — `gm_types[ ref ]`. The step-7 `useWarp = 2` gate requires
    /// `GmType[ RefFrame[0] ] > TRANSLATION`. Indexed by the raw
    /// `RefFrame` value; length must be at least `ALTREF_FRAME + 1`.
    pub gm_types: &'a [u8],
    /// §5.9.24 `gm_params[ ref ][ 0..6 ]` — `gm_params[ ref * 6 + k ]`.
    /// The per-RefFrame global-motion affine matrix the GLOBAL_GLOBALMV
    /// `useWarp == 2` arm feeds to §7.11.3.5 `block_warp`. Indexed by the
    /// raw `RefFrame` value; length must be at least
    /// `(ALTREF_FRAME + 1) * 6`.
    pub gm_params: &'a [i32],
    /// §5.9.5 `force_integer_mv` frame flag — when `true`, the §7.11.3.1
    /// step-7 derivation forces `useWarp = 0` on every leaf regardless of
    /// `motion_mode`.
    pub force_integer_mv: bool,
    /// §5.11.27 `is_scaled( refFrame )` per raw `RefFrame` value
    /// (`is_scaled[ ref ]`, entry 0 unused) — the §7.11.3.1 step-7
    /// `useWarp = 2` global gate requires `is_scaled( refFrame ) ==
    /// 0`. Length must be at least `ALTREF_FRAME + 1`.
    pub is_scaled: &'a [bool],
}

/// §5.11.27 / §7.11.3.9-10 per-frame OBMC context for
/// [`InterModeInfoGrid`] — `Some(_)` enables the `motion_mode == OBMC`
/// arm of the single-reference frame walk, dispatching a decoded OBMC
/// leaf to [`reconstruct_inter_block_obmc`] with the §7.11.3.9 above /
/// left neighbour lists [`reconstruct_inter_frame`] resolves internally
/// from the grid's own `mi_sizes` / `ref_frames` / `mvs` slices.
///
/// Unlike the per-block [`ObmcParams`] bundle (which carries the
/// caller-resolved neighbour lists ready-made), this grid context carries
/// only the decoded `motion_mode` ordinal per cell plus the §5.11.18
/// `AvailU` / `AvailL` availability bits the frame walk needs to gate the
/// two §7.11.3.9 passes. The frame walk itself runs the §7.11.3.9 outer
/// `(x4, y4, step4)` neighbour scan against the grid (candidate cell
/// `(MiRow - 1, x4 | 1)` for the above-pass, `(y4 | 1, MiCol - 1)` for
/// the left-pass), filters on `RefFrames[cand][0] > INTRA_FRAME`, and
/// resolves each qualifying neighbour's per-plane reference buffer through
/// the same `ref_frame_idx[..]` → `frame_store` indirection the leaf's own
/// prediction uses — so the caller supplies decode output, not §7
/// mi-grid state.
#[derive(Debug, Clone, Copy)]
pub struct GridObmcContext<'a> {
    /// §5.11.27 decoded `motion_mode` ordinal per cell
    /// ([`crate::cdf::MOTION_MODE_SIMPLE`] / `MOTION_MODE_OBMC` /
    /// `MOTION_MODE_WARPED_CAUSAL`) — `motion_modes[ r * mi_cols + c ]`.
    /// Read only at a single-reference inter leaf's origin. An `OBMC`
    /// value routes the leaf to [`reconstruct_inter_block_obmc`]; every
    /// other value takes the translational [`reconstruct_inter_block`] /
    /// warp path. Length must be at least `mi_rows * mi_cols`. (This is
    /// the same `motion_modes` grid [`GridWarpContext`] reads; the two
    /// contexts may share one backing slice — a `WARPED_CAUSAL` cell is
    /// claimed by the warp arm first, an `OBMC` cell by this arm.)
    pub motion_modes: &'a [u8],
    /// §5.11.18 `AvailU[ r * mi_cols + c ]` per cell — the above-neighbour
    /// availability bit (`0` / `1`) the §7.11.3.9 above-pass is gated on
    /// (av1-spec p.275 line 15301). Read at the leaf origin. A leaf on the
    /// frame's top edge has `AvailU == 0` (no above-pass). Length must be
    /// at least `mi_rows * mi_cols`.
    pub avail_u: &'a [u8],
    /// §5.11.18 `AvailL[ r * mi_cols + c ]` per cell — the left-neighbour
    /// availability bit (`0` / `1`) the §7.11.3.9 left-pass is gated on
    /// (av1-spec p.275 line 15325). Read at the leaf origin. A leaf on the
    /// frame's left edge has `AvailL == 0` (no left-pass). Length must be
    /// at least `mi_rows * mi_cols`.
    pub avail_l: &'a [u8],
}

/// §7.11.3.9 OBMC frame-walk dispatch for one decoded `motion_mode ==
/// OBMC` single-reference leaf at grid origin `(mi_row, mi_col)` of size
/// `mi_size` with forward reference `ref_frame0`.
///
/// For each plane the helper resolves the §7.11.3.9 above-pass and
/// left-pass neighbour candidate lists from the grid's own
/// `mi_sizes` / `ref_frames` / `mvs` slices — running the spec's outer
/// `(x4, y4, step4, nLimit)` scan (av1-spec p.275 lines 15301-15346):
///
///   * above-pass: `x4` from `MiCol`, candidate `(MiRow - 1, x4 | 1)`,
///     `step4 = Clip3(2, 16, Num_4x4_Blocks_Wide[ candSz ])`, gated by
///     `AvailU && get_plane_residual_size(MiSize, plane) >= BLOCK_8X8`
///     and `nLimit = Min(4, Mi_Width_Log2[ MiSize ])`;
///   * left-pass: `y4` from `MiRow`, candidate `(y4 | 1, MiCol - 1)`,
///     `step4 = Clip3(2, 16, Num_4x4_Blocks_High[ candSz ])`, gated by
///     `AvailL` and `nLimit = Min(4, Mi_Height_Log2[ MiSize ])`,
///
/// keeping only candidates whose `RefFrames[cand][0] > INTRA_FRAME`. Each
/// kept candidate's `Mvs[cand][0]` motion vector and its
/// `ref_frame_idx[ candRefFrame - LAST_FRAME ]` → `frame_store[refIdx]`
/// per-plane reference buffer are bundled into an [`ObmcNeighbour`]; the
/// assembled [`ObmcParams`] is handed to [`reconstruct_inter_block_obmc`]
/// for that plane (which runs the §7.11.3.9-10 overlap blend over the
/// leaf's own §7.11.3.1 prediction).
///
/// The neighbour lists are resolved per plane because the
/// [`ObmcNeighbour::bundle`] is plane-specific (the `(plane,
/// subsampling_*)` reference buffer differs between luma and chroma); the
/// `step4` advances and the `RefFrames[cand][0] > INTRA_FRAME` gate are
/// plane-invariant (driven off the luma mi-grid), so the candidate
/// *sequence* is identical across planes — only the bundle resolution
/// changes.
#[allow(clippy::too_many_arguments)]
fn obmc_dispatch_leaf(
    grid: &InterModeInfoGrid<'_>,
    oc: &GridObmcContext<'_>,
    ref_frame_idx: &[u8],
    planes: &mut [PlaneReconContext<'_>],
    mi_row: usize,
    mi_col: usize,
    mi_size: usize,
    ref_frame0: i8,
) -> Result<(), crate::Error> {
    let mi_rows = grid.mi_rows as usize;
    let mi_cols = grid.mi_cols as usize;
    let origin = mi_row * mi_cols + mi_col;

    // The OBMC leaf's own block is single-reference translational for its
    // own MV; `ref_frame0` / `Mvs[origin][0]` drive the base prediction.
    let block_ref_frame = ref_frame0;
    if !(crate::uncompressed_header_tail::LAST_FRAME as i8
        ..=crate::uncompressed_header_tail::ALTREF_FRAME as i8)
        .contains(&block_ref_frame)
    {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let block_mode_info = InterModeInfo {
        ref_frame: block_ref_frame as u8,
        mv: [grid.mvs[origin * 4], grid.mvs[origin * 4 + 1]],
    };

    let avail_u = oc.avail_u[origin] != 0;
    let avail_l = oc.avail_l[origin] != 0;

    // §7.11.3.4: the HORIZONTAL (`intermediate[][]`) pass reads
    // `InterpFilters[ candRow ][ candCol ][ 1 ]` (grid slot 1) and the
    // VERTICAL (`pred[][]`) pass `InterpFilters[ .. ][ 0 ]` (slot 0).
    // Distinguishable only on `enable_dual_filter` streams whose two
    // per-direction filters differ (r394 dual-filter fix — every
    // single-filter stream stamps both slots equal).
    let interp_x = grid.interp_filters[origin * 2 + 1];
    let interp_y = grid.interp_filters[origin * 2];

    const INTRA_FRAME_REF0: i8 = crate::uncompressed_header_tail::INTRA_FRAME as i8;

    // §7.11.3.9 `step4 = Clip3(2, 16, Num_4x4_Blocks_{Wide,High}[candSz])`.
    let clip4 = |n: usize| -> usize { n.clamp(2, 16) };

    for ctx in planes.iter_mut() {
        let p = ctx.plane;
        let sub_x = if p > 0 { ctx.subsampling_x } else { 0 };
        let sub_y = if p > 0 { ctx.subsampling_y } else { 0 };

        // §7.11.3.9 above-pass gate (line 15302): only fires when
        // `get_plane_residual_size(MiSize, plane) >= BLOCK_8X8`.
        let plane_sz = crate::cdf::get_plane_residual_size(mi_size, p, sub_x, sub_y)
            .ok_or(crate::Error::PartitionWalkOutOfRange)?;
        let above_gate = avail_u && plane_sz >= crate::cdf::BLOCK_8X8;

        // ----- above-pass neighbour list (line 15301-15324) -----
        let mut above: Vec<ObmcNeighbour<'_>> = Vec::new();
        if above_gate {
            let w4 = crate::cdf::num_4x4_blocks_wide(mi_size);
            let n_limit = core::cmp::min(4, crate::cdf::mi_width_log2(mi_size));
            let x_end = core::cmp::min(mi_cols, mi_col + w4);
            let cand_row = mi_row.wrapping_sub(1); // MiRow - 1 (AvailU ⇒ MiRow >= 1)
            let mut x4 = mi_col;
            let mut n_count = 0usize;
            while n_count < n_limit && x4 < x_end {
                let cand_col = x4 | 1;
                // `candCol` may round up past the leaf; clamp into the grid
                // (the §5.11.5 fill stamped a valid leaf there).
                let cc = cand_col.min(mi_cols.saturating_sub(1));
                let cand = cand_row * mi_cols + cc;
                let cand_sz = grid.mi_sizes[cand];
                let step4 = if cand_sz < crate::cdf::BLOCK_SIZES {
                    clip4(crate::cdf::num_4x4_blocks_wide(cand_sz))
                } else {
                    2
                };
                if grid.ref_frames[cand * 2] > INTRA_FRAME_REF0 {
                    n_count += 1;
                    let bundle = resolve_obmc_neighbour_bundle(
                        grid.ref_frames[cand * 2],
                        [grid.mvs[cand * 4], grid.mvs[cand * 4 + 1]],
                        ref_frame_idx,
                        ctx.frame_store,
                    )?;
                    above.push(ObmcNeighbour {
                        bundle,
                        step4: step4 as u8,
                        // §7.11.3.4 at (candRow, candCol): slot 1 =
                        // horizontal, slot 0 = vertical.
                        interp_filter_x: grid.interp_filters[cand * 2 + 1],
                        interp_filter_y: grid.interp_filters[cand * 2],
                        axis_pos4: x4 as u16,
                    });
                }
                x4 += step4;
            }
        }

        // ----- left-pass neighbour list (line 15325-15346) -----
        // The left-pass is unconditional on the §7.11.3.9 "small blocks →
        // left neighbour only" carve-out; only `AvailL` gates it.
        let mut left: Vec<ObmcNeighbour<'_>> = Vec::new();
        if avail_l {
            let h4 = crate::cdf::num_4x4_blocks_high(mi_size);
            let n_limit = core::cmp::min(4, crate::cdf::mi_height_log2(mi_size));
            let y_end = core::cmp::min(mi_rows, mi_row + h4);
            let cand_col = mi_col.wrapping_sub(1); // MiCol - 1 (AvailL ⇒ MiCol >= 1)
            let mut y4 = mi_row;
            let mut n_count = 0usize;
            while n_count < n_limit && y4 < y_end {
                let cand_row = y4 | 1;
                let cr = cand_row.min(mi_rows.saturating_sub(1));
                let cand = cr * mi_cols + cand_col;
                let cand_sz = grid.mi_sizes[cand];
                let step4 = if cand_sz < crate::cdf::BLOCK_SIZES {
                    clip4(crate::cdf::num_4x4_blocks_high(cand_sz))
                } else {
                    2
                };
                if grid.ref_frames[cand * 2] > INTRA_FRAME_REF0 {
                    n_count += 1;
                    let bundle = resolve_obmc_neighbour_bundle(
                        grid.ref_frames[cand * 2],
                        [grid.mvs[cand * 4], grid.mvs[cand * 4 + 1]],
                        ref_frame_idx,
                        ctx.frame_store,
                    )?;
                    left.push(ObmcNeighbour {
                        bundle,
                        step4: step4 as u8,
                        interp_filter_x: grid.interp_filters[cand * 2 + 1],
                        interp_filter_y: grid.interp_filters[cand * 2],
                        axis_pos4: y4 as u16,
                    });
                }
                y4 += step4;
            }
        }

        let obmc = ObmcParams {
            mi_row: mi_row as u32,
            mi_col: mi_col as u32,
            mi_cols: grid.mi_cols,
            mi_rows: grid.mi_rows,
            mi_width_log2: crate::cdf::mi_width_log2(mi_size) as u8,
            mi_height_log2: crate::cdf::mi_height_log2(mi_size) as u8,
            avail_u,
            avail_l,
            plane_residual_size_ge_block_8x8: above_gate,
            above_neighbours: &above,
            left_neighbours: &left,
        };

        // Plane-space block origin + size (§5.11.33 lines 5135-5136 / the
        // §7.11.3.1 `(x, y, w, h)` write region — OBMC has no
        // `someUseIntra` split, so one call covers the whole plane block).
        let x = ((mi_col >> sub_x) * crate::cdf::MI_SIZE) as i32;
        let y = ((mi_row >> sub_y) * crate::cdf::MI_SIZE) as i32;
        let w = crate::cdf::block_width(mi_size) >> sub_x;
        let h = crate::cdf::block_height(mi_size) >> sub_y;

        reconstruct_inter_block_obmc(
            block_mode_info,
            &obmc,
            ref_frame_idx,
            ctx.frame_store,
            p,
            x,
            y,
            w,
            h,
            grid.bit_depth,
            ctx.subsampling_x,
            ctx.subsampling_y,
            ctx.frame_width,
            ctx.frame_height,
            interp_x,
            interp_y,
            ctx.curr,
            ctx.curr_stride,
        )?;
    }

    Ok(())
}

/// §7.11.3.9 step 2 / 5: resolve one OBMC neighbour candidate's
/// `RefFrames[cand][0]` + `Mvs[cand][0]` into the plane-resolved
/// [`PredictInterRef`] bundle the driver's overlap walk consumes —
/// `refIdx = ref_frame_idx[ candRefFrame - LAST_FRAME ]`, then
/// `frame_store[refIdx]` (already the per-plane store for the plane being
/// reconstructed).
///
/// The caller has already confirmed `cand_ref_frame > INTRA_FRAME`; this
/// helper additionally bounds it at `ALTREF_FRAME` and validates the
/// resolved `refIdx` against `frame_store`, returning
/// [`crate::Error::PartitionWalkOutOfRange`] for an out-of-range value
/// (caller-bug grid).
fn resolve_obmc_neighbour_bundle<'a>(
    cand_ref_frame: i8,
    mv: [i16; 2],
    ref_frame_idx: &[u8],
    frame_store: &[RefFrameStoreEntry<'a>],
) -> Result<PredictInterRef<'a>, crate::Error> {
    let rf = cand_ref_frame as usize;
    if !(crate::uncompressed_header_tail::LAST_FRAME
        ..=crate::uncompressed_header_tail::ALTREF_FRAME)
        .contains(&rf)
    {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    let slot = rf - crate::uncompressed_header_tail::LAST_FRAME;
    let ref_idx = *ref_frame_idx
        .get(slot)
        .ok_or(crate::Error::PartitionWalkOutOfRange)? as usize;
    let entry = frame_store
        .get(ref_idx)
        .ok_or(crate::Error::PartitionWalkOutOfRange)?;
    Ok(PredictInterRef {
        ref_plane: entry.plane,
        ref_stride: entry.stride,
        ref_upscaled_width: entry.upscaled_width,
        ref_width: entry.width,
        ref_height: entry.height,
        mv,
    })
}

/// §5.11.33 `predict()` frame-level inter reconstruction — walks the
/// decoded mode-info grid and reconstructs every single-reference
/// translational inter leaf into its `CurrFrame[plane]` buffers.
///
/// This is the §5.11.33 `predict()` body (av1-spec p.82-83, lines
/// 5127-5191) on the single-forward-reference translational arm: for
/// each decoded leaf block (top-left of its `MiSize` footprint) whose
/// `IsInters == 1` and `RefFrame[1] == NONE`, it iterates the supplied
/// planes and runs the §7.11.3 per-plane prediction via
/// [`reconstruct_inter_block`], including the full §5.11.33 inner
/// `predict_inter` tiling loop with the `someUseIntra` scan:
///
///   * `baseX = (MiCol >> subX) * MI_SIZE`,
///     `baseY = (MiRow >> subY) * MI_SIZE` (the plane-space block
///     origin, av1-spec lines 5135-5136).
///   * `candRow = (MiRow >> subY) << subY`,
///     `candCol = (MiCol >> subX) << subX` (the chroma-collocated
///     candidate anchor, lines 5137-5138).
///   * `someUseIntra` scan (lines 5168-5172): the
///     `(num4x4H << subY) × (num4x4W << subX)` luma cells the plane
///     block collocates with are tested for
///     `RefFrames[candRow+r][candCol+c][0] == INTRA_FRAME`. On a hit
///     (lines 5173-5178) the prediction splits into `num4x4{W,H}`
///     4-sample sub-blocks re-anchored at the unsubsampled
///     `(MiRow, MiCol)`, so each chroma sub-block reads its own
///     collocated luma candidate's MV (the §7.11.3.1 `predict_inter`
///     step-5/-8 read `RefFrames[cand][0]` / `Mvs[cand][0]`). Off the
///     split, `predW = Block_Width[MiSize] >> subX`,
///     `predH = Block_Height[MiSize] >> subY` and the candidate stays
///     the subsampled anchor (lines 5166-5167). On luma
///     (`subX = subY = 0`) the anchor already equals `(MiRow, MiCol)`,
///     so the two paths coincide. The canonical `someUseIntra == 1`
///     case is a sub-8×8 chroma block under 4:2:0 whose bottom-right
///     `HasChroma` leaf collocates with sibling intra leaves: it then
///     correctly predicts from the bottom-right block's MV.
///   * the inner `for y/x` loop (lines 5179-5189) tiles the
///     `num4x4H*4 × num4x4W*4` plane region with `predW × predH`
///     sub-blocks.
///
/// **Leaf detection.** The §5.11.5 walker stamps each leaf's `MiSize`
/// over its whole `bh4 × bw4` footprint, so a block origin is the
/// top-left cell of its rectangle. Walking the grid row-major, the
/// top-left of any rectangle is the first not-yet-consumed cell of
/// that rectangle reached — so this walk marks each leaf's footprint
/// consumed on first sight and processes a cell only the once. Cells
/// carrying [`crate::cdf::BLOCK_INVALID`] (no leaf covered them) are
/// skipped.
///
/// Compound leaves (`RefFrame[1] >= LAST_FRAME`) carrying the mask-free
/// [`COMPOUND_AVERAGE`] / [`COMPOUND_DISTANCE`] combine types, the
/// regenerable-mask [`COMPOUND_WEDGE`] type, or the [`COMPOUND_DIFFWTD`]
/// type are driven through [`reconstruct_inter_block_compound`]: both
/// references are resolved, the §7.11.3.15 distance weights are derived
/// per leaf from `order_hints_by_ref[ RefFrame[0/1] ]` (DISTANCE), the
/// §7.11.3.11 wedge mask is regenerated per leaf from
/// `wedge_indices[origin]` / `wedge_signs[origin]` (WEDGE), and for
/// DIFFWTD the §7.11.3.12 mask is derived inside the driver from the two
/// `preds[]` at `plane == 0` (the `mask_type` toggle comes from
/// `mask_types[origin]`) into a per-leaf luma-grid scratch buffer reused
/// for the chroma planes — then `predict_inter` forms the two-reference
/// combine.
///
/// Inter-intra leaves (`RefFrame[1] == INTRA_FRAME`, `isCompound == 0`)
/// are driven through [`reconstruct_inter_block_interintra`]: one inter
/// prediction is formed from `RefFrame[0]` and blended (§7.11.3.14)
/// against the §7.11.2 intra prediction **already present in the plane's
/// `curr` buffer** (av1-spec p.83 lines 5141-5163 run `predict_intra`
/// before `predict_inter` on this arm; p.284 line 15786 reads it as
/// `pred1 = CurrFrame[plane][..]`). The walk reads
/// `interintra_modes[origin]` (§5.11.28 mode), `wedge_interintras[origin]`
/// (the §7.11.3.13 intra-variant vs §7.11.3.11 luma-grid wedge sub-arm
/// selector), and `interintra_wedge_indices[origin]` (the wedge codebook
/// ordinal, with `wedge_sign` fixed at `0` per §5.11.28). **The caller
/// must have written the §7.11.2 intra prediction into each plane's `curr`
/// buffer for every inter-intra leaf's footprint before calling this
/// function** — this walk supplies only the inter half of the blend.
///
/// **Scope / skips (untouched CurrFrame regions, for a later driver):**
///   * intra leaves (`IsInters == 0`);
///   * compound leaves carrying [`COMPOUND_INTRA`] — a *two-inter-ref*
///     `COMPOUND_INTRA` `compound_type` is never produced by the spec
///     (the intra-variant mask only arises on the inter-intra arm), so a
///     compound leaf so tagged is rejected.
///
/// The §7.11.3.1 horizontal / vertical interpolation filters are read
/// per leaf from `InterpFilters[origin][0..2]` (the §5.11.x decoded
/// `interp_filter[dir]` the walker stamped).
///
/// Returns [`crate::Error::PartitionWalkOutOfRange`] if a grid slice
/// is too short for `mi_rows * mi_cols`, if a leaf carries an
/// out-of-range `MiSize`, or for anything [`reconstruct_inter_block`]
/// itself rejects (out-of-range `ref_frame` / resolved `refIdx`, a
/// `CurrFrame` plane too small for the write region, …).
pub fn reconstruct_inter_frame(
    grid: &InterModeInfoGrid<'_>,
    ref_frame_idx: &[u8],
    planes: &mut [PlaneReconContext<'_>],
) -> Result<(), crate::Error> {
    let mi_rows = grid.mi_rows as usize;
    let mi_cols = grid.mi_cols as usize;
    let cells = mi_rows
        .checked_mul(mi_cols)
        .ok_or(crate::Error::PartitionWalkOutOfRange)?;

    // Grid-slice length guards: every accessor below indexes within
    // `cells` (×2 / ×4 for the multi-slot grids), so a short slice is
    // a caller bug.
    if grid.mi_sizes.len() < cells
        || grid.is_inters.len() < cells
        || grid.ref_frames.len() < cells * 2
        || grid.mvs.len() < cells * 4
        || grid.interp_filters.len() < cells * 2
        || grid.compound_types.len() < cells
        || grid.wedge_indices.len() < cells
        || grid.wedge_signs.len() < cells
        || grid.mask_types.len() < cells
        || grid.interintra_modes.len() < cells
        || grid.wedge_interintras.len() < cells
        || grid.interintra_wedge_indices.len() < cells
    {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    // The compound-distance arm reads `order_hints_by_ref[ RefFrame ]`
    // for `RefFrame` up to `ALTREF_FRAME`; a short table is a caller bug.
    if grid.order_hints_by_ref.len() <= crate::uncompressed_header_tail::ALTREF_FRAME {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    // §5.11.27 warp-context slice guards (only when the WARPED_CAUSAL arm
    // is enabled). The per-cell slices index within `cells` (×6 for the
    // local-warp matrix); the per-RefFrame global-motion tables index up
    // to `ALTREF_FRAME` (×6 for the matrix). A short slice is a caller
    // bug.
    if let Some(wc) = grid.warp.as_ref() {
        let refs = crate::uncompressed_header_tail::ALTREF_FRAME + 1;
        // r464 — an EMPTY `local_warp_params` is the lazily
        // materialised all-zero grid (no WARPED_CAUSAL leaf stamped a
        // fit yet; every read below sees 0).
        if wc.motion_modes.len() < cells
            || (!wc.local_warp_params.is_empty() && wc.local_warp_params.len() < cells * 6)
            || wc.local_warp_valid.len() < cells
            || wc.y_modes.len() < cells
            || wc.gm_types.len() < refs
            || wc.gm_params.len() < refs * 6
        {
            return Err(crate::Error::PartitionWalkOutOfRange);
        }
    }
    // §7.11.3.9 OBMC-context slice guards (only when the OBMC arm is
    // enabled). The per-cell slices index within `cells`. A short slice
    // is a caller bug.
    if let Some(oc) = grid.obmc.as_ref() {
        if oc.motion_modes.len() < cells || oc.avail_u.len() < cells || oc.avail_l.len() < cells {
            return Err(crate::Error::PartitionWalkOutOfRange);
        }
    }

    // §5.11.5 leaf-origin detection: a leaf's `MiSize` is stamped over
    // its whole rectangle, so in row-major order the first unconsumed
    // cell of any rectangle is its top-left. `consumed[cell]` marks
    // cells already claimed by a processed leaf.
    let mut consumed = vec![false; cells];

    for mi_row in 0..mi_rows {
        for mi_col in 0..mi_cols {
            let origin = mi_row * mi_cols + mi_col;
            if consumed[origin] {
                continue;
            }
            let mi_size = grid.mi_sizes[origin];
            if mi_size == crate::cdf::BLOCK_INVALID {
                // No leaf covered this cell; nothing to consume. (A
                // BLOCK_INVALID hole is a single cell — a real leaf
                // always has a valid MiSize at its origin.)
                continue;
            }
            if mi_size >= crate::cdf::BLOCK_SIZES {
                return Err(crate::Error::PartitionWalkOutOfRange);
            }
            let bw4 = crate::cdf::num_4x4_blocks_wide(mi_size);
            let bh4 = crate::cdf::num_4x4_blocks_high(mi_size);

            // Claim the whole `bh4 × bw4` footprint (clipped to the
            // grid extent, exactly like the §5.11.5 grid-fill loops),
            // so its non-origin cells are not re-processed.
            for dr in 0..bh4 {
                let rr = mi_row + dr;
                if rr >= mi_rows {
                    break;
                }
                for dc in 0..bw4 {
                    let cc = mi_col + dc;
                    if cc >= mi_cols {
                        break;
                    }
                    consumed[rr * mi_cols + cc] = true;
                }
            }

            reconstruct_inter_leaf_at(grid, ref_frame_idx, planes, mi_row, mi_col)?;
        }
    }

    Ok(())
}

/// §5.11.33 single-leaf inter reconstruction — the per-leaf body of
/// [`reconstruct_inter_frame`], invocable at one leaf origin so the
/// §5.11.5 syntax walker can run the spec's in-walk `compute_prediction()`
/// (§5.11.5 orders it per block, between `mode_info()` and `residual()`,
/// so a later intra block's §7.11.2 neighbour reads observe this leaf's
/// motion-compensated pixels).
///
/// `(mi_row, mi_col)` is the leaf origin; the leaf's `MiSize` is read
/// from `grid.mi_sizes` at the origin cell. Intra leaves (`IsInters ==
/// 0`) return without touching the planes (the §7.11.2 arm owns them).
/// The caller guarantees the grid slices cover `mi_rows * mi_cols`
/// cells ([`reconstruct_inter_frame`] guards them once per frame; the
/// in-walk caller sizes its walker grids at construction).
///
/// Error surface matches [`reconstruct_inter_frame`] (out-of-range
/// `MiSize` / `RefFrame` / resolved `refIdx`, a too-small `curr`
/// plane, …).
pub(crate) fn reconstruct_inter_leaf_at(
    grid: &InterModeInfoGrid<'_>,
    ref_frame_idx: &[u8],
    planes: &mut [PlaneReconContext<'_>],
    mi_row: usize,
    mi_col: usize,
) -> Result<(), crate::Error> {
    let mi_rows = grid.mi_rows as usize;
    let mi_cols = grid.mi_cols as usize;
    let origin = mi_row * mi_cols + mi_col;
    let mi_size = grid.mi_sizes[origin];
    if mi_size >= crate::cdf::BLOCK_SIZES {
        return Err(crate::Error::PartitionWalkOutOfRange);
    }
    // --- §5.11.33 leaf gating: inter arm. ---
    if grid.is_inters[origin] == 0 {
        return Ok(()); // intra leaf — §7.11.2 arm's responsibility.
    }
    let ref_frame0 = grid.ref_frames[origin * 2];
    let ref_frame1 = grid.ref_frames[origin * 2 + 1];
    // `RefFrame[1]` selects the §7.11.3.1 combine arm:
    //   * `NONE` (the `-1` sentinel the §5.11.18 grid pre-fill
    //     stamps into slot 1) ⇒ single forward reference.
    //   * `>= LAST_FRAME` (1..=7) ⇒ compound two-reference.
    //   * `INTRA_FRAME` (0) ⇒ inter-intra — blended against the
    //     §7.11.2 intra prediction already in `CurrFrame[plane]`.
    const NONE_REF_FRAME: i8 = -1;
    const INTRA_FRAME_REF: i8 = crate::uncompressed_header_tail::INTRA_FRAME as i8;
    let is_compound_leaf = ref_frame1 >= crate::uncompressed_header_tail::LAST_FRAME as i8;

    // §7.11.3.4: the HORIZONTAL (`intermediate[][]`) pass reads
    // `InterpFilters[ candRow ][ candCol ][ 1 ]` (grid slot 1) and the
    // VERTICAL (`pred[][]`) pass `InterpFilters[ .. ][ 0 ]` (slot 0).
    // Distinguishable only on `enable_dual_filter` streams whose two
    // per-direction filters differ (r394 dual-filter fix — every
    // single-filter stream stamps both slots equal).
    let interp_x = grid.interp_filters[origin * 2 + 1];
    let interp_y = grid.interp_filters[origin * 2];

    if ref_frame1 == INTRA_FRAME_REF {
        // --- inter-intra arm (§7.11.3.14 blend). ---
        //
        // av1-spec p.83 lines 5141-5163 run `predict_intra` on
        // this leaf *before* `predict_inter`, leaving the intra
        // prediction in `CurrFrame[plane]`; the §7.11.3.14 body
        // then reads it as `pred1 = CurrFrame[plane][y+dstY]
        // [x+dstX]` (p.284 line 15786). This walk consumes that
        // in-place intra prediction, so the caller MUST have
        // written it into each plane's `curr` buffer for this
        // leaf's footprint before invoking `reconstruct_inter_frame`.
        let ii_mode = grid.interintra_modes[origin];
        let wedge_on = grid.wedge_interintras[origin] != 0;
        let leaf = InterIntraLeaf {
            mode_info: InterIntraModeInfo {
                ref_frame: ref_frame0 as u8,
                mv: [grid.mvs[origin * 4], grid.mvs[origin * 4 + 1]],
                interintra_mode: ii_mode,
                wedge: if wedge_on {
                    Some(InterIntraWedgeModeInfo {
                        mi_size,
                        wedge_index: grid.interintra_wedge_indices[origin],
                    })
                } else {
                    None
                },
            },
            mi_size,
            mi_row: mi_row as u32,
            mi_col: mi_col as u32,
            interp_filter_x: interp_x,
            interp_filter_y: interp_y,
        };
        // §7.11.3.1 step-7 warp context for a GLOBALMV-class
        // inter-intra leaf: `useWarp = 2` fires on the single inter
        // half exactly as on a plain SIMPLE leaf — the §7.11.3.14
        // blend combines the WARPED inter prediction with the intra
        // half (r408 fix; the pre-r408 inter half was always
        // translational, leaving isolated ±1 diffs on global-motion
        // interintra blocks). `derive_use_warp` re-checks the full
        // gate (w/h ≥ 8, `force_integer_mv`, `!is_scaled`, §7.11.3.6
        // `warpValid`).
        let ii_warp: Option<WarpDriverParams> = grid.warp.as_ref().and_then(|wc| {
            let y_mode = wc.y_modes.get(origin).copied().unwrap_or(0);
            if !matches!(
                y_mode,
                crate::cdf::MODE_GLOBALMV | crate::cdf::MODE_GLOBAL_GLOBALMV
            ) {
                return None;
            }
            let t0 = wc.gm_types.get(ref_frame0 as usize).copied().unwrap_or(0);
            if (t0 as i32) <= crate::cdf::GM_TYPE_TRANSLATION {
                return None;
            }
            let b = (ref_frame0 as usize) * 6;
            let gm0: [i32; 6] = [
                wc.gm_params[b],
                wc.gm_params[b + 1],
                wc.gm_params[b + 2],
                wc.gm_params[b + 3],
                wc.gm_params[b + 4],
                wc.gm_params[b + 5],
            ];
            const WARP_IDENTITY_MATRIX: [i32; 6] = [
                0,
                0,
                1 << WARP_WARPEDMODEL_PREC_BITS,
                0,
                0,
                1 << WARP_WARPEDMODEL_PREC_BITS,
            ];
            Some(WarpDriverParams {
                y_mode: [y_mode, y_mode],
                gm_type: [t0, t0],
                gm_params: [gm0, gm0],
                // §7.11.3.1 step-7 clause 3 cannot fire (§5.11.27
                // forces SIMPLE on inter-intra blocks).
                local_warp_params: WARP_IDENTITY_MATRIX,
                local_valid: false,
                ref_is_scaled: [
                    wc.is_scaled
                        .get(ref_frame0 as usize)
                        .copied()
                        .unwrap_or(false),
                    false,
                ],
                force_integer_mv: wc.force_integer_mv,
            })
        });
        // The §5.11.33 frame-walk and the §5.11.33 task-dispatcher
        // bridge share this one per-block inter-intra driver.
        reconstruct_inter_intra_block(
            &leaf,
            ref_frame_idx,
            grid.bit_depth,
            ii_warp.as_ref(),
            planes,
        )?;
        return Ok(());
    }

    if is_compound_leaf {
        // --- compound two-reference arm
        //     (AVERAGE / DISTANCE / WEDGE). ---
        let comp_type = grid.compound_types[origin];
        // The intra-variant mask arm (COMPOUND_INTRA) needs a
        // §7.11.3.13 mask that the interintra driver owns; leave
        // its region for that later arc. AVERAGE / DISTANCE need
        // no mask, WEDGE's mask is a pure function of the decoded
        // (MiSize, wedge_index, wedge_sign), and DIFFWTD's
        // §7.11.3.12 mask is derived by the driver from the two
        // `preds[]` at `plane == 0` and persisted across planes
        // via the per-block luma-grid buffer allocated below —
        // all four are driven.
        if !matches!(
            comp_type,
            COMPOUND_AVERAGE | COMPOUND_DISTANCE | COMPOUND_WEDGE | COMPOUND_DIFFWTD
        ) {
            return Ok(());
        }
        // §7.11.3.11 wedge side-data — only meaningful on the
        // WEDGE arm. `MiSize` is the luma block size at this
        // leaf's origin, so the regenerated mask is luma-grid.
        let wedge = if comp_type == COMPOUND_WEDGE {
            Some(WedgeModeInfo {
                mi_size,
                wedge_index: grid.wedge_indices[origin],
                wedge_sign: grid.wedge_signs[origin],
            })
        } else {
            None
        };
        let mode_info = CompoundInterModeInfo {
            ref_frame_0: ref_frame0 as u8,
            ref_frame_1: ref_frame1 as u8,
            mv0: [grid.mvs[origin * 4], grid.mvs[origin * 4 + 1]],
            mv1: [grid.mvs[origin * 4 + 2], grid.mvs[origin * 4 + 3]],
            compound_type: comp_type,
            wedge,
            mask_type: grid.mask_types[origin],
        };
        // §7.11.3.12 persistent luma-grid `Mask` array — the
        // DIFFWTD driver fills it on the `plane == 0` call and
        // reuses it for chroma (av1-spec p.258 line 14392). Sized
        // to the *luma* block extent; `None` on the non-DIFFWTD
        // arms (the wrapper ignores it there).
        let mut diffwtd_mask: Option<Vec<u8>> = if comp_type == COMPOUND_DIFFWTD {
            Some(vec![
                0u8;
                crate::cdf::block_width(mi_size)
                    * crate::cdf::block_height(mi_size)
            ])
        } else {
            None
        };
        // §7.11.3.15 order-hint context — resolve each ref's
        // `OrderHints[]` from the per-RefFrame table. The two
        // `ref_frame*` values are in `LAST_FRAME..=ALTREF_FRAME`
        // (the grid-slice guard bounded the table at
        // `ALTREF_FRAME`), so the indexing is in range.
        let order_hints = CompoundOrderHintContext {
            order_hint_bits: grid.order_hint_bits,
            current_order_hint: grid.current_order_hint,
            order_hint_ref0: grid.order_hints_by_ref[ref_frame0 as usize],
            order_hint_ref1: grid.order_hints_by_ref[ref_frame1 as usize],
        };

        // §7.11.3.1 step-7 warp context for the GLOBALMV-class
        // compound leaf — `useWarp = 2` fires PER refList when that
        // list's `GmType > TRANSLATION` (and `!is_scaled`, w/h ≥ 8,
        // !force_integer_mv, §7.11.3.6 `warpValid` — all re-checked
        // by `derive_use_warp`).
        let comp_warp: Option<WarpDriverParams> = grid.warp.as_ref().and_then(|wc| {
            let y_mode = wc.y_modes.get(origin).copied().unwrap_or(0);
            if !matches!(
                y_mode,
                crate::cdf::MODE_GLOBALMV | crate::cdf::MODE_GLOBAL_GLOBALMV
            ) {
                return None;
            }
            let t0 = wc.gm_types.get(ref_frame0 as usize).copied().unwrap_or(0);
            let t1 = wc.gm_types.get(ref_frame1 as usize).copied().unwrap_or(0);
            if (t0 as i32) <= crate::cdf::GM_TYPE_TRANSLATION
                && (t1 as i32) <= crate::cdf::GM_TYPE_TRANSLATION
            {
                return None;
            }
            let gm_of = |rf: usize| -> [i32; 6] {
                let b = rf * 6;
                [
                    wc.gm_params[b],
                    wc.gm_params[b + 1],
                    wc.gm_params[b + 2],
                    wc.gm_params[b + 3],
                    wc.gm_params[b + 4],
                    wc.gm_params[b + 5],
                ]
            };
            const WARP_IDENTITY_MATRIX: [i32; 6] = [
                0,
                0,
                1 << WARP_WARPEDMODEL_PREC_BITS,
                0,
                0,
                1 << WARP_WARPEDMODEL_PREC_BITS,
            ];
            Some(WarpDriverParams {
                y_mode: [y_mode, y_mode],
                gm_type: [t0, t1],
                gm_params: [gm_of(ref_frame0 as usize), gm_of(ref_frame1 as usize)],
                // §7.11.3.1 step-7 clause 3 cannot fire (SIMPLE leaf).
                local_warp_params: WARP_IDENTITY_MATRIX,
                local_valid: false,
                ref_is_scaled: [
                    wc.is_scaled
                        .get(ref_frame0 as usize)
                        .copied()
                        .unwrap_or(false),
                    wc.is_scaled
                        .get(ref_frame1 as usize)
                        .copied()
                        .unwrap_or(false),
                ],
                force_integer_mv: wc.force_integer_mv,
            })
        });

        for ctx in planes.iter_mut() {
            let sub_x = if ctx.plane > 0 { ctx.subsampling_x } else { 0 };
            let sub_y = if ctx.plane > 0 { ctx.subsampling_y } else { 0 };
            let base_x = ((mi_col >> sub_x) * crate::cdf::MI_SIZE) as i32;
            let base_y = ((mi_row >> sub_y) * crate::cdf::MI_SIZE) as i32;
            let pred_w = crate::cdf::block_width(mi_size) >> sub_x;
            let pred_h = crate::cdf::block_height(mi_size) >> sub_y;

            reconstruct_inter_block_compound(
                mode_info,
                order_hints,
                ref_frame_idx,
                ctx.frame_store,
                ctx.plane,
                base_x,
                base_y,
                pred_w,
                pred_h,
                grid.bit_depth,
                ctx.subsampling_x,
                ctx.subsampling_y,
                ctx.frame_width,
                ctx.frame_height,
                interp_x,
                interp_y,
                diffwtd_mask.as_deref_mut(),
                comp_warp.as_ref(),
                ctx.curr,
                ctx.curr_stride,
            )?;
        }
        return Ok(());
    }

    debug_assert_eq!(ref_frame1, NONE_REF_FRAME);
    // --- single forward-reference arm (SIMPLE + WARPED_CAUSAL). ---
    //
    // §5.11.33 `predict()` per-plane body (av1-spec p.82-83 lines
    // 5127-5190) in full, including the `someUseIntra` scan and
    // the resulting `predict_inter` sub-block tiling.

    // §5.11.27 motion-mode dispatch: a `WARPED_CAUSAL` leaf (the
    // grid carries the decoded ordinal + the §7.11.3.8 local fit
    // + the per-RefFrame global-motion model in `grid.warp`)
    // routes each sub-block to `reconstruct_inter_block_warp`; on
    // `None`/`SIMPLE`/`OBMC` the translational
    // `reconstruct_inter_block` path runs unchanged. The warp
    // context is read at the leaf origin (the §5.11.27 LOCALWARP
    // arm is per-block and luma-only — `block_warp`'s step-7 gate
    // already falls back to translational for chroma / sub-8×8 /
    // invalid-fit windows, so a single per-leaf `WarpDriverParams`
    // is bit-correct across the §5.11.33 sub-block tiling).
    let leaf_warp: Option<WarpDriverParams> = grid.warp.as_ref().and_then(|wc| {
        let is_warped_causal =
            wc.motion_modes.get(origin).copied() == Some(crate::cdf::MOTION_MODE_WARPED_CAUSAL);
        // §7.11.3.1 step 7: the `useWarp = 2` global arm fires for a
        // GLOBALMV-class leaf whose `GmType[ RefFrame[0] ] >
        // TRANSLATION` REGARDLESS of `motion_mode` (§5.11.27
        // `read_motion_mode` forces SIMPLE on exactly this block
        // class, so such leaves never carry WARPED_CAUSAL). Supply
        // the warp context for them too; `derive_use_warp` re-checks
        // the full gate (w/h ≥ 8, `force_integer_mv`,
        // `!is_scaled( refFrame )`, §7.11.3.6 `warpValid`) and falls
        // back to the translational kernel when any term fails.
        let y_is_global = matches!(
            wc.y_modes.get(origin).copied(),
            Some(crate::cdf::MODE_GLOBALMV) | Some(crate::cdf::MODE_GLOBAL_GLOBALMV)
        );
        let gm_is_warp = wc
            .gm_types
            .get(ref_frame0 as usize)
            .map(|&t| (t as i32) > crate::cdf::GM_TYPE_TRANSLATION)
            .unwrap_or(false);
        if !(is_warped_causal || (y_is_global && gm_is_warp)) {
            return None;
        }
        let lw_base = origin * 6;
        let lw_at = |k: usize| wc.local_warp_params.get(lw_base + k).copied().unwrap_or(0);
        let lwp: [i32; 6] = [lw_at(0), lw_at(1), lw_at(2), lw_at(3), lw_at(4), lw_at(5)];
        let rf0 = ref_frame0 as usize;
        let gm_base = rf0 * 6;
        let gmp: [i32; 6] = [
            wc.gm_params[gm_base],
            wc.gm_params[gm_base + 1],
            wc.gm_params[gm_base + 2],
            wc.gm_params[gm_base + 3],
            wc.gm_params[gm_base + 4],
            wc.gm_params[gm_base + 5],
        ];
        // §7.11.3.6 identity affine matrix for the unused
        // refList-1 slot (never consulted on the single-ref
        // path): `[0, 0, 1<<PREC, 0, 0, 1<<PREC]`.
        const WARP_IDENTITY_MATRIX: [i32; 6] = [
            0,
            0,
            1 << WARP_WARPEDMODEL_PREC_BITS,
            0,
            0,
            1 << WARP_WARPEDMODEL_PREC_BITS,
        ];
        Some(WarpDriverParams {
            y_mode: [wc.y_modes[origin], 0],
            gm_type: [wc.gm_types[rf0], 0],
            gm_params: [gmp, WARP_IDENTITY_MATRIX],
            local_warp_params: lwp,
            // §7.11.3.1 step-7 clause 3 gates on `motion_mode ==
            // LOCALWARP && LocalValid` — a SIMPLE GLOBALMV leaf
            // reaches this driver with `local_valid = false` so only
            // the global arm can fire for it.
            local_valid: is_warped_causal && wc.local_warp_valid[origin] != 0,
            // §5.11.27 `is_scaled( refFrame )` — the step-7
            // `useWarp = 2` global gate turns the warp OFF against a
            // scaled reference (§7.11.3.1 p.257: `is_scaled(
            // refFrame ) is equal to 0`).
            ref_is_scaled: [
                wc.is_scaled
                    .get(ref_frame0 as usize)
                    .copied()
                    .unwrap_or(false),
                false,
            ],
            force_integer_mv: wc.force_integer_mv,
        })
    });

    // §5.11.27 OBMC dispatch: an `OBMC` single-ref leaf (and not a
    // `WARPED_CAUSAL` leaf, which the warp arm above already
    // claimed) routes each plane to `reconstruct_inter_block_obmc`
    // with the §7.11.3.9 above / left neighbour lists resolved from
    // this grid. The whole leaf (all planes) is reconstructed here;
    // the SIMPLE translational loop below is skipped via `continue`.
    // The leaf's own MV/ref is single-reference and translational
    // (the §7.11.3.9 post-step overlays the neighbour
    // contributions), so the leaf gates exactly like SIMPLE: it has
    // no `someUseIntra` sub-block split (OBMC blocks are >= 8×8 luma
    // by the §5.11.27 `use_obmc` eligibility, so the §5.11.33 chroma
    // intra-neighbour split does not arise for them).
    if leaf_warp.is_none() {
        if let Some(oc) = grid.obmc.as_ref() {
            if oc.motion_modes[origin] == crate::cdf::MOTION_MODE_OBMC {
                obmc_dispatch_leaf(
                    grid,
                    oc,
                    ref_frame_idx,
                    planes,
                    mi_row,
                    mi_col,
                    mi_size,
                    ref_frame0,
                )?;
                return Ok(());
            }
        }
    }

    for ctx in planes.iter_mut() {
        let sub_x = if ctx.plane > 0 { ctx.subsampling_x } else { 0 };
        let sub_y = if ctx.plane > 0 { ctx.subsampling_y } else { 0 };

        // §5.11.33 lines 5128-5130: per-plane residual size →
        // `num4x4W` / `num4x4H`. `get_plane_residual_size` is
        // guaranteed non-`BLOCK_INVALID` for plane 1 by §6.4.1
        // conformance, and for plane 0 it is the identity; a
        // `None` is a caller bug (non-conformant grid).
        let plane_sz = crate::cdf::get_plane_residual_size(mi_size, ctx.plane, sub_x, sub_y)
            .ok_or(crate::Error::PartitionWalkOutOfRange)?;
        let num4x4_w = crate::cdf::num_4x4_blocks_wide(plane_sz);
        let num4x4_h = crate::cdf::num_4x4_blocks_high(plane_sz);

        // §5.11.33 lines 5135-5138: plane-space block origin and
        // the chroma-collocated candidate anchor `candRow` /
        // `candCol` (`(MiRow >> subY) << subY` etc.).
        let base_x = ((mi_col >> sub_x) * crate::cdf::MI_SIZE) as i32;
        let base_y = ((mi_row >> sub_y) * crate::cdf::MI_SIZE) as i32;
        let mut cand_row = (mi_row >> sub_y) << sub_y;
        let mut cand_col = (mi_col >> sub_x) << sub_x;

        // §5.11.33 lines 5166-5167: default (`someUseIntra == 0`)
        // prediction footprint.
        let mut pred_w = crate::cdf::block_width(mi_size) >> sub_x;
        let mut pred_h = crate::cdf::block_height(mi_size) >> sub_y;

        // §5.11.33 lines 5168-5172: `someUseIntra` scan over the
        // `(num4x4H << subY) × (num4x4W << subX)` luma cells the
        // chroma block collocates with. A cell whose
        // `RefFrames[ candRow + r ][ candCol + c ][ 0 ] ==
        // INTRA_FRAME` flags the split. Cells off the grid edge
        // are not stamped (treated as non-intra), matching the
        // §5.11.5 grid-fill clip.
        const INTRA_FRAME_REF0: i8 = crate::uncompressed_header_tail::INTRA_FRAME as i8;
        let mut some_use_intra = false;
        'scan: for r in 0..(num4x4_h << sub_y) {
            let rr = cand_row + r;
            if rr >= mi_rows {
                break;
            }
            for c in 0..(num4x4_w << sub_x) {
                let cc = cand_col + c;
                if cc >= mi_cols {
                    break;
                }
                if grid.ref_frames[(rr * mi_cols + cc) * 2] == INTRA_FRAME_REF0 {
                    some_use_intra = true;
                    break 'scan;
                }
            }
        }

        // §5.11.33 lines 5173-5178: on `someUseIntra` the
        // prediction is split into `num4x4{W,H}` sub-blocks of
        // 4 samples each, anchored at the unsubsampled
        // `(MiRow, MiCol)` so each sub-block reads its own
        // collocated luma candidate.
        if some_use_intra {
            pred_w = num4x4_w * 4;
            pred_h = num4x4_h * 4;
            cand_row = mi_row;
            cand_col = mi_col;
        }

        // §5.11.33 lines 5179-5189: tile the
        // `num4x4H*4 × num4x4W*4` plane region with
        // `predW × predH` sub-blocks, advancing the candidate
        // `(candRow + r, candCol + c)` per sub-block. Each
        // sub-block's `predict_inter` reads `Mvs[cand][0]` /
        // `RefFrames[cand][0]` at its own candidate cell (all
        // cells of one leaf carry the leaf's stamped MV/ref, so
        // on `someUseIntra == 0` this collapses to the single
        // origin call the prior arm performed).
        let region_w = num4x4_w * 4;
        let region_h = num4x4_h * 4;
        let mut r_idx = 0usize;
        let mut y = 0usize;
        while y < region_h {
            let mut c_idx = 0usize;
            let mut x = 0usize;
            while x < region_w {
                let cr = cand_row + r_idx;
                let cc = cand_col + c_idx;
                // Clamp the candidate to the grid; the leaf
                // stamped its MV/ref over the whole footprint,
                // so an off-edge candidate (only reachable when
                // the leaf is clipped at the frame boundary)
                // re-reads the nearest in-grid cell of the same
                // leaf.
                let cr = cr.min(mi_rows.saturating_sub(1));
                let cc = cc.min(mi_cols.saturating_sub(1));
                let cand = cr * mi_cols + cc;
                let mode_info = InterModeInfo {
                    ref_frame: grid.ref_frames[cand * 2] as u8,
                    mv: [grid.mvs[cand * 4], grid.mvs[cand * 4 + 1]],
                };
                // §7.11.3.4 runs with (candRow, candCol): the
                // interpolation-filter pair is the CANDIDATE cell's,
                // like the MV / ref — on the sub-8×8 chroma stitch the
                // collocated luma leaves may have signalled different
                // per-direction filters (r394 dual-filter fix).
                let cand_fx = grid.interp_filters[cand * 2 + 1];
                let cand_fy = grid.interp_filters[cand * 2];

                match leaf_warp.as_ref() {
                    Some(warp) => {
                        reconstruct_inter_block_warp(
                            mode_info,
                            warp,
                            ref_frame_idx,
                            ctx.frame_store,
                            ctx.plane,
                            base_x + x as i32,
                            base_y + y as i32,
                            pred_w,
                            pred_h,
                            grid.bit_depth,
                            ctx.subsampling_x,
                            ctx.subsampling_y,
                            ctx.frame_width,
                            ctx.frame_height,
                            cand_fx,
                            cand_fy,
                            ctx.curr,
                            ctx.curr_stride,
                        )?;
                    }
                    None => {
                        reconstruct_inter_block(
                            mode_info,
                            ref_frame_idx,
                            ctx.frame_store,
                            ctx.plane,
                            base_x + x as i32,
                            base_y + y as i32,
                            pred_w,
                            pred_h,
                            grid.bit_depth,
                            ctx.subsampling_x,
                            ctx.subsampling_y,
                            ctx.frame_width,
                            ctx.frame_height,
                            cand_fx,
                            cand_fy,
                            ctx.curr,
                            ctx.curr_stride,
                        )?;
                    }
                }

                c_idx += 1;
                x += pred_w;
            }
            r_idx += 1;
            y += pred_h;
        }
    }

    Ok(())
}

// ---------------------------------------------------------------------
// §7.9 motion field estimation (r413) — the shared core the decode
// driver and the encoder's write-mirror both run so the §7.10.2.5
// temporal scan sees identical `MotionFieldMvs` on both sides.
// ---------------------------------------------------------------------

/// One §7.20-stored reference slot's motion-field payload for
/// [`motion_field_estimation_core`]: the §7.19 `SavedMvs` /
/// `SavedRefFrames` filter output (one candidate per 4×4 cell), the
/// frame's `SavedOrderHints[ 0..8 ]`, its mi extent and its
/// `frame_is_intra` flag (§7.9.2 skips intra sources).
#[derive(Debug, Clone, Copy)]
pub struct MotionFieldSlot<'a> {
    /// `SavedMvs` — `[ row, col ]` per cell, row-major over
    /// `mi_rows * mi_cols` cells (2 entries per cell).
    pub mf_mvs: &'a [i16],
    /// `SavedRefFrames` — one `RefFrame` ordinal per cell (`-1` =
    /// no stored candidate).
    pub mf_ref_frames: &'a [i8],
    /// `SavedOrderHints[ ref ]` for `ref` in `0..=ALTREF_FRAME`.
    pub saved_order_hints: [i32; 8],
    /// Stored frame's `MiRows`.
    pub mi_rows: u32,
    /// Stored frame's `MiCols`.
    pub mi_cols: u32,
    /// Stored frame's `FrameIsIntra`.
    pub frame_is_intra: bool,
}

/// §7.9 `motion_field_estimation()` — project the §7.20-saved motion
/// vectors of up to four reference frames onto the current frame's
/// 8×8 motion-field grid, one projected MV per (destination
/// reference, cell). `slots[ i ]` is physical slot `i`'s payload
/// (`None` = empty slot); `ref_frame_idx` / `order_hints` /
/// `order_hint` / `hint_bits` are the current frame's §5.9.2 scalars.
#[must_use]
pub fn motion_field_estimation_core(
    slots: &[Option<MotionFieldSlot<'_>>; 8],
    ref_frame_idx: &[u8; 7],
    order_hints: &[i32; 8],
    order_hint: i32,
    hint_bits: u32,
    mi_rows: u32,
    mi_cols: u32,
) -> crate::cdf::MotionFieldMvs {
    use crate::cdf::MotionFieldMvs;
    // §3 constants scoped to the §7.9 processes.
    const MFMV_STACK_SIZE: i32 = 3;
    const MAX_FRAME_DISTANCE: i32 = 31;
    const MAX_OFFSET_WIDTH: i32 = 8;
    const MAX_OFFSET_HEIGHT: i32 = 0;
    /// §7.9.3 `Div_Mult[ 32 ]`.
    const DIV_MULT: [i32; 32] = [
        0, 16384, 8192, 5461, 4096, 3276, 2730, 2340, 2048, 1820, 1638, 1489, 1365, 1260, 1170,
        1092, 1024, 963, 910, 862, 819, 780, 744, 712, 682, 655, 630, 606, 585, 564, 546, 528,
    ];
    // Reference ordinals (§6.10.24): LAST=1, LAST2=2, GOLDEN=4,
    // BWDREF=5, ALTREF2=6, ALTREF=7.
    const LAST_FRAME: usize = 1;
    const LAST2_FRAME: usize = 2;
    const GOLDEN_FRAME: usize = 4;
    const BWDREF_FRAME: usize = 5;
    const ALTREF2_FRAME: usize = 6;
    const ALTREF_FRAME: usize = 7;

    let mut mfmvs = MotionFieldMvs::new_invalid(mi_rows, mi_cols);
    let w8 = (mi_cols >> 1) as i32;
    let h8 = (mi_rows >> 1) as i32;

    // §7.9.2 projection for one source reference.
    let project_ref = |src: usize, dst_sign: i32, mfmvs: &mut MotionFieldMvs| -> bool {
        let src_idx = ref_frame_idx[src - LAST_FRAME] as usize;
        let Some(slot) = slots[src_idx].as_ref() else {
            return false;
        };
        if slot.mi_rows != mi_rows || slot.mi_cols != mi_cols || slot.frame_is_intra {
            return false;
        }
        for y8 in 0..h8 {
            for x8 in 0..w8 {
                let row = (2 * y8 + 1) as usize;
                let col = (2 * x8 + 1) as usize;
                let cell = row * (mi_cols as usize) + col;
                let src_ref = slot.mf_ref_frames[cell];
                if src_ref <= 0 {
                    continue;
                }
                let ref_to_cur = get_relative_dist(order_hints[src], order_hint, hint_bits);
                let ref_offset = get_relative_dist(
                    order_hints[src],
                    slot.saved_order_hints[src_ref as usize],
                    hint_bits,
                );
                let pos_valid = ref_to_cur.abs() <= MAX_FRAME_DISTANCE
                    && ref_offset.abs() <= MAX_FRAME_DISTANCE
                    && ref_offset > 0;
                if !pos_valid {
                    continue;
                }
                let mv = [
                    i32::from(slot.mf_mvs[cell * 2]),
                    i32::from(slot.mf_mvs[cell * 2 + 1]),
                ];
                // §7.9.3 get_mv_projection.
                let mv_projection = |mv: [i32; 2], numerator: i32, denominator: i32| -> [i32; 2] {
                    let clipped_den = denominator.min(MAX_FRAME_DISTANCE);
                    let clipped_num = numerator.clamp(-MAX_FRAME_DISTANCE, MAX_FRAME_DISTANCE);
                    let mut out = [0i32; 2];
                    for i in 0..2 {
                        let v = mv[i] * clipped_num * DIV_MULT[clipped_den as usize];
                        // Round2Signed(v, 14).
                        let scaled = if v >= 0 {
                            (v + (1 << 13)) >> 14
                        } else {
                            -((-v + (1 << 13)) >> 14)
                        };
                        out[i] = scaled.clamp(-(1 << 14) + 1, (1 << 14) - 1);
                    }
                    out
                };
                let proj_mv = mv_projection(mv, ref_to_cur * dst_sign, ref_offset);
                // §7.9.4 get_block_position.
                let project = |v8: i32, delta: i32, max8: i32, max_off8: i32| -> (i32, bool) {
                    let base8 = (v8 >> 3) << 3;
                    let offset8 = if delta >= 0 {
                        delta >> (3 + 1 + 2)
                    } else {
                        -((-delta) >> (3 + 1 + 2))
                    };
                    let v8 = v8 + dst_sign * offset8;
                    let valid = !(v8 < 0
                        || v8 >= max8
                        || v8 < base8 - max_off8
                        || v8 >= base8 + 8 + max_off8);
                    (v8, valid)
                };
                let (pos_y8, vy) = project(y8, proj_mv[0], h8, MAX_OFFSET_HEIGHT);
                let (pos_x8, vx) = project(x8, proj_mv[1], w8, MAX_OFFSET_WIDTH);
                if !(vy && vx) {
                    continue;
                }
                for (dst, &dst_hint) in order_hints
                    .iter()
                    .enumerate()
                    .take(ALTREF_FRAME + 1)
                    .skip(LAST_FRAME)
                {
                    let ref_to_dst = get_relative_dist(order_hint, dst_hint, hint_bits);
                    let out = mv_projection(mv, ref_to_dst, ref_offset);
                    mfmvs.set(
                        dst,
                        pos_y8 as u32,
                        pos_x8 as u32,
                        [out[0] as i16, out[1] as i16],
                    );
                }
            }
        }
        true
    };

    // §7.9.1 source-selection order.
    let last_idx = ref_frame_idx[0] as usize;
    let cur_gold_order_hint = order_hints[GOLDEN_FRAME];
    let last_alt_order_hint = slots[last_idx]
        .as_ref()
        .map_or(0, |s| s.saved_order_hints[ALTREF_FRAME]);
    let use_last = last_alt_order_hint != cur_gold_order_hint;
    if use_last {
        project_ref(LAST_FRAME, -1, &mut mfmvs);
    }
    let mut ref_stamp = MFMV_STACK_SIZE - 2;
    let use_bwd = get_relative_dist(order_hints[BWDREF_FRAME], order_hint, hint_bits) > 0;
    if use_bwd && project_ref(BWDREF_FRAME, 1, &mut mfmvs) {
        ref_stamp -= 1;
    }
    let use_alt2 = get_relative_dist(order_hints[ALTREF2_FRAME], order_hint, hint_bits) > 0;
    if use_alt2 && project_ref(ALTREF2_FRAME, 1, &mut mfmvs) {
        ref_stamp -= 1;
    }
    let use_alt = get_relative_dist(order_hints[ALTREF_FRAME], order_hint, hint_bits) > 0;
    if use_alt && ref_stamp >= 0 && project_ref(ALTREF_FRAME, 1, &mut mfmvs) {
        ref_stamp -= 1;
    }
    if ref_stamp >= 0 {
        project_ref(LAST2_FRAME, -1, &mut mfmvs);
    }
    mfmvs
}

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

    // ---------- §7.11.3.2 rounding_variables ----------

    /// §7.11.3.2 spec table — `(bit_depth, is_compound) → (R0, R1,
    /// InterPostRound)`. Hand-derived from the av1-spec p.259 body:
    /// * `(8, false)  → (3, 11, 0)`  — `2*7 - (3 + 11) = 0`.
    /// * `(8, true)   → (3,  7, 4)`  — `2*7 - (3 +  7) = 4`.
    /// * `(10, false) → (3, 11, 0)`  — same as 8-bit, no BD-12 adjust.
    /// * `(10, true)  → (3,  7, 4)`.
    /// * `(12, false) → (5,  9, 0)`  — `R0 += 2`, `R1 -= 2`; `2*7 -
    ///   (5 + 9) = 0`.
    /// * `(12, true)  → (5,  7, 2)`  — `R0 += 2` only; `2*7 - (5 + 7) = 2`.
    #[test]
    fn rounding_variables_matches_spec_table() {
        let cases: &[(u8, bool, u32, u32, u32)] = &[
            (8, false, 3, 11, 0),
            (8, true, 3, 7, 4),
            (10, false, 3, 11, 0),
            (10, true, 3, 7, 4),
            (12, false, 5, 9, 0),
            (12, true, 5, 7, 2),
        ];
        for &(bd, ic, r0, r1, pr) in cases {
            let got = rounding_variables(bd, ic).unwrap();
            assert_eq!(
                (got.inter_round0, got.inter_round1, got.inter_post_round),
                (r0, r1, pr),
                "BD={bd} compound={ic}",
            );
        }
    }

    /// §7.11.3.2: `bit_depth` outside `{8, 10, 12}` is a caller bug.
    #[test]
    fn rounding_variables_rejects_invalid_bit_depth() {
        assert!(rounding_variables(7, false).is_err());
        assert!(rounding_variables(9, false).is_err());
        assert!(rounding_variables(16, false).is_err());
    }

    // ---------- §7.11.3.3 motion_vector_scaling ----------

    /// §7.11.3.3 identity case: `RefUpscaledWidth == FrameWidth`,
    /// `RefFrameHeight == FrameHeight`, `plane == 0`, zero MV — the
    /// `(x, y)` input should map to itself in 10-bit fractional units:
    /// `startX = (x << 10)`, `startY = (y << 10)`, `stepX = stepY = 1024`.
    ///
    /// Derivation:
    /// * `xScale = (W << 14 + W/2) / W = 1 << 14 = 16384` (the rounded
    ///   division is exact for our inputs).
    /// * `halfSample = 8` (1/16 sample).
    /// * `origX = (x << 4) + 0 + 8 = x*16 + 8`.
    /// * `baseX = (x*16 + 8) * 16384 - 8 * 16384 = x * 16 * 16384 = x << 18`.
    /// * `Round2Signed(baseX, 8) = x << 10`.
    /// * `off = (1 << 6) / 2 = 32`.
    /// * `startX = (x << 10) + 32`. Same for Y.
    /// * `stepX = Round2Signed(16384, 4) = 1024`.
    #[test]
    fn motion_vector_scaling_identity_yields_unit_scale() {
        let s = motion_vector_scaling(
            /*plane*/ 0,
            /*ssx*/ 0,
            /*ssy*/ 0,
            /*fw*/ 640,
            /*fh*/ 360,
            /*ruw*/ 640,
            /*rfh*/ 360,
            /*x*/ 16,
            /*y*/ 8,
            /*mv*/ [0, 0],
        )
        .unwrap();
        assert_eq!(s.step_x, 1024);
        assert_eq!(s.step_y, 1024);
        assert_eq!(s.start_x, (16 << 10) + 32);
        assert_eq!(s.start_y, (8 << 10) + 32);
    }

    /// §7.11.3.3 with a non-zero integer-sample MV: a `(+8, 0)` row
    /// MV (= 1 full luma sample down in 1/8-sample units; 2 * 8 = 16,
    /// which adds 16 sixteenths = one full sample) should shift the
    /// reference Y coordinate by `+1 << 10`.
    #[test]
    fn motion_vector_scaling_integer_mv_shifts_origin() {
        let base = motion_vector_scaling(0, 0, 0, 640, 360, 640, 360, 0, 0, [0, 0]).unwrap();
        let shifted = motion_vector_scaling(0, 0, 0, 640, 360, 640, 360, 0, 0, [8, 0]).unwrap();
        assert_eq!(shifted.start_y - base.start_y, 1 << SCALE_SUBPEL_BITS);
        assert_eq!(shifted.start_x, base.start_x);
    }

    /// §7.11.3.3 rejects caller-bug arguments.
    #[test]
    fn motion_vector_scaling_rejects_invalid_inputs() {
        assert!(motion_vector_scaling(3, 0, 0, 8, 8, 8, 8, 0, 0, [0, 0]).is_err());
        assert!(motion_vector_scaling(0, 2, 0, 8, 8, 8, 8, 0, 0, [0, 0]).is_err());
        assert!(motion_vector_scaling(0, 0, 2, 8, 8, 8, 8, 0, 0, [0, 0]).is_err());
        assert!(motion_vector_scaling(0, 0, 0, 0, 8, 8, 8, 0, 0, [0, 0]).is_err());
        assert!(motion_vector_scaling(0, 0, 0, 8, 0, 8, 8, 0, 0, [0, 0]).is_err());
        assert!(motion_vector_scaling(0, 0, 0, 8, 8, 0, 8, 0, 0, [0, 0]).is_err());
        assert!(motion_vector_scaling(0, 0, 0, 8, 8, 8, 0, 0, 0, [0, 0]).is_err());
    }

    // ---------- §7.11.3.4 SUBPEL_FILTERS table shape ----------

    /// av1-spec p.265 line 14786: every Subpel_Filters value is even.
    /// All 6 × 16 × 8 = 768 entries satisfy this.
    #[test]
    fn subpel_filters_all_even() {
        for (f, phases) in SUBPEL_FILTERS.iter().enumerate() {
            for (p, row) in phases.iter().enumerate() {
                for (t, &v) in row.iter().enumerate() {
                    assert_eq!(v & 1, 0, "filter {f} phase {p} tap {t} = {v} (odd)");
                }
            }
        }
    }

    /// av1-spec p.262: the phase-0 row of every filter is the unit
    /// row `(0, 0, 0, 128, 0, 0, 0, 0)` so an integer-aligned tap
    /// reproduces the reference sample exactly. (`128 = 1 <<
    /// FILTER_BITS`.)
    #[test]
    fn subpel_filters_phase_zero_is_unit_copy() {
        let unit = [0, 0, 0, 128, 0, 0, 0, 0];
        for (f, phases) in SUBPEL_FILTERS.iter().enumerate() {
            assert_eq!(phases[0], unit, "filter {f} phase 0 not unit");
        }
    }

    /// av1-spec p.265 note (line 14786): the §7.11.3.4 8-tap
    /// coefficients sum to `1 << FILTER_BITS = 128` at every phase
    /// — sample-conservation property. Verified for all 96 phase
    /// rows across all six filter banks.
    #[test]
    fn subpel_filters_taps_sum_to_filter_bits_unity() {
        for (f, phases) in SUBPEL_FILTERS.iter().enumerate() {
            for (p, row) in phases.iter().enumerate() {
                let sum: i32 = row.iter().sum();
                assert_eq!(sum, 128, "filter {f} phase {p} taps sum = {sum} != 128");
            }
        }
    }

    /// av1-spec p.264 lines 14737-14781: filters 4 and 5 (small-block
    /// reductions) zero out taps 0, 1, 6, 7 at every phase — the
    /// 4-tap structure is taps 2..6.
    #[test]
    fn small_block_filters_have_4tap_structure() {
        for f in [EIGHTTAP_4TAP as usize, EIGHTTAP_SMOOTH_4TAP as usize] {
            for (p, row) in SUBPEL_FILTERS[f].iter().enumerate() {
                for &t in &[0usize, 1, 6, 7] {
                    assert_eq!(
                        row[t], 0,
                        "filter {f} phase {p} tap {t} = {} (must be 0)",
                        row[t],
                    );
                }
            }
        }
    }

    /// §7.11.3.4 small-block remap per av1-spec p.262.
    #[test]
    fn select_interp_filter_small_block_remap() {
        assert_eq!(select_interp_filter_small_block(EIGHTTAP), EIGHTTAP_4TAP);
        assert_eq!(
            select_interp_filter_small_block(EIGHTTAP_SHARP),
            EIGHTTAP_4TAP,
        );
        assert_eq!(
            select_interp_filter_small_block(EIGHTTAP_SMOOTH),
            EIGHTTAP_SMOOTH_4TAP,
        );
        assert_eq!(select_interp_filter_small_block(BILINEAR), BILINEAR);
        assert_eq!(
            select_interp_filter_small_block(EIGHTTAP_4TAP),
            EIGHTTAP_4TAP,
        );
    }

    // ---------- §7.11.3.4 block_inter_prediction ----------

    /// §7.11.3.4 identity case: zero motion vector with an integer-
    /// aligned start position should reproduce a copy of the
    /// corresponding reference-frame region.
    ///
    /// `start_y = 4 << 10 = 4096` (4 luma samples down, integer-
    /// aligned — phase 0), same for X. The kernel's phase-0 unit
    /// copy means horizontal & vertical filters are both pass-
    /// throughs; the output `Round2(128 * sample, 11)` reduces to
    /// `Round2((128 * 128 * sample), 14) = sample` for 8-bit content
    /// (the `128` factors and the `2^14` rounding shift cancel).
    #[test]
    fn block_inter_prediction_zero_mv_copies_reference() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        // Build a reference plane with sample[r][c] = (r * 16 + c).
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = (r * 16 + c) as u16;
            }
        }

        // 4x4 region starting at (2, 2) in plane coords, zero MV.
        let s = motion_vector_scaling(
            0,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            ref_w as u32,
            ref_h as u32,
            2,
            2,
            [0, 0],
        )
        .unwrap();
        let rv = rounding_variables(8, false).unwrap();
        let w = 4;
        let h = 4;
        let mut pred = vec![0i32; h * w];
        block_inter_prediction(
            0,
            0,
            0,
            &refp,
            stride,
            ref_w as u32,
            ref_h as u32,
            s.start_x,
            s.start_y,
            s.step_x,
            s.step_y,
            w,
            h,
            EIGHTTAP,
            EIGHTTAP,
            rv.inter_round0,
            rv.inter_round1,
            &mut pred,
        )
        .unwrap();

        // The `+ off` term (`off = 32`) lives entirely in the
        // fractional bits (10) and rounds out — the phase index
        // `(start >> 6) & 15` of `((2 << 10) + 32) >> 6 = 33 & 15 =
        // 1` instead of 0, which violates the integer-aligned
        // assumption. So apply the spec-level integer-pixel test
        // differently: assert the copy holds at the *centre* of the
        // half-sample grid — i.e. compare against the same kernel
        // applied to a different MV. Instead, use the unit-row
        // property: a deliberate `phase == 0` setup needs `start_x
        // % 1024 == 0` AND `off == 0`. The §7.11.3.3 `off` is a
        // fixed bias so we cannot get phase 0 from MV scaling alone.
        //
        // We therefore validate via the unit-row direct injection
        // below — the phase-0 row of every filter is `(0, 0, 0,
        // 128, 0, 0, 0, 0)`, so applying the kernel with
        // hand-crafted `start_x` / `start_y` that align to integer
        // sample positions and produce phase 0 yields a copy.
        let _ = pred; // discard the off-biased output

        // Hand-crafted integer-aligned start (phase 0 horizontal,
        // phase 0 vertical).
        let mut pred2 = vec![0i32; h * w];
        block_inter_prediction(
            0,
            0,
            0,
            &refp,
            stride,
            ref_w as u32,
            ref_h as u32,
            /*start_x*/ 2 << 10,
            /*start_y*/ 2 << 10,
            /*step_x*/ 1 << 10,
            /*step_y*/ 1 << 10,
            w,
            h,
            EIGHTTAP,
            EIGHTTAP,
            rv.inter_round0,
            rv.inter_round1,
            &mut pred2,
        )
        .unwrap();

        // With both filters at phase 0, the horizontal pass writes
        // `Round2(128 * ref, 3) = 16 * ref`, then vertical writes
        // `Round2(128 * 16 * ref, 11) = ref` (Round2(2048*ref, 11) =
        // ref).
        for r in 0..h {
            for c in 0..w {
                let expected = refp[(2 + r) * stride + (2 + c)] as i32;
                assert_eq!(
                    pred2[r * w + c],
                    expected,
                    "pred2[{r}][{c}] = {} expected {}",
                    pred2[r * w + c],
                    expected,
                );
            }
        }
    }

    /// §7.11.3.4 boundary-clamp: a `start_x = -4 << 10` puts the first
    /// tap at `Clip3(0, lastX, -7)` = `0`, so the kernel clamps to
    /// the left edge. The output for the left-edge column of a
    /// constant-row reference should match the constant.
    #[test]
    fn block_inter_prediction_clamps_at_negative_start() {
        let ref_w: usize = 8;
        let ref_h: usize = 8;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = 42; // constant
            }
        }
        let rv = rounding_variables(8, false).unwrap();
        let w = 4;
        let h = 4;
        let mut pred = vec![0i32; h * w];
        // Use the small-block 4-tap filter for w=4.
        block_inter_prediction(
            0,
            0,
            0,
            &refp,
            stride,
            ref_w as u32,
            ref_h as u32,
            /*start_x*/ -4i32 << SCALE_SUBPEL_BITS,
            /*start_y*/ 0,
            /*step_x*/ 1 << SCALE_SUBPEL_BITS,
            /*step_y*/ 1 << SCALE_SUBPEL_BITS,
            w,
            h,
            EIGHTTAP,
            EIGHTTAP,
            rv.inter_round0,
            rv.inter_round1,
            &mut pred,
        )
        .unwrap();
        // Output of a constant reference under any phase / clamp =
        // the constant (sample-conservation property — taps sum to
        // 128, Round2 by R0=3 → 128*42/8 = 672, then 128*672/2048 =
        // 42).
        for r in 0..h {
            for c in 0..w {
                assert_eq!(pred[r * w + c], 42);
            }
        }
    }

    /// §7.11.3.4 caller-bug rejection.
    #[test]
    fn block_inter_prediction_rejects_invalid_inputs() {
        let refp = vec![0u16; 64];
        let mut pred = vec![0i32; 16];
        // plane > 2
        assert!(block_inter_prediction(
            3, 0, 0, &refp, 8, 8, 8, 0, 0, 1024, 1024, 4, 4, 0, 0, 3, 11, &mut pred
        )
        .is_err());
        // subsampling_x > 1
        assert!(block_inter_prediction(
            0, 2, 0, &refp, 8, 8, 8, 0, 0, 1024, 1024, 4, 4, 0, 0, 3, 11, &mut pred
        )
        .is_err());
        // ref_width == 0
        assert!(block_inter_prediction(
            0, 0, 0, &refp, 8, 0, 8, 0, 0, 1024, 1024, 4, 4, 0, 0, 3, 11, &mut pred
        )
        .is_err());
        // step_x == 0
        assert!(block_inter_prediction(
            0, 0, 0, &refp, 8, 8, 8, 0, 0, 0, 1024, 4, 4, 0, 0, 3, 11, &mut pred
        )
        .is_err());
        // interp_filter_x out of range
        assert!(block_inter_prediction(
            0, 0, 0, &refp, 8, 8, 8, 0, 0, 1024, 1024, 4, 4, 6, 0, 3, 11, &mut pred
        )
        .is_err());
        // pred too small
        let mut tiny = vec![0i32; 8];
        assert!(block_inter_prediction(
            0, 0, 0, &refp, 8, 8, 8, 0, 0, 1024, 1024, 4, 4, 0, 0, 3, 11, &mut tiny
        )
        .is_err());
    }

    /// `clip1_single_ref` bounds.
    #[test]
    fn clip1_single_ref_clamps_to_bit_depth() {
        let pred = [-3i32, 0, 255, 256, 1023, 4096, -1];
        let mut out8 = [0u16; 7];
        clip1_single_ref(8, &pred, &mut out8).unwrap();
        assert_eq!(out8, [0, 0, 255, 255, 255, 255, 0]);
        let mut out10 = [0u16; 7];
        clip1_single_ref(10, &pred, &mut out10).unwrap();
        assert_eq!(out10, [0, 0, 255, 256, 1023, 1023, 0]);
        let mut out12 = [0u16; 7];
        clip1_single_ref(12, &pred, &mut out12).unwrap();
        assert_eq!(out12, [0, 0, 255, 256, 1023, 4095, 0]);
        // Invalid bit depth.
        let mut out = [0u16; 7];
        assert!(clip1_single_ref(9, &pred, &mut out).is_err());
    }

    // ---------- §7.11.3.11 wedge_mask ----------

    /// §7.11.3.11 (av1-spec p.279 lines 15550-15569) — the three 1d
    /// master arrays carry only values in `{0..=64}` (the spec's
    /// blending granularity).
    #[test]
    fn r191_wedge_master_1d_values_within_0_64() {
        for &v in WEDGE_MASTER_OBLIQUE_ODD.iter() {
            assert!(v <= 64, "odd entry {} > 64", v);
        }
        for &v in WEDGE_MASTER_OBLIQUE_EVEN.iter() {
            assert!(v <= 64, "even entry {} > 64", v);
        }
        for &v in WEDGE_MASTER_VERTICAL.iter() {
            assert!(v <= 64, "vertical entry {} > 64", v);
        }
        // Edge values: each array starts with 28+ zeros and ends with
        // a flat run of 64s (per the symmetric-around-centre shape).
        assert_eq!(WEDGE_MASTER_OBLIQUE_ODD[0], 0);
        assert_eq!(WEDGE_MASTER_OBLIQUE_ODD[63], 64);
        assert_eq!(WEDGE_MASTER_OBLIQUE_EVEN[0], 0);
        assert_eq!(WEDGE_MASTER_OBLIQUE_EVEN[63], 64);
        assert_eq!(WEDGE_MASTER_VERTICAL[0], 0);
        assert_eq!(WEDGE_MASTER_VERTICAL[63], 64);
    }

    /// §7.11.3.11 (av1-spec p.279) — the lazily-built `MasterMask`
    /// table populates all six directions; every value lives in
    /// `{0..=64}`. The 6 × 64 × 64 = 24576 byte slab is finite.
    #[test]
    fn r191_master_mask_table_values_within_0_64() {
        let table = master_mask_table();
        for (idx, &v) in table.iter().enumerate() {
            assert!(v <= 64, "entry {idx} = {v} > 64");
        }
    }

    /// §7.11.3.11 (av1-spec p.279 line 15506) — the HORIZONTAL master
    /// is the transpose of the VERTICAL master.
    #[test]
    fn r191_master_mask_horizontal_is_vertical_transpose() {
        let table = master_mask_table();
        for i in 0..MASK_MASTER_SIZE {
            for j in 0..MASK_MASTER_SIZE {
                let h = table[idx3(WEDGE_HORIZONTAL as usize, j, i)];
                let v = table[idx3(WEDGE_VERTICAL as usize, i, j)];
                assert_eq!(h, v, "HORIZONTAL[{j}][{i}] != VERTICAL[{i}][{j}]");
            }
        }
    }

    /// §7.11.3.11 (av1-spec p.279 line 15503) — the OBLIQUE27 master
    /// is the transpose of the OBLIQUE63 master.
    #[test]
    fn r191_master_mask_oblique27_is_oblique63_transpose() {
        let table = master_mask_table();
        for i in 0..MASK_MASTER_SIZE {
            for j in 0..MASK_MASTER_SIZE {
                let m27 = table[idx3(WEDGE_OBLIQUE27 as usize, j, i)];
                let m63 = table[idx3(WEDGE_OBLIQUE63 as usize, i, j)];
                assert_eq!(m27, m63, "OBLIQUE27[{j}][{i}] != OBLIQUE63[{i}][{j}]");
            }
        }
    }

    /// §7.11.3.11 — `block_shape` truth-table.
    #[test]
    fn r191_block_shape_truth_table() {
        // tall (h > w): 0
        assert_eq!(block_shape(1, 2), 0);
        assert_eq!(block_shape(2, 4), 0);
        // wide (h < w): 1
        assert_eq!(block_shape(2, 1), 1);
        assert_eq!(block_shape(4, 2), 1);
        // square (h == w): 2
        assert_eq!(block_shape(2, 2), 2);
        assert_eq!(block_shape(4, 4), 2);
    }

    /// §7.11.3.11 — `wedge_mask` populates a BLOCK_8X8 mask buffer
    /// with values in `{0..=64}` for every (wedge_sign, wedge_index)
    /// combination.
    #[test]
    fn r191_wedge_mask_block_8x8_values_within_0_64() {
        const BLOCK_8X8: usize = 3;
        const NUM_4X4: u32 = 2; // 8 / 4
        let mut mask = vec![0u8; 8 * 8];
        for wedge_index in 0..16u8 {
            for wedge_sign in 0..2u8 {
                wedge_mask(
                    BLOCK_8X8,
                    NUM_4X4,
                    NUM_4X4,
                    wedge_index,
                    wedge_sign,
                    &mut mask,
                )
                .unwrap();
                for (idx, &m) in mask.iter().enumerate() {
                    assert!(
                        m <= 64,
                        "wedge_index={wedge_index} wedge_sign={wedge_sign} mask[{idx}] = {m} > 64"
                    );
                }
            }
        }
    }

    /// §7.11.3.11 — flipping `wedge_sign` inverts the mask per pixel
    /// (`new = 64 - old`).
    #[test]
    fn r191_wedge_mask_sign_flip_inverts() {
        const BLOCK_16X16: usize = 6;
        const NUM_4X4: u32 = 4; // 16 / 4
        let mut m0 = vec![0u8; 16 * 16];
        let mut m1 = vec![0u8; 16 * 16];
        wedge_mask(BLOCK_16X16, NUM_4X4, NUM_4X4, 5, 0, &mut m0).unwrap();
        wedge_mask(BLOCK_16X16, NUM_4X4, NUM_4X4, 5, 1, &mut m1).unwrap();
        for i in 0..(16 * 16) {
            assert_eq!(
                m0[i] + m1[i],
                64,
                "pixel {i}: m0={} m1={} sum != 64",
                m0[i],
                m1[i],
            );
        }
    }

    /// §7.11.3.11 — caller-bug rejection.
    #[test]
    fn r191_wedge_mask_rejects_invalid_inputs() {
        let mut mask = vec![0u8; 64];
        // mi_size >= 22 (BLOCK_SIZES)
        assert!(wedge_mask(22, 2, 2, 0, 0, &mut mask).is_err());
        // wedge_index >= 16
        assert!(wedge_mask(3, 2, 2, 16, 0, &mut mask).is_err());
        // wedge_sign > 1
        assert!(wedge_mask(3, 2, 2, 0, 2, &mut mask).is_err());
        // mi_size with WEDGE_BITS == 0 (e.g. BLOCK_4X4 = 0)
        assert!(wedge_mask(0, 1, 1, 0, 0, &mut mask).is_err());
        // num_4x4_wide == 0
        assert!(wedge_mask(3, 0, 2, 0, 0, &mut mask).is_err());
        // mask too small (BLOCK_8X8 wants 64 bytes, give 32)
        let mut tiny = vec![0u8; 32];
        assert!(wedge_mask(3, 2, 2, 0, 0, &mut tiny).is_err());
    }

    // ---------- §7.11.3.12 difference_weight_mask ----------

    /// §7.11.3.12 — for identical predictions (`p0 == p1`), the
    /// per-pixel `diff = 0`, so `m = Clip3(0, 64, 38 + 0/16) = 38`.
    /// `mask_type == 0` yields `38` everywhere; `mask_type == 1`
    /// yields `64 - 38 = 26`.
    #[test]
    fn r191_difference_weight_mask_equal_preds_yields_38() {
        let preds = vec![100i32; 16];
        let mut mask = vec![0u8; 16];
        difference_weight_mask(8, 4, 0, &preds, &preds, 4, 4, &mut mask).unwrap();
        for &m in mask.iter() {
            assert_eq!(m, 38);
        }
        difference_weight_mask(8, 4, 1, &preds, &preds, 4, 4, &mut mask).unwrap();
        for &m in mask.iter() {
            assert_eq!(m, 64 - 38);
        }
    }

    /// §7.11.3.12 — for very large preds difference, the mask
    /// saturates at `64` (`mask_type == 0`) or `0` (`mask_type == 1`).
    /// Spec formula: `m = Clip3(0, 64, 38 + Round2(|p0-p1|, BD-8+IPR) / 16)`.
    /// With 8-bit compound (`IPR = 4`), `BD - 8 = 0`, shift = 4. For
    /// `|p0 - p1| = 10000`, `Round2(10000, 4) = 625`, `625 / 16 = 39`,
    /// `38 + 39 = 77`, clipped to `64`.
    #[test]
    fn r191_difference_weight_mask_saturates_at_64() {
        let preds0 = vec![10000i32; 4];
        let preds1 = vec![0i32; 4];
        let mut mask = vec![0u8; 4];
        difference_weight_mask(8, 4, 0, &preds0, &preds1, 2, 2, &mut mask).unwrap();
        for &m in mask.iter() {
            assert_eq!(m, 64);
        }
        difference_weight_mask(8, 4, 1, &preds0, &preds1, 2, 2, &mut mask).unwrap();
        for &m in mask.iter() {
            assert_eq!(m, 0);
        }
    }

    /// §7.11.3.12 — caller-bug rejection.
    #[test]
    fn r191_difference_weight_mask_rejects_invalid_inputs() {
        let preds = vec![0i32; 16];
        let mut mask = vec![0u8; 16];
        // bit_depth invalid
        assert!(difference_weight_mask(7, 4, 0, &preds, &preds, 4, 4, &mut mask).is_err());
        // mask_type > 1
        assert!(difference_weight_mask(8, 4, 2, &preds, &preds, 4, 4, &mut mask).is_err());
        // w == 0
        assert!(difference_weight_mask(8, 4, 0, &preds, &preds, 0, 4, &mut mask).is_err());
        // mask too small
        let mut tiny = vec![0u8; 8];
        assert!(difference_weight_mask(8, 4, 0, &preds, &preds, 4, 4, &mut tiny).is_err());
        // preds0 too small
        let small = vec![0i32; 4];
        assert!(difference_weight_mask(8, 4, 0, &small, &preds, 4, 4, &mut mask).is_err());
    }

    // ---------- §7.11.3.13 intra_mode_variant_mask ----------

    /// §7.11.3.13 — `II_DC_PRED` yields a uniform mask of `32`
    /// (50/50 blend).
    #[test]
    fn r191_intra_mode_variant_mask_dc_yields_32() {
        let mut mask = vec![0u8; 64];
        intra_mode_variant_mask(II_DC_PRED, 8, 8, &mut mask).unwrap();
        for &m in mask.iter() {
            assert_eq!(m, 32);
        }
    }

    /// §7.11.3.13 — `II_V_PRED` yields a row-only mask (every column
    /// in row `i` is the same value).
    #[test]
    fn r191_intra_mode_variant_mask_v_pred_row_uniform() {
        let mut mask = vec![0u8; 8 * 8];
        intra_mode_variant_mask(II_V_PRED, 8, 8, &mut mask).unwrap();
        for i in 0..8 {
            let row0 = mask[i * 8];
            for j in 0..8 {
                assert_eq!(mask[i * 8 + j], row0, "row {i} col {j} differs");
            }
        }
        // Monotone non-increasing down the rows (matches Ii_Weights_1d).
        for i in 1..8 {
            assert!(mask[i * 8] <= mask[(i - 1) * 8]);
        }
    }

    /// §7.11.3.13 — `II_H_PRED` yields a column-only mask (every row
    /// in col `j` is the same value).
    #[test]
    fn r191_intra_mode_variant_mask_h_pred_col_uniform() {
        let mut mask = vec![0u8; 8 * 8];
        intra_mode_variant_mask(II_H_PRED, 8, 8, &mut mask).unwrap();
        for j in 0..8 {
            let col0 = mask[j];
            for i in 0..8 {
                assert_eq!(mask[i * 8 + j], col0, "col {j} row {i} differs");
            }
        }
    }

    /// §7.11.3.13 — `II_SMOOTH_PRED` is symmetric across the
    /// `i==j` diagonal because it indexes via `Min(i, j)`.
    #[test]
    fn r191_intra_mode_variant_mask_smooth_pred_diagonal_symmetric() {
        let mut mask = vec![0u8; 16 * 16];
        intra_mode_variant_mask(II_SMOOTH_PRED, 16, 16, &mut mask).unwrap();
        for i in 0..16 {
            for j in 0..16 {
                assert_eq!(
                    mask[i * 16 + j],
                    mask[j * 16 + i],
                    "mask[{i}][{j}] != mask[{j}][{i}]"
                );
            }
        }
    }

    /// §7.11.3.13 — `Ii_Weights_1d` is monotonically non-increasing.
    #[test]
    fn r191_ii_weights_1d_monotone_non_increasing() {
        for i in 1..MAX_SB_SIZE {
            assert!(
                II_WEIGHTS_1D[i] <= II_WEIGHTS_1D[i - 1],
                "Ii_Weights_1d[{}] = {} > [{}] = {}",
                i,
                II_WEIGHTS_1D[i],
                i - 1,
                II_WEIGHTS_1D[i - 1],
            );
        }
        assert_eq!(II_WEIGHTS_1D[0], 60);
        assert_eq!(II_WEIGHTS_1D[127], 1);
    }

    /// §7.11.3.13 — caller-bug rejection.
    #[test]
    fn r191_intra_mode_variant_mask_rejects_invalid_inputs() {
        let mut mask = vec![0u8; 64];
        // interintra_mode > 3
        assert!(intra_mode_variant_mask(4, 8, 8, &mut mask).is_err());
        // w == 0
        assert!(intra_mode_variant_mask(II_V_PRED, 0, 8, &mut mask).is_err());
        // h > MAX_SB_SIZE
        assert!(intra_mode_variant_mask(II_V_PRED, 8, 256, &mut mask).is_err());
        // mask too small
        let mut tiny = vec![0u8; 32];
        assert!(intra_mode_variant_mask(II_V_PRED, 8, 8, &mut tiny).is_err());
    }

    // ---------- §7.11.3.14 mask_blend ----------

    /// §7.11.3.14 — `m == 64` ⇒ `out == p0` (entirely the first
    /// prediction). With `m == 0` ⇒ `out == p1`.
    #[test]
    fn r191_mask_blend_full_mask_yields_pred0() {
        let rv = rounding_variables(8, true).unwrap();
        let preds0 = vec![100i32 << (rv.inter_post_round); 16];
        let preds1 = vec![200i32 << (rv.inter_post_round); 16];
        let mask = vec![64u8; 16];
        let mut out = vec![0u16; 16];
        mask_blend(
            8,
            rv.inter_post_round,
            0,
            0,
            &preds0,
            &preds1,
            4,
            4,
            &mask,
            0,
            &mut out,
        )
        .unwrap();
        // m=64, (64-m)=0 ⇒ out = Clip1(Round2(64 * p0, 6 + IPR)).
        // p0 = 100 << IPR, so 64 * 100 << IPR. Round2 by 6 + IPR =>
        // 64 * 100 / 64 = 100.
        for &v in out.iter() {
            assert_eq!(v, 100);
        }

        // m == 0 ⇒ out == p1.
        let mask0 = vec![0u8; 16];
        mask_blend(
            8,
            rv.inter_post_round,
            0,
            0,
            &preds0,
            &preds1,
            4,
            4,
            &mask0,
            0,
            &mut out,
        )
        .unwrap();
        for &v in out.iter() {
            assert_eq!(v, 200);
        }
    }

    /// §7.11.3.14 — `(sub_x, sub_y) == (1, 1)` averages 4 luma-mask
    /// values per chroma pixel; for a uniform luma mask of value
    /// `M`, the chroma mask average is `M` too.
    #[test]
    fn r191_mask_blend_chroma_subsample_4x_average() {
        let rv = rounding_variables(8, true).unwrap();
        // Chroma region 2x2; luma mask region therefore 4x4 (16 entries).
        let preds0 = vec![100i32 << rv.inter_post_round; 4];
        let preds1 = vec![200i32 << rv.inter_post_round; 4];
        let mask = vec![32u8; 16];
        let mut out = vec![0u16; 4];
        mask_blend(
            8,
            rv.inter_post_round,
            1,
            1,
            &preds0,
            &preds1,
            2,
            2,
            &mask,
            0,
            &mut out,
        )
        .unwrap();
        // Average of (32, 32, 32, 32) = 32. out = Round2(32 * p0 + 32 *
        // p1, 6 + IPR) = (100 + 200) / 2 = 150.
        for &v in out.iter() {
            assert_eq!(v, 150);
        }
    }

    /// §7.11.3.14 — interintra mask blend with `m == 64` ⇒ out
    /// stays at `pred1` (the intra prediction). `m == 0` ⇒ out
    /// becomes Clip1(Round2(preds[0], IPR)).
    #[test]
    fn r191_mask_blend_interintra_endpoints() {
        let rv = rounding_variables(8, false).unwrap();
        // IPR for 8-bit, !compound = 0.
        assert_eq!(rv.inter_post_round, 0);
        let preds0 = vec![100i32; 16];
        let mask_full = vec![64u8; 16];
        let mut dst_full = vec![50u16; 16];
        mask_blend_interintra(
            8,
            rv.inter_post_round,
            0,
            0,
            &preds0,
            4,
            4,
            &mask_full,
            0,
            &mut dst_full,
        )
        .unwrap();
        // m=64: out = Round2(64 * pred1 + 0 * pred0, 6) = pred1 = 50.
        for &v in dst_full.iter() {
            assert_eq!(v, 50);
        }
        let mask_zero = vec![0u8; 16];
        let mut dst_zero = vec![50u16; 16];
        mask_blend_interintra(
            8,
            rv.inter_post_round,
            0,
            0,
            &preds0,
            4,
            4,
            &mask_zero,
            0,
            &mut dst_zero,
        )
        .unwrap();
        // m=0: out = Round2(0 * pred1 + 64 * Clip1(Round2(100, 0)), 6)
        //         = Round2(64 * 100, 6) = 100.
        for &v in dst_zero.iter() {
            assert_eq!(v, 100);
        }
    }

    /// §7.11.3.14 — caller-bug rejection.
    #[test]
    fn r191_mask_blend_rejects_invalid_inputs() {
        let preds = vec![0i32; 16];
        let mask = vec![0u8; 16];
        let mut out = vec![0u16; 16];
        // bit_depth invalid
        assert!(mask_blend(7, 0, 0, 0, &preds, &preds, 4, 4, &mask, 0, &mut out).is_err());
        // sub_x > 1
        assert!(mask_blend(8, 0, 2, 0, &preds, &preds, 4, 4, &mask, 0, &mut out).is_err());
        // w == 0
        assert!(mask_blend(8, 0, 0, 0, &preds, &preds, 0, 4, &mask, 0, &mut out).is_err());
        // mask undersized for (sub_x=1, sub_y=1) requires 8*8 = 64 bytes.
        let small_mask = vec![0u8; 16];
        let preds_c = vec![0i32; 4];
        let mut out_c = vec![0u16; 4];
        assert!(mask_blend(
            8,
            0,
            1,
            1,
            &preds_c,
            &preds_c,
            2,
            2,
            &small_mask,
            0,
            &mut out_c
        )
        .is_ok()); // 16 == 4*4 = 64? wait, 2*w=4, 2*h=4, stride*4-1+4 = 4*3+4 = 16 ⇒ exactly 16
        let too_small = vec![0u8; 15];
        assert!(
            mask_blend(8, 0, 1, 1, &preds_c, &preds_c, 2, 2, &too_small, 0, &mut out_c).is_err()
        );
    }

    // ---------- r297 §7.11.3.1 IsInterIntra driver arm ----------

    /// §7.11.3.1 `IsInterIntra == 1` (`isCompound == 0`) arm: the driver
    /// forms a single inter prediction from `refs[0]`, then blends it
    /// with the in-place intra prediction already in `pred_out` through
    /// the §7.11.3.14 inter-intra body, using the §7.11.3.13
    /// intra-variant mask. We drive `predict_inter` and then reproduce
    /// the exact composition standalone — `predict_inter_one_ref`
    /// (refList 0) → `intra_mode_variant_mask` → `mask_blend_interintra`
    /// over the same intra seed — and assert byte-equality.
    #[test]
    fn r297_predict_inter_interintra_matches_standalone_composition() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 13 + c * 7) & 0xFF) as u16;
            }
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        let w = 8;
        let h = 8;
        let bit_depth = 8u8;
        // The §7.11.2 intra prediction the dispatcher already wrote into
        // CurrFrame (here a non-uniform ramp so the blend is observable).
        let intra_seed: Vec<u16> = (0..w * h).map(|k| ((k * 3) & 0xFF) as u16).collect();

        let ii_mode = II_SMOOTH_PRED;

        let mut driver_out = intra_seed.clone();
        predict_inter(
            /* plane */ 0,
            /* x */ 4,
            /* y */ 4,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            /* is_compound */ false,
            /* is_inter_intra */ true,
            bit_depth,
            /* subsampling_x */ 0,
            /* subsampling_y */ 0,
            /* frame_width */ ref_w as u32,
            /* frame_height */ ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            /* compound */ None,
            Some(InterIntraParams {
                interintra_mode: ii_mode,
                wedge: None,
            }),
            /* warp */ None,
            /* obmc */ None,
            &mut driver_out,
        )
        .expect("predict_inter interintra arm");

        // Standalone composition: form preds[0] (pre-clip) exactly like
        // the driver's refList-0 body, build the §7.11.3.13 mask, blend.
        let rv = rounding_variables(bit_depth, /* is_compound */ false).unwrap();
        let pred0 = predict_inter_one_ref(
            &refs[0],
            /* ref_list */ 0,
            /* plane */ 0,
            /* x */ 4,
            /* y */ 4,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            rv.inter_round0,
            rv.inter_round1,
            /* warp */ None,
            /* effective_local_valid */ false,
        )
        .unwrap();
        let mut mask = vec![0u8; w * h];
        intra_mode_variant_mask(ii_mode, w, h, &mut mask).unwrap();
        let mut standalone = intra_seed.clone();
        mask_blend_interintra(
            bit_depth,
            rv.inter_post_round,
            0,
            0,
            &pred0,
            w,
            h,
            &mask,
            0,
            &mut standalone,
        )
        .unwrap();

        assert_eq!(driver_out, standalone);
        // Sanity: the blend actually moved the buffer off the intra seed
        // (the inter prediction is non-trivial here).
        assert_ne!(driver_out, intra_seed);
    }

    /// §7.11.3.1 IsInterIntra arm — caller-bug rejections at the driver
    /// contract: `is_inter_intra` requires `InterIntraParams`, forbids
    /// `is_compound`, and rejects an out-of-range `interintra_mode`; a
    /// spurious `inter_intra = Some(_)` on a non-interintra call is also
    /// rejected.
    #[test]
    fn r297_predict_inter_interintra_caller_bug_rejections() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let refp = vec![7u16; ref_h * ref_w];
        let one = PredictInterRef {
            ref_plane: &refp,
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        };
        let refs1 = [one];
        let refs2 = [
            PredictInterRef {
                ref_plane: &refp,
                ref_stride: ref_w,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [0, 0],
            },
            PredictInterRef {
                ref_plane: &refp,
                ref_stride: ref_w,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [0, 0],
            },
        ];
        let w = 8;
        let h = 8;
        let call = |is_compound: bool,
                    is_ii: bool,
                    refs: &[PredictInterRef<'_>],
                    compound: Option<CompoundParams<'_>>,
                    ii: Option<InterIntraParams<'_>>| {
            let mut out = vec![0u16; w * h];
            predict_inter(
                0,
                2,
                2,
                w,
                h,
                crate::cdf::MOTION_MODE_SIMPLE,
                is_compound,
                is_ii,
                8,
                0,
                0,
                ref_w as u32,
                ref_h as u32,
                EIGHTTAP,
                EIGHTTAP,
                refs,
                compound,
                ii,
                None,
                None,
                &mut out,
            )
        };
        // is_inter_intra without InterIntraParams.
        assert!(call(false, true, &refs1, None, None).is_err());
        // is_inter_intra with out-of-range interintra_mode (> 3).
        assert!(call(
            false,
            true,
            &refs1,
            None,
            Some(InterIntraParams {
                interintra_mode: 4,
                wedge: None,
            })
        )
        .is_err());
        // is_compound && is_inter_intra is contradictory (RefFrame[1]
        // cannot be both > INTRA_FRAME and == INTRA_FRAME).
        assert!(call(
            true,
            true,
            &refs2,
            Some(CompoundParams::Average),
            Some(InterIntraParams {
                interintra_mode: II_DC_PRED,
                wedge: None,
            })
        )
        .is_err());
        // Spurious inter_intra on a plain single-ref call.
        assert!(call(
            false,
            false,
            &refs1,
            None,
            Some(InterIntraParams {
                interintra_mode: II_DC_PRED,
                wedge: None,
            })
        )
        .is_err());
        // Valid interintra call succeeds.
        assert!(call(
            false,
            true,
            &refs1,
            None,
            Some(InterIntraParams {
                interintra_mode: II_DC_PRED,
                wedge: None,
            })
        )
        .is_ok());
    }

    // ---------- r298 §7.11.3.1 wedge inter-intra driver arm ----------

    /// §7.11.3.1 `IsInterIntra == 1` wedge sub-arm (`wedge_interintra ==
    /// 1` ⇒ `compound_type == COMPOUND_WEDGE`, av1-spec p.80 line 5017):
    /// the driver forms a single inter prediction from `refs[0]`, then
    /// blends it with the in-place intra prediction through the
    /// §7.11.3.14 inter-intra body using the §7.11.3.11 luma-grid wedge
    /// mask. At the *luma* plane (`sub_x == sub_y == 0`) the mask is read
    /// directly at `Mask[y][x]`. We drive `predict_inter` and reproduce
    /// the exact composition standalone, asserting byte-equality, and
    /// confirm the wedge mask makes the result differ from the non-wedge
    /// (`wedge == None`) interintra blend on the same seed.
    #[test]
    fn r298_predict_inter_wedge_interintra_luma_matches_standalone() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 11 + c * 5) & 0xFF) as u16;
            }
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        let w = 8;
        let h = 8;
        let bit_depth = 8u8;
        let intra_seed: Vec<u16> = (0..w * h).map(|k| ((k * 3) & 0xFF) as u16).collect();

        // §7.11.3.11 luma-grid wedge mask for BLOCK_8X8 (mi_size 3,
        // 2×2 4×4-units), wedge_index 5, wedge_sign 0 (the value
        // §5.11.28 fixes for the interintra arm, av1-spec p.79 line 4965).
        let mut wmask = vec![0u8; w * h];
        wedge_mask(3, 2, 2, 5, 0, &mut wmask).unwrap();

        // interintra_mode still selects the §7.11.2 intra prediction the
        // caller already wrote into pred_out; the §7.11.3.13 mask is
        // unused on the wedge arm.
        let ii_mode = II_DC_PRED;

        let mut driver_out = intra_seed.clone();
        predict_inter(
            /* plane */ 0,
            /* x */ 4,
            /* y */ 4,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            /* is_compound */ false,
            /* is_inter_intra */ true,
            bit_depth,
            /* subsampling_x */ 0,
            /* subsampling_y */ 0,
            /* frame_width */ ref_w as u32,
            /* frame_height */ ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            /* compound */ None,
            Some(InterIntraParams {
                interintra_mode: ii_mode,
                wedge: Some(WedgeInterIntraInfo {
                    mask: &wmask,
                    mask_stride: 0,
                }),
            }),
            /* warp */ None,
            /* obmc */ None,
            &mut driver_out,
        )
        .expect("predict_inter wedge interintra arm");

        // Standalone composition: refList-0 inter prediction → wedge
        // mask → §7.11.3.14 blend over the same seed.
        let rv = rounding_variables(bit_depth, /* is_compound */ false).unwrap();
        let pred0 = predict_inter_one_ref(
            &refs[0],
            /* ref_list */ 0,
            /* plane */ 0,
            /* x */ 4,
            /* y */ 4,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            rv.inter_round0,
            rv.inter_round1,
            /* warp */ None,
            /* effective_local_valid */ false,
        )
        .unwrap();
        let mut standalone = intra_seed.clone();
        mask_blend_interintra(
            bit_depth,
            rv.inter_post_round,
            0,
            0,
            &pred0,
            w,
            h,
            &wmask,
            0,
            &mut standalone,
        )
        .unwrap();
        assert_eq!(driver_out, standalone);
        assert_ne!(driver_out, intra_seed);

        // The wedge mask genuinely shapes the output: a non-wedge
        // (§7.11.3.13) interintra blend on the same seed differs.
        let mut nonwedge = intra_seed.clone();
        predict_inter(
            0,
            4,
            4,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            true,
            bit_depth,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            Some(InterIntraParams {
                interintra_mode: ii_mode,
                wedge: None,
            }),
            None,
            None,
            &mut nonwedge,
        )
        .unwrap();
        assert_ne!(
            driver_out, nonwedge,
            "wedge mask must shape the blend differently from the §7.11.3.13 mask"
        );
    }

    /// §7.11.3.1 wedge inter-intra at a 4:2:0 *chroma* plane: the
    /// §7.11.3.11 wedge mask is built once on the luma grid, then read
    /// with the `(subX, subY) == (1, 1)` 4-tap averaging the §7.11.3.14
    /// body applies (av1-spec p.284 lines 15778-15781 — the
    /// `(interintra && !wedge_interintra)` short-circuit does NOT fire
    /// on the wedge arm). We drive the chroma `predict_inter` call and
    /// reproduce the downsampled blend standalone.
    #[test]
    fn r298_predict_inter_wedge_interintra_chroma_downsamples_mask() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 9 + c * 17) & 0xFF) as u16;
            }
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        // Chroma prediction region 4×4; the luma block is 8×8, so the
        // luma-grid wedge mask is 8×8 and the chroma plane reads it with
        // 4-tap averaging.
        let cw = 4;
        let ch = 4;
        let luma_w = 8;
        let luma_h = 8;
        let bit_depth = 8u8;
        let intra_seed: Vec<u16> = (0..cw * ch).map(|k| ((k * 7 + 11) & 0xFF) as u16).collect();

        let mut wmask = vec![0u8; luma_w * luma_h];
        wedge_mask(3, 2, 2, 5, 0, &mut wmask).unwrap();

        let mut driver_out = intra_seed.clone();
        predict_inter(
            /* plane */ 1,
            /* x */ 0,
            /* y */ 0,
            cw,
            ch,
            crate::cdf::MOTION_MODE_SIMPLE,
            /* is_compound */ false,
            /* is_inter_intra */ true,
            bit_depth,
            /* subsampling_x */ 1,
            /* subsampling_y */ 1,
            /* frame_width */ ref_w as u32,
            /* frame_height */ ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            /* compound */ None,
            Some(InterIntraParams {
                interintra_mode: II_DC_PRED,
                wedge: Some(WedgeInterIntraInfo {
                    mask: &wmask,
                    mask_stride: 0,
                }),
            }),
            /* warp */ None,
            /* obmc */ None,
            &mut driver_out,
        )
        .expect("predict_inter wedge interintra chroma arm");

        // Standalone: chroma refList-0 inter prediction, then the
        // §7.11.3.14 `(1,1)` averaging over the luma-grid wedge mask.
        let rv = rounding_variables(bit_depth, false).unwrap();
        let pred0 = predict_inter_one_ref(
            &refs[0],
            0,
            /* plane */ 1,
            0,
            0,
            cw,
            ch,
            crate::cdf::MOTION_MODE_SIMPLE,
            1,
            1,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            rv.inter_round0,
            rv.inter_round1,
            None,
            false,
        )
        .unwrap();
        let mut standalone = intra_seed.clone();
        mask_blend_interintra(
            bit_depth,
            rv.inter_post_round,
            /* sub_x */ 1,
            /* sub_y */ 1,
            &pred0,
            cw,
            ch,
            &wmask,
            0,
            &mut standalone,
        )
        .unwrap();
        assert_eq!(driver_out, standalone);

        // Independent oracle for the averaging: build the 4×4 chroma mask
        // by hand (4-tap Round2 average of each 2×2 luma-mask quad) and
        // run the non-subsampled blend over it; the two must agree.
        let mut chroma_mask = vec![0u8; cw * ch];
        for y in 0..ch {
            for x in 0..cw {
                let s = wmask[2 * y * luma_w + 2 * x] as i64
                    + wmask[2 * y * luma_w + 2 * x + 1] as i64
                    + wmask[(2 * y + 1) * luma_w + 2 * x] as i64
                    + wmask[(2 * y + 1) * luma_w + 2 * x + 1] as i64;
                chroma_mask[y * cw + x] = round2(s, 2) as u8;
            }
        }
        let mut oracle = intra_seed.clone();
        mask_blend_interintra(
            bit_depth,
            rv.inter_post_round,
            0,
            0,
            &pred0,
            cw,
            ch,
            &chroma_mask,
            0,
            &mut oracle,
        )
        .unwrap();
        assert_eq!(
            driver_out, oracle,
            "chroma wedge interintra must equal a hand-downsampled non-subsampled blend"
        );
    }

    // ---------- §7.11.3.15 distance_weights ----------

    /// §5.9.3 `get_relative_dist` — basic sign-extension truth table.
    #[test]
    fn r191_get_relative_dist_truth_table() {
        // enable_order_hint == 0 -> always 0.
        assert_eq!(get_relative_dist(5, 3, 0), 0);
        assert_eq!(get_relative_dist(-5, 3, 0), 0);
        // 7-bit OrderHintBits: range -64..64.
        // diff = 10 - 5 = 5; m = 64; (5 & 63) - (5 & 64) = 5 - 0 = 5
        assert_eq!(get_relative_dist(10, 5, 7), 5);
        // diff = 5 - 10 = -5; -5 in two's complement i32 = 0xFFFFFFFB
        // mask m-1=63 yields 0x3B = 59; mask m=64 yields 0x40 = 64
        // 59 - 64 = -5.
        assert_eq!(get_relative_dist(5, 10, 7), -5);
        // wrap-around test: diff = 100, m = 64; (100 & 63) - (100 & 64)
        // = 36 - 64 = -28.
        assert_eq!(get_relative_dist(100, 0, 7), -28);
    }

    /// §7.11.3.15 — `Quant_Dist_Lookup` rows always sum to `16`.
    #[test]
    fn r191_quant_dist_lookup_sums_to_16() {
        for (i, row) in QUANT_DIST_LOOKUP.iter().enumerate() {
            assert_eq!(row[0] + row[1], 16, "row {i} = {:?}", row);
        }
    }

    /// §7.11.3.15 — equal-distance refs (`d0 == d1`) take the
    /// `order_bool == true` (d0 <= d1) path. With `dist0 == dist1
    /// == 5`, the loop's first iteration (`i = 0`, `c0 = 2`, `c1 = 3`)
    /// fires `5 * 2 > 5 * 3` ⇒ `10 > 15` ⇒ false; second (`i = 1`,
    /// `c0 = 2`, `c1 = 5`): `10 > 25` ⇒ false; third (`i = 2`, `c0 =
    /// 2`, `c1 = 7`): `10 > 35` ⇒ false. Fall-through to `i = 3`:
    /// `Lookup[3][1]`/`[0]` ⇒ FwdWeight=3, BckWeight=13 — the
    /// strongest backward-skew.
    #[test]
    fn r191_distance_weights_equal_distances() {
        // current=0, ref0=5, ref1=5 ⇒ dist0=5, dist1=5, d0=d1=5
        let dw = distance_weights(7, 0, 5, 5);
        assert_eq!(dw.fwd_weight + dw.bck_weight, 16);
    }

    /// §7.11.3.15 — zero-distance ref triggers the early-return
    /// `Quant_Dist_Lookup[3]` branch.
    #[test]
    fn r191_distance_weights_zero_distance_branch() {
        // current=10, ref0=10 (dist0=0), ref1=5 (dist1=5).
        // d0 = dist1 = 5, d1 = dist0 = 0. d0 == 0 false; d1 == 0 true.
        // order = d0 <= d1 ⇒ 5 <= 0 ⇒ false ⇒ order=0, other=1.
        // FwdWeight = Lookup[3][0] = 13, BckWeight = Lookup[3][1] = 3.
        let dw = distance_weights(7, 10, 10, 5);
        assert_eq!(dw.fwd_weight, 13);
        assert_eq!(dw.bck_weight, 3);
    }

    /// §7.11.3.15 — `enable_order_hint == 0` (`order_hint_bits == 0`)
    /// ⇒ both distances collapse to 0 ⇒ early-return branch with
    /// `order_bool = (d0 <= d1) = (0 <= 0) = true` ⇒
    /// FwdWeight=Lookup[3][order=1]=3, BckWeight=Lookup[3][other=0]=13.
    #[test]
    fn r191_distance_weights_no_order_hint() {
        let dw = distance_weights(0, 0, 0, 0);
        assert_eq!(dw.fwd_weight, 3);
        assert_eq!(dw.bck_weight, 13);
    }

    /// §7.11.3.15 — asymmetric distances exercise the per-`i`
    /// search. current=0, ref0=1 (dist0=1), ref1=10 (dist1=10).
    /// d0=dist1=10, d1=dist0=1. order = (10 <= 1) = false ⇒ order=0,
    /// other=1.
    /// i=0: c0=Weight[0][0]=2, c1=Weight[0][1]=3, lhs=10*2=20,
    /// rhs=1*3=3, break if lhs < rhs ⇒ 20 < 3 false, continue.
    /// i=1: c0=2, c1=5, lhs=20, rhs=5, 20 < 5 false.
    /// i=2: c0=2, c1=7, lhs=20, rhs=7, 20 < 7 false.
    /// Fall-through i=3 ⇒ FwdWeight=Lookup[3][0]=13, BckWeight=Lookup[3][1]=3.
    #[test]
    fn r191_distance_weights_asymmetric_far_forward() {
        let dw = distance_weights(7, 0, 1, 10);
        assert_eq!(dw.fwd_weight, 13);
        assert_eq!(dw.bck_weight, 3);
    }

    /// §7.11.3.15 — `compound_distance_blend` with `FwdWeight =
    /// BckWeight = 8` reduces to the same `Round2(8 * (p0 + p1), 4 +
    /// IPR)`. With p0 = p1 = 100 << IPR, output = 100.
    #[test]
    fn r191_compound_distance_blend_symmetric() {
        let rv = rounding_variables(8, true).unwrap();
        let preds0 = vec![100i32 << rv.inter_post_round; 16];
        let preds1 = vec![200i32 << rv.inter_post_round; 16];
        let weights = DistanceWeights {
            fwd_weight: 8,
            bck_weight: 8,
        };
        let mut out = vec![0u16; 16];
        compound_distance_blend(
            8,
            rv.inter_post_round,
            weights,
            &preds0,
            &preds1,
            4,
            4,
            &mut out,
        )
        .unwrap();
        // (8 * 100 + 8 * 200) / 16 = (8 * 300) / 16 = 150.
        for &v in out.iter() {
            assert_eq!(v, 150);
        }
    }

    /// §7.11.3.15 — `compound_distance_blend` caller-bug rejection.
    #[test]
    fn r191_compound_distance_blend_rejects_invalid_inputs() {
        let preds = vec![0i32; 16];
        let mut out = vec![0u16; 16];
        let w = DistanceWeights {
            fwd_weight: 8,
            bck_weight: 8,
        };
        assert!(compound_distance_blend(7, 0, w, &preds, &preds, 4, 4, &mut out).is_err());
        assert!(compound_distance_blend(8, 0, w, &preds, &preds, 0, 4, &mut out).is_err());
        let mut tiny = vec![0u16; 8];
        assert!(compound_distance_blend(8, 0, w, &preds, &preds, 4, 4, &mut tiny).is_err());
    }

    // ---------- §7.11.3.5-8 warp MC ----------

    /// §7.11.3.7 — `resolve_divisor(0)` is a caller-bug return.
    #[test]
    fn r192_resolve_divisor_zero_returns_none() {
        assert!(resolve_divisor(0).is_none());
    }

    /// §7.11.3.7 — `resolve_divisor(d) ≈ 1/d`. Walk a couple of
    /// known inputs and check `Round2Signed(d * divFactor, divShift)`
    /// approximates `1` after scaling by `d`.
    #[test]
    fn r192_resolve_divisor_basic_inverse() {
        // d = 256: n = FloorLog2(256) = 8, e = 0, n <= DIV_LUT_BITS
        // ⇒ f = 0 << 0 = 0. divFactor = Div_Lut[0] = 16384,
        // divShift = 8 + 14 = 22. d * divFactor = 256 * 16384 =
        // 4194304; Round2Signed(4194304, 22) = (4194304 + 2^21) >> 22
        // = 6291456 >> 22 = 1. So d * f / 2^shift ≈ 1.
        let div = resolve_divisor(256).unwrap();
        assert_eq!(div.div_factor, 16384);
        assert_eq!(div.div_shift, 22);
        let lhs: i64 = 256i64 * (div.div_factor as i64);
        let approx = round2_signed(lhs, div.div_shift);
        assert_eq!(approx, 1);

        // d = 1024: n = 10, e = 0, n > DIV_LUT_BITS (10 > 8)
        // ⇒ f = Round2(0, 2) = 0. divFactor = 16384, divShift = 24.
        let div = resolve_divisor(1024).unwrap();
        assert_eq!(div.div_factor, 16384);
        assert_eq!(div.div_shift, 24);

        // d = 1: n = 0, e = 0, n <= DIV_LUT_BITS ⇒ f = 0 << 8 = 0.
        // divFactor = 16384, divShift = 14. 1 * 16384 / 16384 = 1.
        let div = resolve_divisor(1).unwrap();
        let approx = round2_signed(div.div_factor as i64, div.div_shift);
        assert_eq!(approx, 1);
    }

    /// §7.11.3.7 — negative `d` ⇒ negated `divFactor`.
    #[test]
    fn r192_resolve_divisor_negative_flips_sign() {
        let p = resolve_divisor(256).unwrap();
        let n = resolve_divisor(-256).unwrap();
        assert_eq!(n.div_factor, -p.div_factor);
        assert_eq!(n.div_shift, p.div_shift);
    }

    /// §7.11.3.6 — identity-affine warpParams `[0, 0, 1<<16, 0, 0,
    /// 1<<16]` shears to `(alpha, beta, gamma, delta) = (0, 0, 0, 0)`
    /// and `warpValid = true`.
    #[test]
    fn r192_setup_shear_identity_is_zero() {
        let one = 1i32 << WARP_WARPEDMODEL_PREC_BITS;
        let shear = setup_shear([0, 0, one, 0, 0, one]).unwrap();
        assert_eq!(shear.alpha, 0);
        assert_eq!(shear.beta, 0);
        assert_eq!(shear.gamma, 0);
        assert_eq!(shear.delta, 0);
        assert!(shear.warp_valid);
    }

    /// §7.11.3.6 — `warpParams[2] = 0` is the only divisor-zero case.
    /// All other matrices yield Some(_).
    #[test]
    fn r192_setup_shear_zero_diag_is_caller_bug() {
        let shear = setup_shear([0, 0, 0, 0, 0, 1 << WARP_WARPEDMODEL_PREC_BITS]);
        assert!(shear.is_none());
    }

    /// §7.11.3.6 — small horizontal shear: warpParams[2] = (1<<16) +
    /// 64 ⇒ alpha0 = 64, beta0 = 0, then Round2Signed/<<6 returns 64.
    #[test]
    fn r192_setup_shear_small_horizontal_shear() {
        let one = 1i32 << WARP_WARPEDMODEL_PREC_BITS;
        let shear = setup_shear([0, 0, one + 64, 0, 0, one]).unwrap();
        // alpha0 = 64 - 0 = 64; reduced: Round2Signed(64, 6) << 6 =
        // ((64 + 32) >> 6) << 6 = 1 << 6 = 64.
        assert_eq!(shear.alpha, 64);
        assert_eq!(shear.beta, 0);
        // gamma derives from warpParams[4] which is 0 ⇒ 0.
        assert_eq!(shear.gamma, 0);
        // delta derives from warpParams[5] - correction - one = 0.
        assert_eq!(shear.delta, 0);
        assert!(shear.warp_valid);
    }

    /// §7.11.3.6 — large alpha makes `warpValid` flip false. The
    /// final bound is `4 * |alpha| + 7 * |beta| < 1 << 16 = 65536`,
    /// so alpha = 16384, beta = 0 gives 65536, NOT strictly less ⇒
    /// invalid.
    #[test]
    fn r192_setup_shear_rejects_unstable_factorisation() {
        let one = 1i32 << WARP_WARPEDMODEL_PREC_BITS;
        // alpha0 = warpParams[2] - one = 16384 ⇒ reduced same.
        let shear = setup_shear([0, 0, one + 16384, 0, 0, one]).unwrap();
        assert_eq!(shear.alpha, 16384);
        // 4 * 16384 = 65536 = 1 << 16 ⇒ NOT strictly less than ⇒
        // warpValid = false.
        assert!(!shear.warp_valid);
    }

    /// §7.11.3.8 — empty candidate list ⇒ det = 0 ⇒ LocalValid = false.
    #[test]
    fn r192_warp_estimation_empty_cands_is_invalid() {
        let lw = warp_estimation(&[], 0, 0, 4, 4, [0, 0]);
        assert!(!lw.local_valid);
    }

    /// §7.11.3.8 — single colinear candidate ⇒ det = 0 ⇒ invalid.
    /// One sample alone can't determine an affine model.
    #[test]
    fn r192_warp_estimation_single_cand_is_invalid() {
        let lw = warp_estimation(
            &[WarpSampleCand {
                sy: 0,
                sx: 0,
                dy: 0,
                dx: 0,
            }],
            0,
            0,
            4,
            4,
            [0, 0],
        );
        // det = A[0][0] * A[1][1] - A[0][1]^2 = 8 * 8 - 4^2 = 48 != 0
        // so this actually is valid! Update expectation.
        assert!(lw.local_valid);
    }

    /// §7.11.3.5 — `useWarp` out of {1, 2} is a caller bug.
    #[test]
    fn r192_block_warp_rejects_invalid_use_warp() {
        let ref_plane = vec![128u16; 64 * 64];
        let mut pred = vec![0i32; 16 * 16];
        let one = 1i32 << WARP_WARPEDMODEL_PREC_BITS;
        let res = block_warp(
            0, // invalid use_warp
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            16,
            16,
            &ref_plane,
            64,
            64,
            64,
            [0, 0, one, 0, 0, one],
            3,
            11,
            16,
            &mut pred,
        );
        assert!(res.is_err());
    }

    /// §7.11.3.5 — caller-bug rejections (sub > 1, dims = 0, etc.).
    #[test]
    fn r192_block_warp_rejects_invalid_dims() {
        let ref_plane = vec![128u16; 64 * 64];
        let mut pred = vec![0i32; 16 * 16];
        let one = 1i32 << WARP_WARPEDMODEL_PREC_BITS;
        // plane > 2.
        assert!(block_warp(
            1,
            3,
            0,
            0,
            0,
            0,
            0,
            0,
            16,
            16,
            &ref_plane,
            64,
            64,
            64,
            [0, 0, one, 0, 0, one],
            3,
            11,
            16,
            &mut pred,
        )
        .is_err());
        // w = 0.
        assert!(block_warp(
            1,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            16,
            &ref_plane,
            64,
            64,
            64,
            [0, 0, one, 0, 0, one],
            3,
            11,
            16,
            &mut pred,
        )
        .is_err());
        // h = 0.
        assert!(block_warp(
            1,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            16,
            0,
            &ref_plane,
            64,
            64,
            64,
            [0, 0, one, 0, 0, one],
            3,
            11,
            16,
            &mut pred,
        )
        .is_err());
        // i8b * 8 >= h ⇒ caller asked for an out-of-range sub-section.
        assert!(block_warp(
            1,
            0,
            0,
            0,
            0,
            0,
            2,
            0,
            16,
            16,
            &ref_plane,
            64,
            64,
            64,
            [0, 0, one, 0, 0, one],
            3,
            11,
            16,
            &mut pred,
        )
        .is_err());
    }

    /// §7.11.3.5 — identity warp on a constant reference plane gives
    /// a constant predicted block (rounding by `inter_round1` brings
    /// the post-Round2 value back to the constant sample value
    /// scaled by 128 (the filter's row sum)).
    ///
    /// Each phase-`offs` row of `Warped_Filters` sums to 128 (the
    /// integer-position rows are `{0,0,127,1,0,0,0,0}` and
    /// `{0,0,0,127,1,0,0,0}` and `{0,0,0,1,127,0,0,0}` all summing
    /// to 128). For a constant input `C`, the horizontal pass
    /// produces `Round2(128 * C, inter_round0) = 128 * C >> 3 = 16 *
    /// C`, then the vertical pass produces `Round2(128 * 16 * C,
    /// inter_round1) = 2048 * C >> 11 = C`. So an identity warp on a
    /// constant ref recovers the constant.
    #[test]
    fn r192_block_warp_identity_on_constant_ref() {
        let cst: u16 = 100;
        let ref_plane = vec![cst; 64 * 64];
        let mut pred = vec![0i32; 8 * 8];
        let one = 1i32 << WARP_WARPEDMODEL_PREC_BITS;
        // Identity warp: warpParams = [0, 0, one, 0, 0, one] —
        // (dstX, dstY) = (one * srcX, one * srcY); after >> sub_x
        // (=0 for luma) and >> WARPEDMODEL_PREC_BITS gives ix4 =
        // srcX, iy4 = srcY, sx4 = sy4 = 0. With alpha = beta = gamma
        // = delta = 0, sx = sy = 0 for every (i1, i2). offs =
        // Round2(0, 10) + 64 = 64 ⇒ row 64 of Warped_Filters
        // ({0, 0, 0, 127, 1, 0, 0, 0}) sums to 128. For a constant
        // ref the convolution reduces to 128 * cst at every
        // (intermediate row, sub-section pixel).
        block_warp(
            1,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            8,
            8,
            &ref_plane,
            64,
            64,
            64,
            [0, 0, one, 0, 0, one],
            3,  // inter_round0 = 3 for 8-bit
            11, // inter_round1 = 11 for 8-bit non-compound
            8,
            &mut pred,
        )
        .unwrap();
        for (i, &v) in pred.iter().enumerate() {
            assert_eq!(v, cst as i32, "pred[{i}] = {v} != {cst}");
        }
    }

    /// §7.11.3.5 — Warped_Filters dimension sanity: outer = 193, inner = 8.
    #[test]
    fn r192_warped_filters_table_shape() {
        assert_eq!(WARPED_FILTERS.len(), WARPEDPIXEL_PREC_SHIFTS * 3 + 1);
        assert_eq!(WARPED_FILTERS.len(), 193);
        for row in WARPED_FILTERS.iter() {
            assert_eq!(row.len(), 8);
        }
    }

    /// §7.11.3.5 — every Warped_Filters row sums to 128 (the
    /// filter normalises to unit response).
    #[test]
    fn r192_warped_filters_rows_sum_to_128() {
        for (i, row) in WARPED_FILTERS.iter().enumerate() {
            let s: i32 = row.iter().sum();
            assert_eq!(s, 128, "row {i} sums to {s}");
        }
    }

    /// §7.11.3.5 — Div_Lut[0] = 16384 = 1 << DIV_LUT_PREC_BITS;
    /// Div_Lut[256] = 8192. Monotonically non-increasing.
    #[test]
    fn r192_div_lut_shape() {
        assert_eq!(DIV_LUT.len(), 257);
        assert_eq!(DIV_LUT[0], 1 << DIV_LUT_PREC_BITS);
        assert_eq!(DIV_LUT[256], 8192);
        for w in DIV_LUT.windows(2) {
            assert!(w[0] >= w[1], "Div_Lut not monotonic at {} > {}", w[0], w[1]);
        }
    }

    // ---------- §7.11.3.9-10 OBMC ----------

    /// §7.11.3.9 + p.277: the five `Obmc_Mask_*` tables have the
    /// declared lengths and every entry is in `0..=64` (since
    /// §7.11.3.10's `64 - m` must stay non-negative).
    #[test]
    fn r193_obmc_mask_table_shapes() {
        assert_eq!(OBMC_MASK_2.len(), 2);
        assert_eq!(OBMC_MASK_4.len(), 4);
        assert_eq!(OBMC_MASK_8.len(), 8);
        assert_eq!(OBMC_MASK_16.len(), 16);
        assert_eq!(OBMC_MASK_32.len(), 32);
        for &m in OBMC_MASK_2
            .iter()
            .chain(OBMC_MASK_4.iter())
            .chain(OBMC_MASK_8.iter())
            .chain(OBMC_MASK_16.iter())
            .chain(OBMC_MASK_32.iter())
        {
            assert!(m <= 64, "obmc mask entry {m} > 64");
        }
    }

    /// §7.11.3.9 p.277 — the spec's literal table values: the first
    /// entries (`Obmc_Mask_2[0] = 45`, `Obmc_Mask_4[0] = 39`,
    /// `Obmc_Mask_8[0] = 36`, `Obmc_Mask_16[0] = 34`,
    /// `Obmc_Mask_32[0] = 33`) and the table tails (last value of each
    /// table = 64, indicating the overlap fully sticks to the original
    /// sample at the boundary furthest from the neighbour).
    #[test]
    fn r193_obmc_mask_first_and_last_values() {
        assert_eq!(OBMC_MASK_2[0], 45);
        assert_eq!(OBMC_MASK_2[1], 64);
        assert_eq!(OBMC_MASK_4[0], 39);
        assert_eq!(*OBMC_MASK_4.last().unwrap(), 64);
        assert_eq!(OBMC_MASK_8[0], 36);
        assert_eq!(*OBMC_MASK_8.last().unwrap(), 64);
        assert_eq!(OBMC_MASK_16[0], 34);
        assert_eq!(*OBMC_MASK_16.last().unwrap(), 64);
        assert_eq!(OBMC_MASK_32[0], 33);
        assert_eq!(*OBMC_MASK_32.last().unwrap(), 64);
    }

    /// §7.11.3.9 `get_obmc_mask(length)` p.276 lines 15381-15393 —
    /// returns the matching table for the five spec-listed lengths.
    #[test]
    fn r193_get_obmc_mask_dispatches_each_size() {
        assert_eq!(get_obmc_mask(2), &OBMC_MASK_2[..]);
        assert_eq!(get_obmc_mask(4), &OBMC_MASK_4[..]);
        assert_eq!(get_obmc_mask(8), &OBMC_MASK_8[..]);
        assert_eq!(get_obmc_mask(16), &OBMC_MASK_16[..]);
        assert_eq!(get_obmc_mask(32), &OBMC_MASK_32[..]);
    }

    /// §7.11.3.9 `get_obmc_mask` `else` branch (p.276 line 15390) — any
    /// length outside `{2, 4, 8, 16}` falls through to
    /// `Obmc_Mask_32`. The driver never produces such a length in
    /// practice but the function's contract preserves the spec's
    /// `else` clause.
    #[test]
    fn r193_get_obmc_mask_else_returns_mask_32() {
        assert_eq!(get_obmc_mask(32), &OBMC_MASK_32[..]);
        assert_eq!(get_obmc_mask(33), &OBMC_MASK_32[..]);
        assert_eq!(get_obmc_mask(1), &OBMC_MASK_32[..]);
        assert_eq!(get_obmc_mask(0), &OBMC_MASK_32[..]);
        assert_eq!(get_obmc_mask(7), &OBMC_MASK_32[..]);
    }

    /// §7.11.3.10 fixed-point invariant — when `obmc_pred == curr`
    /// everywhere, the blend leaves the buffer unchanged for any
    /// mask values:
    ///
    ///   Round2( m * v + (64 - m) * v, 6 ) = Round2(64 * v, 6) = v
    ///
    /// holds exactly because `64 = 1 << 6` so the Round2 rounding bit
    /// `+(1 << 5)` is the canonical mid-point that maps back to v.
    #[test]
    fn r193_overlap_blending_identity_when_obmc_equals_curr() {
        // 4x4 region inside a 6x8 plane, pred_x=1, pred_y=1.
        let curr_stride = 8usize;
        let curr_h = 6usize;
        let mut curr: Vec<u16> = (0..(curr_stride * curr_h) as u16).collect();
        let pre = curr.clone();
        let pred_w = 4usize;
        let pred_h = 4usize;
        let pred_x = 1usize;
        let pred_y = 1usize;
        // obmcPred[i][j] = curr[pred_y + i][pred_x + j].
        let mut obmc = vec![0u16; pred_w * pred_h];
        for i in 0..pred_h {
            for j in 0..pred_w {
                obmc[i * pred_w + j] = curr[(pred_y + i) * curr_stride + pred_x + j];
            }
        }
        overlap_blending(
            &mut curr,
            curr_stride,
            pred_x,
            pred_y,
            pred_w,
            pred_h,
            OverlapPass::Above,
            &obmc,
            pred_w,
            &OBMC_MASK_4,
        )
        .unwrap();
        assert_eq!(curr, pre, "obmc == curr ⇒ blend identity");
    }

    /// §7.11.3.10 — `pass == Above` selects `m = mask[i]` (per row).
    /// With `curr = 0`, `obmc = 64` everywhere, and the `Obmc_Mask_4`
    /// table `{39, 50, 59, 64}`, the output rows are:
    ///
    ///   Round2( m * 0 + (64 - m) * 64, 6 )
    ///     = Round2( (64 - m) * 64, 6 )
    ///     = 64 - m
    ///
    /// so the output rows = {25, 14, 5, 0}.
    #[test]
    fn r193_overlap_blending_above_uses_row_mask() {
        let curr_stride = 4usize;
        let mut curr = vec![0u16; curr_stride * 4];
        let obmc = vec![64u16; curr_stride * 4];
        overlap_blending(
            &mut curr,
            curr_stride,
            0,
            0,
            4,
            4,
            OverlapPass::Above,
            &obmc,
            curr_stride,
            &OBMC_MASK_4,
        )
        .unwrap();
        let expected_per_row: [u16; 4] = [64 - 39, 64 - 50, 64 - 59, 64 - 64];
        for i in 0..4 {
            for j in 0..4 {
                assert_eq!(
                    curr[i * curr_stride + j],
                    expected_per_row[i],
                    "above row {i} col {j}",
                );
            }
        }
    }

    /// §7.11.3.10 — `pass == Left` selects `m = mask[j]` (per col).
    /// Mirror of the above-test: with `curr = 0`, `obmc = 64`, output
    /// columns = `{25, 14, 5, 0}`.
    #[test]
    fn r193_overlap_blending_left_uses_col_mask() {
        let curr_stride = 4usize;
        let mut curr = vec![0u16; curr_stride * 4];
        let obmc = vec![64u16; curr_stride * 4];
        overlap_blending(
            &mut curr,
            curr_stride,
            0,
            0,
            4,
            4,
            OverlapPass::Left,
            &obmc,
            curr_stride,
            &OBMC_MASK_4,
        )
        .unwrap();
        let expected_per_col: [u16; 4] = [64 - 39, 64 - 50, 64 - 59, 64 - 64];
        for i in 0..4 {
            for j in 0..4 {
                assert_eq!(
                    curr[i * curr_stride + j],
                    expected_per_col[j],
                    "left row {i} col {j}",
                );
            }
        }
    }

    /// §7.11.3.10 — the blend is bounded by `max(curr, obmc)` and
    /// floored by `min(curr, obmc)` regardless of mask weights (the
    /// blend is a convex combination of the two inputs).
    #[test]
    fn r193_overlap_blending_is_convex_combination() {
        let curr_stride = 8usize;
        let mut curr = vec![100u16; curr_stride * 8];
        let obmc = vec![300u16; curr_stride * 8];
        overlap_blending(
            &mut curr,
            curr_stride,
            0,
            0,
            8,
            8,
            OverlapPass::Above,
            &obmc,
            curr_stride,
            &OBMC_MASK_8,
        )
        .unwrap();
        for v in &curr {
            assert!(*v >= 100 && *v <= 300, "value {v} outside [100, 300]");
        }
    }

    /// §7.11.3.10 — `pass == Above` with `m = mask[0]` overrides the
    /// top row's blend; the bottom row (`mask[pred_h - 1]`) overrides
    /// the bottom row. For `Obmc_Mask_8 = {36, 42, 48, 53, 57, 61,
    /// 64, 64}`, with `curr = 200`, `obmc = 40`:
    ///
    ///   row 0: Round2( 36 * 200 + 28 * 40, 6 )
    ///        = Round2( 7200 + 1120, 6 ) = Round2( 8320, 6 ) = 130
    ///   row 7: Round2( 64 * 200 +  0 * 40, 6 )
    ///        = Round2( 12800, 6 )                              = 200
    #[test]
    fn r193_overlap_blending_above_hand_computed_8tap() {
        let curr_stride = 8usize;
        let mut curr = vec![200u16; curr_stride * 8];
        let obmc = vec![40u16; curr_stride * 8];
        overlap_blending(
            &mut curr,
            curr_stride,
            0,
            0,
            8,
            8,
            OverlapPass::Above,
            &obmc,
            curr_stride,
            &OBMC_MASK_8,
        )
        .unwrap();
        // Row 0: Round2(36 * 200 + 28 * 40, 6) = Round2(8320, 6) = 130.
        for (j, v) in curr.iter().enumerate().take(8) {
            assert_eq!(*v, 130, "row 0 col {j}");
        }
        // Row 7: Round2(64 * 200 + 0 * 40, 6) = Round2(12800, 6) = 200.
        let row7 = &curr[7 * curr_stride..7 * curr_stride + 8];
        for (j, v) in row7.iter().enumerate() {
            assert_eq!(*v, 200, "row 7 col {j}");
        }
    }

    /// §7.11.3.10 — `pred_x` / `pred_y` correctly offset the write
    /// region. With `pred_x = 2`, `pred_y = 3`, the rows above 3 and
    /// the cols left of 2 must be unchanged.
    #[test]
    fn r193_overlap_blending_offsets_respected() {
        let curr_stride = 8usize;
        let mut curr = vec![17u16; curr_stride * 8];
        let pre = curr.clone();
        let obmc = vec![64u16; 4 * 4];
        overlap_blending(
            &mut curr,
            curr_stride,
            2,
            3,
            4,
            4,
            OverlapPass::Above,
            &obmc,
            4,
            &OBMC_MASK_4,
        )
        .unwrap();
        // Outside region: unchanged.
        for i in 0..8 {
            for j in 0..8 {
                let in_region = (3..7).contains(&i) && (2..6).contains(&j);
                if !in_region {
                    assert_eq!(
                        curr[i * curr_stride + j],
                        pre[i * curr_stride + j],
                        "outside-region ({i},{j}) modified",
                    );
                }
            }
        }
    }

    /// §7.11.3.10 — caller-bug rejections.
    #[test]
    fn r193_overlap_blending_rejects_caller_bugs() {
        let mut curr = vec![0u16; 64];
        let obmc = vec![0u16; 64];
        // pred_w == 0
        assert!(overlap_blending(
            &mut curr,
            8,
            0,
            0,
            0,
            4,
            OverlapPass::Above,
            &obmc,
            4,
            &OBMC_MASK_4
        )
        .is_err());
        // pred_h == 0
        assert!(overlap_blending(
            &mut curr,
            8,
            0,
            0,
            4,
            0,
            OverlapPass::Above,
            &obmc,
            4,
            &OBMC_MASK_4
        )
        .is_err());
        // obmc_stride < pred_w
        assert!(overlap_blending(
            &mut curr,
            8,
            0,
            0,
            4,
            4,
            OverlapPass::Above,
            &obmc,
            3,
            &OBMC_MASK_4
        )
        .is_err());
        // curr_stride < pred_x + pred_w
        assert!(overlap_blending(
            &mut curr,
            4,
            2,
            0,
            4,
            4,
            OverlapPass::Above,
            &obmc,
            4,
            &OBMC_MASK_4
        )
        .is_err());
        // obmc too short
        let tiny = vec![0u16; 4];
        assert!(overlap_blending(
            &mut curr,
            8,
            0,
            0,
            4,
            4,
            OverlapPass::Above,
            &tiny,
            4,
            &OBMC_MASK_4
        )
        .is_err());
        // current_plane too short
        let mut small = vec![0u16; 8];
        assert!(overlap_blending(
            &mut small,
            8,
            0,
            0,
            4,
            4,
            OverlapPass::Above,
            &obmc,
            4,
            &OBMC_MASK_4
        )
        .is_err());
        // mask too short for the pass axis
        let mut curr2 = vec![0u16; 64];
        let one = [64u8; 1];
        assert!(overlap_blending(
            &mut curr2,
            8,
            0,
            0,
            4,
            4,
            OverlapPass::Above,
            &obmc,
            4,
            &one
        )
        .is_err());
    }

    /// §7.11.3.9 `predict_overlap` step-8 wrapper — calling the helper
    /// with `mask_length = pred_h` (the Above-pass default) produces
    /// the same output as a direct `overlap_blending` call with
    /// `OBMC_MASK_4`.
    #[test]
    fn r193_overlap_neighbour_predict_blend_matches_direct() {
        let curr_stride = 4usize;
        let mut curr_a = vec![0u16; curr_stride * 4];
        let mut curr_b = vec![0u16; curr_stride * 4];
        let obmc = vec![64u16; curr_stride * 4];
        overlap_blending(
            &mut curr_a,
            curr_stride,
            0,
            0,
            4,
            4,
            OverlapPass::Above,
            &obmc,
            curr_stride,
            &OBMC_MASK_4,
        )
        .unwrap();
        overlap_neighbour_predict_blend(
            &mut curr_b,
            curr_stride,
            0,
            0,
            4,
            4,
            OverlapPass::Above,
            &obmc,
            curr_stride,
            /* mask_length */ 4,
        )
        .unwrap();
        assert_eq!(curr_a, curr_b);
    }

    /// §7.11.3.9 `predict_overlap` step-8 wrapper — `mask_length`
    /// outside `{2, 4, 8, 16}` falls through to `OBMC_MASK_32` (the
    /// spec's `else` branch). Verifies the dispatch lands on
    /// `OBMC_MASK_32[0] = 33` for an 8x8 above-pass region.
    #[test]
    fn r193_overlap_neighbour_predict_blend_falls_back_to_mask_32() {
        let curr_stride = 8usize;
        let mut curr = vec![0u16; curr_stride * 8];
        let obmc = vec![64u16; curr_stride * 8];
        overlap_neighbour_predict_blend(
            &mut curr,
            curr_stride,
            0,
            0,
            8,
            8,
            OverlapPass::Above,
            &obmc,
            curr_stride,
            /* mask_length */ 100,
        )
        .unwrap();
        // Above-pass row 0 ⇒ m = OBMC_MASK_32[0] = 33. Output:
        //   Round2(33 * 0 + 31 * 64, 6) = Round2(1984, 6) = 31.
        for (j, v) in curr.iter().enumerate().take(8) {
            assert_eq!(*v, 64 - 33, "row 0 col {j}");
        }
    }

    // ---------- r194 §7.11.3.1 predict_inter driver ----------

    /// §7.11.3.1 SIMPLE single-ref translational path — driver
    /// composes `rounding_variables` + `motion_vector_scaling` +
    /// `block_inter_prediction` + `clip1_single_ref`. Reuses the
    /// `block_inter_prediction_zero_mv_copies_reference`
    /// integer-aligned phase-0 trick: with `mv = [0, 0]` and the
    /// §7.11.3.3 `off = 32` bias, the `motion_vector_scaling`
    /// output's phase is 1 — but the driver itself is wired
    /// correctly when we observe the prediction reproduces what
    /// the leaf would have produced standalone for those args.
    #[test]
    fn r194_predict_inter_simple_runs_to_completion_on_translational_path() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = (r * 16 + c) as u16;
            }
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        let w = 4;
        let h = 4;
        let mut pred_out = vec![0u16; w * h];
        predict_inter(
            /* plane */ 0,
            /* x */ 2,
            /* y */ 2,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            /* is_compound */ false,
            /* is_inter_intra */ false,
            /* bit_depth */ 8,
            /* subsampling_x */ 0,
            /* subsampling_y */ 0,
            /* frame_width */ ref_w as u32,
            /* frame_height */ ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            /* compound */ None,
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut pred_out,
        )
        .expect("predict_inter SIMPLE single-ref translational path");

        // Drive the same `block_inter_prediction` leaf the driver
        // dispatched to with the same `motion_vector_scaling`
        // output, then apply `clip1_single_ref`, and verify the
        // driver's `pred_out` matches.
        let mvs = motion_vector_scaling(
            0,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            ref_w as u32,
            ref_h as u32,
            2,
            2,
            [0, 0],
        )
        .unwrap();
        let rv = rounding_variables(8, false).unwrap();
        let mut leaf_pred = vec![0i32; w * h];
        block_inter_prediction(
            0,
            0,
            0,
            &refp,
            stride,
            ref_w as u32,
            ref_h as u32,
            mvs.start_x,
            mvs.start_y,
            mvs.step_x,
            mvs.step_y,
            w,
            h,
            EIGHTTAP,
            EIGHTTAP,
            rv.inter_round0,
            rv.inter_round1,
            &mut leaf_pred,
        )
        .unwrap();
        let mut leaf_out = vec![0u16; w * h];
        clip1_single_ref(8, &leaf_pred, &mut leaf_out).unwrap();
        assert_eq!(
            pred_out, leaf_out,
            "driver output must equal direct leaf composition"
        );
    }

    /// §7.11.3.1 SIMPLE single-ref translational MC against a fully
    /// **independent hand-built reference** — the proof that the
    /// public `predict_inter` entry performs a real §7.11.3.2
    /// sub-pel (fractional-MV) EIGHTTAP interpolation, not just the
    /// integer-aligned copy that the zero-MV test above exercises.
    ///
    /// Setup (all derived directly from av1-spec §7.11.3.3/.4, no
    /// dependence on this crate's own `motion_vector_scaling` /
    /// `block_inter_prediction` outputs):
    ///
    /// * Non-scaled 16×16 reference (`RefUpscaledWidth ==
    ///   FrameWidth == 16`), synthetic samples `ref[r][c] = r*16+c`.
    /// * Prediction origin `(x, y) = (4, 4)`, region `4×4`, luma.
    /// * `mv = [mv_row, mv_col] = [0, 4]` in 1/8-luma-sample units
    ///   — `mv_col = 4` is exactly +0.5 sample horizontally,
    ///   `mv_row = 0` is integer-aligned vertically.
    ///
    /// Walking §7.11.3.3 by hand for the non-scaled case
    /// (`xScale = yScale = 1<<REF_SCALE_SHIFT = 16384`,
    /// `stepX = stepY = 1024`):
    ///
    /// ```text
    ///   origX = (4<<4) + 2*4   + 8 = 64 + 8 + 8 = 80
    ///   baseX = 80*16384 - (8<<14)        = 1179648
    ///   startX = Round2Signed(1179648, 8) + 32 = 4608 + 32 = 4640
    ///   origY = (4<<4) + 2*0   + 8 = 72
    ///   baseY = 72*16384 - (8<<14)        = 1048576
    ///   startY = Round2Signed(1048576, 8) + 32 = 4096 + 32 = 4128
    /// ```
    ///
    /// so the horizontal phase is `(4640>>6)&15 = 8` (the symmetric
    /// half-sample EIGHTTAP row `[0,2,-14,76,76,-14,2,0]`) and the
    /// vertical phase is `((4128&1023)>>6)&15 = 0` (the unit-copy
    /// row `[0,0,0,128,0,0,0,0]`). The integer column origin is
    /// `4640>>10 = 4`, the integer row origin `4128>>10 = 4`.
    ///
    /// Because the vertical filter is the phase-0 unit copy, the
    /// §7.11.3.4 two-pass convolution degenerates to: for each
    /// output row `i` (mapped to reference row `4+i`), the
    /// half-sample horizontal EIGHTTAP applied to `ref[4+i][1..=8]`,
    /// `Round2`'d by `InterRound0 = 3` then by `InterRound1 = 11`
    /// against the `*128` vertical unit tap. Worked for row 0:
    ///
    /// ```text
    ///   s = 2*66 -14*67 +76*68 +76*69 -14*70 +2*71 = 8768
    ///   h = Round2(8768, 3) = 1096
    ///   pred = Round2(128*1096, 11) = Round2(140288, 11) = 69
    /// ```
    ///
    /// The full hand-computed 4×4 oracle (samples stay in 8-bit
    /// range so `Clip1` is a no-op) is the `EXPECTED` literal below.
    #[test]
    fn r291_predict_inter_half_sample_mv_matches_hand_built_reference() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = (r * 16 + c) as u16;
            }
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 4], // [mv_row, mv_col] — +0.5 sample horizontally
        }];
        let w = 4;
        let h = 4;
        let mut pred_out = vec![0u16; w * h];
        predict_inter(
            /* plane */ 0,
            /* x */ 4,
            /* y */ 4,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            /* is_compound */ false,
            /* is_inter_intra */ false,
            /* bit_depth */ 8,
            /* subsampling_x */ 0,
            /* subsampling_y */ 0,
            /* frame_width */ ref_w as u32,
            /* frame_height */ ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            /* compound */ None,
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut pred_out,
        )
        .expect("predict_inter SIMPLE single-ref half-sample MC");

        // Hand-built reference (see doc comment for the §7.11.3.4
        // derivation): a +0.5-sample horizontal shift of the
        // synthetic `ref[r][c] = r*16+c` plane over the 4×4 region
        // rooted at reference (row=4, col=4).
        #[rustfmt::skip]
        let expected: [u16; 16] = [
            69,  70,  71,  72,
            85,  86,  87,  88,
            101, 102, 103, 104,
            117, 118, 119, 120,
        ];
        assert_eq!(
            pred_out, expected,
            "predict_inter half-sample MV must match the hand-built \
             §7.11.3.4 EIGHTTAP oracle"
        );

        // Sanity: the half-sample shift genuinely interpolated —
        // the output must differ from the integer-aligned copy of
        // the same region (`ref[4+i][4+j]`), confirming a real
        // sub-pel filter ran rather than a passthrough.
        let mut differs = false;
        for i in 0..h {
            for j in 0..w {
                let integer = refp[(4 + i) * stride + (4 + j)];
                if pred_out[i * w + j] != integer {
                    differs = true;
                }
            }
        }
        assert!(
            differs,
            "half-sample MV must interpolate, not copy the integer grid"
        );
    }

    // ---------- r292 §7.11.3.1 mode-info → CurrFrame driver ----------

    /// §7.11.3.1 end-to-end single-forward-reference translational
    /// reconstruction — drives one decoded inter block from mode-info
    /// (`RefFrame[0] = LAST_FRAME`, `mv = [0, 4]`) through the
    /// §7.11.3.3 `ref_frame_idx → FrameStore` resolution into
    /// `predict_inter` and stitches the result into a `CurrFrame`
    /// plane at plane coordinates `(x, y)`.
    ///
    /// This proves the mi-grid → `predict_inter` wiring closes both
    /// pieces the leaf left to "the walker": the §7.11.3.1 step-5 /
    /// §7.11.3.3 ref-buffer indirection (a small `RefFrame` index does
    /// **not** name a buffer directly — it must be routed through
    /// `ref_frame_idx[]` to a `FrameStore` slot) and the §7.11.3.1
    /// final `CurrFrame[plane][y+i][x+j] = Clip1(preds[0][i][j])`
    /// merge.
    ///
    /// The reference samples + MV reuse the r291 hand-built oracle
    /// (16×16 `ref[r][c] = r*16+c`, region `4×4` rooted at `(4, 4)`,
    /// `mv = [0, 4]` ⇒ +0.5 sample horizontally), so the predicted
    /// 4×4 block is the same independent `EXPECTED` literal — here
    /// asserted at its *plane offset* inside a larger 8×8 CurrFrame
    /// buffer, with the surrounding samples left untouched.
    #[test]
    fn r292_reconstruct_inter_block_drives_modeinfo_through_predict_inter() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = (r * 16 + c) as u16;
            }
        }

        // FrameStore with the LAST_FRAME plane parked at slot 3, every
        // other slot a distinct decoy. `ref_frame_idx[LAST_FRAME -
        // LAST_FRAME] = ref_frame_idx[0] = 3` is the only route that
        // selects the real plane, so a passing test proves the
        // indirection is honoured (not a direct `RefFrame`-as-index
        // shortcut).
        let decoy = vec![0u16; ref_h * stride];
        let frame_store = [
            RefFrameStoreEntry {
                plane: &decoy,
                stride,
                upscaled_width: ref_w as u32,
                width: ref_w as u32,
                height: ref_h as u32,
            },
            RefFrameStoreEntry {
                plane: &decoy,
                stride,
                upscaled_width: ref_w as u32,
                width: ref_w as u32,
                height: ref_h as u32,
            },
            RefFrameStoreEntry {
                plane: &decoy,
                stride,
                upscaled_width: ref_w as u32,
                width: ref_w as u32,
                height: ref_h as u32,
            },
            RefFrameStoreEntry {
                plane: &refp,
                stride,
                upscaled_width: ref_w as u32,
                width: ref_w as u32,
                height: ref_h as u32,
            },
        ];
        // ref_frame_idx[ RefFrame - LAST_FRAME ] for the 7 inter refs.
        let ref_frame_idx: [u8; 7] = [3, 0, 1, 2, 0, 1, 2];

        let w = 4;
        let h = 4;
        // 8×8 CurrFrame plane pre-filled with a sentinel so we can
        // prove the surrounding region is untouched.
        let curr_w = 8;
        let curr_h = 8;
        let sentinel = 999u16;
        let mut curr = vec![sentinel; curr_w * curr_h];

        let mode_info = InterModeInfo {
            ref_frame: crate::uncompressed_header_tail::LAST_FRAME as u8,
            mv: [0, 4],
        };
        reconstruct_inter_block(
            mode_info,
            &ref_frame_idx,
            &frame_store,
            /* plane */ 0,
            /* x */ 4,
            /* y */ 4,
            w,
            h,
            /* bit_depth */ 8,
            /* subsampling_x */ 0,
            /* subsampling_y */ 0,
            /* frame_width */ ref_w as u32,
            /* frame_height */ ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &mut curr,
            /* curr_stride */ curr_w,
        )
        .expect("reconstruct_inter_block SIMPLE single-ref half-sample");

        // The same independent hand-built 4×4 oracle from r291 — the
        // +0.5-sample horizontal shift of `ref[r][c] = r*16+c` over the
        // region rooted at reference (row=4, col=4).
        #[rustfmt::skip]
        let expected: [u16; 16] = [
            69,  70,  71,  72,
            85,  86,  87,  88,
            101, 102, 103, 104,
            117, 118, 119, 120,
        ];
        // Block stitched at plane coords (x=4, y=4) of the 8×8 plane.
        for i in 0..h {
            for j in 0..w {
                assert_eq!(
                    curr[(4 + i) * curr_w + (4 + j)],
                    expected[i * w + j],
                    "reconstructed sample ({}, {}) must match the oracle",
                    4 + j,
                    4 + i,
                );
            }
        }
        // Every sample outside the 4×4 write region is still the
        // sentinel — the stitch wrote exactly the prediction region.
        for r in 0..curr_h {
            for c in 0..curr_w {
                let inside = (4..8).contains(&r) && (4..8).contains(&c);
                if !inside {
                    assert_eq!(
                        curr[r * curr_w + c],
                        sentinel,
                        "sample ({c}, {r}) outside the write region must be untouched"
                    );
                }
            }
        }
    }

    /// §7.11.3.1 reconstruction driver caller-bug matrix — the
    /// mode-info → CurrFrame driver rejects an `INTRA_FRAME` ref, an
    /// out-of-range `ref_frame`, an out-of-range resolved `refIdx`,
    /// and a `CurrFrame` plane too small for the write region, each
    /// with `PartitionWalkOutOfRange`.
    #[test]
    fn r292_reconstruct_inter_block_rejects_caller_bugs() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let refp = vec![0u16; ref_w * ref_h];
        let store = [RefFrameStoreEntry {
            plane: &refp,
            stride: ref_w,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        }];
        let ref_frame_idx: [u8; 7] = [0, 0, 0, 0, 0, 0, 0];
        let w = 4;
        let h = 4;
        let mut curr = vec![0u16; ref_w * ref_h];

        let call = |ref_frame: u8,
                    rfi: &[u8],
                    fs: &[RefFrameStoreEntry<'_>],
                    curr: &mut [u16],
                    curr_stride: usize| {
            reconstruct_inter_block(
                InterModeInfo {
                    ref_frame,
                    mv: [0, 0],
                },
                rfi,
                fs,
                0,
                0,
                0,
                w,
                h,
                8,
                0,
                0,
                ref_w as u32,
                ref_h as u32,
                EIGHTTAP,
                EIGHTTAP,
                curr,
                curr_stride,
            )
        };

        // INTRA_FRAME (0) is not an inter reference.
        assert_eq!(
            call(
                crate::uncompressed_header_tail::INTRA_FRAME as u8,
                &ref_frame_idx,
                &store,
                &mut curr,
                ref_w
            )
            .unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );

        // ref_frame past ALTREF_FRAME (7) is out of range.
        assert_eq!(
            call(8, &ref_frame_idx, &store, &mut curr, ref_w).unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );

        // ref_frame_idx routes to a FrameStore slot that doesn't exist
        // (slot 5 into a 1-entry store).
        let bad_idx: [u8; 7] = [5, 0, 0, 0, 0, 0, 0];
        assert_eq!(
            call(
                crate::uncompressed_header_tail::LAST_FRAME as u8,
                &bad_idx,
                &store,
                &mut curr,
                ref_w
            )
            .unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );

        // r394 — a CurrFrame plane SMALLER than the block is the legal
        // §5.11.4 bottom/right overhang shape, no longer a caller bug:
        // the prediction runs at full block geometry and the stitch
        // CLIPS to the plane (2×2 of the 4×4 written here).
        let mut tiny = vec![9999u16; 4];
        call(
            crate::uncompressed_header_tail::LAST_FRAME as u8,
            &ref_frame_idx,
            &store,
            &mut tiny,
            2,
        )
        .expect("overhanging write clips instead of erroring");
        assert!(
            tiny.iter().all(|&v| v <= 255),
            "the clipped 2×2 window (all four samples of the stride-2 plane) is written"
        );

        // A block whose ORIGIN is outside the plane is still a caller
        // bug (nothing of it can be stitched).
        let mut empty: Vec<u16> = Vec::new();
        assert_eq!(
            call(
                crate::uncompressed_header_tail::LAST_FRAME as u8,
                &ref_frame_idx,
                &store,
                &mut empty,
                2
            )
            .unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );
    }

    /// §5.11.33 `predict()` frame-level walk — drives a small decoded
    /// mode-info grid of mixed leaves through
    /// [`reconstruct_inter_frame`] and proves the §7.11.3 per-plane
    /// loop reconstructs every single-reference translational inter
    /// leaf into `CurrFrame[0]` at its plane origin while leaving the
    /// intra / compound / inter-intra leaves untouched.
    ///
    /// The 2×4 mi-grid (luma, no subsampling, `MI_SIZE = 4` ⇒ an 8×16
    /// luma plane) carries:
    /// * (0,0) BLOCK_4X4 single-ref inter (`LAST_FRAME`, mv=[0,4]) ⇒ a
    ///   4×4 prediction at plane origin (0,0);
    /// * (0,1) BLOCK_4X4 intra ⇒ skipped;
    /// * (0,2) BLOCK_8X8 single-ref inter (`LAST_FRAME`, mv=[0,4]) ⇒ an
    ///   8×8 prediction at plane origin (8,0), exercising multi-cell
    ///   footprint origin detection;
    /// * (1,0) BLOCK_4X4 intra ⇒ skipped;
    /// * (1,1) BLOCK_4X4 inter with `RefFrame[1] == LAST_FRAME`
    ///   (compound) ⇒ skipped.
    ///
    /// The two inter leaves' outputs are cross-checked against direct
    /// [`reconstruct_inter_block`] calls (same ref store / mv /
    /// origins), proving the walk dispatches identically to the
    /// per-block driver; every skipped-leaf plane region stays the
    /// pre-fill sentinel.
    #[test]
    fn r293_reconstruct_inter_frame_walks_grid_single_ref_translational() {
        // Shared 16×16 reference plane `ref[r][c] = r*16+c`, parked at
        // FrameStore slot 3 (the r292 indirection oracle).
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = (r * 16 + c) as u16;
            }
        }
        let decoy = vec![0u16; ref_h * stride];
        let decoy_entry = || RefFrameStoreEntry {
            plane: &decoy[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let real_entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        // LAST_FRAME plane at slot 3; every other slot a decoy.
        let store = [decoy_entry(), decoy_entry(), decoy_entry(), real_entry];
        // `RefFrameStoreEntry` is `Copy`, so the same store backs both
        // the frame walk and the per-block oracle below.
        let store2 = store;
        let ref_frame_idx: [u8; 7] = [3, 0, 1, 2, 0, 1, 2];

        let mi_rows: u32 = 2;
        let mi_cols: u32 = 4;
        let cells = (mi_rows * mi_cols) as usize;
        let last = crate::uncompressed_header_tail::LAST_FRAME as i8;

        // --- Build the persisted mode-info grids. ---
        use crate::cdf::{BLOCK_4X4, BLOCK_8X8, BLOCK_INVALID};
        let mut mi_sizes = vec![BLOCK_INVALID; cells];
        let mut is_inters = vec![0u8; cells];
        let mut ref_frames = vec![0i8; cells * 2];
        // Slot 1 pre-fill = NONE (-1), as the §5.11.18 walker stamps.
        for cell in 0..cells {
            ref_frames[cell * 2 + 1] = -1;
        }
        let mut mvs = vec![0i16; cells * 4];
        let interp_filters = vec![EIGHTTAP; cells * 2];
        // The compound leaf in this grid is a WEDGE-mask type so it
        // stays skipped (this test exercises the single-ref dispatch
        // identity; the AVERAGE/DISTANCE compound walk is covered
        // separately below).
        let mut compound_types = vec![COMPOUND_AVERAGE; cells];

        let set_cell = |mi_sizes: &mut [usize], r: usize, c: usize, sz: usize| {
            mi_sizes[r * mi_cols as usize + c] = sz;
        };
        let stamp_inter = |is_inters: &mut [u8],
                           ref_frames: &mut [i8],
                           mvs: &mut [i16],
                           r: usize,
                           c: usize,
                           rf0: i8,
                           rf1: i8,
                           mv: [i16; 2]| {
            let cell = r * mi_cols as usize + c;
            is_inters[cell] = 1;
            ref_frames[cell * 2] = rf0;
            ref_frames[cell * 2 + 1] = rf1;
            mvs[cell * 4] = mv[0];
            mvs[cell * 4 + 1] = mv[1];
        };

        // (0,0) BLOCK_4X4 single-ref inter.
        set_cell(&mut mi_sizes, 0, 0, BLOCK_4X4);
        stamp_inter(
            &mut is_inters,
            &mut ref_frames,
            &mut mvs,
            0,
            0,
            last,
            -1,
            [0, 4],
        );
        // (0,1) BLOCK_4X4 intra (is_inter stays 0).
        set_cell(&mut mi_sizes, 0, 1, BLOCK_4X4);
        // (0,2) BLOCK_8X8 single-ref inter — fills (0,2),(0,3),(1,2),(1,3).
        for (r, c) in [(0usize, 2usize), (0, 3), (1, 2), (1, 3)] {
            set_cell(&mut mi_sizes, r, c, BLOCK_8X8);
        }
        // §5.11.5 stamps the same MiSize + inter state over the whole
        // footprint; the origin (0,2) is what the walk reads.
        for (r, c) in [(0usize, 2usize), (0, 3), (1, 2), (1, 3)] {
            stamp_inter(
                &mut is_inters,
                &mut ref_frames,
                &mut mvs,
                r,
                c,
                last,
                -1,
                [0, 4],
            );
        }
        // (1,0) BLOCK_4X4 intra.
        set_cell(&mut mi_sizes, 1, 0, BLOCK_4X4);
        // (1,1) BLOCK_4X4 compound inter (RefFrame[1] = LAST_FRAME),
        // marked COMPOUND_INTRA so the walk skips it (the §7.11.3.13
        // intra-variant mask is owned by the interintra driver — unlike
        // COMPOUND_WEDGE / COMPOUND_DIFFWTD which are now driven).
        set_cell(&mut mi_sizes, 1, 1, BLOCK_4X4);
        stamp_inter(
            &mut is_inters,
            &mut ref_frames,
            &mut mvs,
            1,
            1,
            last,
            last,
            [0, 4],
        );
        compound_types[mi_cols as usize + 1] = COMPOUND_INTRA;

        // CurrFrame[0]: 8 rows × 16 cols, sentinel pre-fill.
        let curr_w = (mi_cols * 4) as usize; // 16
        let curr_h = (mi_rows * 4) as usize; // 8
        let sentinel = 7000u16;
        let mut curr = vec![sentinel; curr_w * curr_h];

        let order_hints_by_ref = [0i32; 8];
        let wedge_zeros = vec![0u8; cells];
        let grid = InterModeInfoGrid {
            mi_sizes: &mi_sizes,
            is_inters: &is_inters,
            ref_frames: &ref_frames,
            mvs: &mvs,
            interp_filters: &interp_filters,
            compound_types: &compound_types,
            wedge_indices: &wedge_zeros,
            wedge_signs: &wedge_zeros,
            mask_types: &wedge_zeros,
            interintra_modes: &wedge_zeros,
            wedge_interintras: &wedge_zeros,
            interintra_wedge_indices: &wedge_zeros,
            order_hint_bits: 7,
            current_order_hint: 0,
            order_hints_by_ref: &order_hints_by_ref,
            mi_rows,
            mi_cols,
            bit_depth: 8,
            warp: None,
            obmc: None,
        };
        {
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut curr,
                curr_stride: curr_w,
            }];
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes)
                .expect("frame-level inter reconstruction");
        }

        // --- Independent per-block oracle: drive the two inter leaves
        // through `reconstruct_inter_block` directly into a fresh
        // CurrFrame and assert the frame walk produced the same bytes. ---
        let mut oracle = vec![sentinel; curr_w * curr_h];
        // (0,0) 4×4 at plane origin (0,0).
        reconstruct_inter_block(
            InterModeInfo {
                ref_frame: last as u8,
                mv: [0, 4],
            },
            &ref_frame_idx,
            &store2,
            0,
            0,
            0,
            4,
            4,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &mut oracle,
            curr_w,
        )
        .unwrap();
        // (0,2) 8×8 at plane origin (baseX=8, baseY=0).
        reconstruct_inter_block(
            InterModeInfo {
                ref_frame: last as u8,
                mv: [0, 4],
            },
            &ref_frame_idx,
            &store2,
            0,
            8,
            0,
            8,
            8,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &mut oracle,
            curr_w,
        )
        .unwrap();

        assert_eq!(
            curr, oracle,
            "frame-level walk must dispatch identically to the per-block driver"
        );

        // The two inter write regions overwrote their plane cells; the
        // skipped-leaf regions are still the sentinel. (0,1) intra is
        // luma cols 4..8, rows 0..4; (1,0) intra cols 0..4 rows 4..8;
        // (1,1) compound cols 4..8 rows 4..8.
        for &(x0, y0, x1, y1) in &[(4usize, 0usize, 8usize, 4usize), (0, 4, 4, 8), (4, 4, 8, 8)] {
            for r in y0..y1 {
                for c in x0..x1 {
                    assert_eq!(
                        curr[r * curr_w + c],
                        sentinel,
                        "skipped-leaf plane sample ({c}, {r}) must stay the sentinel"
                    );
                }
            }
        }
        // Spot-check one inter sample is no longer the sentinel.
        assert_ne!(
            curr[0], sentinel,
            "the (0,0) inter leaf must have been reconstructed"
        );
        assert_ne!(
            curr[8], sentinel,
            "the (0,2) inter leaf must have been reconstructed"
        );
    }

    /// §5.11.33 `predict()` `someUseIntra == 1` chroma sub-block split
    /// (av1-spec p.83 lines 5168-5189) on the single-reference frame
    /// walk.
    ///
    /// The canonical trigger is a sub-8×8 luma partition under 4:2:0:
    /// four `BLOCK_4X4` mi-cells where the bottom-right cell (mi 1,1)
    /// is the `HasChroma` block and the partition mixes inter and intra
    /// leaves. For that chroma block:
    ///   * `planeSz = get_plane_residual_size(BLOCK_4X4, 1) = BLOCK_4X4`
    ///     ⇒ `num4x4W = num4x4H = 1`;
    ///   * `candRow = (1 >> 1) << 1 = 0`, `candCol = 0` initially;
    ///   * the `(num4x4H<<subY)×(num4x4W<<subX) = 2×2` scan visits cells
    ///     (0,0),(0,1),(1,0),(1,1); cells (0,1) and (1,0) carry
    ///     `RefFrames[..][0] == INTRA_FRAME` ⇒ `someUseIntra = 1`;
    ///   * the split re-anchors `candRow = MiRow = 1`, `candCol = MiCol
    ///     = 1`, so the single chroma `predict_inter` reads the
    ///     **bottom-right** block's MV (`Mvs[1][1]`), not the
    ///     top-left's (`Mvs[0][0]`).
    ///
    /// The grid stamps DIFFERENT MVs on (0,0) and (1,1), so the chroma
    /// output is MV-distinguishable: it must equal an oracle
    /// `reconstruct_inter_block` driven with the (1,1) MV at the chroma
    /// origin, and must NOT equal the same oracle driven with the (0,0)
    /// MV (the pre-split behaviour). The luma plane is unaffected
    /// (`subX = subY = 0` ⇒ `candRow/candCol == MiRow/MiCol` already,
    /// and each `BLOCK_4X4` luma leaf predicts its own cell).
    #[test]
    fn r308_reconstruct_inter_frame_chroma_some_use_intra_uses_bottom_right_mv() {
        // 16×16 reference plane `ref[r][c] = r*16 + c`, slot 0.
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = (r * 16 + c) as u16;
            }
        }
        let entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [entry];
        let store2 = store;
        let ref_frame_idx: [u8; 7] = [0; 7];

        let mi_rows: u32 = 2;
        let mi_cols: u32 = 2;
        let cells = (mi_rows * mi_cols) as usize;
        let last = crate::uncompressed_header_tail::LAST_FRAME as i8;

        use crate::cdf::{BLOCK_4X4, BLOCK_INVALID};
        let mut mi_sizes = vec![BLOCK_INVALID; cells];
        let mut is_inters = vec![0u8; cells];
        let mut ref_frames = vec![0i8; cells * 2];
        for cell in 0..cells {
            ref_frames[cell * 2 + 1] = -1; // slot-1 NONE pre-fill
        }
        let mut mvs = vec![0i16; cells * 4];
        let interp_filters = vec![EIGHTTAP; cells * 2];
        let comp_types = vec![COMPOUND_AVERAGE; cells];
        let wedge_zeros = vec![0u8; cells];
        let order_hints_by_ref = [0i32; 8];

        let idx = |r: usize, c: usize| r * mi_cols as usize + c;

        // Two distinct integer-sample MVs (in 1/8-luma units: +8 == one
        // full sample). MV-A on (0,0); MV-B on (1,1).
        let mv_a: [i16; 2] = [0, 8]; // shift ref col by +1
        let mv_b: [i16; 2] = [8, 0]; // shift ref row by +1

        // (0,0) inter, MV-A.
        mi_sizes[idx(0, 0)] = BLOCK_4X4;
        is_inters[idx(0, 0)] = 1;
        ref_frames[idx(0, 0) * 2] = last;
        mvs[idx(0, 0) * 4] = mv_a[0];
        mvs[idx(0, 0) * 4 + 1] = mv_a[1];

        // (0,1) intra, (1,0) intra (RefFrames[..][0] = INTRA_FRAME = 0,
        // which is the array's zero pre-fill; is_inter stays 0).
        mi_sizes[idx(0, 1)] = BLOCK_4X4;
        mi_sizes[idx(1, 0)] = BLOCK_4X4;

        // (1,1) inter, MV-B — the HasChroma bottom-right block.
        mi_sizes[idx(1, 1)] = BLOCK_4X4;
        is_inters[idx(1, 1)] = 1;
        ref_frames[idx(1, 1) * 2] = last;
        mvs[idx(1, 1) * 4] = mv_b[0];
        mvs[idx(1, 1) * 4 + 1] = mv_b[1];

        let grid = InterModeInfoGrid {
            mi_sizes: &mi_sizes,
            is_inters: &is_inters,
            ref_frames: &ref_frames,
            mvs: &mvs,
            interp_filters: &interp_filters,
            compound_types: &comp_types,
            wedge_indices: &wedge_zeros,
            wedge_signs: &wedge_zeros,
            mask_types: &wedge_zeros,
            interintra_modes: &wedge_zeros,
            wedge_interintras: &wedge_zeros,
            interintra_wedge_indices: &wedge_zeros,
            order_hint_bits: 7,
            current_order_hint: 0,
            order_hints_by_ref: &order_hints_by_ref,
            mi_rows,
            mi_cols,
            bit_depth: 8,
            warp: None,
            obmc: None,
        };

        // Chroma plane (4:2:0): 4 rows × 4 cols (mi_rows*4>>1 ×
        // mi_cols*4>>1). The chroma reference is sub-sampled width too.
        let chroma_w = ((mi_cols * 4) >> 1) as usize; // 4
        let chroma_h = ((mi_rows * 4) >> 1) as usize; // 4
        let sentinel = 5000u16;
        let mut chroma = vec![sentinel; chroma_w * chroma_h];

        // Luma plane (8×8) just to satisfy the 3-plane loop; its
        // contents are not asserted here.
        let luma_w = (mi_cols * 4) as usize;
        let luma_h = (mi_rows * 4) as usize;
        let mut luma = vec![sentinel; luma_w * luma_h];
        let mut cr = vec![sentinel; chroma_w * chroma_h];

        {
            let mut planes = [
                PlaneReconContext {
                    plane: 0,
                    subsampling_x: 0,
                    subsampling_y: 0,
                    frame_store: &store,
                    frame_width: ref_w as u32,
                    frame_height: ref_h as u32,
                    curr: &mut luma,
                    curr_stride: luma_w,
                },
                PlaneReconContext {
                    plane: 1,
                    subsampling_x: 1,
                    subsampling_y: 1,
                    frame_store: &store,
                    frame_width: (ref_w as u32) >> 1,
                    frame_height: (ref_h as u32) >> 1,
                    curr: &mut chroma,
                    curr_stride: chroma_w,
                },
                PlaneReconContext {
                    plane: 2,
                    subsampling_x: 1,
                    subsampling_y: 1,
                    frame_store: &store,
                    frame_width: (ref_w as u32) >> 1,
                    frame_height: (ref_h as u32) >> 1,
                    curr: &mut cr,
                    curr_stride: chroma_w,
                },
            ];
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes)
                .expect("frame-level inter reconstruction (3-plane 420)");
        }

        // Oracle: the §5.11.33 someUseIntra split drives the (1,1) chroma
        // block as one `predict_inter` at chroma origin (baseX = (MiCol
        // >> 1) * 4 = 0, baseY = 0), predW = predH = num4x4*4 = 4, using
        // the bottom-right candidate's MV (MV-B).
        let mut oracle_b = vec![sentinel; chroma_w * chroma_h];
        reconstruct_inter_block(
            InterModeInfo {
                ref_frame: last as u8,
                mv: mv_b,
            },
            &ref_frame_idx,
            &store2,
            1,
            0,
            0,
            4,
            4,
            8,
            1,
            1,
            (ref_w as u32) >> 1,
            (ref_h as u32) >> 1,
            EIGHTTAP,
            EIGHTTAP,
            &mut oracle_b,
            chroma_w,
        )
        .unwrap();

        assert_eq!(
            chroma, oracle_b,
            "someUseIntra chroma split must predict from the bottom-right block's MV"
        );

        // The pre-split (wrong) behaviour would read the subsampled
        // top-left candidate's MV (MV-A). Prove the split actually
        // changed the bytes.
        let mut oracle_a = vec![sentinel; chroma_w * chroma_h];
        reconstruct_inter_block(
            InterModeInfo {
                ref_frame: last as u8,
                mv: mv_a,
            },
            &ref_frame_idx,
            &store2,
            1,
            0,
            0,
            4,
            4,
            8,
            1,
            1,
            (ref_w as u32) >> 1,
            (ref_h as u32) >> 1,
            EIGHTTAP,
            EIGHTTAP,
            &mut oracle_a,
            chroma_w,
        )
        .unwrap();
        assert_ne!(
            chroma, oracle_a,
            "someUseIntra split must NOT use the top-left subsampled candidate's MV"
        );
    }

    /// [`reconstruct_inter_frame`] caller-bug matrix — a grid slice
    /// too short for `mi_rows * mi_cols` (each of the five grids in
    /// turn) and an out-of-range `MiSize` at a leaf origin each
    /// surface `PartitionWalkOutOfRange`.
    #[test]
    fn r293_reconstruct_inter_frame_rejects_caller_bugs() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let refp = vec![0u16; ref_w * ref_h];
        let store = [RefFrameStoreEntry {
            plane: &refp[..],
            stride: ref_w,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        }];
        let ref_frame_idx: [u8; 7] = [0; 7];
        let mi_rows: u32 = 1;
        let mi_cols: u32 = 1;
        let cells = 1usize;

        let mut curr = vec![0u16; ref_w * ref_h];
        let comp_types = vec![COMPOUND_AVERAGE; cells];
        let wedge_zeros = vec![0u8; cells];
        let order_hints_by_ref = [0i32; 8];
        let run = |mi_sizes: &[usize],
                   is_inters: &[u8],
                   ref_frames: &[i8],
                   mvs: &[i16],
                   interp_filters: &[u8],
                   curr: &mut [u16]| {
            let grid = InterModeInfoGrid {
                mi_sizes,
                is_inters,
                ref_frames,
                mvs,
                interp_filters,
                compound_types: &comp_types,
                wedge_indices: &wedge_zeros,
                wedge_signs: &wedge_zeros,
                mask_types: &wedge_zeros,
                interintra_modes: &wedge_zeros,
                wedge_interintras: &wedge_zeros,
                interintra_wedge_indices: &wedge_zeros,
                order_hint_bits: 7,
                current_order_hint: 0,
                order_hints_by_ref: &order_hints_by_ref,
                mi_rows,
                mi_cols,
                bit_depth: 8,
                warp: None,
                obmc: None,
            };
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr,
                curr_stride: ref_w,
            }];
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes)
        };

        let good_sizes = vec![crate::cdf::BLOCK_4X4; cells];
        let good_is = vec![0u8; cells];
        let good_rf = {
            let mut v = vec![0i8; cells * 2];
            v[1] = -1;
            v
        };
        let good_mv = vec![0i16; cells * 4];
        let good_if = vec![EIGHTTAP; cells * 2];

        // Each grid in turn too short by one slot.
        assert_eq!(
            run(
                &good_sizes[..0],
                &good_is,
                &good_rf,
                &good_mv,
                &good_if,
                &mut curr
            )
            .unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );
        assert_eq!(
            run(
                &good_sizes,
                &good_is[..0],
                &good_rf,
                &good_mv,
                &good_if,
                &mut curr
            )
            .unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );
        assert_eq!(
            run(
                &good_sizes,
                &good_is,
                &good_rf[..1],
                &good_mv,
                &good_if,
                &mut curr
            )
            .unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );
        assert_eq!(
            run(
                &good_sizes,
                &good_is,
                &good_rf,
                &good_mv[..3],
                &good_if,
                &mut curr
            )
            .unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );
        assert_eq!(
            run(
                &good_sizes,
                &good_is,
                &good_rf,
                &good_mv,
                &good_if[..1],
                &mut curr
            )
            .unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );

        // Out-of-range MiSize at a leaf origin (BLOCK_SIZES is the
        // first invalid ordinal past BLOCK_INVALID's hole; use a value
        // strictly greater than BLOCK_INVALID so it is not the
        // skip-this-hole sentinel).
        let bad_sizes = vec![crate::cdf::BLOCK_SIZES + 5; cells];
        assert_eq!(
            run(&bad_sizes, &good_is, &good_rf, &good_mv, &good_if, &mut curr).unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );
    }

    // ---------- r338 §5.11.33 warped-motion frame walk ----------

    /// r338 §5.11.27 — the single-reference frame walk dispatches a
    /// `motion_mode == WARPED_CAUSAL` leaf to `reconstruct_inter_block_warp`
    /// (LOCALWARP arm). The grid carries one 8×8 warped leaf plus a
    /// translational leaf; the walk output for the warped leaf must equal
    /// the bytes the per-block warp driver produces, while the
    /// translational leaf matches `reconstruct_inter_block`. A `grid.warp
    /// == None` walk leaves the warped leaf translational (the pre-r338
    /// behaviour) — proving the dispatch is opt-in.
    #[test]
    fn r338_reconstruct_inter_frame_drives_warped_causal_leaf() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                // A high-frequency, non-linear pattern so a sub-pel warp
                // shift produces samples that genuinely differ from the
                // integer-position translational copy (a smooth ramp would
                // interpolate back to itself).
                refp[r * stride + c] = (((r * 37) ^ (c * 53)) & 0xFF) as u16;
            }
        }
        let real = RefFrameStoreEntry {
            plane: &refp[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [real, real, real, real, real, real, real, real];
        let ref_frame_idx: [u8; 7] = [0, 1, 2, 3, 4, 5, 6];

        // 4×4 mi grid (16×16 luma). One 8×8 WARPED_CAUSAL inter leaf at
        // (0,0); one 8×8 SIMPLE inter leaf at (2,0). Rest BLOCK_INVALID.
        let mi_rows: u32 = 4;
        let mi_cols: u32 = 4;
        let cells = (mi_rows * mi_cols) as usize;
        let last = crate::uncompressed_header_tail::LAST_FRAME as i8;
        use crate::cdf::{BLOCK_8X8, BLOCK_INVALID};

        let mut mi_sizes = vec![BLOCK_INVALID; cells];
        let mut is_inters = vec![0u8; cells];
        let mut ref_frames = vec![0i8; cells * 2];
        for cell in 0..cells {
            ref_frames[cell * 2 + 1] = -1;
        }
        let mvs = vec![0i16; cells * 4];
        let interp_filters = vec![EIGHTTAP; cells * 2];
        let zeros = vec![0u8; cells];

        let mc = mi_cols as usize;
        // 8×8 leaf footprints: (0,0),(0,1),(1,0),(1,1) and
        // (2,0),(2,1),(3,0),(3,1).
        for (r, c) in [
            (0, 0),
            (0, 1),
            (1, 0),
            (1, 1),
            (2, 0),
            (2, 1),
            (3, 0),
            (3, 1),
        ] {
            let cell = r * mc + c;
            mi_sizes[cell] = BLOCK_8X8;
            is_inters[cell] = 1;
            ref_frames[cell * 2] = last;
        }

        // Warp context: cell (0,0) is WARPED_CAUSAL, everything else
        // SIMPLE.
        let mut motion_modes = vec![crate::cdf::MOTION_MODE_SIMPLE; cells];
        motion_modes[0] = crate::cdf::MOTION_MODE_WARPED_CAUSAL;
        const WARP_ID: [i32; 6] = [0, 0, 1 << 16, 0, 0, 1 << 16];
        // A small non-identity horizontal-shear affine matrix (`a2 = one +
        // 256`) so the §7.11.3.5 warped convolution lands on genuine
        // sub-pel positions — `setup_shear` accepts it as valid, so the
        // LOCALWARP arm produces a result that *differs* from the
        // translational fallback (proving the dispatch fired).
        const WARP_SHEAR: [i32; 6] = [0, 0, (1 << 16) + 4096, 0, 0, 1 << 16];
        let mut local_warp_params = vec![0i32; cells * 6];
        for cell in 0..cells {
            local_warp_params[cell * 6..cell * 6 + 6].copy_from_slice(&WARP_ID);
        }
        // The cell-(0,0) leaf carries the shear matrix.
        local_warp_params[0..6].copy_from_slice(&WARP_SHEAR);
        let local_warp_valid = vec![1u8; cells];
        let y_modes = vec![crate::cdf::MODE_NEWMV; cells];
        let gm_types = vec![crate::cdf::GM_TYPE_IDENTITY as u8; 8];
        let mut gm_params = vec![0i32; 8 * 6];
        for rf in 0..8 {
            gm_params[rf * 6..rf * 6 + 6].copy_from_slice(&WARP_ID);
        }
        let order_hints_by_ref = [0i32; 8];

        let warp_ctx = GridWarpContext {
            motion_modes: &motion_modes,
            local_warp_params: &local_warp_params,
            local_warp_valid: &local_warp_valid,
            y_modes: &y_modes,
            gm_types: &gm_types,
            gm_params: &gm_params,
            force_integer_mv: false,
            is_scaled: &[false; 8],
        };
        macro_rules! build_grid {
            ($warp:expr) => {
                InterModeInfoGrid {
                    mi_sizes: &mi_sizes,
                    is_inters: &is_inters,
                    ref_frames: &ref_frames,
                    mvs: &mvs,
                    interp_filters: &interp_filters,
                    compound_types: &zeros,
                    wedge_indices: &zeros,
                    wedge_signs: &zeros,
                    mask_types: &zeros,
                    interintra_modes: &zeros,
                    wedge_interintras: &zeros,
                    interintra_wedge_indices: &zeros,
                    order_hint_bits: 7,
                    current_order_hint: 0,
                    order_hints_by_ref: &order_hints_by_ref,
                    mi_rows,
                    mi_cols,
                    bit_depth: 8,
                    warp: $warp,
                    obmc: None,
                }
            };
        }

        let curr_w = (mi_cols * 4) as usize; // 16
        let curr_h = (mi_rows * 4) as usize; // 16
        let sentinel = 9000u16;

        // Walk WITH warp enabled.
        let mut curr_warp = vec![sentinel; curr_w * curr_h];
        {
            let grid = build_grid!(Some(warp_ctx));
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut curr_warp,
                curr_stride: curr_w,
            }];
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes).unwrap();
        }

        // Walk WITHOUT warp (opt-in proof) — warped leaf goes translational.
        let mut curr_simple = vec![sentinel; curr_w * curr_h];
        {
            let grid = build_grid!(None);
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut curr_simple,
                curr_stride: curr_w,
            }];
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes).unwrap();
        }

        // Oracle: drive the (0,0) leaf through the per-block warp driver
        // and the (2,0) leaf translationally.
        let mut oracle = vec![sentinel; curr_w * curr_h];
        let warp_params = WarpDriverParams {
            y_mode: [crate::cdf::MODE_NEWMV, 0],
            gm_type: [crate::cdf::GM_TYPE_IDENTITY as u8, 0],
            gm_params: [WARP_ID, WARP_ID],
            local_warp_params: WARP_SHEAR,
            local_valid: true,
            ref_is_scaled: [false, false],
            force_integer_mv: false,
        };
        reconstruct_inter_block_warp(
            InterModeInfo {
                ref_frame: last as u8,
                mv: [0, 0],
            },
            &warp_params,
            &ref_frame_idx,
            &store,
            0,
            0,
            0,
            8,
            8,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &mut oracle,
            curr_w,
        )
        .unwrap();
        reconstruct_inter_block(
            InterModeInfo {
                ref_frame: last as u8,
                mv: [0, 0],
            },
            &ref_frame_idx,
            &store,
            /* plane */ 0,
            /* x */ 0,
            /* y */ 8,
            /* w */ 8,
            /* h */ 8,
            /* bit_depth */ 8,
            /* sub_x */ 0,
            /* sub_y */ 0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &mut oracle,
            curr_w,
        )
        .unwrap();

        // The warp-enabled walk equals the mixed oracle.
        assert_eq!(
            curr_warp, oracle,
            "warp-enabled frame walk vs per-block oracle"
        );
        // The warped leaf's footprint differs between warp-on and
        // warp-off walks (proves the dispatch actually fired), while the
        // SIMPLE leaf footprint is identical in both.
        let warp_block_differs = (0..8)
            .any(|i| (0..8).any(|j| curr_warp[i * curr_w + j] != curr_simple[i * curr_w + j]));
        assert!(
            warp_block_differs,
            "WARPED_CAUSAL leaf must differ from the translational fallback"
        );
        for i in 8..16 {
            for j in 0..8 {
                assert_eq!(
                    curr_warp[i * curr_w + j],
                    curr_simple[i * curr_w + j],
                    "SIMPLE leaf must be identical regardless of warp ctx"
                );
            }
        }
    }

    /// r338 — the warp-context slice guards reject a short per-cell or
    /// per-RefFrame slice with `PartitionWalkOutOfRange`.
    #[test]
    fn r338_reconstruct_inter_frame_warp_ctx_slice_guards() {
        let refp = vec![5u16; 32 * 32];
        let entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride: 32,
            upscaled_width: 32,
            width: 32,
            height: 32,
        };
        let store = [entry; 8];
        let ref_frame_idx = [0u8; 7];
        let mi_rows: u32 = 2;
        let mi_cols: u32 = 2;
        let cells = (mi_rows * mi_cols) as usize;
        let mi_sizes = vec![crate::cdf::BLOCK_INVALID; cells];
        let is_inters = vec![0u8; cells];
        let mut ref_frames = vec![0i8; cells * 2];
        for cell in 0..cells {
            ref_frames[cell * 2 + 1] = -1;
        }
        let mvs = vec![0i16; cells * 4];
        let interp_filters = vec![EIGHTTAP; cells * 2];
        let zeros = vec![0u8; cells];
        let order_hints_by_ref = [0i32; 8];
        let full_mm = vec![0u8; cells];
        let full_lwp = vec![0i32; cells * 6];
        let full_v = vec![0u8; cells];
        let full_ym = vec![0u8; cells];
        let full_gt = vec![0u8; 8];
        let full_gp = vec![0i32; 8 * 6];

        // A too-short `motion_modes` slice trips the guard.
        let short_mm = vec![0u8; cells - 1];
        let warp_short = GridWarpContext {
            motion_modes: &short_mm,
            local_warp_params: &full_lwp,
            local_warp_valid: &full_v,
            y_modes: &full_ym,
            gm_types: &full_gt,
            gm_params: &full_gp,
            force_integer_mv: false,
            is_scaled: &[false; 8],
        };
        let _ = &full_mm;
        let grid = InterModeInfoGrid {
            mi_sizes: &mi_sizes,
            is_inters: &is_inters,
            ref_frames: &ref_frames,
            mvs: &mvs,
            interp_filters: &interp_filters,
            compound_types: &zeros,
            wedge_indices: &zeros,
            wedge_signs: &zeros,
            mask_types: &zeros,
            interintra_modes: &zeros,
            wedge_interintras: &zeros,
            interintra_wedge_indices: &zeros,
            order_hint_bits: 7,
            current_order_hint: 0,
            order_hints_by_ref: &order_hints_by_ref,
            mi_rows,
            mi_cols,
            bit_depth: 8,
            warp: Some(warp_short),
            obmc: None,
        };
        let mut curr = vec![0u16; 64];
        let mut planes = [PlaneReconContext {
            plane: 0,
            subsampling_x: 0,
            subsampling_y: 0,
            frame_store: &store,
            frame_width: 32,
            frame_height: 32,
            curr: &mut curr,
            curr_stride: 8,
        }];
        assert_eq!(
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes).unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );
    }

    // ---------- r378 §7.11.3.9 OBMC frame-walk dispatch ----------

    /// r378 — a `motion_mode == OBMC` single-reference leaf decoded into
    /// the grid is dispatched by [`reconstruct_inter_frame`] to the
    /// §7.11.3.9-10 overlap path (via `obmc: Some(_)`), and the
    /// frame-walk-resolved neighbour blend reconstructs **identically** to
    /// a direct [`reconstruct_inter_block_obmc`] call whose above/left
    /// neighbour lists were resolved by hand. The OBMC leaf footprint also
    /// **differs** from the translational fallback (`obmc: None`), proving
    /// the overlap blend actually fired.
    #[test]
    fn r378_reconstruct_inter_frame_obmc_dispatch_matches_per_block() {
        // 32×32 reference plane (`r*32 + c`) so motion-compensated samples
        // vary across the block (the overlap blend then visibly changes
        // the output vs the no-blend translational base).
        let ref_w = 32usize;
        let ref_h = 32usize;
        let mut refp = vec![0u16; ref_w * ref_h];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * ref_w + c] = ((r * 32 + c) & 0xff) as u16;
            }
        }
        let entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride: ref_w,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [entry; 8];
        let ref_frame_idx = [0u8; 7];
        let last = crate::uncompressed_header_tail::LAST_FRAME as u8;

        // 4×4 mi grid (16×16 luma). Layout:
        //   row 0: two 8×8 inter leaves at (0,0) and (0,2) — above
        //          neighbours of the OBMC leaf.
        //   rows 2..4 cols 0..2: 8×8 inter leaf at (2,0) — left neighbour.
        //   rows 2..4 cols 2..4: 8×8 OBMC leaf at (2,2) — the dispatch
        //          target (has both an above and a left inter neighbour).
        let mi_rows: u32 = 4;
        let mi_cols: u32 = 4;
        let cells = (mi_rows * mi_cols) as usize;
        let bw8x8 = crate::cdf::BLOCK_8X8;
        let mut mi_sizes = vec![crate::cdf::BLOCK_INVALID; cells];
        let mut is_inters = vec![0u8; cells];
        let mut ref_frames = vec![0i8; cells * 2];
        let mut mvs = vec![0i16; cells * 4];
        let interp_filters = vec![EIGHTTAP; cells * 2];
        // Stamp an 8×8 (2×2 mi) leaf at mi origin (r0,c0) with the given MV.
        let stamp = |mi_sizes: &mut [usize],
                     is_inters: &mut [u8],
                     ref_frames: &mut [i8],
                     mvs: &mut [i16],
                     r0: usize,
                     c0: usize,
                     mv: [i16; 2]| {
            for dr in 0..2 {
                for dc in 0..2 {
                    let cell = (r0 + dr) * mi_cols as usize + (c0 + dc);
                    mi_sizes[cell] = bw8x8;
                    is_inters[cell] = 1;
                    ref_frames[cell * 2] = last as i8;
                    ref_frames[cell * 2 + 1] = -1; // NONE
                    mvs[cell * 4] = mv[0];
                    mvs[cell * 4 + 1] = mv[1];
                }
            }
        };
        stamp(
            &mut mi_sizes,
            &mut is_inters,
            &mut ref_frames,
            &mut mvs,
            0,
            0,
            [0, 8],
        );
        stamp(
            &mut mi_sizes,
            &mut is_inters,
            &mut ref_frames,
            &mut mvs,
            0,
            2,
            [8, 0],
        );
        stamp(
            &mut mi_sizes,
            &mut is_inters,
            &mut ref_frames,
            &mut mvs,
            2,
            0,
            [4, 4],
        );
        // The OBMC leaf's own MV.
        stamp(
            &mut mi_sizes,
            &mut is_inters,
            &mut ref_frames,
            &mut mvs,
            2,
            2,
            [2, 6],
        );

        let zeros = vec![0u8; cells];
        let order_hints_by_ref = [0i32; 8];

        // motion_modes: OBMC at the (2,2) leaf origin; SIMPLE elsewhere.
        let mut motion_modes = vec![crate::cdf::MOTION_MODE_SIMPLE; cells];
        motion_modes[2 * mi_cols as usize + 2] = crate::cdf::MOTION_MODE_OBMC;
        // AvailU / AvailL for a single-tile frame: avail iff not on the
        // top / left frame edge.
        let mut avail_u = vec![0u8; cells];
        let mut avail_l = vec![0u8; cells];
        for r in 0..mi_rows as usize {
            for c in 0..mi_cols as usize {
                avail_u[r * mi_cols as usize + c] = (r > 0) as u8;
                avail_l[r * mi_cols as usize + c] = (c > 0) as u8;
            }
        }

        macro_rules! make_grid {
            ($obmc:expr) => {
                InterModeInfoGrid {
                    mi_sizes: &mi_sizes,
                    is_inters: &is_inters,
                    ref_frames: &ref_frames,
                    mvs: &mvs,
                    interp_filters: &interp_filters,
                    compound_types: &zeros,
                    wedge_indices: &zeros,
                    wedge_signs: &zeros,
                    mask_types: &zeros,
                    interintra_modes: &zeros,
                    wedge_interintras: &zeros,
                    interintra_wedge_indices: &zeros,
                    order_hint_bits: 7,
                    current_order_hint: 0,
                    order_hints_by_ref: &order_hints_by_ref,
                    mi_rows,
                    mi_cols,
                    bit_depth: 8,
                    warp: None,
                    obmc: $obmc,
                }
            };
        }

        let curr_w = 16usize;
        let curr_h = 16usize;

        // --- (a) OBMC-enabled frame walk. ---
        let mut curr_obmc = vec![0u16; curr_w * curr_h];
        {
            let grid = make_grid!(Some(GridObmcContext {
                motion_modes: &motion_modes,
                avail_u: &avail_u,
                avail_l: &avail_l,
            }));
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut curr_obmc,
                curr_stride: curr_w,
            }];
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes)
                .expect("OBMC-enabled frame walk");
        }

        // --- (b) translational frame walk (obmc: None). ---
        let mut curr_simple = vec![0u16; curr_w * curr_h];
        {
            let grid = make_grid!(None);
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut curr_simple,
                curr_stride: curr_w,
            }];
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes)
                .expect("translational frame walk");
        }

        // --- (c) hand-resolved per-block OBMC oracle for the (2,2) leaf,
        // overlaid on a copy of the translational walk (so the three
        // non-OBMC leaves match by construction). ---
        // The above-pass neighbour is the inter leaf at (0,2) collocated
        // above (2,2): candRow = MiRow-1 = 1, candCol = x4|1 = 3 (for
        // x4 = MiCol = 2). MiSizes[1][3] = BLOCK_8X8 ⇒ step4 = Clip3(2,16,2)
        // = 2; one candidate then x4 = 4 >= Min(MiCols, MiCol+w4) = 4.
        // The left-pass neighbour: candCol = MiCol-1 = 1, candRow = y4|1 =
        // 3 (for y4 = MiRow = 2). MiSizes[3][1] = BLOCK_8X8 ⇒ step4 = 2.
        // above candidate cell index (candRow=1, candCol=3).
        let above_idx = mi_cols as usize + 3;
        let above_ref_frame = ref_frames[above_idx * 2];
        let above_mv = [mvs[above_idx * 4], mvs[above_idx * 4 + 1]];
        let left_ref_frame = ref_frames[(3 * mi_cols as usize + 1) * 2];
        let left_mv = [
            mvs[(3 * mi_cols as usize + 1) * 4],
            mvs[(3 * mi_cols as usize + 1) * 4 + 1],
        ];
        let nb_bundle = |_rf: i8, mv: [i16; 2]| PredictInterRef {
            ref_plane: &refp[..],
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv,
        };
        let _ = (above_ref_frame, left_ref_frame);
        let above_nb = [ObmcNeighbour {
            bundle: nb_bundle(above_ref_frame, above_mv),
            step4: 2,
            interp_filter_x: EIGHTTAP,
            interp_filter_y: EIGHTTAP,
            axis_pos4: 2,
        }];
        let left_nb = [ObmcNeighbour {
            bundle: nb_bundle(left_ref_frame, left_mv),
            step4: 2,
            interp_filter_x: EIGHTTAP,
            interp_filter_y: EIGHTTAP,
            axis_pos4: 2,
        }];
        let obmc_params = ObmcParams {
            mi_row: 2,
            mi_col: 2,
            mi_cols,
            mi_rows,
            mi_width_log2: crate::cdf::mi_width_log2(bw8x8) as u8,
            mi_height_log2: crate::cdf::mi_height_log2(bw8x8) as u8,
            avail_u: true,
            avail_l: true,
            plane_residual_size_ge_block_8x8: true,
            above_neighbours: &above_nb,
            left_neighbours: &left_nb,
        };
        let mut oracle = curr_simple.clone();
        reconstruct_inter_block_obmc(
            InterModeInfo {
                ref_frame: last,
                mv: [2, 6],
            },
            &obmc_params,
            &ref_frame_idx,
            &store,
            0,
            /* x */ 8,
            /* y */ 8,
            /* w */ 8,
            /* h */ 8,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &mut oracle,
            curr_w,
        )
        .expect("per-block OBMC oracle");

        assert_eq!(
            curr_obmc, oracle,
            "OBMC frame-walk dispatch must equal the hand-resolved per-block OBMC oracle"
        );

        // The OBMC leaf footprint (luma rows 8..16, cols 8..16) must differ
        // from the translational walk (proves the overlap blend fired).
        let mut obmc_differs = false;
        for r in 8..16 {
            for c in 8..16 {
                if curr_obmc[r * curr_w + c] != curr_simple[r * curr_w + c] {
                    obmc_differs = true;
                }
            }
        }
        assert!(
            obmc_differs,
            "OBMC leaf must differ from the translational fallback"
        );
        // The three non-OBMC leaves must be byte-identical between the two
        // walks (the OBMC arm only touches its own footprint).
        for r in 0..16 {
            for c in 0..16 {
                if (8..16).contains(&r) && (8..16).contains(&c) {
                    continue;
                }
                assert_eq!(
                    curr_obmc[r * curr_w + c],
                    curr_simple[r * curr_w + c],
                    "non-OBMC leaf sample ({c},{r}) must be identical regardless of OBMC ctx"
                );
            }
        }
    }

    /// r378 — the OBMC-context slice guards reject a short per-cell slice
    /// with `PartitionWalkOutOfRange`.
    #[test]
    fn r378_reconstruct_inter_frame_obmc_ctx_slice_guards() {
        let refp = vec![5u16; 32 * 32];
        let entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride: 32,
            upscaled_width: 32,
            width: 32,
            height: 32,
        };
        let store = [entry; 8];
        let ref_frame_idx = [0u8; 7];
        let mi_rows: u32 = 2;
        let mi_cols: u32 = 2;
        let cells = (mi_rows * mi_cols) as usize;
        let mi_sizes = vec![crate::cdf::BLOCK_INVALID; cells];
        let is_inters = vec![0u8; cells];
        let mut ref_frames = vec![0i8; cells * 2];
        for cell in 0..cells {
            ref_frames[cell * 2 + 1] = -1;
        }
        let mvs = vec![0i16; cells * 4];
        let interp_filters = vec![EIGHTTAP; cells * 2];
        let zeros = vec![0u8; cells];
        let order_hints_by_ref = [0i32; 8];
        let full = vec![0u8; cells];
        let short = vec![0u8; cells - 1];

        // A too-short `avail_u` slice trips the guard.
        let grid = InterModeInfoGrid {
            mi_sizes: &mi_sizes,
            is_inters: &is_inters,
            ref_frames: &ref_frames,
            mvs: &mvs,
            interp_filters: &interp_filters,
            compound_types: &zeros,
            wedge_indices: &zeros,
            wedge_signs: &zeros,
            mask_types: &zeros,
            interintra_modes: &zeros,
            wedge_interintras: &zeros,
            interintra_wedge_indices: &zeros,
            order_hint_bits: 7,
            current_order_hint: 0,
            order_hints_by_ref: &order_hints_by_ref,
            mi_rows,
            mi_cols,
            bit_depth: 8,
            warp: None,
            obmc: Some(GridObmcContext {
                motion_modes: &full,
                avail_u: &short,
                avail_l: &full,
            }),
        };
        let mut curr = vec![0u16; 64];
        let mut planes = [PlaneReconContext {
            plane: 0,
            subsampling_x: 0,
            subsampling_y: 0,
            frame_store: &store,
            frame_width: 32,
            frame_height: 32,
            curr: &mut curr,
            curr_stride: 8,
        }];
        assert_eq!(
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes).unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );
    }

    /// r378 — a **top-left** OBMC leaf (`AvailU == false && AvailL ==
    /// false`) has no qualifying §7.11.3.9 neighbour on either axis, so the
    /// overlap blend is a no-op and the OBMC dispatch reconstructs exactly
    /// the leaf's own §7.11.3.1 translational prediction — i.e. identical
    /// to the SIMPLE fallback. This exercises the `mi_row == 0` /
    /// `mi_col == 0` edge of `obmc_dispatch_leaf` (the `wrapping_sub(1)`
    /// candidate origins are never indexed because both passes gate off).
    #[test]
    fn r378_reconstruct_inter_frame_obmc_top_left_leaf_equals_simple() {
        let ref_w = 32usize;
        let ref_h = 32usize;
        let mut refp = vec![0u16; ref_w * ref_h];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * ref_w + c] = ((r * 9 + c * 3) & 0xff) as u16;
            }
        }
        let entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride: ref_w,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [entry; 8];
        let ref_frame_idx = [0u8; 7];
        let last = crate::uncompressed_header_tail::LAST_FRAME as u8;

        // 2×2 mi grid (8×8 luma). One BLOCK_8X8 OBMC leaf at the top-left
        // origin (0,0) — AvailU == AvailL == false.
        let mi_rows: u32 = 2;
        let mi_cols: u32 = 2;
        let cells = (mi_rows * mi_cols) as usize;
        let bw8x8 = crate::cdf::BLOCK_8X8;
        let mut mi_sizes = vec![crate::cdf::BLOCK_INVALID; cells];
        let mut is_inters = vec![0u8; cells];
        let mut ref_frames = vec![0i8; cells * 2];
        let mut mvs = vec![0i16; cells * 4];
        let interp_filters = vec![EIGHTTAP; cells * 2];
        for cell in 0..cells {
            mi_sizes[cell] = bw8x8;
            is_inters[cell] = 1;
            ref_frames[cell * 2] = last as i8;
            ref_frames[cell * 2 + 1] = -1;
            mvs[cell * 4] = 2;
            mvs[cell * 4 + 1] = 6;
        }
        let zeros = vec![0u8; cells];
        let order_hints_by_ref = [0i32; 8];
        let motion_modes = vec![crate::cdf::MOTION_MODE_OBMC; cells];
        // Top-left leaf: no above / left neighbour available.
        let avail_u = vec![0u8; cells];
        let avail_l = vec![0u8; cells];

        let curr_w = 8usize;
        let mut curr_obmc = vec![0u16; curr_w * curr_w];
        let mut curr_simple = vec![0u16; curr_w * curr_w];

        macro_rules! grid {
            ($obmc:expr) => {
                InterModeInfoGrid {
                    mi_sizes: &mi_sizes,
                    is_inters: &is_inters,
                    ref_frames: &ref_frames,
                    mvs: &mvs,
                    interp_filters: &interp_filters,
                    compound_types: &zeros,
                    wedge_indices: &zeros,
                    wedge_signs: &zeros,
                    mask_types: &zeros,
                    interintra_modes: &zeros,
                    wedge_interintras: &zeros,
                    interintra_wedge_indices: &zeros,
                    order_hint_bits: 7,
                    current_order_hint: 0,
                    order_hints_by_ref: &order_hints_by_ref,
                    mi_rows,
                    mi_cols,
                    bit_depth: 8,
                    warp: None,
                    obmc: $obmc,
                }
            };
        }
        {
            let g = grid!(Some(GridObmcContext {
                motion_modes: &motion_modes,
                avail_u: &avail_u,
                avail_l: &avail_l,
            }));
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut curr_obmc,
                curr_stride: curr_w,
            }];
            reconstruct_inter_frame(&g, &ref_frame_idx, &mut planes).expect("OBMC top-left walk");
        }
        {
            let g = grid!(None);
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut curr_simple,
                curr_stride: curr_w,
            }];
            reconstruct_inter_frame(&g, &ref_frame_idx, &mut planes).expect("SIMPLE walk");
        }
        assert_eq!(
            curr_obmc, curr_simple,
            "a top-left OBMC leaf has no §7.11.3.9 neighbour ⇒ the blend is a \
             no-op ⇒ identical to the SIMPLE translational prediction"
        );
        // Sanity: the leaf actually reconstructed (not left zero).
        assert!(curr_obmc.iter().any(|&s| s != 0));
    }

    /// r378 — the OBMC frame-walk dispatch is per-plane: a 4:2:0
    /// three-plane (Y/Cb/Cr) frame with an 8×8 OBMC leaf reconstructs each
    /// plane through `reconstruct_inter_block_obmc` with the §7.11.3.9
    /// neighbour lists resolved at that plane's `(subsampling_x,
    /// subsampling_y)`. The chroma planes (4×4 OBMC block, where
    /// `get_plane_residual_size(BLOCK_8X8, plane) == BLOCK_4X4 <
    /// BLOCK_8X8`) exercise the §7.11.3.9 above-pass small-block carve-out
    /// (only the left-pass runs). The frame walk must match a hand-resolved
    /// per-block OBMC oracle on every plane.
    #[test]
    fn r378_reconstruct_inter_frame_obmc_dispatch_multiplane_420() {
        let ref_w = 32usize;
        let ref_h = 32usize;
        let mut refp = vec![0u16; ref_w * ref_h];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * ref_w + c] = ((r * 32 + c) & 0xff) as u16;
            }
        }
        let entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride: ref_w,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [entry; 8];
        let ref_frame_idx = [0u8; 7];
        let last = crate::uncompressed_header_tail::LAST_FRAME as u8;

        let mi_rows: u32 = 4;
        let mi_cols: u32 = 4;
        let cells = (mi_rows * mi_cols) as usize;
        let bw8x8 = crate::cdf::BLOCK_8X8;
        let mut mi_sizes = vec![crate::cdf::BLOCK_INVALID; cells];
        let mut is_inters = vec![0u8; cells];
        let mut ref_frames = vec![0i8; cells * 2];
        let mut mvs = vec![0i16; cells * 4];
        let interp_filters = vec![EIGHTTAP; cells * 2];
        let stamp = |mi_sizes: &mut [usize],
                     is_inters: &mut [u8],
                     ref_frames: &mut [i8],
                     mvs: &mut [i16],
                     r0: usize,
                     c0: usize,
                     mv: [i16; 2]| {
            for dr in 0..2 {
                for dc in 0..2 {
                    let cell = (r0 + dr) * mi_cols as usize + (c0 + dc);
                    mi_sizes[cell] = bw8x8;
                    is_inters[cell] = 1;
                    ref_frames[cell * 2] = last as i8;
                    ref_frames[cell * 2 + 1] = -1;
                    mvs[cell * 4] = mv[0];
                    mvs[cell * 4 + 1] = mv[1];
                }
            }
        };
        stamp(
            &mut mi_sizes,
            &mut is_inters,
            &mut ref_frames,
            &mut mvs,
            0,
            2,
            [0, 8],
        );
        stamp(
            &mut mi_sizes,
            &mut is_inters,
            &mut ref_frames,
            &mut mvs,
            2,
            0,
            [8, 0],
        );
        stamp(
            &mut mi_sizes,
            &mut is_inters,
            &mut ref_frames,
            &mut mvs,
            0,
            0,
            [4, 4],
        );
        stamp(
            &mut mi_sizes,
            &mut is_inters,
            &mut ref_frames,
            &mut mvs,
            2,
            2,
            [2, 6],
        );

        let zeros = vec![0u8; cells];
        let order_hints_by_ref = [0i32; 8];
        let mut motion_modes = vec![crate::cdf::MOTION_MODE_SIMPLE; cells];
        motion_modes[2 * mi_cols as usize + 2] = crate::cdf::MOTION_MODE_OBMC;
        let mut avail_u = vec![0u8; cells];
        let mut avail_l = vec![0u8; cells];
        for r in 0..mi_rows as usize {
            for c in 0..mi_cols as usize {
                avail_u[r * mi_cols as usize + c] = (r > 0) as u8;
                avail_l[r * mi_cols as usize + c] = (c > 0) as u8;
            }
        }

        // Plane geometry: luma 16×16, chroma 8×8 (4:2:0).
        let luma_w = 16usize;
        let chroma_w = 8usize;
        let mut y = vec![0u16; luma_w * luma_w];
        let mut u = vec![0u16; chroma_w * chroma_w];
        let mut v = vec![0u16; chroma_w * chroma_w];
        let mut y_or = vec![0u16; luma_w * luma_w];
        let mut u_or = vec![0u16; chroma_w * chroma_w];
        let mut v_or = vec![0u16; chroma_w * chroma_w];

        let grid = InterModeInfoGrid {
            mi_sizes: &mi_sizes,
            is_inters: &is_inters,
            ref_frames: &ref_frames,
            mvs: &mvs,
            interp_filters: &interp_filters,
            compound_types: &zeros,
            wedge_indices: &zeros,
            wedge_signs: &zeros,
            mask_types: &zeros,
            interintra_modes: &zeros,
            wedge_interintras: &zeros,
            interintra_wedge_indices: &zeros,
            order_hint_bits: 7,
            current_order_hint: 0,
            order_hints_by_ref: &order_hints_by_ref,
            mi_rows,
            mi_cols,
            bit_depth: 8,
            warp: None,
            obmc: Some(GridObmcContext {
                motion_modes: &motion_modes,
                avail_u: &avail_u,
                avail_l: &avail_l,
            }),
        };
        {
            let mut planes = [
                PlaneReconContext {
                    plane: 0,
                    subsampling_x: 0,
                    subsampling_y: 0,
                    frame_store: &store,
                    frame_width: ref_w as u32,
                    frame_height: ref_h as u32,
                    curr: &mut y,
                    curr_stride: luma_w,
                },
                PlaneReconContext {
                    plane: 1,
                    subsampling_x: 1,
                    subsampling_y: 1,
                    frame_store: &store,
                    frame_width: ref_w as u32,
                    frame_height: ref_h as u32,
                    curr: &mut u,
                    curr_stride: chroma_w,
                },
                PlaneReconContext {
                    plane: 2,
                    subsampling_x: 1,
                    subsampling_y: 1,
                    frame_store: &store,
                    frame_width: ref_w as u32,
                    frame_height: ref_h as u32,
                    curr: &mut v,
                    curr_stride: chroma_w,
                },
            ];
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes)
                .expect("multiplane OBMC frame walk");
        }

        // Oracle: drive only the (2,2) OBMC leaf per plane via the per-block
        // driver; the three SIMPLE leaves are reconstructed identically by
        // an `obmc: None` walk into the *_or buffers first.
        {
            let grid_simple = InterModeInfoGrid {
                mi_sizes: &mi_sizes,
                is_inters: &is_inters,
                ref_frames: &ref_frames,
                mvs: &mvs,
                interp_filters: &interp_filters,
                compound_types: &zeros,
                wedge_indices: &zeros,
                wedge_signs: &zeros,
                mask_types: &zeros,
                interintra_modes: &zeros,
                wedge_interintras: &zeros,
                interintra_wedge_indices: &zeros,
                order_hint_bits: 7,
                current_order_hint: 0,
                order_hints_by_ref: &order_hints_by_ref,
                mi_rows,
                mi_cols,
                bit_depth: 8,
                warp: None,
                obmc: None,
            };
            let mut planes = [
                PlaneReconContext {
                    plane: 0,
                    subsampling_x: 0,
                    subsampling_y: 0,
                    frame_store: &store,
                    frame_width: ref_w as u32,
                    frame_height: ref_h as u32,
                    curr: &mut y_or,
                    curr_stride: luma_w,
                },
                PlaneReconContext {
                    plane: 1,
                    subsampling_x: 1,
                    subsampling_y: 1,
                    frame_store: &store,
                    frame_width: ref_w as u32,
                    frame_height: ref_h as u32,
                    curr: &mut u_or,
                    curr_stride: chroma_w,
                },
                PlaneReconContext {
                    plane: 2,
                    subsampling_x: 1,
                    subsampling_y: 1,
                    frame_store: &store,
                    frame_width: ref_w as u32,
                    frame_height: ref_h as u32,
                    curr: &mut v_or,
                    curr_stride: chroma_w,
                },
            ];
            reconstruct_inter_frame(&grid_simple, &ref_frame_idx, &mut planes)
                .expect("simple oracle walk");
        }
        // Overlay the per-block OBMC leaf on each oracle plane. Neighbours:
        // above (mi 1,3) MV from the (0,2) leaf; left (mi 3,1) MV from the
        // (2,0) leaf — both 8×8 ⇒ step4 = 2.
        let above_mv = [
            mvs[(mi_cols as usize + 3) * 4],
            mvs[(mi_cols as usize + 3) * 4 + 1],
        ];
        let left_mv = [
            mvs[(3 * mi_cols as usize + 1) * 4],
            mvs[(3 * mi_cols as usize + 1) * 4 + 1],
        ];
        let nb = |mv: [i16; 2]| PredictInterRef {
            ref_plane: &refp[..],
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv,
        };
        for (plane, (orc, cstride)) in [
            (&mut y_or, luma_w),
            (&mut u_or, chroma_w),
            (&mut v_or, chroma_w),
        ]
        .into_iter()
        .enumerate()
        {
            let sub = if plane > 0 { 1u8 } else { 0 };
            let above_gate = sub == 0; // BLOCK_8X8>=8x8 luma; chroma 4×4<8×8
            let above_nb = [ObmcNeighbour {
                bundle: nb(above_mv),
                step4: 2,
                interp_filter_x: EIGHTTAP,
                interp_filter_y: EIGHTTAP,
                axis_pos4: 2,
            }];
            let left_nb = [ObmcNeighbour {
                bundle: nb(left_mv),
                step4: 2,
                interp_filter_x: EIGHTTAP,
                interp_filter_y: EIGHTTAP,
                axis_pos4: 2,
            }];
            let op = ObmcParams {
                mi_row: 2,
                mi_col: 2,
                mi_cols,
                mi_rows,
                mi_width_log2: crate::cdf::mi_width_log2(bw8x8) as u8,
                mi_height_log2: crate::cdf::mi_height_log2(bw8x8) as u8,
                avail_u: true,
                avail_l: true,
                plane_residual_size_ge_block_8x8: above_gate,
                above_neighbours: if above_gate { &above_nb } else { &[] },
                left_neighbours: &left_nb,
            };
            let w = 8usize >> sub;
            let h = 8usize >> sub;
            let x = 8i32 >> sub;
            let yy = 8i32 >> sub;
            reconstruct_inter_block_obmc(
                InterModeInfo {
                    ref_frame: last,
                    mv: [2, 6],
                },
                &op,
                &ref_frame_idx,
                &store,
                plane as u8,
                x,
                yy,
                w,
                h,
                8,
                sub,
                sub,
                ref_w as u32,
                ref_h as u32,
                EIGHTTAP,
                EIGHTTAP,
                orc.as_mut_slice(),
                cstride,
            )
            .expect("per-block OBMC oracle plane");
        }

        assert_eq!(y, y_or, "luma OBMC frame walk vs per-block oracle");
        assert_eq!(u, u_or, "Cb OBMC frame walk vs per-block oracle");
        assert_eq!(v, v_or, "Cr OBMC frame walk vs per-block oracle");
    }

    // ---------- r294 §7.11.3.1 compound block driver ----------

    /// Build a deterministic `16×16` reference plane (`r*16 + c`) and a
    /// frame store with the real plane parked at slot `real_slot` (every
    /// other slot a distinct decoy), plus a `ref_frame_idx` mapping
    /// `LAST_FRAME` / `ALTREF_FRAME` both onto `real_slot`. Returns
    /// `(refp, ref_frame_idx)` for the caller to build the store from.
    fn r294_ref_plane(ref_w: usize, ref_h: usize) -> Vec<u16> {
        let mut refp = vec![0u16; ref_w * ref_h];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * ref_w + c] = (r * 16 + c) as u16;
            }
        }
        refp
    }

    /// §7.11.3.1 compound `COMPOUND_AVERAGE` block driver —
    /// [`reconstruct_inter_block_compound`] must resolve both references
    /// through `ref_frame_idx` / `frame_store` and produce the same
    /// bytes as a direct [`predict_inter`] compound call, stitched at
    /// the plane origin.
    #[test]
    fn r294_reconstruct_inter_block_compound_average_matches_predict_inter() {
        let ref_w = 16usize;
        let ref_h = 16usize;
        let stride = ref_w;
        let refp = r294_ref_plane(ref_w, ref_h);
        let decoy = vec![0u16; ref_w * ref_h];
        let real = RefFrameStoreEntry {
            plane: &refp[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let dec = RefFrameStoreEntry {
            plane: &decoy[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        // Real plane at slot 2; ref_frame_idx maps LAST→2 and ALTREF→2.
        let store = [dec, dec, real, dec];
        let ref_frame_idx: [u8; 7] = [2, 0, 1, 3, 0, 1, 2];
        let last = crate::uncompressed_header_tail::LAST_FRAME as u8;
        let altref = crate::uncompressed_header_tail::ALTREF_FRAME as u8;

        let w = 4;
        let h = 4;
        // Distinct MVs per list so the two predictions differ.
        let mode_info = CompoundInterModeInfo {
            ref_frame_0: last,
            ref_frame_1: altref,
            mv0: [0, 4],
            mv1: [8, 0],
            compound_type: COMPOUND_AVERAGE,
            wedge: None,
            mask_type: 0,
        };
        // Driver output, stitched into an 8×8 plane at (2, 2).
        let curr_w = 8;
        let curr_h = 8;
        let sentinel = 6000u16;
        let mut curr = vec![sentinel; curr_w * curr_h];
        reconstruct_inter_block_compound(
            mode_info,
            CompoundOrderHintContext {
                order_hint_bits: 7,
                current_order_hint: 0,
                order_hint_ref0: 0,
                order_hint_ref1: 0,
            },
            &ref_frame_idx,
            &store,
            0,
            2,
            2,
            w,
            h,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            None,
            /* warp */ None,
            &mut curr,
            curr_w,
        )
        .expect("compound AVERAGE block driver");

        // Oracle: the same two refs (both resolve to `refp`) through a
        // direct predict_inter compound AVERAGE call.
        let refs = [
            PredictInterRef {
                ref_plane: &refp,
                ref_stride: stride,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [0, 4],
            },
            PredictInterRef {
                ref_plane: &refp,
                ref_stride: stride,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [8, 0],
            },
        ];
        let mut expected = vec![0u16; w * h];
        predict_inter(
            0,
            2,
            2,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            true,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            Some(CompoundParams::Average),
            /* inter_intra */ None,
            None,
            None,
            &mut expected,
        )
        .unwrap();

        for i in 0..h {
            for j in 0..w {
                assert_eq!(
                    curr[(2 + i) * curr_w + (2 + j)],
                    expected[i * w + j],
                    "compound AVERAGE stitch mismatch at ({j}, {i})"
                );
            }
        }
        // The block's border outside the 4×4 write region is untouched.
        assert_eq!(curr[0], sentinel);
        assert_eq!(curr[curr_w * curr_h - 1], sentinel);
    }

    /// §7.11.3.1 compound `COMPOUND_DISTANCE` block driver — the
    /// driver must derive `(FwdWeight, BckWeight)` from the supplied
    /// order-hint context via [`distance_weights`] and produce the same
    /// bytes as a direct [`predict_inter`] call given those same
    /// weights.
    #[test]
    fn r294_reconstruct_inter_block_compound_distance_derives_weights() {
        let ref_w = 16usize;
        let ref_h = 16usize;
        let stride = ref_w;
        let refp = r294_ref_plane(ref_w, ref_h);
        let real = RefFrameStoreEntry {
            plane: &refp[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [real, real];
        let ref_frame_idx: [u8; 7] = [0, 1, 0, 0, 0, 0, 0];
        let last = crate::uncompressed_header_tail::LAST_FRAME as u8;
        // RefFrame[1] = LAST_FRAME + 1 → ref_frame_idx slot 1 → store[1].
        let ref1 = last + 1;

        // Asymmetric order hints so FwdWeight != BckWeight.
        let ohc = CompoundOrderHintContext {
            order_hint_bits: 7,
            current_order_hint: 8,
            order_hint_ref0: 4, // dist 4
            order_hint_ref1: 2, // dist 6
        };
        let weights = distance_weights(
            ohc.order_hint_bits,
            ohc.current_order_hint,
            ohc.order_hint_ref0,
            ohc.order_hint_ref1,
        );
        // Guard the test's premise: the two weights actually differ, so
        // this exercises a non-degenerate DISTANCE blend.
        assert_ne!(
            weights.fwd_weight, weights.bck_weight,
            "test premise: order hints chosen for asymmetric weights"
        );

        let w = 4;
        let h = 4;
        let mut curr = vec![0u16; w * h];
        reconstruct_inter_block_compound(
            CompoundInterModeInfo {
                ref_frame_0: last,
                ref_frame_1: ref1,
                mv0: [0, 4],
                mv1: [8, 0],
                compound_type: COMPOUND_DISTANCE,
                wedge: None,
                mask_type: 0,
            },
            ohc,
            &ref_frame_idx,
            &store,
            0,
            0,
            0,
            w,
            h,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            None,
            /* warp */ None,
            &mut curr,
            w,
        )
        .expect("compound DISTANCE block driver");

        let refs = [
            PredictInterRef {
                ref_plane: &refp,
                ref_stride: stride,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [0, 4],
            },
            PredictInterRef {
                ref_plane: &refp,
                ref_stride: stride,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [8, 0],
            },
        ];
        let mut expected = vec![0u16; w * h];
        predict_inter(
            0,
            0,
            0,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            true,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            Some(CompoundParams::Distance(weights)),
            /* inter_intra */ None,
            None,
            None,
            &mut expected,
        )
        .unwrap();
        assert_eq!(
            curr, expected,
            "compound DISTANCE driver must derive the same weights and blend"
        );
    }

    /// [`reconstruct_inter_block_compound`] caller-bug matrix: a mask
    /// `compound_type` (WEDGE / DIFFWTD / INTRA), an INTRA_FRAME /
    /// out-of-range `RefFrame`, an out-of-range resolved `refIdx`, and
    /// a `curr_plane` too small each surface `PartitionWalkOutOfRange`.
    #[test]
    fn r294_reconstruct_inter_block_compound_rejects_caller_bugs() {
        let ref_w = 16usize;
        let ref_h = 16usize;
        let refp = r294_ref_plane(ref_w, ref_h);
        let entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride: ref_w,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [entry, entry];
        let ref_frame_idx: [u8; 7] = [0, 1, 0, 0, 0, 0, 0];
        let last = crate::uncompressed_header_tail::LAST_FRAME as u8;
        let ohc = CompoundOrderHintContext {
            order_hint_bits: 7,
            current_order_hint: 0,
            order_hint_ref0: 0,
            order_hint_ref1: 0,
        };
        let w = 4;
        let h = 4;
        let mk = |rf0: u8, rf1: u8, ct: u8, curr: &mut [u16], stride: usize| {
            reconstruct_inter_block_compound(
                CompoundInterModeInfo {
                    ref_frame_0: rf0,
                    ref_frame_1: rf1,
                    mv0: [0, 0],
                    mv1: [0, 0],
                    compound_type: ct,
                    // `wedge: None` — exercises both the non-wedge arms
                    // and the "WEDGE without wedge side-data" caller bug.
                    wedge: None,
                    mask_type: 0,
                },
                ohc,
                &ref_frame_idx,
                &store,
                0,
                0,
                0,
                w,
                h,
                8,
                0,
                0,
                ref_w as u32,
                ref_h as u32,
                EIGHTTAP,
                EIGHTTAP,
                None,
                /* warp */ None,
                curr,
                stride,
            )
        };
        let mut curr = vec![0u16; w * h];
        // COMPOUND_WEDGE without `wedge` side-data — caller bug.
        assert_eq!(
            mk(last, last + 1, COMPOUND_WEDGE, &mut curr, w).unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );
        // COMPOUND_DIFFWTD routed without the persistent luma-grid mask
        // buffer (the `mk` closure passes `diffwtd_mask = None`) — caller
        // bug per the §7.11.3.12 persistence gate.
        assert_eq!(
            mk(last, last + 1, COMPOUND_DIFFWTD, &mut curr, w).unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );
        // INTRA_FRAME (0) as either ref.
        assert_eq!(
            mk(0, last + 1, COMPOUND_AVERAGE, &mut curr, w).unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );
        assert_eq!(
            mk(last, 0, COMPOUND_AVERAGE, &mut curr, w).unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );
        // Out-of-range RefFrame (> ALTREF_FRAME).
        assert_eq!(
            mk(last, 99, COMPOUND_AVERAGE, &mut curr, w).unwrap_err(),
            crate::Error::PartitionWalkOutOfRange
        );
        // r394 — a short curr_plane is the legal §5.11.4 bottom
        // overhang shape: the compound blend runs at full block
        // geometry and the stitch clips to the `h - 1` whole rows the
        // plane holds.
        let mut tiny = vec![0u16; w * h - 1];
        mk(last, last + 1, COMPOUND_AVERAGE, &mut tiny, w)
            .expect("overhanging compound write clips instead of erroring");
    }

    /// §5.11.33 frame walk — a grid carrying one `COMPOUND_AVERAGE` and
    /// one `COMPOUND_DISTANCE` compound leaf must dispatch each through
    /// [`reconstruct_inter_block_compound`] identically to a direct
    /// per-block call, while a `COMPOUND_DIFFWTD` (prediction-derived
    /// mask) compound leaf and an inter-intra leaf are left as the
    /// sentinel.
    #[test]
    fn r294_reconstruct_inter_frame_drives_average_and_distance_compound() {
        let ref_w = 16usize;
        let ref_h = 16usize;
        let stride = ref_w;
        let refp = r294_ref_plane(ref_w, ref_h);
        let real = RefFrameStoreEntry {
            plane: &refp[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [real, real, real, real];
        let store2 = store;
        let ref_frame_idx: [u8; 7] = [0, 1, 2, 3, 0, 1, 2];
        let last = crate::uncompressed_header_tail::LAST_FRAME as i8;

        let mi_rows: u32 = 1;
        let mi_cols: u32 = 4;
        let cells = (mi_rows * mi_cols) as usize;

        use crate::cdf::{BLOCK_4X4, BLOCK_INVALID};
        let mut mi_sizes = vec![BLOCK_INVALID; cells];
        let mut is_inters = vec![0u8; cells];
        let mut ref_frames = vec![0i8; cells * 2];
        for cell in 0..cells {
            ref_frames[cell * 2 + 1] = -1;
        }
        let mut mvs = vec![0i16; cells * 4];
        let interp_filters = vec![EIGHTTAP; cells * 2];
        let mut compound_types = vec![COMPOUND_AVERAGE; cells];

        // Each cell its own BLOCK_4X4 leaf.
        for sz in mi_sizes.iter_mut() {
            *sz = BLOCK_4X4;
        }
        // Helper to stamp a compound leaf at column `c`.
        let mut stamp = |c: usize, rf1: i8, ct: u8, mv0: [i16; 2], mv1: [i16; 2]| {
            is_inters[c] = 1;
            ref_frames[c * 2] = last;
            ref_frames[c * 2 + 1] = rf1;
            mvs[c * 4] = mv0[0];
            mvs[c * 4 + 1] = mv0[1];
            mvs[c * 4 + 2] = mv1[0];
            mvs[c * 4 + 3] = mv1[1];
            compound_types[c] = ct;
        };
        // col 0: COMPOUND_AVERAGE (RefFrame[1] = LAST+1).
        stamp(0, last + 1, COMPOUND_AVERAGE, [0, 4], [8, 0]);
        // col 1: COMPOUND_DISTANCE (RefFrame[1] = LAST+2).
        stamp(1, last + 2, COMPOUND_DISTANCE, [4, 0], [0, 8]);
        // col 2: COMPOUND_INTRA (a two-inter-ref leaf so tagged is never
        // produced by the spec; the §7.11.3.13 intra-variant mask only
        // arises on the inter-intra arm) — must be skipped by this walk.
        stamp(2, last + 1, COMPOUND_INTRA, [0, 4], [8, 0]);
        // col 3: pure intra leaf (`is_inters == 0`) — the §7.11.2 intra
        // arm's responsibility, skipped by this inter walk. (The
        // inter-intra arm, `is_inter && RefFrame[1] == INTRA_FRAME`, is
        // now *driven* — see `r299_frame_walk_drives_interintra_leaf_*`;
        // it is exercised there, not here.)
        is_inters[3] = 0;

        // OrderHints: ref LAST=ref1 idx → hints chosen so DISTANCE has
        // asymmetric weights. RefFrame indices used: LAST(1), LAST+1(2),
        // LAST+2(3).
        let mut order_hints_by_ref = [0i32; 8];
        order_hints_by_ref[last as usize] = 4; // LAST
        order_hints_by_ref[(last + 1) as usize] = 6;
        order_hints_by_ref[(last + 2) as usize] = 2;
        let current_order_hint = 8;

        let curr_w = (mi_cols * 4) as usize; // 16
        let curr_h = 4usize;
        let sentinel = 5000u16;
        let mut curr = vec![sentinel; curr_w * curr_h];

        let wedge_zeros = vec![0u8; cells];
        let grid = InterModeInfoGrid {
            mi_sizes: &mi_sizes,
            is_inters: &is_inters,
            ref_frames: &ref_frames,
            mvs: &mvs,
            interp_filters: &interp_filters,
            compound_types: &compound_types,
            wedge_indices: &wedge_zeros,
            wedge_signs: &wedge_zeros,
            mask_types: &wedge_zeros,
            interintra_modes: &wedge_zeros,
            wedge_interintras: &wedge_zeros,
            interintra_wedge_indices: &wedge_zeros,
            order_hint_bits: 7,
            current_order_hint,
            order_hints_by_ref: &order_hints_by_ref,
            mi_rows,
            mi_cols,
            bit_depth: 8,
            warp: None,
            obmc: None,
        };
        {
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut curr,
                curr_stride: curr_w,
            }];
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes)
                .expect("frame-level compound reconstruction");
        }

        // Oracle: drive the two mask-free compound leaves directly.
        let mut oracle = vec![sentinel; curr_w * curr_h];
        // col 0 AVERAGE at (baseX=0, baseY=0).
        reconstruct_inter_block_compound(
            CompoundInterModeInfo {
                ref_frame_0: last as u8,
                ref_frame_1: (last + 1) as u8,
                mv0: [0, 4],
                mv1: [8, 0],
                compound_type: COMPOUND_AVERAGE,
                wedge: None,
                mask_type: 0,
            },
            CompoundOrderHintContext {
                order_hint_bits: 7,
                current_order_hint,
                order_hint_ref0: order_hints_by_ref[last as usize],
                order_hint_ref1: order_hints_by_ref[(last + 1) as usize],
            },
            &ref_frame_idx,
            &store2,
            0,
            0,
            0,
            4,
            4,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            None,
            /* warp */ None,
            &mut oracle,
            curr_w,
        )
        .unwrap();
        // col 1 DISTANCE at (baseX=4, baseY=0).
        reconstruct_inter_block_compound(
            CompoundInterModeInfo {
                ref_frame_0: last as u8,
                ref_frame_1: (last + 2) as u8,
                mv0: [4, 0],
                mv1: [0, 8],
                compound_type: COMPOUND_DISTANCE,
                wedge: None,
                mask_type: 0,
            },
            CompoundOrderHintContext {
                order_hint_bits: 7,
                current_order_hint,
                order_hint_ref0: order_hints_by_ref[last as usize],
                order_hint_ref1: order_hints_by_ref[(last + 2) as usize],
            },
            &ref_frame_idx,
            &store2,
            0,
            4,
            0,
            4,
            4,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            None,
            /* warp */ None,
            &mut oracle,
            curr_w,
        )
        .unwrap();

        assert_eq!(
            curr, oracle,
            "frame walk must dispatch compound leaves identically to the per-block driver"
        );
        // The COMPOUND_INTRA (col 2) and inter-intra (col 3) leaves are
        // skipped → still the sentinel (cols 8..16 in plane samples).
        for c in 8..16 {
            for r in 0..curr_h {
                assert_eq!(
                    curr[r * curr_w + c],
                    sentinel,
                    "skipped compound/inter-intra sample ({c}, {r}) must stay sentinel"
                );
            }
        }
        // The two driven leaves were reconstructed.
        assert_ne!(curr[0], sentinel, "AVERAGE leaf reconstructed");
        assert_ne!(curr[4], sentinel, "DISTANCE leaf reconstructed");
    }

    /// §7.11.3.1 step-14 + line 14386 `COMPOUND_WEDGE` block driver —
    /// [`reconstruct_inter_block_compound`] must regenerate the
    /// §7.11.3.11 luma-grid wedge mask from `(MiSize, wedge_index,
    /// wedge_sign)` and produce the same samples as a direct
    /// [`predict_inter`] + [`wedge_mask`] oracle, on the luma plane and
    /// on a `(sub_x, sub_y) == (1, 1)` chroma plane (where the luma mask
    /// is reused with downsampling).
    #[test]
    fn r295_reconstruct_inter_block_compound_wedge_matches_predict_inter() {
        // BLOCK_8X8 is wedge-eligible (WEDGE_BITS[3] == 4); luma 8×8.
        const BLOCK_8X8: usize = 3;
        let ref_w = 24usize;
        let ref_h = 24usize;
        let stride = ref_w;
        let refp = r294_ref_plane(ref_w, ref_h);
        let real = RefFrameStoreEntry {
            plane: &refp[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        // Two distinct refs (slots resolve to the same plane but the two
        // MVs make preds[0] != preds[1], so the wedge mask matters).
        let store = [real, real, real, real];
        let ref_frame_idx: [u8; 7] = [0, 1, 2, 3, 0, 1, 2];
        let last = crate::uncompressed_header_tail::LAST_FRAME as u8;
        let ohc = CompoundOrderHintContext {
            order_hint_bits: 7,
            current_order_hint: 0,
            order_hint_ref0: 0,
            order_hint_ref1: 0,
        };
        let wedge_index = 5u8;
        let wedge_sign = 1u8;
        let mode_info = CompoundInterModeInfo {
            ref_frame_0: last,
            ref_frame_1: last + 1,
            mv0: [0, 4],
            mv1: [8, 0],
            compound_type: COMPOUND_WEDGE,
            wedge: Some(WedgeModeInfo {
                mi_size: BLOCK_8X8,
                wedge_index,
                wedge_sign,
            }),
            mask_type: 0,
        };

        // Pre-build the luma-grid wedge mask once for the oracle.
        let luma_w = crate::cdf::block_width(BLOCK_8X8);
        let luma_h = crate::cdf::block_height(BLOCK_8X8);
        let mut mask = vec![0u8; luma_w * luma_h];
        wedge_mask(
            BLOCK_8X8,
            crate::cdf::num_4x4_blocks_wide(BLOCK_8X8) as u32,
            crate::cdf::num_4x4_blocks_high(BLOCK_8X8) as u32,
            wedge_index,
            wedge_sign,
            &mut mask,
        )
        .unwrap();
        // A wedge mask is non-trivial: it must contain a 0..64 gradient,
        // not a constant, or the test would not exercise the blend.
        assert!(
            mask.iter().any(|&m| m != mask[0]),
            "test premise: wedge mask must be non-constant"
        );

        // Per (plane, sub_x, sub_y, x, y, w, h) oracle: run predict_inter
        // with the same two refs and the pre-built mask, then stitch.
        let drive = |plane: u8, sub_x: u8, sub_y: u8, x: i32, y: i32, w: usize, h: usize| {
            // Driver output.
            let curr_w = ref_w;
            let curr_h = ref_h;
            let mut got = vec![0u16; curr_w * curr_h];
            reconstruct_inter_block_compound(
                mode_info,
                ohc,
                &ref_frame_idx,
                &store,
                plane,
                x,
                y,
                w,
                h,
                8,
                sub_x,
                sub_y,
                ref_w as u32,
                ref_h as u32,
                EIGHTTAP,
                EIGHTTAP,
                None,
                /* warp */ None,
                &mut got,
                curr_w,
            )
            .expect("WEDGE block driver");

            // Oracle: predict_inter into a w×h buffer, then stitch.
            let refs = [
                PredictInterRef {
                    ref_plane: &refp,
                    ref_stride: stride,
                    ref_upscaled_width: ref_w as u32,
                    ref_width: ref_w as u32,
                    ref_height: ref_h as u32,
                    mv: [0, 4],
                },
                PredictInterRef {
                    ref_plane: &refp,
                    ref_stride: stride,
                    ref_upscaled_width: ref_w as u32,
                    ref_width: ref_w as u32,
                    ref_height: ref_h as u32,
                    mv: [8, 0],
                },
            ];
            let mut pred = vec![0u16; w * h];
            predict_inter(
                plane,
                x,
                y,
                w,
                h,
                crate::cdf::MOTION_MODE_SIMPLE,
                true,
                false,
                8,
                sub_x,
                sub_y,
                ref_w as u32,
                ref_h as u32,
                EIGHTTAP,
                EIGHTTAP,
                &refs,
                Some(CompoundParams::Wedge {
                    mask: &mask,
                    mask_stride: luma_w,
                }),
                /* inter_intra */ None,
                None,
                None,
                &mut pred,
            )
            .expect("WEDGE oracle predict_inter");
            // Compare the driver's stitched region against the oracle.
            for i in 0..h {
                for j in 0..w {
                    let dst = (y as usize + i) * curr_w + (x as usize + j);
                    assert_eq!(
                        got[dst],
                        pred[i * w + j],
                        "WEDGE mismatch plane={plane} at ({j},{i})"
                    );
                }
            }
        };

        // Luma plane: full 8×8 at (0, 0).
        drive(0, 0, 0, 0, 0, luma_w, luma_h);
        // Chroma plane with 4:2:0 subsampling: 4×4 region, same luma mask
        // reused via mask_blend's (1, 1) downsampling.
        drive(1, 1, 1, 0, 0, luma_w / 2, luma_h / 2);
    }

    /// §5.11.33 frame walk — a `COMPOUND_WEDGE` leaf (BLOCK_8X8,
    /// wedge-eligible) must be driven through
    /// [`reconstruct_inter_block_compound`] with the per-leaf
    /// `wedge_indices` / `wedge_signs`, producing the same samples as a
    /// direct per-block WEDGE call.
    #[test]
    fn r295_reconstruct_inter_frame_drives_wedge_compound() {
        const BLOCK_8X8: usize = 3;
        let ref_w = 16usize;
        let ref_h = 16usize;
        let stride = ref_w;
        let refp = r294_ref_plane(ref_w, ref_h);
        let real = RefFrameStoreEntry {
            plane: &refp[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [real, real, real, real];
        let store2 = store;
        let ref_frame_idx: [u8; 7] = [0, 1, 2, 3, 0, 1, 2];
        let last = crate::uncompressed_header_tail::LAST_FRAME as i8;

        // One BLOCK_8X8 leaf (2×2 mi cells) at the grid origin.
        let mi_rows: u32 = 2;
        let mi_cols: u32 = 2;
        let cells = (mi_rows * mi_cols) as usize;
        use crate::cdf::BLOCK_INVALID;
        let mut mi_sizes = vec![BLOCK_INVALID; cells];
        mi_sizes[0] = BLOCK_8X8; // origin; walk stamps the 2×2 footprint.
        let mut is_inters = vec![0u8; cells];
        is_inters[0] = 1;
        let mut ref_frames = vec![0i8; cells * 2];
        for cell in 0..cells {
            ref_frames[cell * 2 + 1] = -1;
        }
        ref_frames[0] = last; // RefFrame[0] = LAST.
        ref_frames[1] = last + 1; // RefFrame[1] = LAST+1 (compound).
        let mut mvs = vec![0i16; cells * 4];
        mvs[0] = 0;
        mvs[1] = 4;
        mvs[2] = 8;
        mvs[3] = 0;
        let interp_filters = vec![EIGHTTAP; cells * 2];
        let mut compound_types = vec![COMPOUND_AVERAGE; cells];
        compound_types[0] = COMPOUND_WEDGE;
        let wedge_index = 7u8;
        let wedge_sign = 0u8;
        let mut wedge_indices = vec![0u8; cells];
        wedge_indices[0] = wedge_index;
        let mut wedge_signs = vec![0u8; cells];
        wedge_signs[0] = wedge_sign;
        let mask_types = vec![0u8; cells];
        let zeros_ii = vec![0u8; cells];

        let order_hints_by_ref = [0i32; 8];
        let curr_w = (mi_cols * 4) as usize; // 8
        let curr_h = (mi_rows * 4) as usize; // 8
        let sentinel = 5000u16;
        let mut curr = vec![sentinel; curr_w * curr_h];

        let grid = InterModeInfoGrid {
            mi_sizes: &mi_sizes,
            is_inters: &is_inters,
            ref_frames: &ref_frames,
            mvs: &mvs,
            interp_filters: &interp_filters,
            compound_types: &compound_types,
            wedge_indices: &wedge_indices,
            wedge_signs: &wedge_signs,
            mask_types: &mask_types,
            interintra_modes: &zeros_ii,
            wedge_interintras: &zeros_ii,
            interintra_wedge_indices: &zeros_ii,
            order_hint_bits: 7,
            current_order_hint: 0,
            order_hints_by_ref: &order_hints_by_ref,
            mi_rows,
            mi_cols,
            bit_depth: 8,
            warp: None,
            obmc: None,
        };
        {
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut curr,
                curr_stride: curr_w,
            }];
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes)
                .expect("frame-level WEDGE reconstruction");
        }

        // Oracle: drive the single WEDGE leaf directly.
        let mut oracle = vec![sentinel; curr_w * curr_h];
        reconstruct_inter_block_compound(
            CompoundInterModeInfo {
                ref_frame_0: last as u8,
                ref_frame_1: (last + 1) as u8,
                mv0: [0, 4],
                mv1: [8, 0],
                compound_type: COMPOUND_WEDGE,
                wedge: Some(WedgeModeInfo {
                    mi_size: BLOCK_8X8,
                    wedge_index,
                    wedge_sign,
                }),
                mask_type: 0,
            },
            CompoundOrderHintContext {
                order_hint_bits: 7,
                current_order_hint: 0,
                order_hint_ref0: 0,
                order_hint_ref1: 0,
            },
            &ref_frame_idx,
            &store2,
            0,
            0,
            0,
            8,
            8,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            None,
            /* warp */ None,
            &mut oracle,
            curr_w,
        )
        .unwrap();

        assert_eq!(
            curr, oracle,
            "frame walk must drive the WEDGE leaf identically to the per-block driver"
        );
        // The 8×8 region was reconstructed (no sentinel left).
        assert!(
            curr.iter().all(|&s| s != sentinel),
            "all WEDGE samples reconstructed"
        );
    }

    /// §5.11.33 frame walk — a `COMPOUND_DIFFWTD` leaf (BLOCK_8X8) must
    /// be driven through [`reconstruct_inter_block_compound`] with a
    /// per-block persistent luma-grid mask buffer. The §7.11.3.12 mask
    /// is derived *internally* from the two `preds[]` (av1-spec p.258
    /// line 14392), so the walk must match a per-block driver invoked
    /// with the same `mask_type` and its own scratch buffer, and the
    /// result must differ from a plain `COMPOUND_AVERAGE` blend (proving
    /// the diff-weight mask actually shapes the output).
    #[test]
    fn r296_reconstruct_inter_frame_drives_diffwtd_compound() {
        const BLOCK_8X8: usize = 3;
        let ref_w = 16usize;
        let ref_h = 16usize;
        let stride = ref_w;
        let refp = r294_ref_plane(ref_w, ref_h);
        let real = RefFrameStoreEntry {
            plane: &refp[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [real, real, real, real];
        let store2 = store;
        let ref_frame_idx: [u8; 7] = [0, 1, 2, 3, 0, 1, 2];
        let last = crate::uncompressed_header_tail::LAST_FRAME as i8;

        let mi_rows: u32 = 2;
        let mi_cols: u32 = 2;
        let cells = (mi_rows * mi_cols) as usize;
        use crate::cdf::BLOCK_INVALID;
        let mut mi_sizes = vec![BLOCK_INVALID; cells];
        mi_sizes[0] = BLOCK_8X8;
        let mut is_inters = vec![0u8; cells];
        is_inters[0] = 1;
        let mut ref_frames = vec![0i8; cells * 2];
        for cell in 0..cells {
            ref_frames[cell * 2 + 1] = -1;
        }
        ref_frames[0] = last;
        ref_frames[1] = last + 1;
        // Two distinct MVs so preds[0] != preds[1] and the §7.11.3.12
        // difference is non-trivial across the block.
        let mv0 = [0i16, 4];
        let mv1 = [8i16, 0];
        let mut mvs = vec![0i16; cells * 4];
        mvs[0] = mv0[0];
        mvs[1] = mv0[1];
        mvs[2] = mv1[0];
        mvs[3] = mv1[1];
        let interp_filters = vec![EIGHTTAP; cells * 2];
        let mut compound_types = vec![COMPOUND_AVERAGE; cells];
        compound_types[0] = COMPOUND_DIFFWTD;
        let mask_type = 1u8; // DIFFWTD_38_INV.
        let mut mask_types = vec![0u8; cells];
        mask_types[0] = mask_type;
        let zeros = vec![0u8; cells];
        let zeros_ii = vec![0u8; cells];

        let order_hints_by_ref = [0i32; 8];
        let curr_w = (mi_cols * 4) as usize; // 8
        let curr_h = (mi_rows * 4) as usize; // 8
        let sentinel = 5000u16;
        let mut curr = vec![sentinel; curr_w * curr_h];

        let grid = InterModeInfoGrid {
            mi_sizes: &mi_sizes,
            is_inters: &is_inters,
            ref_frames: &ref_frames,
            mvs: &mvs,
            interp_filters: &interp_filters,
            compound_types: &compound_types,
            wedge_indices: &zeros,
            wedge_signs: &zeros,
            mask_types: &mask_types,
            interintra_modes: &zeros_ii,
            wedge_interintras: &zeros_ii,
            interintra_wedge_indices: &zeros_ii,
            order_hint_bits: 7,
            current_order_hint: 0,
            order_hints_by_ref: &order_hints_by_ref,
            mi_rows,
            mi_cols,
            bit_depth: 8,
            warp: None,
            obmc: None,
        };
        {
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut curr,
                curr_stride: curr_w,
            }];
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes)
                .expect("frame-level DIFFWTD reconstruction");
        }

        // Oracle: drive the single DIFFWTD leaf directly with its own
        // persistent luma-grid mask buffer.
        let mut oracle = vec![sentinel; curr_w * curr_h];
        let mut oracle_mask = vec![0u8; 8 * 8];
        reconstruct_inter_block_compound(
            CompoundInterModeInfo {
                ref_frame_0: last as u8,
                ref_frame_1: (last + 1) as u8,
                mv0,
                mv1,
                compound_type: COMPOUND_DIFFWTD,
                wedge: None,
                mask_type,
            },
            CompoundOrderHintContext {
                order_hint_bits: 7,
                current_order_hint: 0,
                order_hint_ref0: 0,
                order_hint_ref1: 0,
            },
            &ref_frame_idx,
            &store2,
            0,
            0,
            0,
            8,
            8,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            Some(&mut oracle_mask),
            /* warp */ None,
            &mut oracle,
            curr_w,
        )
        .unwrap();

        assert_eq!(
            curr, oracle,
            "frame walk must drive the DIFFWTD leaf identically to the per-block driver"
        );
        assert!(
            curr.iter().all(|&s| s != sentinel),
            "all DIFFWTD samples reconstructed"
        );

        // A plain AVERAGE blend of the same two preds must differ — the
        // diff-weight mask genuinely shapes the output.
        let mut avg = vec![sentinel; curr_w * curr_h];
        reconstruct_inter_block_compound(
            CompoundInterModeInfo {
                ref_frame_0: last as u8,
                ref_frame_1: (last + 1) as u8,
                mv0,
                mv1,
                compound_type: COMPOUND_AVERAGE,
                wedge: None,
                mask_type: 0,
            },
            CompoundOrderHintContext {
                order_hint_bits: 7,
                current_order_hint: 0,
                order_hint_ref0: 0,
                order_hint_ref1: 0,
            },
            &ref_frame_idx,
            &store2,
            0,
            0,
            0,
            8,
            8,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            None,
            /* warp */ None,
            &mut avg,
            curr_w,
        )
        .unwrap();
        assert_ne!(
            curr, avg,
            "DIFFWTD mask blend must differ from a plain AVERAGE blend"
        );
    }

    /// §7.11.3.1 caller-bug matrix (post-r203) — all four motion
    /// modes now have driver-side wiring; what remain are the
    /// caller-bug guards that surface `PartitionWalkOutOfRange` when
    /// the caller signals a motion mode without supplying its
    /// required context bundle:
    ///
    /// * `motion_mode == WARPED_CAUSAL` without `WarpDriverParams` ⇒
    ///   `PartitionWalkOutOfRange` (r202 guard).
    /// * `motion_mode == OBMC` without `ObmcParams` ⇒
    ///   `PartitionWalkOutOfRange` (r203 guard — replaces the prior
    ///   `PredictInterObmcUnsupported` stub).
    ///
    /// The r194 `PredictInterCompoundUnsupported` / r194
    /// `PredictInterWarpUnsupported` / r194 `PredictInterObmcUnsupported`
    /// stub arms are all retired (r201 / r202 / r203 respectively).
    #[test]
    fn r194_predict_inter_stub_arms_each_surface_dedicated_error() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let refp = vec![0u16; ref_w * ref_h];
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        let mut pred_out = vec![0u16; 16];

        // r202 caller-bug guard: motion_mode == WARPED_CAUSAL
        // without `WarpDriverParams` ⇒ PartitionWalkOutOfRange.
        let mut pred_out_8x8 = vec![0u16; 64];
        let e = predict_inter(
            0,
            0,
            0,
            8,
            8,
            crate::cdf::MOTION_MODE_WARPED_CAUSAL,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut pred_out_8x8,
        )
        .unwrap_err();
        assert_eq!(e, crate::Error::PartitionWalkOutOfRange);

        // r203 caller-bug guard: motion_mode == OBMC without
        // `ObmcParams` ⇒ PartitionWalkOutOfRange. The §7.11.3.9
        // mi-grid walk needs MiRow/MiCol/MiSize + the AvailU/AvailL
        // gates + the above/left qualifying neighbour lists; a
        // caller that signals OBMC without surfacing that context
        // is a caller bug.
        let e = predict_inter(
            0,
            0,
            0,
            4,
            4,
            crate::cdf::MOTION_MODE_OBMC,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut pred_out,
        )
        .unwrap_err();
        assert_eq!(e, crate::Error::PartitionWalkOutOfRange);
    }

    /// §7.11.3.1 caller-bug guards: `refs.is_empty()`,
    /// `pred_out` undersized, and an out-of-range `bit_depth` each
    /// return `PartitionWalkOutOfRange` without entering the
    /// rounding-variables / scaling / convolution pipeline.
    #[test]
    fn r194_predict_inter_rejects_caller_bugs() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let refp = vec![0u16; ref_w * ref_h];
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        let mut pred_out = vec![0u16; 16];

        // Empty refs.
        let empty_refs: [PredictInterRef<'_>; 0] = [];
        let e = predict_inter(
            0,
            0,
            0,
            4,
            4,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &empty_refs,
            None,
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut pred_out,
        )
        .unwrap_err();
        assert_eq!(e, crate::Error::PartitionWalkOutOfRange);

        // Undersized pred_out (w*h = 16, slice = 8).
        let mut small = vec![0u16; 8];
        let e = predict_inter(
            0,
            0,
            0,
            4,
            4,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut small,
        )
        .unwrap_err();
        assert_eq!(e, crate::Error::PartitionWalkOutOfRange);

        // Out-of-range bit_depth.
        let e = predict_inter(
            0,
            0,
            0,
            4,
            4,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            9,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut pred_out,
        )
        .unwrap_err();
        assert_eq!(e, crate::Error::PartitionWalkOutOfRange);
    }

    // ---------- r201 §7.11.3.1 predict_inter compound arm ----------

    /// §7.11.3.1 step-14 + line 14405 — `COMPOUND_AVERAGE` driver path.
    /// The compound driver must produce the same per-pixel output as a
    /// hand-composed two-`predict_inter_per_ref`-plus-blend path
    /// (`Clip1(Round2(p0+p1, 1+InterPostRound))`). We use the degenerate
    /// `ref0 == ref1` setup so the expected pixel value is just the
    /// standalone single-ref prediction (preds round-trip through the
    /// blend identity `(p+p)/2 == p`).
    #[test]
    fn r201_predict_inter_compound_average_matches_hand_blend() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = (r * 16 + c) as u16;
            }
        }
        let refs = [
            PredictInterRef {
                ref_plane: &refp,
                ref_stride: stride,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [0, 0],
            },
            PredictInterRef {
                ref_plane: &refp,
                ref_stride: stride,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [0, 0],
            },
        ];
        let w = 4;
        let h = 4;
        let mut pred_out = vec![0u16; w * h];
        predict_inter(
            0,
            2,
            2,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            /* is_compound */ true,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            Some(CompoundParams::Average),
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut pred_out,
        )
        .expect("compound AVERAGE arm");

        // Hand-derived expected: run the same leaf twice (both refs
        // identical) → preds[0] == preds[1] → average is the
        // single-ref prediction (after rounding).
        let rv = rounding_variables(8, true).unwrap();
        let mvs = motion_vector_scaling(
            0,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            ref_w as u32,
            ref_h as u32,
            2,
            2,
            [0, 0],
        )
        .unwrap();
        let mut leaf = vec![0i32; w * h];
        block_inter_prediction(
            0,
            0,
            0,
            &refp,
            stride,
            ref_w as u32,
            ref_h as u32,
            mvs.start_x,
            mvs.start_y,
            mvs.step_x,
            mvs.step_y,
            w,
            h,
            EIGHTTAP,
            EIGHTTAP,
            rv.inter_round0,
            rv.inter_round1,
            &mut leaf,
        )
        .unwrap();
        let shift: u32 = 1 + rv.inter_post_round;
        let max: i32 = (1i32 << 8) - 1;
        let mut expected = vec![0u16; w * h];
        for i in 0..h {
            for j in 0..w {
                let acc = leaf[i * w + j] as i64 + leaf[i * w + j] as i64;
                let r = ((acc + (1i64 << (shift - 1))) >> shift) as i32;
                expected[i * w + j] = r.clamp(0, max) as u16;
            }
        }
        assert_eq!(pred_out, expected, "AVERAGE arm pixel mismatch");
    }

    /// §7.11.3.1 step-14 + line 14408 — `COMPOUND_DISTANCE` driver
    /// path. Verifies the driver routes to `compound_distance_blend`
    /// with the caller-supplied `(FwdWeight, BckWeight)`.
    #[test]
    fn r201_predict_inter_compound_distance_matches_hand_blend() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 17 + c * 5) & 0xFF) as u16;
            }
        }
        let refs = [
            PredictInterRef {
                ref_plane: &refp,
                ref_stride: stride,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [0, 0],
            },
            PredictInterRef {
                ref_plane: &refp,
                ref_stride: stride,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [0, 0],
            },
        ];
        let weights = DistanceWeights {
            fwd_weight: 9,
            bck_weight: 7,
        };
        let w = 4;
        let h = 4;
        let mut pred_out = vec![0u16; w * h];
        predict_inter(
            0,
            2,
            2,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            true,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            Some(CompoundParams::Distance(weights)),
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut pred_out,
        )
        .expect("compound DISTANCE arm");

        let rv = rounding_variables(8, true).unwrap();
        let mvs = motion_vector_scaling(
            0,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            ref_w as u32,
            ref_h as u32,
            2,
            2,
            [0, 0],
        )
        .unwrap();
        let mut leaf = vec![0i32; w * h];
        block_inter_prediction(
            0,
            0,
            0,
            &refp,
            stride,
            ref_w as u32,
            ref_h as u32,
            mvs.start_x,
            mvs.start_y,
            mvs.step_x,
            mvs.step_y,
            w,
            h,
            EIGHTTAP,
            EIGHTTAP,
            rv.inter_round0,
            rv.inter_round1,
            &mut leaf,
        )
        .unwrap();
        let mut expected = vec![0u16; w * h];
        compound_distance_blend(
            8,
            rv.inter_post_round,
            weights,
            &leaf,
            &leaf,
            w,
            h,
            &mut expected,
        )
        .unwrap();
        assert_eq!(pred_out, expected, "DISTANCE arm pixel mismatch");
    }

    /// §7.11.3.1 step-14 + line 14412 — `COMPOUND_WEDGE` driver path.
    /// The mask is a hand-built 8×8 wedge buffer (no chroma subsampling
    /// so the mask is read directly per pixel by `mask_blend`).
    #[test]
    fn r201_predict_inter_compound_wedge_routes_to_mask_blend() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r + c) & 0xFF) as u16;
            }
        }
        let refs = [
            PredictInterRef {
                ref_plane: &refp,
                ref_stride: stride,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [0, 0],
            },
            PredictInterRef {
                ref_plane: &refp,
                ref_stride: stride,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [0, 0],
            },
        ];
        let w = 8;
        let h = 8;
        // Build an 8×8 wedge mask via the §7.11.3.11 leaf
        // (BLOCK_8X8 ⇒ num_4x4 = 2,2; mi_size = 3 per BLOCK_8X8
        // ordinal — `WEDGE_BITS[3]` is 4 so a wedge_index in 0..16).
        let mut mask = vec![0u8; w * h];
        wedge_mask(3, 2, 2, 0, 0, &mut mask).unwrap();

        let mut pred_out = vec![0u16; w * h];
        predict_inter(
            0,
            0,
            0,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            true,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            Some(CompoundParams::Wedge {
                mask: &mask,
                mask_stride: 0,
            }),
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut pred_out,
        )
        .expect("compound WEDGE arm");

        // With ref0 == ref1, preds[0] == preds[1], and the mask blend
        // collapses to `Round2((m + 64 - m) * pred, 6 + InterPostRound)
        // = Round2(64 * pred, 6 + InterPostRound) = pred (rounded)`.
        let rv = rounding_variables(8, true).unwrap();
        let mvs = motion_vector_scaling(
            0,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            ref_w as u32,
            ref_h as u32,
            0,
            0,
            [0, 0],
        )
        .unwrap();
        let mut leaf = vec![0i32; w * h];
        block_inter_prediction(
            0,
            0,
            0,
            &refp,
            stride,
            ref_w as u32,
            ref_h as u32,
            mvs.start_x,
            mvs.start_y,
            mvs.step_x,
            mvs.step_y,
            w,
            h,
            EIGHTTAP,
            EIGHTTAP,
            rv.inter_round0,
            rv.inter_round1,
            &mut leaf,
        )
        .unwrap();
        let mut expected = vec![0u16; w * h];
        mask_blend(
            8,
            rv.inter_post_round,
            0,
            0,
            &leaf,
            &leaf,
            w,
            h,
            &mask,
            0,
            &mut expected,
        )
        .unwrap();
        assert_eq!(pred_out, expected, "WEDGE arm pixel mismatch");
    }

    /// §7.11.3.1 step-14 + line 14412 — `COMPOUND_DIFFWTD` driver path:
    /// the §7.11.3.12 mask is derived *internally* from the two actual
    /// `preds[]` the driver forms (the caller supplies only `mask_type`
    /// plus a persistent luma-grid scratch buffer per av1-spec p.258
    /// line 14392), then blended via §7.11.3.14. The oracle re-derives
    /// the mask from the *same* per-ref §7.11.3.4 leaf predictions and
    /// blends them, so a match proves the driver consumes real preds
    /// rather than a fabricated mask.
    #[test]
    fn r296_predict_inter_compound_diffwtd_derives_mask_from_preds() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        // Two *distinct* reference planes so the per-pixel difference —
        // and therefore the §7.11.3.12 mask — varies across the block.
        let mut refp0 = vec![0u16; ref_h * stride];
        let mut refp1 = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp0[r * stride + c] = ((r * 9 + c) & 0xFF) as u16;
                refp1[r * stride + c] = ((r * 3 + c * 5 + 17) & 0xFF) as u16;
            }
        }
        let refs = [
            PredictInterRef {
                ref_plane: &refp0,
                ref_stride: stride,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [0, 0],
            },
            PredictInterRef {
                ref_plane: &refp1,
                ref_stride: stride,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [0, 0],
            },
        ];
        let w = 8;
        let h = 8;
        let rv = rounding_variables(8, true).unwrap();
        let mask_type = 1u8; // exercise the DIFFWTD_38_INV inversion.

        let mut pred_out = vec![0u16; w * h];
        let mut persistent_mask = vec![0u8; w * h];
        predict_inter(
            0,
            0,
            0,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            true,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            Some(CompoundParams::Diffwtd {
                mask_type,
                mask: &mut persistent_mask,
            }),
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut pred_out,
        )
        .expect("compound DIFFWTD arm");

        // Oracle: form the two per-ref §7.11.3.4 leaf predictions,
        // derive the §7.11.3.12 mask from them, then §7.11.3.14 blend.
        let mvs = motion_vector_scaling(
            0,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            ref_w as u32,
            ref_h as u32,
            0,
            0,
            [0, 0],
        )
        .unwrap();
        let leaf = |rp: &[u16]| -> Vec<i32> {
            let mut out = vec![0i32; w * h];
            block_inter_prediction(
                0,
                0,
                0,
                rp,
                stride,
                ref_w as u32,
                ref_h as u32,
                mvs.start_x,
                mvs.start_y,
                mvs.step_x,
                mvs.step_y,
                w,
                h,
                EIGHTTAP,
                EIGHTTAP,
                rv.inter_round0,
                rv.inter_round1,
                &mut out,
            )
            .unwrap();
            out
        };
        let leaf0 = leaf(&refp0);
        let leaf1 = leaf(&refp1);
        let mut oracle_mask = vec![0u8; w * h];
        difference_weight_mask(
            8,
            rv.inter_post_round,
            mask_type,
            &leaf0,
            &leaf1,
            w,
            h,
            &mut oracle_mask,
        )
        .unwrap();
        // The driver must have written the same mask into the persistent
        // luma-grid buffer.
        assert_eq!(
            persistent_mask, oracle_mask,
            "DIFFWTD persistent mask mismatch"
        );
        let mut expected = vec![0u16; w * h];
        mask_blend(
            8,
            rv.inter_post_round,
            0,
            0,
            &leaf0,
            &leaf1,
            w,
            h,
            &oracle_mask,
            0,
            &mut expected,
        )
        .unwrap();
        assert_eq!(pred_out, expected, "DIFFWTD arm pixel mismatch");
        // The mask must genuinely vary (proves real-pred derivation, not
        // a constant fallback).
        assert!(
            oracle_mask.iter().any(|&m| m != oracle_mask[0]),
            "DIFFWTD mask should vary across the block"
        );
    }

    /// §7.11.3.1 step-14 + line 14412 — `COMPOUND_INTRA` driver path
    /// (mask buffer supplied by caller via §7.11.3.13
    /// `intra_mode_variant_mask`).
    #[test]
    fn r201_predict_inter_compound_intra_routes_to_mask_blend() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r + c * 2) & 0xFF) as u16;
            }
        }
        let refs = [
            PredictInterRef {
                ref_plane: &refp,
                ref_stride: stride,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [0, 0],
            },
            PredictInterRef {
                ref_plane: &refp,
                ref_stride: stride,
                ref_upscaled_width: ref_w as u32,
                ref_width: ref_w as u32,
                ref_height: ref_h as u32,
                mv: [0, 0],
            },
        ];
        let w = 8;
        let h = 8;
        let mut mask = vec![0u8; w * h];
        intra_mode_variant_mask(II_SMOOTH_PRED, w, h, &mut mask).unwrap();

        let mut pred_out = vec![0u16; w * h];
        predict_inter(
            0,
            0,
            0,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            true,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            Some(CompoundParams::Intra {
                mask: &mask,
                mask_stride: 0,
            }),
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut pred_out,
        )
        .expect("compound INTRA arm");

        let rv = rounding_variables(8, true).unwrap();
        let mvs = motion_vector_scaling(
            0,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            ref_w as u32,
            ref_h as u32,
            0,
            0,
            [0, 0],
        )
        .unwrap();
        let mut leaf = vec![0i32; w * h];
        block_inter_prediction(
            0,
            0,
            0,
            &refp,
            stride,
            ref_w as u32,
            ref_h as u32,
            mvs.start_x,
            mvs.start_y,
            mvs.step_x,
            mvs.step_y,
            w,
            h,
            EIGHTTAP,
            EIGHTTAP,
            rv.inter_round0,
            rv.inter_round1,
            &mut leaf,
        )
        .unwrap();
        let mut expected = vec![0u16; w * h];
        mask_blend(
            8,
            rv.inter_post_round,
            0,
            0,
            &leaf,
            &leaf,
            w,
            h,
            &mask,
            0,
            &mut expected,
        )
        .unwrap();
        assert_eq!(pred_out, expected, "INTRA arm pixel mismatch");
    }

    /// §7.11.3.1 r201 — caller-bug guards on the compound arm:
    /// `is_compound == true` with `refs.len() < 2` or
    /// `compound == None`; and the reverse `is_compound == false`
    /// with a spurious `Some(_)` compound argument.
    #[test]
    fn r201_predict_inter_compound_rejects_caller_bugs() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let refp = vec![0u16; ref_w * ref_h];
        let single = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        let double = [single[0]; 2];
        let mut pred_out = vec![0u16; 16];

        // is_compound == true but refs.len() == 1.
        let e = predict_inter(
            0,
            0,
            0,
            4,
            4,
            crate::cdf::MOTION_MODE_SIMPLE,
            true,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &single,
            Some(CompoundParams::Average),
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut pred_out,
        )
        .unwrap_err();
        assert_eq!(e, crate::Error::PartitionWalkOutOfRange);

        // is_compound == true but compound == None.
        let e = predict_inter(
            0,
            0,
            0,
            4,
            4,
            crate::cdf::MOTION_MODE_SIMPLE,
            true,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &double,
            None,
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut pred_out,
        )
        .unwrap_err();
        assert_eq!(e, crate::Error::PartitionWalkOutOfRange);

        // is_compound == false but a Some(_) compound supplied.
        let e = predict_inter(
            0,
            0,
            0,
            4,
            4,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &single,
            Some(CompoundParams::Average),
            /* inter_intra */ None,
            /* warp */ None,
            /* obmc */ None,
            &mut pred_out,
        )
        .unwrap_err();
        assert_eq!(e, crate::Error::PartitionWalkOutOfRange);
    }

    // ---------- r202 §7.11.3.1 predict_inter WARP arm ----------

    /// Identity warp matrix per the §7.11.3.5 / §5.9.x convention:
    /// `[a0=0, a1=0, a2=1<<16, a3=0, a4=0, a5=1<<16]` ⇒ the affine
    /// transform `dst = (a2*src + a0, a5*src + a1)` is the identity in
    /// fixed-point. Useful as a degenerate warp matrix that should
    /// reproduce (modulo the warp filter phase) a zero-MV translational
    /// prediction.
    const WARP_IDENTITY: [i32; 6] = [0, 0, 1 << 16, 0, 0, 1 << 16];

    /// §7.11.3.1 step-7 ◦ 3 (`useWarp = 1` for LOCALWARP + LocalValid)
    /// — invoking the driver with `motion_mode == WARPED_CAUSAL` and
    /// a valid `WarpDriverParams` triggers per-8×8 `block_warp`
    /// dispatch instead of `block_inter_prediction`. The output must
    /// equal the per-sub-block `block_warp` composition computed
    /// outside the driver.
    #[test]
    fn r202_predict_inter_localwarp_routes_to_block_warp() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 19 + c * 7) & 0xFF) as u16;
            }
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        let warp = WarpDriverParams {
            y_mode: [crate::cdf::MODE_GLOBALMV, 0],
            gm_type: [crate::cdf::GM_TYPE_IDENTITY as u8, 0],
            gm_params: [WARP_IDENTITY, WARP_IDENTITY],
            local_warp_params: WARP_IDENTITY,
            local_valid: true,
            ref_is_scaled: [false, false],
            force_integer_mv: false,
        };

        let w = 8;
        let h = 8;
        let mut pred_out = vec![0u16; w * h];
        predict_inter(
            /* plane */ 0,
            /* x */ 8,
            /* y */ 8,
            w,
            h,
            crate::cdf::MOTION_MODE_WARPED_CAUSAL,
            /* is_compound */ false,
            /* is_inter_intra */ false,
            /* bit_depth */ 8,
            /* subsampling_x */ 0,
            /* subsampling_y */ 0,
            /* frame_width */ ref_w as u32,
            /* frame_height */ ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            /* compound */ None,
            /* inter_intra */ None,
            /* warp */ Some(&warp),
            /* obmc */ None,
            &mut pred_out,
        )
        .expect("predict_inter LOCALWARP arm");

        // Hand-composition: run block_warp(USE_WARP_LOCAL, ..) per
        // 8×8 sub-block (here a single sub-block since w == h == 8),
        // then clip1.
        let rv = rounding_variables(8, false).unwrap();
        let mut leaf = vec![0i32; w * h];
        block_warp(
            USE_WARP_LOCAL,
            0,
            0,
            0,
            8,
            8,
            0,
            0,
            w,
            h,
            &refp,
            stride,
            ref_w as u32,
            ref_h as u32,
            WARP_IDENTITY,
            rv.inter_round0,
            rv.inter_round1,
            /* pred_stride */ w,
            &mut leaf,
        )
        .unwrap();
        let mut expected = vec![0u16; w * h];
        clip1_single_ref(8, &leaf, &mut expected).unwrap();
        assert_eq!(
            pred_out, expected,
            "LOCALWARP driver output must equal hand-composed block_warp"
        );
    }

    /// §7.11.3.1 step-7 ◦ 4 (`useWarp = 2` for GLOBAL_GLOBALMV) — when
    /// motion_mode is SIMPLE but `YMode == GLOBAL_GLOBALMV` and
    /// `GmType[refFrame] > TRANSLATION`, the driver routes to
    /// `block_warp(USE_WARP_GLOBAL, gm_params[refFrame])`. We use a
    /// `setup_shear`-valid identity-class matrix so `globalValid` is
    /// `true` and the step-7 AND chain clears.
    #[test]
    fn r202_predict_inter_global_warp_routes_to_block_warp() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 13 + c * 11) & 0xFF) as u16;
            }
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        // GmType = ROTZOOM (> TRANSLATION) so step-7's `gm_type >
        // TRANSLATION` gate fires.
        let warp = WarpDriverParams {
            y_mode: [crate::cdf::MODE_GLOBAL_GLOBALMV, 0],
            gm_type: [crate::cdf::GM_TYPE_ROTZOOM as u8, 0],
            gm_params: [WARP_IDENTITY, WARP_IDENTITY],
            local_warp_params: WARP_IDENTITY,
            local_valid: false,
            ref_is_scaled: [false, false],
            force_integer_mv: false,
        };

        let w = 8;
        let h = 8;
        let mut pred_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            // SIMPLE motion mode; the step-7 ◦ 4 GLOBAL arm fires
            // independent of motion_mode per av1-spec p.257 line 14339.
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            Some(&warp),
            /* obmc */ None,
            &mut pred_out,
        )
        .expect("predict_inter GLOBAL_WARP arm");

        let rv = rounding_variables(8, false).unwrap();
        let mut leaf = vec![0i32; w * h];
        block_warp(
            USE_WARP_GLOBAL,
            0,
            0,
            0,
            8,
            8,
            0,
            0,
            w,
            h,
            &refp,
            stride,
            ref_w as u32,
            ref_h as u32,
            WARP_IDENTITY,
            rv.inter_round0,
            rv.inter_round1,
            w,
            &mut leaf,
        )
        .unwrap();
        let mut expected = vec![0u16; w * h];
        clip1_single_ref(8, &leaf, &mut expected).unwrap();
        assert_eq!(
            pred_out, expected,
            "GLOBAL_WARP driver output must equal hand-composed block_warp"
        );
    }

    // ---------- r338 reconstruct_inter_block_warp bridge ----------

    /// r338 §7.11.3.1 WARP reconstruction bridge — the `block_warp`
    /// counterpart of `reconstruct_inter_block`. With a valid LOCALWARP
    /// `WarpDriverParams` and an 8×8 leaf the bridge must stitch into
    /// `curr_plane` exactly the `Clip1`-ed `predict_inter` WARP output.
    #[test]
    fn r338_reconstruct_inter_block_warp_localwarp_stitches_into_curr() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 23 + c * 5) & 0xFF) as u16;
            }
        }
        let store = [RefFrameStoreEntry {
            plane: &refp,
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        }];
        // ref_frame_idx maps LAST_FRAME (1) -> slot 0 -> store[0].
        let ref_frame_idx = [0u8; 7];
        let warp = WarpDriverParams {
            y_mode: [crate::cdf::MODE_NEWMV, 0],
            gm_type: [crate::cdf::GM_TYPE_IDENTITY as u8, 0],
            gm_params: [WARP_IDENTITY, WARP_IDENTITY],
            local_warp_params: WARP_IDENTITY,
            local_valid: true,
            ref_is_scaled: [false, false],
            force_integer_mv: false,
        };
        let mode_info = InterModeInfo {
            ref_frame: crate::uncompressed_header_tail::LAST_FRAME as u8,
            mv: [0, 0],
        };
        let (w, h) = (8usize, 8usize);
        // Curr plane is the whole 32×32 frame; the bridge overwrites the
        // 8×8 footprint at (8, 8).
        let mut curr = vec![0u16; ref_h * stride];
        reconstruct_inter_block_warp(
            mode_info,
            &warp,
            &ref_frame_idx,
            &store,
            /* plane */ 0,
            /* x */ 8,
            /* y */ 8,
            w,
            h,
            /* bit_depth */ 8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &mut curr,
            stride,
        )
        .expect("reconstruct_inter_block_warp LOCALWARP");

        // Expected: predict_inter WARP arm into a w×h scratch, then the
        // same (x, y) footprint copy.
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        let mut pred = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_WARPED_CAUSAL,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            None,
            Some(&warp),
            None,
            &mut pred,
        )
        .unwrap();
        for i in 0..h {
            for j in 0..w {
                assert_eq!(
                    curr[(8 + i) * stride + (8 + j)],
                    pred[i * w + j],
                    "warp bridge sample ({i},{j}) must match predict_inter WARP arm"
                );
            }
        }
    }

    /// r338 — the bridge mirrors `reconstruct_inter_block`'s caller-bug
    /// guards: `INTRA_FRAME` ref, out-of-range `refIdx`, a too-small
    /// `curr_plane`, and a negative origin all return
    /// `PartitionWalkOutOfRange`.
    #[test]
    fn r338_reconstruct_inter_block_warp_arg_guards() {
        let refp = vec![7u16; 32 * 32];
        let store = [RefFrameStoreEntry {
            plane: &refp,
            stride: 32,
            upscaled_width: 32,
            width: 32,
            height: 32,
        }];
        let ref_frame_idx = [0u8; 7];
        let warp = WarpDriverParams {
            y_mode: [crate::cdf::MODE_NEWMV, 0],
            gm_type: [crate::cdf::GM_TYPE_IDENTITY as u8, 0],
            gm_params: [WARP_IDENTITY, WARP_IDENTITY],
            local_warp_params: WARP_IDENTITY,
            local_valid: true,
            ref_is_scaled: [false, false],
            force_integer_mv: false,
        };
        let mut curr = vec![0u16; 32 * 32];

        // INTRA_FRAME (0) ref.
        let mi_intra = InterModeInfo {
            ref_frame: crate::uncompressed_header_tail::INTRA_FRAME as u8,
            mv: [0, 0],
        };
        assert!(reconstruct_inter_block_warp(
            mi_intra,
            &warp,
            &ref_frame_idx,
            &store,
            0,
            0,
            0,
            8,
            8,
            8,
            0,
            0,
            32,
            32,
            EIGHTTAP,
            EIGHTTAP,
            &mut curr,
            32,
        )
        .is_err());

        let mi = InterModeInfo {
            ref_frame: crate::uncompressed_header_tail::LAST_FRAME as u8,
            mv: [0, 0],
        };
        // Out-of-range resolved refIdx (slot 0 -> 9, store has 1 entry).
        let bad_idx = [9u8; 7];
        assert!(reconstruct_inter_block_warp(
            mi, &warp, &bad_idx, &store, 0, 0, 0, 8, 8, 8, 0, 0, 32, 32, EIGHTTAP, EIGHTTAP,
            &mut curr, 32,
        )
        .is_err());

        // curr_plane too small for the (x, y, w, h) write region.
        let mut tiny = vec![0u16; 8];
        assert!(reconstruct_inter_block_warp(
            mi,
            &warp,
            &ref_frame_idx,
            &store,
            0,
            0,
            0,
            8,
            8,
            8,
            0,
            0,
            32,
            32,
            EIGHTTAP,
            EIGHTTAP,
            &mut tiny,
            32,
        )
        .is_err());

        // Negative origin.
        assert!(reconstruct_inter_block_warp(
            mi,
            &warp,
            &ref_frame_idx,
            &store,
            0,
            -4,
            0,
            8,
            8,
            8,
            0,
            0,
            32,
            32,
            EIGHTTAP,
            EIGHTTAP,
            &mut curr,
            32,
        )
        .is_err());
    }

    /// §7.11.3.1 step-7 ◦ 1 — `w < 8 || h < 8` forces `useWarp = 0`
    /// (translational fallback) even on `motion_mode == WARPED_CAUSAL`
    /// with a valid `local_warp_params`. The driver output must match
    /// the SIMPLE translational path.
    #[test]
    fn r202_predict_inter_use_warp_small_block_falls_back_to_translational() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r + c * 3) & 0xFF) as u16;
            }
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        let warp = WarpDriverParams {
            y_mode: [0, 0],
            gm_type: [0, 0],
            gm_params: [WARP_IDENTITY, WARP_IDENTITY],
            local_warp_params: WARP_IDENTITY,
            local_valid: true,
            ref_is_scaled: [false, false],
            force_integer_mv: false,
        };

        // w = 4 < 8 — step-7 ◦ 1 short-circuits to translational.
        let w = 4;
        let h = 4;
        let mut warp_out = vec![0u16; w * h];
        predict_inter(
            0,
            2,
            2,
            w,
            h,
            crate::cdf::MOTION_MODE_WARPED_CAUSAL,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            Some(&warp),
            /* obmc */ None,
            &mut warp_out,
        )
        .expect("WARP arm with w<8 must fall back to translational");

        // Equivalent SIMPLE call with no WarpDriverParams.
        let mut simple_out = vec![0u16; w * h];
        predict_inter(
            0,
            2,
            2,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            /* obmc */ None,
            &mut simple_out,
        )
        .expect("SIMPLE arm baseline");

        assert_eq!(
            warp_out, simple_out,
            "step-7 ◦ 1 (w/h < 8) must produce the SIMPLE translational output"
        );
    }

    /// §7.11.3.1 step-7 ◦ 2 — `force_integer_mv == 1` forces
    /// `useWarp = 0` regardless of motion_mode. Same shape as the
    /// w<8 test above.
    #[test]
    fn r202_predict_inter_force_integer_mv_disables_warp() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 5 + c * 3) & 0xFF) as u16;
            }
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        let warp_force_int = WarpDriverParams {
            y_mode: [0, 0],
            gm_type: [0, 0],
            gm_params: [WARP_IDENTITY, WARP_IDENTITY],
            local_warp_params: WARP_IDENTITY,
            local_valid: true,
            ref_is_scaled: [false, false],
            force_integer_mv: true,
        };

        let w = 8;
        let h = 8;
        let mut force_int_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_WARPED_CAUSAL,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            Some(&warp_force_int),
            /* obmc */ None,
            &mut force_int_out,
        )
        .expect("WARP arm with force_integer_mv must fall back to translational");

        let mut simple_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            /* obmc */ None,
            &mut simple_out,
        )
        .expect("SIMPLE arm baseline");

        assert_eq!(
            force_int_out, simple_out,
            "step-7 ◦ 2 (force_integer_mv) must produce SIMPLE translational output"
        );
    }

    /// §7.11.3.1 step-7 ◦ 3 negative path — LOCALWARP with
    /// `LocalValid == false` falls through to step-7 ◦ 5 (the bottom
    /// `useWarp = 0` branch) since the global-warp gate of ◦ 4 also
    /// can't fire (`GmType == IDENTITY`). The driver must produce the
    /// same output as a SIMPLE-mode call.
    #[test]
    fn r202_predict_inter_local_invalid_falls_back_to_translational() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 7 + c * 17) & 0xFF) as u16;
            }
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        // local_valid = false ⇒ step-7 ◦ 3 doesn't fire.
        let warp = WarpDriverParams {
            y_mode: [0, 0],
            gm_type: [crate::cdf::GM_TYPE_IDENTITY as u8, 0],
            gm_params: [WARP_IDENTITY, WARP_IDENTITY],
            local_warp_params: WARP_IDENTITY,
            local_valid: false,
            ref_is_scaled: [false, false],
            force_integer_mv: false,
        };

        let w = 8;
        let h = 8;
        let mut warp_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_WARPED_CAUSAL,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            Some(&warp),
            /* obmc */ None,
            &mut warp_out,
        )
        .expect("LOCALWARP+!LocalValid must fall back to translational");

        let mut simple_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            /* obmc */ None,
            &mut simple_out,
        )
        .expect("SIMPLE arm baseline");

        assert_eq!(warp_out, simple_out);
    }

    /// §7.11.3.1 step-7 ◦ 4 — the global-warp AND chain has four
    /// terms (y_mode in {GLOBALMV, GLOBAL_GLOBALMV}, gm_type >
    /// TRANSLATION, !is_scaled, globalValid). Flipping the
    /// `is_scaled` term blocks the dispatch (which would otherwise
    /// pick GLOBAL) and the driver falls back to translational.
    #[test]
    fn r202_predict_inter_global_blocked_by_is_scaled() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r + c) & 0xFF) as u16;
            }
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        let warp = WarpDriverParams {
            y_mode: [crate::cdf::MODE_GLOBAL_GLOBALMV, 0],
            gm_type: [crate::cdf::GM_TYPE_ROTZOOM as u8, 0],
            gm_params: [WARP_IDENTITY, WARP_IDENTITY],
            local_warp_params: WARP_IDENTITY,
            local_valid: false,
            ref_is_scaled: [true, false], // ⇐ blocks step-7 ◦ 4
            force_integer_mv: false,
        };

        let w = 8;
        let h = 8;
        let mut warp_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            Some(&warp),
            /* obmc */ None,
            &mut warp_out,
        )
        .expect("is_scaled must block step-7 ◦ 4");

        let mut simple_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            /* obmc */ None,
            &mut simple_out,
        )
        .expect("SIMPLE baseline");

        assert_eq!(warp_out, simple_out);
    }

    /// §7.11.3.1 step-3 — `setup_shear(LocalWarpParams)` must
    /// re-validate. A `LocalWarpParams` with `[2] == 0` (which
    /// `setup_shear` rejects via `resolve_divisor` returning `None`)
    /// must demote `effective_local_valid` to `false` and route the
    /// dispatch to translational fallback. This pins the step-3
    /// re-validation gate.
    #[test]
    fn r202_predict_inter_step3_shear_revalidates_localwarp() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let stride = ref_w;
        let refp = vec![0u16; ref_h * stride];
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        // LocalWarpParams with [2] = 0: resolve_divisor(0) ⇒ None ⇒
        // setup_shear ⇒ None ⇒ effective_local_valid = false.
        let bad_local = [0, 0, 0, 0, 0, 1 << 16];
        let warp = WarpDriverParams {
            y_mode: [0, 0],
            gm_type: [0, 0],
            gm_params: [WARP_IDENTITY, WARP_IDENTITY],
            local_warp_params: bad_local,
            // Caller claims local_valid=true, but step-3 must reject.
            local_valid: true,
            ref_is_scaled: [false, false],
            force_integer_mv: false,
        };

        let w = 8;
        let h = 8;
        let mut warp_out = vec![0u16; w * h];
        // Must not panic / error — the step-3 demotion turns the
        // LOCALWARP path into a translational fallback.
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_WARPED_CAUSAL,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            Some(&warp),
            /* obmc */ None,
            &mut warp_out,
        )
        .expect("step-3 must demote bad_local to translational fallback");

        // Output must match a SIMPLE-mode prediction on the same
        // zero-constant ref (which is identically zero post-clip).
        assert!(warp_out.iter().all(|&v| v == 0));
    }

    /// `derive_use_warp` truth table — pin the five cases of the
    /// step-7 decision tree. Helper-level test (the `derive_use_warp`
    /// signature is module-private).
    #[test]
    fn r202_derive_use_warp_truth_table() {
        // Case 1 — w < 8 ⇒ Translational regardless.
        assert_eq!(
            derive_use_warp(
                4,
                8,
                crate::cdf::MOTION_MODE_WARPED_CAUSAL,
                0,
                0,
                false,
                true,
                true,
                false
            ),
            UseWarpDecision::Translational
        );
        // Case 2 — force_integer_mv ⇒ Translational.
        assert_eq!(
            derive_use_warp(
                8,
                8,
                crate::cdf::MOTION_MODE_WARPED_CAUSAL,
                0,
                0,
                false,
                true,
                true,
                /* force_int */ true
            ),
            UseWarpDecision::Translational
        );
        // Case 3 — LOCALWARP + LocalValid ⇒ Local.
        assert_eq!(
            derive_use_warp(
                8,
                8,
                crate::cdf::MOTION_MODE_WARPED_CAUSAL,
                0,
                0,
                false,
                true,
                false,
                false
            ),
            UseWarpDecision::Local
        );
        // Case 4 — GLOBAL_GLOBALMV + GmType > TRANSLATION + !is_scaled
        //   + globalValid ⇒ Global.
        assert_eq!(
            derive_use_warp(
                8,
                8,
                crate::cdf::MOTION_MODE_SIMPLE,
                crate::cdf::MODE_GLOBAL_GLOBALMV,
                crate::cdf::GM_TYPE_ROTZOOM as u8,
                false,
                false,
                true,
                false
            ),
            UseWarpDecision::Global
        );
        // Case 4 negative — gm_type == TRANSLATION ⇒ Translational.
        assert_eq!(
            derive_use_warp(
                8,
                8,
                crate::cdf::MOTION_MODE_SIMPLE,
                crate::cdf::MODE_GLOBAL_GLOBALMV,
                crate::cdf::GM_TYPE_TRANSLATION as u8,
                false,
                false,
                true,
                false
            ),
            UseWarpDecision::Translational
        );
        // Case 4 negative — globalValid == false ⇒ Translational.
        assert_eq!(
            derive_use_warp(
                8,
                8,
                crate::cdf::MOTION_MODE_SIMPLE,
                crate::cdf::MODE_GLOBAL_GLOBALMV,
                crate::cdf::GM_TYPE_AFFINE as u8,
                false,
                false,
                false,
                false
            ),
            UseWarpDecision::Translational
        );
        // Case 5 — SIMPLE + no LOCALWARP + no global gate ⇒ Translational.
        assert_eq!(
            derive_use_warp(
                16,
                16,
                crate::cdf::MOTION_MODE_SIMPLE,
                crate::cdf::MODE_GLOBALMV,
                crate::cdf::GM_TYPE_TRANSLATION as u8,
                false,
                false,
                false,
                false
            ),
            UseWarpDecision::Translational
        );
    }

    // ---------- r203 §7.11.3.1 predict_inter OBMC arm ----------

    /// §7.11.3.9 OBMC arm — when both `above_neighbours` and
    /// `left_neighbours` lists are empty (the spec's `AvailU` or
    /// `AvailL` gate triggers but no qualifying `RefFrames[..][0] >
    /// INTRA_FRAME` neighbour exists), the post-step is a no-op and
    /// `pred_out` matches the SIMPLE single-ref translational
    /// prediction byte-for-byte.
    #[test]
    fn r203_predict_inter_obmc_no_neighbours_matches_simple() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 16 + c) & 0xff) as u16;
            }
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];

        let w = 8;
        let h = 8;
        let mut simple_out = vec![0u16; w * h];
        predict_inter(
            0,
            4,
            4,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            /* obmc */ None,
            &mut simple_out,
        )
        .expect("SIMPLE baseline");

        // OBMC with empty neighbour lists. AvailU/AvailL true so the
        // outer gates fire, but the inner walk exhausts before
        // visiting any qualifying neighbour.
        let obmc = ObmcParams {
            mi_row: 1,
            mi_col: 1,
            mi_cols: 8,
            mi_rows: 8,
            mi_width_log2: 1,
            mi_height_log2: 1,
            avail_u: true,
            avail_l: true,
            plane_residual_size_ge_block_8x8: true,
            above_neighbours: &[],
            left_neighbours: &[],
        };
        let mut obmc_out = vec![0u16; w * h];
        predict_inter(
            0,
            4,
            4,
            w,
            h,
            crate::cdf::MOTION_MODE_OBMC,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            Some(&obmc),
            &mut obmc_out,
        )
        .expect("OBMC with no neighbours");

        assert_eq!(
            simple_out, obmc_out,
            "OBMC with no qualifying neighbours must match SIMPLE translational"
        );
    }

    /// §7.11.3.9 OBMC arm — when `AvailU == false && AvailL ==
    /// false` both passes are gated off (no §7.11.3.10 invocation),
    /// matching the SIMPLE translational prediction.
    #[test]
    fn r203_predict_inter_obmc_unavailable_neighbours_noops() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let mut refp = vec![0u16; ref_w * ref_h];
        for v in refp.iter_mut().enumerate() {
            *v.1 = (v.0 & 0xff) as u16;
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];

        let w = 8;
        let h = 8;
        let mut simple_out = vec![0u16; w * h];
        predict_inter(
            0,
            4,
            4,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            /* obmc */ None,
            &mut simple_out,
        )
        .unwrap();

        // The neighbour-bundle below would normally contribute, but
        // AvailU == false && AvailL == false short-circuits both
        // outer gates per av1-spec p.275 lines 15301 / 15325.
        let nb = ObmcNeighbour {
            bundle: refs[0],
            step4: 2,
            interp_filter_x: EIGHTTAP,
            interp_filter_y: EIGHTTAP,
            axis_pos4: 2,
        };
        let obmc = ObmcParams {
            mi_row: 1,
            mi_col: 1,
            mi_cols: 8,
            mi_rows: 8,
            mi_width_log2: 1,
            mi_height_log2: 1,
            avail_u: false,
            avail_l: false,
            plane_residual_size_ge_block_8x8: true,
            above_neighbours: &[nb],
            left_neighbours: &[nb],
        };
        let mut obmc_out = vec![0u16; w * h];
        predict_inter(
            0,
            4,
            4,
            w,
            h,
            crate::cdf::MOTION_MODE_OBMC,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            Some(&obmc),
            &mut obmc_out,
        )
        .unwrap();

        assert_eq!(simple_out, obmc_out);
    }

    /// §7.11.3.9 above-pass with an identical neighbour (same ref +
    /// same MV) — the blend `Round2(m*curr + (64 - m)*obmc, 6)` with
    /// `curr == obmc` reduces to `Round2(64 * curr, 6) = curr`, so
    /// the result is byte-identical to SIMPLE translational. This
    /// pins the above-pass blend kernel without depending on
    /// reference samples that exercise off-by-one.
    #[test]
    fn r203_predict_inter_obmc_identical_above_neighbour_idempotent() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let mut refp = vec![0u16; ref_w * ref_h];
        for (i, v) in refp.iter_mut().enumerate() {
            *v = ((i * 7) & 0xff) as u16;
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];

        // Block at plane coords (x=8, y=8) ⇒ MiRow = MiCol = 2.
        let w = 8;
        let h = 8;
        let mut simple_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            /* obmc */ None,
            &mut simple_out,
        )
        .unwrap();

        // One qualifying above-row neighbour with identical ref +
        // identical MV; step4 = 2 covers the first half of the
        // 8-sample-wide block. Identity property of the blend.
        let above_nb = ObmcNeighbour {
            bundle: refs[0],
            step4: 2,
            interp_filter_x: EIGHTTAP,
            interp_filter_y: EIGHTTAP,
            axis_pos4: 2,
        };
        let obmc = ObmcParams {
            mi_row: 2,
            mi_col: 2,
            mi_cols: 8,
            mi_rows: 8,
            mi_width_log2: 1,
            mi_height_log2: 1,
            avail_u: true,
            avail_l: false,
            plane_residual_size_ge_block_8x8: true,
            above_neighbours: &[above_nb],
            left_neighbours: &[],
        };
        let mut obmc_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_OBMC,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            Some(&obmc),
            &mut obmc_out,
        )
        .unwrap();

        // Identity property: Round2(64 * curr, 6) = curr exactly.
        assert_eq!(
            simple_out, obmc_out,
            "identical-neighbour OBMC blend must be identity"
        );
    }

    /// §7.11.3.9 left-pass with an identical neighbour — same
    /// identity property as above, but exercising the left-pass
    /// `mask[j]` axis (vs above-pass `mask[i]`).
    #[test]
    fn r203_predict_inter_obmc_identical_left_neighbour_idempotent() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let mut refp = vec![0u16; ref_w * ref_h];
        for (i, v) in refp.iter_mut().enumerate() {
            *v = ((i * 11) & 0xff) as u16;
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];

        let w = 8;
        let h = 8;
        let mut simple_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            /* obmc */ None,
            &mut simple_out,
        )
        .unwrap();

        let left_nb = ObmcNeighbour {
            bundle: refs[0],
            step4: 2,
            interp_filter_x: EIGHTTAP,
            interp_filter_y: EIGHTTAP,
            axis_pos4: 2,
        };
        let obmc = ObmcParams {
            mi_row: 2,
            mi_col: 2,
            mi_cols: 8,
            mi_rows: 8,
            mi_width_log2: 1,
            mi_height_log2: 1,
            avail_u: false,
            avail_l: true,
            plane_residual_size_ge_block_8x8: true,
            above_neighbours: &[],
            left_neighbours: &[left_nb],
        };
        let mut obmc_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_OBMC,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            Some(&obmc),
            &mut obmc_out,
        )
        .unwrap();

        assert_eq!(simple_out, obmc_out);
    }

    /// §7.11.3.9 above-pass with a *different* neighbour MV — the
    /// overlap region (top half of the block) must change vs.
    /// SIMPLE, while the non-overlap region (bottom half) must
    /// match SIMPLE byte-for-byte (the blend only writes rows 0..predH).
    /// For w=h=8, subY=0: predH = min(8 >> 1, 32) = 4. The bottom
    /// 4 rows are outside any blend.
    #[test]
    fn r203_predict_inter_obmc_above_modifies_top_half_only() {
        let ref_w: usize = 48;
        let ref_h: usize = 48;
        let mut refp = vec![0u16; ref_w * ref_h];
        for (i, v) in refp.iter_mut().enumerate() {
            *v = ((i * 3) & 0xff) as u16;
        }

        let curr_ref = PredictInterRef {
            ref_plane: &refp,
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        };
        let refs = [curr_ref];

        let w = 8;
        let h = 8;
        let bx = 8;
        let by = 8;

        let mut simple_out = vec![0u16; w * h];
        predict_inter(
            0,
            bx,
            by,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            /* obmc */ None,
            &mut simple_out,
        )
        .unwrap();

        // Neighbour with the same ref-plane buffer but a non-zero
        // integer-aligned MV (mv_row = 8 ⇒ 1 luma sample). This
        // changes the neighbour's translational MC vs. the current
        // block's prediction so the blend has a real effect.
        let nb_ref = PredictInterRef {
            ref_plane: &refp,
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [8, 0],
        };
        let above_nb = ObmcNeighbour {
            bundle: nb_ref,
            step4: 2,
            interp_filter_x: EIGHTTAP,
            interp_filter_y: EIGHTTAP,
            axis_pos4: 2,
        };
        let obmc = ObmcParams {
            mi_row: 2,
            mi_col: 2,
            mi_cols: 16,
            mi_rows: 16,
            mi_width_log2: 1,
            mi_height_log2: 1,
            avail_u: true,
            avail_l: false,
            plane_residual_size_ge_block_8x8: true,
            above_neighbours: &[above_nb],
            left_neighbours: &[],
        };
        let mut obmc_out = vec![0u16; w * h];
        predict_inter(
            0,
            bx,
            by,
            w,
            h,
            crate::cdf::MOTION_MODE_OBMC,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            Some(&obmc),
            &mut obmc_out,
        )
        .unwrap();

        // Above-pass predH = h >> 1 = 4. Rows 4..8 are outside any
        // blend (no left-pass either), so they must match SIMPLE
        // byte-for-byte.
        for row in 4..h {
            for col in 0..w {
                assert_eq!(
                    simple_out[row * w + col],
                    obmc_out[row * w + col],
                    "row {row} col {col} below the above-pass extent must equal SIMPLE"
                );
            }
        }

        // The blend region top-half must differ from SIMPLE because
        // the neighbour's MV is non-zero — at least one cell of rows
        // 0..4 changes.
        let differs = (0..4)
            .any(|row| (0..w).any(|col| simple_out[row * w + col] != obmc_out[row * w + col]));
        assert!(
            differs,
            "above-pass with a different MV must change the top half"
        );
    }

    /// §7.11.3.9 above-pass small-block carve-out — when
    /// `plane_residual_size_ge_block_8x8 == false`, the above-pass
    /// gate at av1-spec p.275 line 15302 fails and only the
    /// left-pass runs. With `avail_l == false` too, the OBMC arm
    /// becomes a no-op even when above_neighbours is non-empty.
    #[test]
    fn r203_predict_inter_obmc_above_gated_by_plane_residual_size() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let mut refp = vec![0u16; ref_w * ref_h];
        for (i, v) in refp.iter_mut().enumerate() {
            *v = ((i * 5) & 0xff) as u16;
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];

        let w = 8;
        let h = 8;
        let mut simple_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            /* obmc */ None,
            &mut simple_out,
        )
        .unwrap();

        // Non-zero-MV neighbour that *would* change pred_out if the
        // above-pass were to fire. With
        // `plane_residual_size_ge_block_8x8 == false` it doesn't.
        let nb_ref = PredictInterRef {
            ref_plane: &refp,
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [16, 0],
        };
        let above_nb = ObmcNeighbour {
            bundle: nb_ref,
            step4: 2,
            interp_filter_x: EIGHTTAP,
            interp_filter_y: EIGHTTAP,
            axis_pos4: 2,
        };
        let obmc = ObmcParams {
            mi_row: 2,
            mi_col: 2,
            mi_cols: 8,
            mi_rows: 8,
            mi_width_log2: 1,
            mi_height_log2: 1,
            avail_u: true,
            avail_l: false,
            plane_residual_size_ge_block_8x8: false,
            above_neighbours: &[above_nb],
            left_neighbours: &[],
        };
        let mut obmc_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_OBMC,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            Some(&obmc),
            &mut obmc_out,
        )
        .unwrap();

        assert_eq!(
            simple_out, obmc_out,
            "above-pass must be gated off when plane_residual_size < BLOCK_8X8"
        );
    }

    /// §7.11.3.9 `nLimit = Min(4, Mi_Width_Log2[ MiSize ])` — the
    /// driver must cap the neighbour walk at `nLimit`. With
    /// `mi_width_log2 = 0` (BLOCK_4X4 width), `nLimit = 0`, so no
    /// neighbours are visited regardless of the slice length. The
    /// output must match SIMPLE byte-for-byte.
    #[test]
    fn r203_predict_inter_obmc_n_limit_caps_above_walk() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let mut refp = vec![0u16; ref_w * ref_h];
        for (i, v) in refp.iter_mut().enumerate() {
            *v = ((i * 13) & 0xff) as u16;
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];

        // 4-wide block (w = 4). `nLimit` reads `Mi_Width_Log2[
        // BLOCK_4X*]` which is 0, so nLimit = Min(4, 0) = 0; the
        // walk does not enter the loop body.
        let w = 4;
        let h = 8;
        let bx = 8;
        let by = 8;

        let mut simple_out = vec![0u16; w * h];
        predict_inter(
            0,
            bx,
            by,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            /* obmc */ None,
            &mut simple_out,
        )
        .unwrap();

        // Would-be-effective neighbour — but the nLimit = 0 cap
        // means the driver doesn't visit it.
        let nb_ref = PredictInterRef {
            ref_plane: &refp,
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [8, 0],
        };
        let above_nb = ObmcNeighbour {
            bundle: nb_ref,
            step4: 2,
            interp_filter_x: EIGHTTAP,
            interp_filter_y: EIGHTTAP,
            axis_pos4: 2,
        };
        let obmc = ObmcParams {
            mi_row: 2,
            mi_col: 2,
            mi_cols: 8,
            mi_rows: 8,
            // mi_width_log2 = 0 ⇒ nLimit = 0.
            mi_width_log2: 0,
            mi_height_log2: 0,
            avail_u: true,
            avail_l: false,
            plane_residual_size_ge_block_8x8: true,
            above_neighbours: &[above_nb],
            left_neighbours: &[],
        };
        let mut obmc_out = vec![0u16; w * h];
        predict_inter(
            0,
            bx,
            by,
            w,
            h,
            crate::cdf::MOTION_MODE_OBMC,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            Some(&obmc),
            &mut obmc_out,
        )
        .unwrap();

        assert_eq!(simple_out, obmc_out);
    }

    /// §7.11.3.9 multi-neighbour above-pass — two ordered neighbours
    /// with `step4 = 2` each, visiting the left half and right half
    /// of a 16-wide block in turn. With both neighbours identical to
    /// the current MV, the blend is identity on both halves; this
    /// pins that the driver iterates more than one neighbour per
    /// axis correctly. For BLOCK_16X16: `mi_width_log2 = 2 ⇒ w4 =
    /// 4`, `nLimit = Min(4, 2) = 2`, so both neighbours are visited
    /// (axis_pos walks `MiCol`, `MiCol + 2`, then halts at `MiCol +
    /// 4 = MiCol + w4`).
    #[test]
    fn r203_predict_inter_obmc_multi_above_neighbours_walk_correctly() {
        let ref_w: usize = 32;
        let ref_h: usize = 32;
        let mut refp = vec![0u16; ref_w * ref_h];
        for (i, v) in refp.iter_mut().enumerate() {
            *v = ((i * 17) & 0xff) as u16;
        }
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: ref_w,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];

        // BLOCK_16X16: w = h = 16, block top-left at plane (8, 8)
        // ⇒ MiRow = MiCol = 2.
        let w = 16;
        let h = 16;
        let mut simple_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            /* obmc */ None,
            &mut simple_out,
        )
        .unwrap();

        let nb = ObmcNeighbour {
            bundle: refs[0],
            step4: 2,
            interp_filter_x: EIGHTTAP,
            interp_filter_y: EIGHTTAP,
            axis_pos4: 2,
        };
        let nb2 = ObmcNeighbour { axis_pos4: 4, ..nb };
        // BLOCK_16X16: mi_width_log2 = 2 ⇒ w4 = 4, nLimit = Min(4, 2)
        // = 2. The walk visits x4 = MiCol (2), then x4 + 2 (4), then
        // stops because x4 + 2 = 6 == MiCol + w4 = 6 fails the
        // strict-less-than bound (Min(MiCols, MiCol + w4) = 6). The
        // resolved list carries those positions per neighbour.
        let obmc = ObmcParams {
            mi_row: 2,
            mi_col: 2,
            mi_cols: 8,
            mi_rows: 8,
            mi_width_log2: 2,
            mi_height_log2: 2,
            avail_u: true,
            avail_l: false,
            plane_residual_size_ge_block_8x8: true,
            above_neighbours: &[nb, nb2],
            left_neighbours: &[],
        };
        let mut obmc_out = vec![0u16; w * h];
        predict_inter(
            0,
            8,
            8,
            w,
            h,
            crate::cdf::MOTION_MODE_OBMC,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            /* inter_intra */ None,
            None,
            Some(&obmc),
            &mut obmc_out,
        )
        .unwrap();

        // Both neighbours produce identity blends ⇒ output equals SIMPLE.
        assert_eq!(simple_out, obmc_out);
    }

    // ---------- r355 §7.11.3.1 reconstruct_inter_block_obmc driver ----------

    /// §7.11.3.1 OBMC per-block driver
    /// ([`reconstruct_inter_block_obmc`]): the driver must resolve
    /// `refIdx = ref_frame_idx[ RefFrame[0] - LAST_FRAME ]` →
    /// `FrameStore[ refIdx ]`, run the §7.11.3.9-10 OBMC composition, and
    /// stitch the `w × h` block into `curr_plane` at plane `(x, y)` —
    /// byte-for-byte identical to a direct `predict_inter` OBMC call into a
    /// scratch buffer copied to the same `(x, y)` window.
    #[test]
    fn r355_reconstruct_inter_block_obmc_matches_predict_inter() {
        let ref_w: usize = 48;
        let ref_h: usize = 48;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 9 + c * 5 + 1) & 0xFF) as u16;
            }
        }
        let entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [entry, entry, entry, entry];
        // Map LAST_FRAME (RefFrame 1) → ref_frame_idx slot 0 → FrameStore 2
        // so the driver's §7.11.3.3 indirection is actually exercised.
        let ref_frame_idx: [u8; 7] = [2, 1, 3, 0, 0, 1, 2];
        let last = crate::uncompressed_header_tail::LAST_FRAME as u8;

        let w = 8usize;
        let h = 8usize;
        let (bx, by) = (8i32, 8i32);
        let mode_info = InterModeInfo {
            ref_frame: last,
            mv: [0, 0],
        };

        // Build the same ObmcParams the driver consumes: one distinct-MV
        // above neighbour resolved against the same FrameStore entry.
        let nb_bundle = PredictInterRef {
            ref_plane: &refp[..],
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [8, 0],
        };
        let above_nb = ObmcNeighbour {
            bundle: nb_bundle,
            step4: 2,
            interp_filter_x: EIGHTTAP,
            interp_filter_y: EIGHTTAP,
            axis_pos4: 2,
        };
        let obmc = ObmcParams {
            mi_row: 2,
            mi_col: 2,
            mi_cols: 16,
            mi_rows: 16,
            mi_width_log2: 1,
            mi_height_log2: 1,
            avail_u: true,
            avail_l: false,
            plane_residual_size_ge_block_8x8: true,
            above_neighbours: &[above_nb],
            left_neighbours: &[],
        };

        // Direct predict_inter OBMC oracle into a w×h scratch (the block's
        // own ref is FrameStore[2] = same buffer, mv [0,0]).
        let own = [PredictInterRef {
            ref_plane: &refp[..],
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv: [0, 0],
        }];
        let mut scratch = vec![0u16; w * h];
        predict_inter(
            0,
            bx,
            by,
            w,
            h,
            crate::cdf::MOTION_MODE_OBMC,
            false,
            false,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &own,
            None,
            /* inter_intra */ None,
            None,
            Some(&obmc),
            &mut scratch,
        )
        .unwrap();

        // Driver into a 16×16 plane; the block stitches at (8, 8).
        let plane_stride = 16usize;
        let mut plane = vec![0u16; plane_stride * 16];
        reconstruct_inter_block_obmc(
            mode_info,
            &obmc,
            &ref_frame_idx,
            &store,
            0,
            bx,
            by,
            w,
            h,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &mut plane,
            plane_stride,
        )
        .unwrap();

        for i in 0..h {
            for j in 0..w {
                assert_eq!(
                    plane[(by as usize + i) * plane_stride + (bx as usize + j)],
                    scratch[i * w + j],
                    "driver row {i} col {j} must match the predict_inter OBMC oracle"
                );
            }
        }
    }

    /// §7.11.3.1 OBMC driver guards: `RefFrame[0] == INTRA_FRAME` (0) is a
    /// caller bug surfaced as [`crate::Error::PartitionWalkOutOfRange`].
    #[test]
    fn r355_reconstruct_inter_block_obmc_rejects_intra_ref() {
        let refp = vec![5u16; 16 * 16];
        let entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride: 16,
            upscaled_width: 16,
            width: 16,
            height: 16,
        };
        let store = [entry, entry, entry, entry];
        let ref_frame_idx: [u8; 7] = [0, 1, 2, 3, 0, 1, 2];
        let obmc = ObmcParams {
            mi_row: 0,
            mi_col: 0,
            mi_cols: 4,
            mi_rows: 4,
            mi_width_log2: 1,
            mi_height_log2: 1,
            avail_u: false,
            avail_l: false,
            plane_residual_size_ge_block_8x8: true,
            above_neighbours: &[],
            left_neighbours: &[],
        };
        let mut plane = vec![0u16; 16 * 16];
        let intra_ref = crate::uncompressed_header_tail::INTRA_FRAME as u8; // 0
        assert!(matches!(
            reconstruct_inter_block_obmc(
                InterModeInfo {
                    ref_frame: intra_ref,
                    mv: [0, 0],
                },
                &obmc,
                &ref_frame_idx,
                &store,
                0,
                0,
                0,
                8,
                8,
                8,
                0,
                0,
                16,
                16,
                EIGHTTAP,
                EIGHTTAP,
                &mut plane,
                16,
            ),
            Err(crate::Error::PartitionWalkOutOfRange)
        ));
    }

    // ---------- r299 §5.11.33 inter-intra frame-walk leaf ----------

    /// §7.11.3.1 inter-intra per-block driver
    /// ([`reconstruct_inter_block_interintra`], non-wedge arm): the driver
    /// must reproduce exactly the `predict_inter` (`is_inter_intra ==
    /// true`) composition over the same in-place intra seed. We seed
    /// `curr` with a ramp (the §7.11.2 intra prediction the dispatcher
    /// already wrote), drive the per-block leaf, and cross-check against a
    /// direct `predict_inter` call on a copy of that seed.
    #[test]
    fn r299_reconstruct_inter_block_interintra_matches_predict_inter() {
        let ref_w: usize = 24;
        let ref_h: usize = 24;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 9 + c * 5) & 0xFF) as u16;
            }
        }
        let entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [entry, entry, entry, entry];
        let ref_frame_idx: [u8; 7] = [0, 1, 2, 3, 0, 1, 2];
        let last = crate::uncompressed_header_tail::LAST_FRAME as u8;

        let w = 8usize;
        let h = 8usize;
        let bit_depth = 8u8;
        let mv = [4i16, 2];
        let ii_mode = II_SMOOTH_PRED;

        // CurrFrame already holds the §7.11.2 intra prediction; the block
        // sits at plane coords (4, 4) inside a larger plane buffer.
        let curr_w = 16usize;
        let curr_h = 16usize;
        let (px, py) = (4usize, 4usize);
        let mut curr = vec![0u16; curr_w * curr_h];
        for i in 0..h {
            for j in 0..w {
                curr[(py + i) * curr_w + (px + j)] = ((i * 7 + j * 3 + 11) & 0xFF) as u16;
            }
        }
        let intra_window: Vec<u16> = (0..h)
            .flat_map(|i| (0..w).map(move |j| ((i * 7 + j * 3 + 11) & 0xFF) as u16))
            .collect();

        reconstruct_inter_block_interintra(
            InterIntraModeInfo {
                ref_frame: last,
                mv,
                interintra_mode: ii_mode,
                wedge: None,
            },
            &ref_frame_idx,
            &store,
            /* plane */ 0,
            px as i32,
            py as i32,
            w,
            h,
            bit_depth,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            /* wedge_mask_buf */ None,
            /* warp */ None,
            &mut curr,
            curr_w,
        )
        .expect("inter-intra per-block driver");

        // Oracle: `predict_inter` over a copy of the intra window.
        let refs = [PredictInterRef {
            ref_plane: &refp,
            ref_stride: stride,
            ref_upscaled_width: ref_w as u32,
            ref_width: ref_w as u32,
            ref_height: ref_h as u32,
            mv,
        }];
        let mut oracle = intra_window.clone();
        predict_inter(
            0,
            px as i32,
            py as i32,
            w,
            h,
            crate::cdf::MOTION_MODE_SIMPLE,
            false,
            /* is_inter_intra */ true,
            bit_depth,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            &refs,
            None,
            Some(InterIntraParams {
                interintra_mode: ii_mode,
                wedge: None,
            }),
            None,
            None,
            &mut oracle,
        )
        .unwrap();

        // Stitch the oracle window back and compare the whole plane.
        let mut expected = vec![0u16; curr_w * curr_h];
        for i in 0..h {
            for j in 0..w {
                expected[(py + i) * curr_w + (px + j)] = ((i * 7 + j * 3 + 11) & 0xFF) as u16;
            }
        }
        for i in 0..h {
            for j in 0..w {
                expected[(py + i) * curr_w + (px + j)] = oracle[i * w + j];
            }
        }
        assert_eq!(curr, expected);
        // The blend actually moved the buffer off the intra seed.
        assert_ne!(
            &curr[(py) * curr_w + px..(py) * curr_w + px + w],
            &intra_window[..w]
        );
    }

    /// §5.11.33 frame walk: one inter-intra `BLOCK_8X8` leaf
    /// (`RefFrame[1] == INTRA_FRAME`) must be driven identically to the
    /// per-block [`reconstruct_inter_block_interintra`] driver. The intra
    /// prediction is pre-seeded into `curr` (the §7.11.3.14 body reads it
    /// in place); both the walk and the oracle start from the same seed.
    #[test]
    fn r299_frame_walk_drives_interintra_leaf_like_per_block() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 13 + c * 7) & 0xFF) as u16;
            }
        }
        let entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [entry, entry, entry, entry];
        let store2 = store;
        let ref_frame_idx: [u8; 7] = [0, 1, 2, 3, 0, 1, 2];
        let last = crate::uncompressed_header_tail::LAST_FRAME as i8;
        let intra_frame = crate::uncompressed_header_tail::INTRA_FRAME as i8;

        let mi_rows: u32 = 2;
        let mi_cols: u32 = 2;
        let cells = (mi_rows * mi_cols) as usize;
        const BLOCK_8X8: usize = 3;
        use crate::cdf::BLOCK_INVALID;
        let mut mi_sizes = vec![BLOCK_INVALID; cells];
        mi_sizes[0] = BLOCK_8X8;
        let mut is_inters = vec![0u8; cells];
        is_inters[0] = 1;
        let mut ref_frames = vec![0i8; cells * 2];
        for cell in 0..cells {
            ref_frames[cell * 2 + 1] = -1;
        }
        ref_frames[0] = last;
        ref_frames[1] = intra_frame; // RefFrame[1] == INTRA_FRAME.
        let mv = [4i16, 6];
        let mut mvs = vec![0i16; cells * 4];
        mvs[0] = mv[0];
        mvs[1] = mv[1];
        let interp_filters = vec![EIGHTTAP; cells * 2];
        let compound_types = vec![COMPOUND_AVERAGE; cells];
        let zeros = vec![0u8; cells];
        let ii_mode = II_H_PRED;
        let mut interintra_modes = vec![0u8; cells];
        interintra_modes[0] = ii_mode;

        let curr_w = (mi_cols * 4) as usize; // 8
        let curr_h = (mi_rows * 4) as usize; // 8
                                             // Pre-seed the §7.11.2 intra prediction for the leaf footprint.
        let mut curr = vec![0u16; curr_w * curr_h];
        for i in 0..8usize {
            for j in 0..8usize {
                curr[i * curr_w + j] = ((i * 5 + j * 11 + 3) & 0xFF) as u16;
            }
        }
        let seed = curr.clone();
        let order_hints_by_ref = [0i32; 8];

        let grid = InterModeInfoGrid {
            mi_sizes: &mi_sizes,
            is_inters: &is_inters,
            ref_frames: &ref_frames,
            mvs: &mvs,
            interp_filters: &interp_filters,
            compound_types: &compound_types,
            wedge_indices: &zeros,
            wedge_signs: &zeros,
            mask_types: &zeros,
            interintra_modes: &interintra_modes,
            wedge_interintras: &zeros,
            interintra_wedge_indices: &zeros,
            order_hint_bits: 7,
            current_order_hint: 0,
            order_hints_by_ref: &order_hints_by_ref,
            mi_rows,
            mi_cols,
            bit_depth: 8,
            warp: None,
            obmc: None,
        };
        {
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut curr,
                curr_stride: curr_w,
            }];
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes)
                .expect("frame-level inter-intra reconstruction");
        }

        // Oracle: per-block driver on the same seed.
        let mut oracle = seed.clone();
        reconstruct_inter_block_interintra(
            InterIntraModeInfo {
                ref_frame: last as u8,
                mv,
                interintra_mode: ii_mode,
                wedge: None,
            },
            &ref_frame_idx,
            &store2,
            0,
            0,
            0,
            8,
            8,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            None,
            /* warp */ None,
            &mut oracle,
            curr_w,
        )
        .unwrap();

        assert_eq!(
            curr, oracle,
            "frame walk must drive the inter-intra leaf identically to the per-block driver"
        );
        assert_ne!(curr, seed, "the inter-intra blend must modify the plane");
    }

    /// §5.11.33 frame walk: a `wedge_interintra == 1` inter-intra leaf
    /// regenerates the §7.11.3.11 luma-grid wedge mask (with `wedge_sign
    /// == 0`) and must differ from the non-wedge intra-variant blend on
    /// the same seed.
    #[test]
    fn r299_frame_walk_interintra_wedge_differs_from_non_wedge() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 11 + c * 5) & 0xFF) as u16;
            }
        }
        let entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [entry, entry, entry, entry];
        let ref_frame_idx: [u8; 7] = [0, 1, 2, 3, 0, 1, 2];
        let last = crate::uncompressed_header_tail::LAST_FRAME as i8;
        let intra_frame = crate::uncompressed_header_tail::INTRA_FRAME as i8;

        let mi_rows: u32 = 2;
        let mi_cols: u32 = 2;
        let cells = (mi_rows * mi_cols) as usize;
        const BLOCK_8X8: usize = 3;
        use crate::cdf::BLOCK_INVALID;
        let mut mi_sizes = vec![BLOCK_INVALID; cells];
        mi_sizes[0] = BLOCK_8X8;
        let mut is_inters = vec![0u8; cells];
        is_inters[0] = 1;
        let mut ref_frames = vec![0i8; cells * 2];
        for cell in 0..cells {
            ref_frames[cell * 2 + 1] = -1;
        }
        ref_frames[0] = last;
        ref_frames[1] = intra_frame;
        let mv = [2i16, 2];
        let mut mvs = vec![0i16; cells * 4];
        mvs[0] = mv[0];
        mvs[1] = mv[1];
        let interp_filters = vec![EIGHTTAP; cells * 2];
        let compound_types = vec![COMPOUND_AVERAGE; cells];
        let zeros = vec![0u8; cells];
        let ii_mode = II_DC_PRED;
        let mut interintra_modes = vec![0u8; cells];
        interintra_modes[0] = ii_mode;
        let mut wedge_interintras = vec![0u8; cells];
        let mut interintra_wedge_indices = vec![0u8; cells];
        interintra_wedge_indices[0] = 5;

        let curr_w = (mi_cols * 4) as usize;
        let curr_h = (mi_rows * 4) as usize;
        let mut seed = vec![0u16; curr_w * curr_h];
        for i in 0..8usize {
            for j in 0..8usize {
                seed[i * curr_w + j] = ((i * 5 + j * 11 + 3) & 0xFF) as u16;
            }
        }
        let order_hints_by_ref = [0i32; 8];
        // `wedge_interintras` already declared as all-zero; the wedge run
        // flips cell 0 to 1.
        let wii_non_wedge = wedge_interintras.clone();
        wedge_interintras[0] = 1;
        let wii_wedge = wedge_interintras.clone();

        // Non-wedge run.
        let mut non_wedge = seed.clone();
        {
            let grid = InterModeInfoGrid {
                mi_sizes: &mi_sizes,
                is_inters: &is_inters,
                ref_frames: &ref_frames,
                mvs: &mvs,
                interp_filters: &interp_filters,
                compound_types: &compound_types,
                wedge_indices: &zeros,
                wedge_signs: &zeros,
                mask_types: &zeros,
                interintra_modes: &interintra_modes,
                wedge_interintras: &wii_non_wedge,
                interintra_wedge_indices: &interintra_wedge_indices,
                order_hint_bits: 7,
                current_order_hint: 0,
                order_hints_by_ref: &order_hints_by_ref,
                mi_rows,
                mi_cols,
                bit_depth: 8,
                warp: None,
                obmc: None,
            };
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut non_wedge,
                curr_stride: curr_w,
            }];
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes).unwrap();
        }

        // Wedge run (same seed, wedge_interintra == 1).
        let mut wedge = seed.clone();
        {
            let grid = InterModeInfoGrid {
                mi_sizes: &mi_sizes,
                is_inters: &is_inters,
                ref_frames: &ref_frames,
                mvs: &mvs,
                interp_filters: &interp_filters,
                compound_types: &compound_types,
                wedge_indices: &zeros,
                wedge_signs: &zeros,
                mask_types: &zeros,
                interintra_modes: &interintra_modes,
                wedge_interintras: &wii_wedge,
                interintra_wedge_indices: &interintra_wedge_indices,
                order_hint_bits: 7,
                current_order_hint: 0,
                order_hints_by_ref: &order_hints_by_ref,
                mi_rows,
                mi_cols,
                bit_depth: 8,
                warp: None,
                obmc: None,
            };
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut wedge,
                curr_stride: curr_w,
            }];
            reconstruct_inter_frame(&grid, &ref_frame_idx, &mut planes).unwrap();
        }

        assert_ne!(
            non_wedge, seed,
            "non-wedge interintra blend must modify the plane"
        );
        assert_ne!(wedge, seed, "wedge interintra blend must modify the plane");
        assert_ne!(
            wedge, non_wedge,
            "the §7.11.3.11 wedge mask must produce a different blend from the §7.11.3.13 mask"
        );
    }

    /// r301 §5.11.33 task-dispatcher → reconstruction bridge: a dispatcher
    /// readout (`is_inter_intra == true`, one intra-half task per plane)
    /// threaded through [`reconstruct_inter_intra_from_dispatch`] must drive
    /// the §7.11.3.14 blend byte-for-byte identically to both the
    /// per-block [`reconstruct_inter_block_interintra`] driver and the
    /// §5.11.33 frame-walk — proving the two paths share one driver.
    #[test]
    fn r301_dispatch_bridge_drives_interintra_like_frame_walk() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let stride = ref_w;
        let mut refp = vec![0u16; ref_h * stride];
        for r in 0..ref_h {
            for c in 0..ref_w {
                refp[r * stride + c] = ((r * 13 + c * 7) & 0xFF) as u16;
            }
        }
        let entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [entry, entry, entry, entry];
        let ref_frame_idx: [u8; 7] = [0, 1, 2, 3, 0, 1, 2];
        let last = crate::uncompressed_header_tail::LAST_FRAME as u8;

        const BLOCK_8X8: usize = 3;
        let ii_mode = II_H_PRED;
        let mv = [4i16, 6];
        let curr_w = 8usize;
        let curr_h = 8usize;
        let mut seed = vec![0u16; curr_w * curr_h];
        for i in 0..curr_h {
            for j in 0..curr_w {
                seed[i * curr_w + j] = ((i * 5 + j * 11 + 3) & 0xFF) as u16;
            }
        }

        let leaf = InterIntraLeaf {
            mode_info: InterIntraModeInfo {
                ref_frame: last,
                mv,
                interintra_mode: ii_mode,
                wedge: None,
            },
            mi_size: BLOCK_8X8,
            mi_row: 0,
            mi_col: 0,
            interp_filter_x: EIGHTTAP,
            interp_filter_y: EIGHTTAP,
        };

        // Oracle: the per-block driver on the seed.
        let mut oracle = seed.clone();
        reconstruct_inter_block_interintra(
            leaf.mode_info,
            &ref_frame_idx,
            &store,
            0,
            0,
            0,
            8,
            8,
            8,
            0,
            0,
            ref_w as u32,
            ref_h as u32,
            EIGHTTAP,
            EIGHTTAP,
            None,
            /* warp */ None,
            &mut oracle,
            curr_w,
        )
        .unwrap();

        // The dispatcher's emitted readout for the same block: the
        // §5.11.33 `IsInterIntra` arm emits one intra-half task per plane
        // (mode == II_H_PRED → H_PRED) ahead of the inter tasks. Here the
        // block is luma-only (one plane). `start_*` / `log2_*` mirror the
        // §5.11.33 plane-0 geometry.
        let readout = crate::cdf::ComputePredictionReadout {
            is_inter_intra: true,
            is_inter: true,
            num_planes_visited: 1,
            tasks: vec![crate::cdf::PlanePredictionTask {
                plane: 0,
                start_x: 0,
                start_y: 0,
                log2_w: 3,
                log2_h: 3,
                mode: crate::cdf::H_PRED as u8, // II_H_PRED → H_PRED
                have_left: false,
                have_above: false,
            }],
        };

        let mut bridged = seed.clone();
        {
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut bridged,
                curr_stride: curr_w,
            }];
            reconstruct_inter_intra_from_dispatch(
                &readout,
                &leaf,
                &ref_frame_idx,
                8,
                None,
                &mut planes,
            )
            .expect("dispatch-bridge inter-intra reconstruction");
        }

        assert_eq!(
            bridged, oracle,
            "the dispatch bridge must drive the shared inter-intra driver identically to the per-block driver"
        );
        assert_ne!(bridged, seed, "the inter-intra blend must modify the plane");
    }

    /// r301 dispatch-bridge guards: a non-inter-intra readout, a plane
    /// coverage shorter than the supplied planes, and a readout whose
    /// intra-half mode disagrees with the leaf's `interintra_mode` are all
    /// caller bugs.
    #[test]
    fn r301_dispatch_bridge_rejects_inconsistent_readout() {
        let ref_w: usize = 16;
        let ref_h: usize = 16;
        let refp = vec![7u16; ref_h * ref_w];
        let entry = RefFrameStoreEntry {
            plane: &refp[..],
            stride: ref_w,
            upscaled_width: ref_w as u32,
            width: ref_w as u32,
            height: ref_h as u32,
        };
        let store = [entry, entry, entry, entry];
        let ref_frame_idx: [u8; 7] = [0, 1, 2, 3, 0, 1, 2];
        let last = crate::uncompressed_header_tail::LAST_FRAME as u8;
        const BLOCK_8X8: usize = 3;

        let leaf = InterIntraLeaf {
            mode_info: InterIntraModeInfo {
                ref_frame: last,
                mv: [0, 0],
                interintra_mode: II_DC_PRED,
                wedge: None,
            },
            mi_size: BLOCK_8X8,
            mi_row: 0,
            mi_col: 0,
            interp_filter_x: EIGHTTAP,
            interp_filter_y: EIGHTTAP,
        };
        let mk_task = |mode: u8| crate::cdf::PlanePredictionTask {
            plane: 0,
            start_x: 0,
            start_y: 0,
            log2_w: 3,
            log2_h: 3,
            mode,
            have_left: false,
            have_above: false,
        };

        // (1) `is_inter_intra == false`.
        let not_ii = crate::cdf::ComputePredictionReadout {
            is_inter_intra: false,
            is_inter: true,
            num_planes_visited: 1,
            tasks: vec![mk_task(crate::cdf::DC_PRED as u8)],
        };
        // (2) plane coverage shorter than the supplied planes.
        let short_cov = crate::cdf::ComputePredictionReadout {
            is_inter_intra: true,
            is_inter: true,
            num_planes_visited: 0,
            tasks: vec![],
        };
        // (3) intra-half mode disagrees with the leaf's interintra_mode
        // (leaf says II_DC_PRED → DC_PRED, readout carries H_PRED).
        let mode_mismatch = crate::cdf::ComputePredictionReadout {
            is_inter_intra: true,
            is_inter: true,
            num_planes_visited: 1,
            tasks: vec![mk_task(crate::cdf::H_PRED as u8)],
        };

        for bad in [&not_ii, &short_cov, &mode_mismatch] {
            let mut curr = vec![0u16; 8 * 8];
            let mut planes = [PlaneReconContext {
                plane: 0,
                subsampling_x: 0,
                subsampling_y: 0,
                frame_store: &store,
                frame_width: ref_w as u32,
                frame_height: ref_h as u32,
                curr: &mut curr,
                curr_stride: 8,
            }];
            assert!(matches!(
                reconstruct_inter_intra_from_dispatch(
                    bad,
                    &leaf,
                    &ref_frame_idx,
                    8,
                    None,
                    &mut planes
                ),
                Err(crate::Error::PartitionWalkOutOfRange)
            ));
        }
    }
}