oxideav-opus 0.0.12

//! CELT §4.3.3 band-boost decoder (RFC 6716 §4.3.3, pp. 113–114).
//!
//! The §4.3.3 *Bit Allocation* procedure permits an encoder to boost
//! the per-band shape allocation for specific bands. The §4.3.3
//! narrative (RFC 6716 §4.3.3, pp. 113–114) reads:
//!
//! > The band boosts are represented by a series of binary symbols
//! > that are entropy coded with very low probability. Each band can
//! > potentially be boosted multiple times, subject to the frame
//! > actually having enough room to obey the boost and having enough
//! > room to code the boost symbol. The default coding cost for a
//! > boost starts out at six bits (probability p=1/64), but
//! > subsequent boosts in a band cost only a single bit and every
//! > time a band is boosted the initial cost is reduced (down to a
//! > minimum of two bits, or p=1/4). \[…\]
//! >
//! > To decode the band boosts: First, set 'dynalloc_logp' to 6, the
//! > initial amount of storage required to signal a boost in bits,
//! > 'total_bits' to the size of the frame in 8th bits, 'total_boost'
//! > to zero, and 'tell' to the total number of 8th bits decoded so
//! > far. For each band from the coding start (0 normally, but 17 in
//! > Hybrid mode) to the coding end (which changes depending on the
//! > signaled bandwidth), the boost quanta in units of 1/8 bit is
//! > calculated as `quanta = min(8*N, max(48, N))`. This represents
//! > a boost step size of six bits, subject to a lower limit of 1/8th
//! > bit/sample and an upper limit of 1 bit/sample. Set 'boost' to
//! > zero and 'dynalloc_loop_logp' to dynalloc_logp. While
//! > dynalloc_loop_log \[sic — `dynalloc_loop_logp`\] (the current
//! > worst case symbol cost) in 8th bits plus tell is less than
//! > total_bits plus total_boost and boost is less than `cap[]` for
//! > this band: Decode a bit from the bitstream with
//! > dynalloc_loop_logp as the cost of a one and update tell to
//! > reflect the current used capacity. If the decoded value is zero
//! > break the loop. Otherwise, add quanta to boost and total_boost,
//! > subtract quanta from total_bits, and set dynalloc_loop_log to 1.
//! > When the loop finishes 'boost' contains the bit allocation boost
//! > for this band. If boost is non-zero and dynalloc_logp is greater
//! > than 2, decrease dynalloc_logp. Once this process has been
//! > executed on all bands, the band boosts have been decoded.
//!
//! This module owns the §4.3.3 band-boost decode loop. It does *not*
//! own the per-band `cap[]` vector (provided by the caller from
//! [`crate::celt_cache_caps50::cap_for_band_bits`]) and it does *not*
//! own the §4.3.3 band-loop iteration policy (the caller picks the
//! `start..end` window per the §4.3 Hybrid / bandwidth-conditioned
//! rules in [`crate::celt_band_layout`]). It owns the *per-band* and
//! *cross-band* state machines that drive the §4.3.3 boost-bit reads
//! and the `total_boost` / `dynalloc_logp` updates.
//!
//! ## §4.3.3 quanta rule
//!
//! For a band with `N` MDCT bins (one channel), the §4.3.3 boost
//! quanta is
//!
//! ```text
//!     quanta = min(8*N, max(48, N))   (units: 1/8 bits)
//! ```
//!
//! Interpretation:
//!
//! * 48 1/8 bits = 6 whole bits = one full §4.3.3 boost step cost.
//! * `8*N` 1/8 bits = N whole bits = 1 bit/sample cap (the §4.3.3
//!   "upper limit of 1 bit/sample").
//! * `N` 1/8 bits = 1/8 bit/sample = the §4.3.3 "lower limit of 1/8th
//!   bit/sample".
//!
//! The 48 1/8-bit floor only matters for `N < 48` (i.e. the narrow
//! single-bin and 2-bin bands the §4.3 Table 55 layout produces for
//! the smallest LM); the `8*N` 1/8-bit ceiling only matters for
//! `N < 8` (the same narrow bands). For most of the band range the
//! quanta simply equals 48 1/8 bits (`max(48, N) = N` once `N ≥ 48`,
//! then `min(8*N, N) = N`). When `N ≥ 8` and `N ≥ 48`, all three
//! values collapse to `quanta = N`. The [`band_boost_quanta`] helper
//! computes this in one place.
//!
//! ## §4.3.3 cross-band `dynalloc_logp` state
//!
//! `dynalloc_logp` starts at 6 (the §4.3.3 "default cost for a boost
//! starts out at six bits") and decreases by 1 every time a band is
//! boosted at least once, floored at 2 (the §4.3.3 "down to a minimum
//! of two bits, or p=1/4"). This decrement is the §4.3.3 "every time
//! a band is boosted the initial cost is reduced" rule: it makes
//! subsequent bands' first boost cheaper to signal, encouraging the
//! encoder to concentrate boosts.
//!
//! The §4.3.3 rule is applied *only* at the boundary between two
//! band's boost loops, *after* one band's loop finishes and *before*
//! the next band's loop starts. Within a single band's loop, the
//! per-band `dynalloc_loop_logp` drops from `dynalloc_logp` to `1`
//! after the first boost bit (the §4.3.3 "subsequent boosts in a band
//! cost only a single bit" rule).
//!
//! ## §4.3.3 budget conservation
//!
//! The §4.3.3 inner-loop gate is `dynalloc_loop_logp + tell <
//! total_bits + total_boost`. Each boost step does `total_boost +=
//! quanta; total_bits -= quanta`, so the sum `total_bits + total_boost`
//! is conserved across boost steps and equals the original frame
//! budget in 1/8 bits throughout the entire §4.3.3 boost procedure.
//! The §4.3.3 procedure thus tracks two quantities — `total_bits` (the
//! capacity still available for non-boost allocation) and
//! `total_boost` (the §4.3.3 accumulator consumed by the downstream
//! §4.3.3 allocation-trim gate) — whose *sum* is fixed.
//!
//! ## Provenance
//!
//! Narrative: RFC 6716 §4.3.3 (pp. 113–114) in
//! `docs/audio/opus/rfc6716-opus.txt`; cross-referenced by
//! `docs/audio/celt/spec/celt-coarse-energy-and-allocation.md` §2.3.
//! No external numeric table is required for this module: the
//! `dynalloc_logp` start (6) and floor (2), the 48 1/8-bit boost step,
//! and the `min(8*N, max(48, N))` quanta rule are all inlined in the
//! RFC body.

use crate::range_decoder::RangeDecoder;

/// §4.3.3 initial coding cost for the first boost in a band, in
/// whole bits (RFC 6716 §4.3.3 p. 113: "default coding cost for a
/// boost starts out at six bits (probability p=1/64)").
pub const DYNALLOC_LOGP_INIT: u32 = 6;

/// §4.3.3 minimum coding cost for the first boost in a band, in
/// whole bits (RFC 6716 §4.3.3 p. 113: "down to a minimum of two
/// bits, or p=1/4").
pub const DYNALLOC_LOGP_MIN: u32 = 2;

/// §4.3.3 coding cost for the second and subsequent boost bits within
/// a single band's loop, in whole bits (RFC 6716 §4.3.3 p. 114: "set
/// dynalloc_loop_log to 1").
pub const DYNALLOC_LOOP_LOGP_AFTER_FIRST: u32 = 1;

/// §4.3.3 minimum boost-quanta floor (RFC 6716 §4.3.3 p. 114: "max(48,
/// N)"). 48 1/8 bits = 6 whole bits = one full §4.3.3 boost step.
pub const BAND_BOOST_QUANTA_FLOOR_EIGHTH_BITS: u32 = 48;

/// §4.3.3 ceiling multiplier for the boost quanta in 1/8 bits per
/// MDCT bin (RFC 6716 §4.3.3 p. 114: `min(8*N, …)`). 8 1/8 bits =
/// 1 whole bit, so `8*N` 1/8 bits is the 1 bit/sample ceiling.
pub const BAND_BOOST_QUANTA_CEIL_MULT: u32 = 8;

/// Errors returned by [`decode_band_boosts`] for inputs that violate
/// the §4.3.3 frame-budget bookkeeping or the per-band cap surface.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BandBoostError {
    /// The caller-provided `cap[]` slice does not cover the §4.3.3
    /// `start..end` window. Each band the loop visits must have a
    /// corresponding cap entry.
    CapsLengthMismatch { expected: usize, provided: usize },
    /// The caller-provided `n_bins[]` slice does not cover the §4.3.3
    /// `start..end` window. Each band the loop visits must have a
    /// corresponding per-channel MDCT-bin count.
    NBinsLengthMismatch { expected: usize, provided: usize },
    /// The §4.3.3 band-loop window is empty (`start == end`) but the
    /// §4.3.3 procedure expects at least one coded band. Reported so a
    /// caller that miscomputes the window is detected at the boundary
    /// rather than silently producing `total_boost = 0`.
    EmptyBandWindow { start: usize, end: usize },
    /// The §4.3.3 band-loop window is inverted (`start > end`). The
    /// §4.3.3 procedure enumerates bands forward.
    InvertedBandWindow { start: usize, end: usize },
}

/// §4.3.3 boost-quanta lookup for a single band (RFC 6716 §4.3.3,
/// p. 114).
///
/// `n_bins_per_channel` is the §4.3 Table 55 per-channel MDCT-bin
/// count for the band at the current `LM` (use
/// [`crate::celt_band_layout::celt_band_bins_per_channel`]). The
/// returned value is in 1/8-bit units, matching the §4.3.3
/// budget-bookkeeping convention.
///
/// `quanta = min(8*N, max(48, N))` per the §4.3.3 narrative. The
/// helper returns `0` for a zero-bin band (a malformed configuration
/// the §4.3 Table 55 layout never produces, but the math defines
/// naturally as `min(0, max(48, 0)) = 0`).
pub const fn band_boost_quanta(n_bins_per_channel: u32) -> u32 {
    let floored = if n_bins_per_channel > BAND_BOOST_QUANTA_FLOOR_EIGHTH_BITS {
        n_bins_per_channel
    } else {
        BAND_BOOST_QUANTA_FLOOR_EIGHTH_BITS
    };
    let ceiling = BAND_BOOST_QUANTA_CEIL_MULT * n_bins_per_channel;
    if ceiling < floored {
        ceiling
    } else {
        floored
    }
}

/// §4.3.3 per-band boost-loop outcome (RFC 6716 §4.3.3, pp. 113–114).
///
/// Records the §4.3.3 boost accumulator for one band — the value the
/// §4.3.3 allocator adds to that band's shape allocation — and the
/// number of inner-loop iterations the §4.3.3 procedure ran (so a
/// caller can spot a band whose loop bailed on the §4.3.3 budget
/// gate vs. one that decoded an explicit zero stop bit).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct BandBoost {
    /// §4.3.3 boost accumulator for this band, in 1/8 bits. Always a
    /// non-negative multiple of the band's quanta. The §4.3.3
    /// "boost < cap[band]" inner-loop check guarantees this value
    /// does not exceed `cap[band] + quanta − 1` (the worst case where
    /// one final boost is decoded with `boost = cap − 1`).
    pub boost_eighth_bits: u32,
    /// §4.3.3 boost-bit count: the number of bits this band's inner
    /// loop drew from the range coder. Equals the number of inner-loop
    /// iterations that completed a `dec_bit_logp` read.
    pub bits_read: u32,
}

/// §4.3.3 band-boost decode outcome (RFC 6716 §4.3.3, pp. 113–114).
///
/// Bundles the full §4.3.3 state-mutation result: the per-band boost
/// values, the cross-band `total_boost` accumulator (consumed by the
/// §4.3.3 allocation-trim gate at [`crate::celt_alloc_trim::decode_alloc_trim`]),
/// the residual `total_bits` budget (the §4.3.3 procedure's "capacity
/// still available for non-boost allocation"), and the final
/// `dynalloc_logp` value at the end of the band loop.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BandBoostOutcome {
    /// Per-band boost results. `per_band[i]` covers the band at index
    /// `start + i` of the §4.3.3 band loop.
    pub per_band: Vec<BandBoost>,
    /// §4.3.3 `total_boost`: the sum of every band's
    /// `boost_eighth_bits`. In 1/8 bits. The §4.3.3 allocation-trim
    /// gate at [`crate::celt_alloc_trim::decode_alloc_trim`] consumes
    /// this directly.
    pub total_boost_eighth_bits: u32,
    /// §4.3.3 `total_bits`: the frame budget minus `total_boost`, in
    /// 1/8 bits. The §4.3.3 procedure invariant
    /// `total_bits + total_boost = frame_eighth_bits` holds.
    pub total_bits_remaining_eighth_bits: u32,
    /// §4.3.3 `dynalloc_logp` value at the end of the band loop, in
    /// whole bits. Always in `DYNALLOC_LOGP_MIN..=DYNALLOC_LOGP_INIT`
    /// (i.e. `2..=6`) because the §4.3.3 floor is 2 and the decrement
    /// can only run as many times as bands were boosted.
    pub dynalloc_logp_final: u32,
}

/// Decode the §4.3.3 band boosts (RFC 6716 §4.3.3, pp. 113–114).
///
/// Walks the band loop from `start` to `end - 1` (the §4.3.3 coding
/// window: `0..end` normally, `17..end` in Hybrid mode, where `end`
/// depends on the §4.3 Table 55 bandwidth selection). For each band:
///
/// 1. Compute the §4.3.3 quanta from `n_bins[band - start]` via
///    [`band_boost_quanta`].
/// 2. Initialise `boost = 0` and `dynalloc_loop_logp = dynalloc_logp`.
/// 3. Loop while
///    `(dynalloc_loop_logp * 8) + tell < total_bits + total_boost`
///    AND `boost < caps[band - start]`. Inside the loop:
///    a. Decode one bit at cost `dynalloc_loop_logp` (in whole bits)
///    via [`RangeDecoder::dec_bit_logp`].
///    b. If the bit is `0`, break.
///    c. Otherwise add `quanta` to `boost` and `total_boost`,
///    subtract `quanta` from `total_bits`, and set
///    `dynalloc_loop_logp = 1`.
/// 4. If `boost > 0` and `dynalloc_logp > 2`, decrement
///    `dynalloc_logp`.
///
/// `frame_size_bytes` is the §3.4 Opus frame size in bytes; the
/// procedure converts it internally to 1/8 bits via the
/// `frame_size_bytes * 64` rule.
///
/// `caps[]` is the per-band §4.3.3 cap vector, indexed by `band -
/// start`, in 1/8 bits (use [`crate::celt_cache_caps50::cap_for_band_bits`]).
///
/// `n_bins[]` is the per-band per-channel MDCT-bin count, indexed by
/// `band - start` (use [`crate::celt_band_layout::celt_band_bins_per_channel`]).
///
/// On a malformed `start..end` window or a `caps[]` / `n_bins[]`
/// length mismatch, returns the appropriate [`BandBoostError`] *without
/// touching the range coder*. The range coder's own sticky error flag
/// is the right channel for a corrupt bitstream signal; this return
/// type captures only caller-side bookkeeping bugs.
pub fn decode_band_boosts(
    rd: &mut RangeDecoder<'_>,
    start: usize,
    end: usize,
    caps: &[u32],
    n_bins: &[u32],
    frame_size_bytes: u32,
) -> Result<BandBoostOutcome, BandBoostError> {
    if start > end {
        return Err(BandBoostError::InvertedBandWindow { start, end });
    }
    if start == end {
        return Err(BandBoostError::EmptyBandWindow { start, end });
    }
    let band_count = end - start;
    if caps.len() != band_count {
        return Err(BandBoostError::CapsLengthMismatch {
            expected: band_count,
            provided: caps.len(),
        });
    }
    if n_bins.len() != band_count {
        return Err(BandBoostError::NBinsLengthMismatch {
            expected: band_count,
            provided: n_bins.len(),
        });
    }

    // §4.3.3: total_bits is the frame size in 1/8 bits, total_boost
    // starts at zero. The two are kept separate because total_boost
    // feeds the §4.3.3 allocation-trim gate downstream, but the
    // §4.3.3 inner-loop check `tell + dynalloc_loop_logp <
    // total_bits + total_boost` always sums the two — yielding the
    // §4.3.3 invariant that the sum equals the original frame budget
    // throughout.
    let mut total_bits_eighth: u32 = frame_size_bytes.saturating_mul(64);
    let mut total_boost_eighth: u32 = 0;
    let mut dynalloc_logp = DYNALLOC_LOGP_INIT;

    let mut per_band: Vec<BandBoost> = Vec::with_capacity(band_count);

    for i in 0..band_count {
        let cap_band = caps[i];
        let quanta = band_boost_quanta(n_bins[i]);

        let mut boost: u32 = 0;
        let mut dynalloc_loop_logp = dynalloc_logp;
        let mut bits_read: u32 = 0;

        loop {
            // §4.3.3 inner-loop gate: `dynalloc_loop_logp + tell <
            // total_bits + total_boost`. `tell` and the logp budget
            // are in 1/8 bits; `dynalloc_loop_logp` is in whole bits
            // so we scale it by 8.
            let tell_frac = rd.tell_frac();
            let logp_eighth = dynalloc_loop_logp.saturating_mul(8);
            let budget_eighth = total_bits_eighth.saturating_add(total_boost_eighth);
            let projected_tell = tell_frac.saturating_add(logp_eighth);
            if projected_tell >= budget_eighth {
                break;
            }
            if boost >= cap_band {
                break;
            }

            // §4.3.3: decode one bit at cost dynalloc_loop_logp. The
            // range decoder's dec_bit_logp consumes ~dynalloc_loop_logp
            // whole bits (the renormalization carries the residual).
            let bit = rd.dec_bit_logp(dynalloc_loop_logp);
            bits_read = bits_read.saturating_add(1);

            if bit == 0 {
                break;
            }

            // §4.3.3 boost step: add quanta to boost / total_boost,
            // subtract quanta from total_bits. saturating_sub guards
            // against malformed input; well-formed inputs preserve the
            // §4.3.3 sum invariant.
            boost = boost.saturating_add(quanta);
            total_boost_eighth = total_boost_eighth.saturating_add(quanta);
            total_bits_eighth = total_bits_eighth.saturating_sub(quanta);
            dynalloc_loop_logp = DYNALLOC_LOOP_LOGP_AFTER_FIRST;
        }

        // §4.3.3 cross-band update: a non-zero boost at this band
        // discounts the first-boost cost for subsequent bands.
        if boost > 0 && dynalloc_logp > DYNALLOC_LOGP_MIN {
            dynalloc_logp -= 1;
        }

        per_band.push(BandBoost {
            boost_eighth_bits: boost,
            bits_read,
        });
    }

    Ok(BandBoostOutcome {
        per_band,
        total_boost_eighth_bits: total_boost_eighth,
        total_bits_remaining_eighth_bits: total_bits_eighth,
        dynalloc_logp_final: dynalloc_logp,
    })
}

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

    // ---- §4.3.3 constants pinned to the RFC body ----

    #[test]
    fn dynalloc_logp_init_is_six() {
        // RFC 6716 §4.3.3 p. 113: "default coding cost for a boost
        // starts out at six bits (probability p=1/64)".
        assert_eq!(DYNALLOC_LOGP_INIT, 6);
    }

    #[test]
    fn dynalloc_logp_min_is_two() {
        // RFC 6716 §4.3.3 p. 113: "down to a minimum of two bits, or
        // p=1/4".
        assert_eq!(DYNALLOC_LOGP_MIN, 2);
    }

    #[test]
    fn dynalloc_loop_logp_after_first_is_one() {
        // RFC 6716 §4.3.3 p. 114: "set dynalloc_loop_log to 1".
        assert_eq!(DYNALLOC_LOOP_LOGP_AFTER_FIRST, 1);
    }

    #[test]
    fn quanta_floor_constant_matches_six_bits() {
        // RFC 6716 §4.3.3 p. 114: "max(48, N)" 1/8 bits = 6 whole
        // bits = one full boost step.
        assert_eq!(BAND_BOOST_QUANTA_FLOOR_EIGHTH_BITS, 48);
        assert_eq!(BAND_BOOST_QUANTA_FLOOR_EIGHTH_BITS / 8, 6);
    }

    #[test]
    fn quanta_ceil_mult_is_eight_for_one_bit_per_sample() {
        // RFC 6716 §4.3.3 p. 114: "8*N" 1/8 bits = 1 bit/sample.
        assert_eq!(BAND_BOOST_QUANTA_CEIL_MULT, 8);
    }

    // ---- §4.3.3 quanta = min(8*N, max(48, N)) ----

    #[test]
    fn quanta_for_n_equals_48_is_48() {
        // Boundary: N = 48 hits the floor exactly.
        // min(8*48, max(48, 48)) = min(384, 48) = 48.
        assert_eq!(band_boost_quanta(48), 48);
    }

    #[test]
    fn quanta_above_48_equals_n() {
        // For N ≥ 48: max(48, N) = N; min(8*N, N) = N.
        for n in [49u32, 64, 96, 128, 176] {
            assert_eq!(band_boost_quanta(n), n, "N = {}", n);
        }
    }

    #[test]
    fn quanta_below_48_floors_at_48_until_ceiling_kicks_in() {
        // For 6 ≤ N < 48: max(48, N) = 48; min(8*N, 48). The crossover
        // is at 8*N = 48 ⇒ N = 6. So for N ≥ 6 and N < 48, quanta = 48.
        for n in 6u32..48 {
            assert_eq!(band_boost_quanta(n), 48, "N = {}", n);
        }
    }

    #[test]
    fn quanta_below_six_is_eight_n() {
        // For 0 < N < 6: 8*N < 48, so the ceiling clips the floor.
        // min(8*N, 48) = 8*N.
        for n in 1u32..6 {
            assert_eq!(band_boost_quanta(n), 8 * n, "N = {}", n);
        }
    }

    #[test]
    fn quanta_at_zero_is_zero() {
        // Degenerate zero-bin band: min(0, max(48, 0)) = 0.
        assert_eq!(band_boost_quanta(0), 0);
    }

    #[test]
    fn quanta_invariants_across_table_55_range() {
        // §4.3 Table 55 bin counts at LM=3 (20 ms, max bins) range
        // 8..=176 per channel. At any §4.3.3-reachable bin count, the
        // quanta is always ≥ 48 1/8 bits (1 bit step floor).
        for n in [8u32, 16, 24, 32, 48, 64, 88, 128, 176] {
            assert!(
                band_boost_quanta(n) >= 48,
                "N = {} produced {}",
                n,
                band_boost_quanta(n)
            );
        }
    }

    // ---- decode_band_boosts argument validation ----

    fn rd<'a>(buf: &'a [u8]) -> RangeDecoder<'a> {
        RangeDecoder::new(buf)
    }

    #[test]
    fn empty_band_window_rejected() {
        let buf = [0x80u8; 8];
        let mut d = rd(&buf);
        let err = decode_band_boosts(&mut d, 0, 0, &[], &[], 60).unwrap_err();
        assert_eq!(err, BandBoostError::EmptyBandWindow { start: 0, end: 0 });
    }

    #[test]
    fn inverted_band_window_rejected() {
        let buf = [0x80u8; 8];
        let mut d = rd(&buf);
        let err = decode_band_boosts(&mut d, 5, 3, &[], &[], 60).unwrap_err();
        assert_eq!(err, BandBoostError::InvertedBandWindow { start: 5, end: 3 });
    }

    #[test]
    fn caps_length_mismatch_rejected() {
        let buf = [0x80u8; 8];
        let mut d = rd(&buf);
        // 5 bands expected (0..5), only 4 caps provided.
        let err = decode_band_boosts(&mut d, 0, 5, &[100, 100, 100, 100], &[8, 8, 8, 8, 8], 60)
            .unwrap_err();
        assert_eq!(
            err,
            BandBoostError::CapsLengthMismatch {
                expected: 5,
                provided: 4,
            }
        );
    }

    #[test]
    fn n_bins_length_mismatch_rejected() {
        let buf = [0x80u8; 8];
        let mut d = rd(&buf);
        let err = decode_band_boosts(&mut d, 0, 3, &[100, 100, 100], &[8, 8], 60).unwrap_err();
        assert_eq!(
            err,
            BandBoostError::NBinsLengthMismatch {
                expected: 3,
                provided: 2,
            }
        );
    }

    #[test]
    fn argument_validation_does_not_touch_range_coder() {
        let buf = [0x80u8; 8];
        let mut d = rd(&buf);
        let before = d.tell_frac();
        let _ = decode_band_boosts(&mut d, 5, 3, &[], &[], 60);
        let _ = decode_band_boosts(&mut d, 0, 0, &[], &[], 60);
        let _ = decode_band_boosts(&mut d, 0, 3, &[1, 2], &[1, 2, 3], 60);
        let _ = decode_band_boosts(&mut d, 0, 3, &[1, 2, 3], &[1, 2], 60);
        assert_eq!(d.tell_frac(), before);
    }

    // ---- decode_band_boosts at the very low rate (no boost possible) ----

    #[test]
    fn no_room_for_any_boost_returns_all_zeros() {
        // A 1-byte frame (64 1/8 bits) leaves no room for the §4.3.3
        // 6-whole-bit (48 1/8 bit) first-boost cost once the range
        // coder is initialised: rd.tell_frac() is already ~9 1/8 bits
        // after `new()`, so `tell + 48 = 57 < 64` actually does fit
        // initially. Use a smaller frame: 0 bytes makes total_bits = 0
        // so the inner-loop gate fails on every band.
        let buf = [0x80u8; 8];
        let mut d = rd(&buf);
        let outcome = decode_band_boosts(&mut d, 0, 3, &[100, 100, 100], &[8, 8, 8], 0).unwrap();
        // No boosts, no bits consumed from the band-boost path.
        for band in &outcome.per_band {
            assert_eq!(band.boost_eighth_bits, 0);
            assert_eq!(band.bits_read, 0);
        }
        assert_eq!(outcome.total_boost_eighth_bits, 0);
        assert_eq!(outcome.dynalloc_logp_final, DYNALLOC_LOGP_INIT);
    }

    #[test]
    fn no_room_outcome_preserves_total_bits_at_zero() {
        // Same scenario as above: frame_size_bytes = 0 ⇒ total_bits
        // starts at 0. The §4.3.3 invariant
        // total_bits + total_boost = frame_eighth_bits = 0 must hold.
        let buf = [0x80u8; 8];
        let mut d = rd(&buf);
        let outcome = decode_band_boosts(&mut d, 0, 3, &[100, 100, 100], &[8, 8, 8], 0).unwrap();
        assert_eq!(outcome.total_bits_remaining_eighth_bits, 0);
        assert_eq!(outcome.total_boost_eighth_bits, 0);
    }

    // ---- decode_band_boosts in the "stop bit" regime ----
    //
    // `dec_bit_logp(K)` returns 1 (the §4.3.3 "boost" branch) when
    // `val < s = rng >> K`, and 0 (the §4.3.3 "stop" branch) otherwise.
    // The §4.1.1 init sets `val = 127 - (b0 >> 1)`, so a high first
    // byte yields a small `val` which biases toward the "1" branch
    // after renormalization. We pick payloads accordingly.

    /// Payload biased toward the §4.3.3 "stop bit" branch. The §4.1.1
    /// init `val = 127 - (b0 >> 1)` with `b0 = 0x00` yields `val =
    /// 127`, the largest initial value, so the first few decodes take
    /// the `val >= s` branch (bit = 0).
    const PAYLOAD_STOP_BIASED: [u8; 64] = [0x00u8; 64];

    /// Payload biased toward the §4.3.3 "boost bit" branch (val small
    /// after init).
    const PAYLOAD_BOOST_BIASED: [u8; 64] = [0xFFu8; 64];

    #[test]
    fn stop_biased_payload_decodes_no_boosts() {
        let mut d = rd(&PAYLOAD_STOP_BIASED);
        let before = d.tell_frac();
        let outcome = decode_band_boosts(
            &mut d,
            0,
            5,
            &[1000, 1000, 1000, 1000, 1000],
            &[48; 5],
            1275,
        )
        .unwrap();
        // Each band: one stop bit, zero boost.
        for band in &outcome.per_band {
            assert_eq!(band.boost_eighth_bits, 0, "boost not zero: {:?}", band);
            assert_eq!(band.bits_read, 1, "expected 1 bit: {:?}", band);
        }
        assert_eq!(outcome.total_boost_eighth_bits, 0);
        // dynalloc_logp doesn't decrement when no band boosted.
        assert_eq!(outcome.dynalloc_logp_final, DYNALLOC_LOGP_INIT);
        // Some bits consumed from the range coder.
        assert!(d.tell_frac() > before);
    }

    #[test]
    fn boost_biased_payload_actually_boosts_at_least_one_band() {
        // Sanity check the test payload: the §4.3.3 "1" branch is
        // taken on at least one band of the boost-biased payload.
        let mut d = rd(&PAYLOAD_BOOST_BIASED);
        let outcome = decode_band_boosts(
            &mut d,
            0,
            5,
            &[1000, 1000, 1000, 1000, 1000],
            &[48; 5],
            1275,
        )
        .unwrap();
        let any_boosted = outcome.per_band.iter().any(|b| b.boost_eighth_bits > 0);
        assert!(
            any_boosted,
            "boost-biased payload did not boost: {:?}",
            outcome
        );
        // total_boost is the sum of per-band boosts.
        let sum: u32 = outcome.per_band.iter().map(|b| b.boost_eighth_bits).sum();
        assert_eq!(sum, outcome.total_boost_eighth_bits);
    }

    #[test]
    fn boost_biased_payload_decrements_dynalloc_logp() {
        // Since boost-biased payload boosts at least one band, the
        // §4.3.3 cross-band decrement should drop dynalloc_logp below
        // its initial 6 (down to MIN=2 floor over many boosts).
        let mut d = rd(&PAYLOAD_BOOST_BIASED);
        let outcome = decode_band_boosts(&mut d, 0, 10, &[1000; 10], &[48; 10], 1275).unwrap();
        assert!(outcome.dynalloc_logp_final < DYNALLOC_LOGP_INIT);
        assert!(outcome.dynalloc_logp_final >= DYNALLOC_LOGP_MIN);
    }

    #[test]
    fn band_count_matches_per_band_length() {
        let mut d = rd(&PAYLOAD_STOP_BIASED);
        let outcome = decode_band_boosts(&mut d, 0, 7, &[1000; 7], &[48; 7], 1275).unwrap();
        assert_eq!(outcome.per_band.len(), 7);
    }

    #[test]
    fn hybrid_start_window_yields_four_bands_with_end_21() {
        // §4.3 Hybrid coding window is 17..21 (4 bands) per
        // [`HYBRID_FIRST_CODED_BAND`].
        let mut d = rd(&PAYLOAD_STOP_BIASED);
        let outcome = decode_band_boosts(&mut d, 17, 21, &[1000; 4], &[48; 4], 1275).unwrap();
        assert_eq!(outcome.per_band.len(), 4);
    }

    // ---- §4.3.3 budget conservation invariant ----

    #[test]
    fn total_bits_plus_total_boost_equals_frame_budget_stop_path() {
        // The §4.3.3 invariant `total_bits + total_boost =
        // frame_eighth_bits` must hold across the boost loop. With
        // the stop-biased payload no band actually boosts, so the
        // invariant is trivially satisfied — but we still pin it.
        let mut d = rd(&PAYLOAD_STOP_BIASED);
        let outcome = decode_band_boosts(&mut d, 0, 5, &[1000; 5], &[48; 5], 1275).unwrap();
        let sum = outcome
            .total_bits_remaining_eighth_bits
            .saturating_add(outcome.total_boost_eighth_bits);
        assert_eq!(sum, 1275 * 64);
    }

    #[test]
    fn total_bits_plus_total_boost_equals_frame_budget_boost_path() {
        // Same invariant on the boost-biased payload: even when
        // boosts fire, the §4.3.3 budget conservation holds because
        // each boost step moves quanta from `total_bits` into
        // `total_boost`.
        let mut d = rd(&PAYLOAD_BOOST_BIASED);
        let outcome = decode_band_boosts(&mut d, 0, 10, &[1000; 10], &[48; 10], 1275).unwrap();
        let sum = outcome
            .total_bits_remaining_eighth_bits
            .saturating_add(outcome.total_boost_eighth_bits);
        assert_eq!(sum, 1275 * 64);
    }

    // ---- §4.3.3 cross-band dynalloc_logp floor ----

    #[test]
    fn dynalloc_logp_floors_at_min_after_many_boosts() {
        // dynalloc_logp decreases by 1 per boosted band, floored at 2.
        // Starting at 6, after 4 boosted bands it would reach 2 and
        // stop. With 21 bands (the standard CELT layout) plenty of
        // headroom. We can't easily force boosts without crafting a
        // bitstream — instead, pin the floor with a pure-math
        // simulation against the per-band update rule.
        let mut dynalloc = DYNALLOC_LOGP_INIT;
        for _ in 0..21 {
            // Simulate: each band boosts → decrement, floored at MIN.
            if dynalloc > DYNALLOC_LOGP_MIN {
                dynalloc -= 1;
            }
        }
        assert_eq!(dynalloc, DYNALLOC_LOGP_MIN);
    }

    #[test]
    fn dynalloc_logp_only_decrements_when_band_actually_boosted() {
        // Stop-biased payload: every band decodes a stop bit, no band
        // boosts, so dynalloc_logp must NOT decrement.
        let mut d = rd(&PAYLOAD_STOP_BIASED);
        let outcome = decode_band_boosts(&mut d, 0, 21, &[1000; 21], &[48; 21], 1275).unwrap();
        assert_eq!(outcome.dynalloc_logp_final, DYNALLOC_LOGP_INIT);
    }

    // ---- BandBoost / BandBoostOutcome shape ----

    #[test]
    fn band_boost_default_is_zero() {
        let bb = BandBoost::default();
        assert_eq!(bb.boost_eighth_bits, 0);
        assert_eq!(bb.bits_read, 0);
    }

    #[test]
    fn per_band_outcome_alignment_with_window() {
        // The per_band vector aligns 1:1 with the start..end window.
        let mut d = rd(&PAYLOAD_STOP_BIASED);
        let outcome = decode_band_boosts(&mut d, 3, 10, &[500; 7], &[64; 7], 1275).unwrap();
        assert_eq!(outcome.per_band.len(), 10 - 3);
    }

    // ---- §4.3.3 inner-loop bound: boost capped near cap[] ----
    //
    // Worst case the inner loop decodes one boost above cap (the
    // §4.3.3 check is `boost < cap`, then we boost by quanta, so a
    // band could land at `cap + quanta - 1`). Pin this property by
    // constructing a low-cap band on a payload that would otherwise
    // boost it indefinitely.

    #[test]
    fn boost_does_not_grossly_exceed_cap() {
        // Even on a maximally-aggressive payload, the §4.3.3 inner
        // loop stops once `boost >= cap`. The largest overshoot is
        // one quanta (`boost = cap - 1` then one more boost). Pin
        // the invariant that the loop bails out promptly.
        //
        // For a §4.3.3 payload that DOES decode boost=1 bits, we'd
        // need a crafted range stream. The stop-bit payload above
        // exercises the bit==0 branch; here we instead reason about
        // the cap gate analytically: for any cap and any quanta > 0,
        // after at most `(cap + quanta - 1) / quanta` iterations the
        // gate fails.
        for cap in [0u32, 48, 96, 144, 1000] {
            for quanta in [48u32, 64, 96] {
                let max_iters = match cap.checked_div(quanta) {
                    Some(q) => q + 1,
                    None => 0,
                };
                let max_boost = max_iters * quanta;
                // worst case: boost ≤ cap + (quanta − 1)
                assert!(
                    max_boost <= cap + quanta,
                    "cap={} quanta={} max_boost={}",
                    cap,
                    quanta,
                    max_boost
                );
            }
        }
    }

    // ---- §4.3.3 zero-cap band cannot be boosted ----

    #[test]
    fn zero_cap_band_yields_zero_boost() {
        // A band with cap=0 fails the inner-loop gate immediately
        // (`boost < cap` is false for boost=0, cap=0), so the loop
        // never reads a bit.
        let mut d = rd(&PAYLOAD_BOOST_BIASED);
        let before = d.tell_frac();
        let outcome = decode_band_boosts(&mut d, 0, 3, &[0, 0, 0], &[48, 48, 48], 1275).unwrap();
        for band in &outcome.per_band {
            assert_eq!(band.boost_eighth_bits, 0);
            assert_eq!(band.bits_read, 0);
        }
        // No bits consumed.
        assert_eq!(d.tell_frac(), before);
        assert_eq!(outcome.total_boost_eighth_bits, 0);
    }

    // ---- §4.3.3 quanta totally-defined ----

    #[test]
    fn band_boost_quanta_is_total_function_over_u16() {
        // The §4.3 Table 55 bin counts fit in u16; the helper must
        // not panic for any u16 input.
        for n in 0u32..=u16::MAX as u32 {
            let _ = band_boost_quanta(n);
        }
    }

    // ---- §4.3.3 outcome dynalloc_logp range ----

    #[test]
    fn dynalloc_logp_final_within_min_max() {
        let mut d = rd(&PAYLOAD_BOOST_BIASED);
        let outcome = decode_band_boosts(&mut d, 0, 21, &[1000; 21], &[48; 21], 1275).unwrap();
        assert!(outcome.dynalloc_logp_final >= DYNALLOC_LOGP_MIN);
        assert!(outcome.dynalloc_logp_final <= DYNALLOC_LOGP_INIT);
    }

    // ---- Constants pinned vs RFC text ----

    #[test]
    fn rfc_eighth_bit_unit_conversion_pinned() {
        // 1 whole bit = 8 1/8 bits; the BAND_BOOST_QUANTA_FLOOR is
        // 6 whole bits = 48 1/8 bits.
        assert_eq!(DYNALLOC_LOGP_INIT * 8, BAND_BOOST_QUANTA_FLOOR_EIGHTH_BITS);
    }

    // ---- §4.3.3 budget bookkeeping sums to frame ----

    #[test]
    fn budget_sum_invariant_at_zero_frame_bytes() {
        // Edge case: a 0-byte frame has total_eighth = 0 throughout,
        // and total_boost stays 0 because no inner-loop iteration can
        // run.
        let buf = [0xFFu8; 8];
        let mut d = RangeDecoder::new(&buf);
        let outcome = decode_band_boosts(&mut d, 0, 1, &[1000], &[48], 0).unwrap();
        assert_eq!(outcome.total_bits_remaining_eighth_bits, 0);
        assert_eq!(outcome.total_boost_eighth_bits, 0);
    }

    // ---- §4.3.3 multi-band frame_size 1275 (max Opus packet) ----

    #[test]
    fn frame_size_max_opus_does_not_overflow() {
        // §3.4 R5: max Opus packet is 1275 bytes ⇒ 1275 × 64 = 81600
        // 1/8 bits. Comfortably below u32::MAX. Pin the headroom.
        assert!(1275u32.checked_mul(64).is_some());
        let mut d = rd(&PAYLOAD_STOP_BIASED);
        let outcome = decode_band_boosts(&mut d, 0, 21, &[1000; 21], &[48; 21], 1275).unwrap();
        let sum = outcome
            .total_bits_remaining_eighth_bits
            .saturating_add(outcome.total_boost_eighth_bits);
        assert_eq!(sum, 1275 * 64);
    }

    // ---- §4.3.3 BandBoostOutcome equality / debug round-trip ----

    #[test]
    fn outcome_equality_holds_for_identical_runs() {
        let mut d1 = rd(&PAYLOAD_STOP_BIASED);
        let mut d2 = rd(&PAYLOAD_STOP_BIASED);
        let a = decode_band_boosts(&mut d1, 0, 5, &[100; 5], &[48; 5], 1275).unwrap();
        let b = decode_band_boosts(&mut d2, 0, 5, &[100; 5], &[48; 5], 1275).unwrap();
        assert_eq!(a, b);
    }
}