fix(codec): address PR-195 review — overflow Merge alias + mode-sized pack_leaf

P1 (codex) — overflow δ no longer aliases to Merge:
  predict_intra previously took `our_delta_u8 = δ as u8` BEFORE
  checking i8 fit, so e.g. δ=200 wrapped to 0xC8 and could match a
  neighbour byte 0xC8 (i8=-56), silently corrupting reconstruction.
  Now the i8 range check gates both the Merge scan and the Delta
  branch; out-of-range δ falls straight through to Escape (or the
  documented lossy clamp).
  + 2 regression tests:
    - overflow_delta_does_not_alias_to_merge
    - overflow_delta_with_allocator_takes_escape

P2 (coderabbit + codex) — pack_leaf accepts mode-sized buffers:
  pack_leaf used a 6-byte minimum for all modes; callers pre-sizing
  by packed_byte_len() got spurious None for Skip(2)/Merge,Delta(3).
  Length check now gates on packed_byte_len(leaf.mode).
  + 1 regression test: pack_leaf_accepts_mode_sized_buffers

P3 (coderabbit) — doctest examples on the public-API surface:
  Added /// runnable examples to MAX_BASIN_IDX, BASIN_NONE,
  unpack_header, pack_merge_dir, unpack_merge_dir, unpack_leaf,
  packed_byte_len, IntraContext, IntraConfig, is_no_basin.
  Removed unused LeafCu import from existing predict_intra doctest.

Gates:
  cargo test --features codec --lib hpc::codec → 48 passed
  cargo test --features codec --doc hpc::codec → 14 passed
  cargo fmt --all -- --check → clean
  cargo clippy --features codec --lib -- -D warnings → clean

Author: claude

src/hpc/codec/mode.rs

@@ -57,10 +57,20 @@ use super::ctu::{CellMode, LeafCu, MergeDir};
 
 /// Maximum encodable `basin_idx`. Stored in the lower 12 bits of the
 /// header; values >= this constant overflow the header field.
+///
+/// ```
+/// use ndarray::hpc::codec::MAX_BASIN_IDX;
+/// assert_eq!(MAX_BASIN_IDX, (1 << 12) - 1);
+/// ```
 pub const MAX_BASIN_IDX: u16 = (1 << 12) - 1; // 4095
 
 /// Tag inside the per-frame basin codebook for "no basin assigned"
 /// (encoder-side sentinel during mode decision).
+///
+/// ```
+/// use ndarray::hpc::codec::{BASIN_NONE, MAX_BASIN_IDX};
+/// assert_eq!(BASIN_NONE, MAX_BASIN_IDX);
+/// ```
 pub const BASIN_NONE: u16 = MAX_BASIN_IDX;
 
 /// Pack `(mode, basin_idx)` into a 16-bit header.
@@ -85,6 +95,12 @@ pub fn pack_header(mode: CellMode, basin_idx: u16) -> u16 {
 ///
 /// The 2-bit mode field always decodes (all 4 variants are valid).
 /// `basin_idx` is the 12-bit lower field, exactly as packed.
+///
+/// ```
+/// use ndarray::hpc::codec::{pack_header, unpack_header, CellMode};
+/// let h = pack_header(CellMode::Escape, 7);
+/// assert_eq!(unpack_header(h), (CellMode::Escape, 7));
+/// ```
 #[inline]
 pub fn unpack_header(packed: u16) -> (CellMode, u16) {
     let mode_bits = ((packed >> 12) & 0b11) as u8;
@@ -103,6 +119,11 @@ pub fn unpack_header(packed: u16) -> (CellMode, u16) {
 // ════════════════════════════════════════════════════════════════════
 
 /// Pack a [`MergeDir`] into the lower 2 bits of a `u8`.
+///
+/// ```
+/// use ndarray::hpc::codec::{pack_merge_dir, MergeDir};
+/// assert_eq!(pack_merge_dir(MergeDir::East), 1);
+/// ```
 #[inline]
 pub fn pack_merge_dir(dir: MergeDir) -> u8 {
     dir as u8
@@ -112,6 +133,13 @@ pub fn pack_merge_dir(dir: MergeDir) -> u8 {
 ///
 /// All four 2-bit values map to a valid `MergeDir`; bits 2-7 are
 /// ignored.
+///
+/// ```
+/// use ndarray::hpc::codec::{pack_merge_dir, unpack_merge_dir, MergeDir};
+/// for d in [MergeDir::North, MergeDir::East, MergeDir::West, MergeDir::South] {
+///     assert_eq!(unpack_merge_dir(pack_merge_dir(d)), d);
+/// }
+/// ```
 #[inline]
 pub fn unpack_merge_dir(byte: u8) -> MergeDir {
     match byte & 0b11 {
@@ -133,7 +161,9 @@ pub fn unpack_merge_dir(byte: u8) -> MergeDir {
 /// worst case) — callers iterating CTUs typically pre-allocate
 /// `6 * cell_count` and trim afterwards.
 ///
-/// Returns `None` if `out.len() < 6` (insufficient capacity).
+/// Returns `None` if `out.len() < packed_byte_len(leaf.mode)` (insufficient
+/// capacity for the *mode's* width — Skip needs 2, Merge/Delta need 3,
+/// Escape needs 6).
 ///
 /// Format:
 /// - Bytes 0-1: header (`pack_header(mode, basin_idx)`, LE)
@@ -151,7 +181,8 @@ pub fn unpack_merge_dir(byte: u8) -> MergeDir {
 /// assert_eq!(consumed, 3);
 /// ```
 pub fn pack_leaf(leaf: &LeafCu, out: &mut [u8]) -> Option<usize> {
-    if out.len() < 6 {
+    let required = packed_byte_len(leaf.mode);
+    if out.len() < required {
         return None;
     }
     let header = pack_header(leaf.mode, leaf.basin_idx);
@@ -184,6 +215,16 @@ pub fn pack_leaf(leaf: &LeafCu, out: &mut [u8]) -> Option<usize> {
 ///
 /// Returns `None` if the buffer is shorter than the per-mode width
 /// (2 for Skip, 3 for Merge/Delta, 6 for Escape).
+///
+/// ```
+/// use ndarray::hpc::codec::{pack_leaf, unpack_leaf, LeafCu, MergeDir};
+/// let leaf = LeafCu::merge(7, MergeDir::West);
+/// let mut buf = [0u8; 3];
+/// pack_leaf(&leaf, &mut buf).unwrap();
+/// let (decoded, n) = unpack_leaf(&buf).unwrap();
+/// assert_eq!(decoded, leaf);
+/// assert_eq!(n, 3);
+/// ```
 pub fn unpack_leaf(buf: &[u8]) -> Option<(LeafCu, usize)> {
     if buf.len() < 2 {
         return None;
@@ -217,6 +258,14 @@ pub fn unpack_leaf(buf: &[u8]) -> Option<(LeafCu, usize)> {
 
 /// Byte cost of packing a leaf in this mode. Useful for pre-sizing
 /// a buffer without packing first.
+///
+/// ```
+/// use ndarray::hpc::codec::{packed_byte_len, CellMode};
+/// assert_eq!(packed_byte_len(CellMode::Skip), 2);
+/// assert_eq!(packed_byte_len(CellMode::Merge), 3);
+/// assert_eq!(packed_byte_len(CellMode::Delta), 3);
+/// assert_eq!(packed_byte_len(CellMode::Escape), 6);
+/// ```
 #[inline]
 pub const fn packed_byte_len(mode: CellMode) -> usize {
     match mode {

src/hpc/codec/predict.rs

@@ -87,6 +87,17 @@ use super::mode::BASIN_NONE;
 /// - `neighbours`: NESW (in [`MergeDir`] discriminant order) optional
 ///   neighbour leaves. `None` for boundary cells; the Merge candidate
 ///   scan skips `None` entries.
+///
+/// ```
+/// use ndarray::hpc::codec::{IntraContext, LeafCu};
+/// let north = LeafCu::delta(5, 17);
+/// let ctx = IntraContext {
+///     basin_idx: 5,
+///     delta_i32: 17,
+///     neighbours: [Some(&north), None, None, None],
+/// };
+/// assert_eq!(ctx.basin_idx, 5);
+/// ```
 #[derive(Debug, Clone, Copy)]
 pub struct IntraContext<'a> {
     /// Pre-resolved basin index (12-bit max).
@@ -102,6 +113,14 @@ pub struct IntraContext<'a> {
 ///
 /// Today a single field; the field exists so the API can grow
 /// (Merge tolerance, RDO knobs in A6) without a signature break.
+///
+/// ```
+/// use ndarray::hpc::codec::IntraConfig;
+/// let default_cfg = IntraConfig::default();
+/// assert!(default_cfg.escape_next_idx.is_none());
+/// let allocated = IntraConfig { escape_next_idx: Some(42) };
+/// assert_eq!(allocated.escape_next_idx, Some(42));
+/// ```
 #[derive(Debug, Clone, Copy)]
 pub struct IntraConfig {
     /// Future allocator for the encoder's escape vector — returns the
@@ -139,7 +158,7 @@ impl Default for IntraConfig {
 ///
 /// ```
 /// use ndarray::hpc::codec::predict::{predict_intra, IntraContext, IntraConfig};
-/// use ndarray::hpc::codec::{CellMode, LeafCu};
+/// use ndarray::hpc::codec::CellMode;
 /// let ctx = IntraContext {
 ///     basin_idx: 42,
 ///     delta_i32: 0,
@@ -170,6 +189,14 @@ pub fn predict_intra(ctx: &IntraContext, cfg: &IntraConfig) -> LeafCu {
         return LeafCu::skip(ctx.basin_idx);
     }
 
+    // i8-fit gates both Merge and Delta. Out-of-range δ must skip
+    // Merge entirely — wrapping `200_i32 as u8` aliases to `0xC8`,
+    // which could spuriously match a neighbour whose byte equals
+    // `0xC8` (i8 = -56), producing a leaf the decoder reconstructs as
+    // -56 instead of 200.
+    let fits_i8 = (-128..=127).contains(&ctx.delta_i32);
+    let our_delta_u8 = ctx.delta_i32 as u8; // wrapping cast matches A2 pack
+
     // ── 2. Merge ─────────────────────────────────────────────────────
     //
     // A neighbour is a Merge candidate iff:
@@ -186,20 +213,21 @@ pub fn predict_intra(ctx: &IntraContext, cfg: &IntraConfig) -> LeafCu {
     // Multiple matches all collapse to the same coded leaf, so the
     // first-hit policy is order-deterministic without affecting
     // bitstream length.
-    let our_delta_u8 = ctx.delta_i32 as u8; // wrapping cast matches A2 pack
-    for (i, nb_slot) in ctx.neighbours.iter().enumerate() {
-        let Some(nb) = nb_slot else { continue };
-        if nb.mode != CellMode::Delta {
-            continue;
+    if fits_i8 {
+        for (i, nb_slot) in ctx.neighbours.iter().enumerate() {
+            let Some(nb) = nb_slot else { continue };
+            if nb.mode != CellMode::Delta {
+                continue;
+            }
+            if nb.basin_idx != ctx.basin_idx {
+                continue;
+            }
+            if nb.delta != Some(our_delta_u8) {
+                continue;
+            }
+            let dir = merge_dir_from_index(i);
+            return LeafCu::merge(ctx.basin_idx, dir);
         }
-        if nb.basin_idx != ctx.basin_idx {
-            continue;
-        }
-        if nb.delta != Some(our_delta_u8) {
-            continue;
-        }
-        let dir = merge_dir_from_index(i);
-        return LeafCu::merge(ctx.basin_idx, dir);
     }
 
     // ── 3. Delta ─────────────────────────────────────────────────────
@@ -208,7 +236,7 @@ pub fn predict_intra(ctx: &IntraContext, cfg: &IntraConfig) -> LeafCu {
     // the encoder's reconstruction must read the byte back as i8 to
     // recover the sign. This matches how `LeafCu::delta` stores it and
     // how `super::mode::pack_leaf` writes it.
-    if (-128..=127).contains(&ctx.delta_i32) {
+    if fits_i8 {
         return LeafCu::delta(ctx.basin_idx, our_delta_u8);
     }
 
@@ -244,6 +272,12 @@ fn merge_dir_from_index(i: usize) -> MergeDir {
 /// is the "no basin" marker. Encoders that compute basins lazily can
 /// short-circuit Skip/Merge/Delta and emit Escape directly when this
 /// fires.
+///
+/// ```
+/// use ndarray::hpc::codec::{is_no_basin, BASIN_NONE};
+/// assert!(is_no_basin(BASIN_NONE));
+/// assert!(!is_no_basin(0));
+/// ```
 #[inline]
 pub fn is_no_basin(basin_idx: u16) -> bool {
     basin_idx == BASIN_NONE
@@ -394,4 +428,52 @@ mod tests {
         assert!(!is_no_basin(0));
         assert!(!is_no_basin(100));
     }
+
+    #[test]
+    fn overflow_delta_does_not_alias_to_merge() {
+        // Regression for the wrapping-cast Merge alias bug:
+        // δ = 200 (overflows i8) must NOT match a neighbour whose
+        // u8 byte equals (200 as u8) = 0xC8 (= -56 in i8). The
+        // encoder must take the Escape path (or, here, the lossy
+        // clamp fallback because no allocator is wired).
+        let nb_alias = LeafCu::delta(100, 0xC8);
+        let neighbours = [Some(&nb_alias), None, None, None];
+        let leaf = predict_intra(&ctx_with_neighbours(100, 200, neighbours), &IntraConfig::default());
+        assert_ne!(leaf.mode, CellMode::Merge, "overflow δ must not Merge");
+        // With no allocator the encoder clamps to +127 (lossy Delta).
+        assert_eq!(leaf.mode, CellMode::Delta);
+        assert_eq!(leaf.delta, Some(127));
+    }
+
+    #[test]
+    fn overflow_delta_with_allocator_takes_escape() {
+        let nb_alias = LeafCu::delta(100, 0xC8);
+        let neighbours = [Some(&nb_alias), None, None, None];
+        let cfg = IntraConfig {
+            escape_next_idx: Some(7),
+        };
+        let leaf = predict_intra(&ctx_with_neighbours(100, 200, neighbours), &cfg);
+        assert_eq!(leaf.mode, CellMode::Escape);
+        assert_eq!(leaf.escape_idx, Some(7));
+    }
+
+    #[test]
+    fn pack_leaf_accepts_mode_sized_buffers() {
+        // Regression for the P2 6-byte-minimum bug: Skip should pack
+        // into a 2-byte buffer, Merge/Delta into a 3-byte buffer.
+        use super::super::mode::{pack_leaf, packed_byte_len};
+        let skip = LeafCu::skip(10);
+        let mut buf2 = [0u8; 2];
+        assert_eq!(pack_leaf(&skip, &mut buf2), Some(2));
+        assert_eq!(packed_byte_len(CellMode::Skip), 2);
+
+        let delta = LeafCu::delta(10, 7);
+        let mut buf3 = [0u8; 3];
+        assert_eq!(pack_leaf(&delta, &mut buf3), Some(3));
+
+        // Escape still needs 6 bytes; a 3-byte buffer is rejected.
+        let esc = LeafCu::escape(10, 99);
+        let mut buf3b = [0u8; 3];
+        assert_eq!(pack_leaf(&esc, &mut buf3b), None);
+    }
 }