ptwm 1.0.1__tar.gz → 1.1.0__tar.gz

{ptwm-1.0.1 → ptwm-1.1.0}/Cargo.lock

@@ -1945,7 +1945,7 @@ dependencies = [
 
 [[package]]
 name = "ptwm-core"
-version = "1.0.1"
+version = "1.1.0"
 dependencies = [
  "blake3",
  "ciborium",
@@ -1980,7 +1980,7 @@ dependencies = [
 
 [[package]]
 name = "ptwm-py"
-version = "1.0.1"
+version = "1.1.0"
 dependencies = [
  "hex",
  "memmap2",

{ptwm-1.0.1 → ptwm-1.1.0}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/ptwm-core", "crates/ptwm-py"]
 
 [workspace.package]
-version = "1.0.1"
+version = "1.1.0"
 edition = "2024"
 rust-version = "1.87"
 license = "MIT"

{ptwm-1.0.1 → ptwm-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ptwm
-Version: 1.0.1
+Version: 1.1.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -354,8 +354,8 @@ fields; see its docstring for the full list.
 | `bfloat16` / `float16` | Bit reorder + 2-plane byte split | Exponent → plane 1 |
 | `float8_e4m3fn` / `float8_e5m2` | Bit reorder + 2-plane nibble split | Exponent → high nibble |
 | `float4_e2m1fn_x2` (weight nibbles) | Passthrough, per-plane trial-encode | `PerGroupCodebook` competes against Huffman / rANS on the nibble-packed byte stream |
-| MXFP4 scale (`uint8`, E8M0) | Passthrough, per-plane trial-encode | Pure 8-bit exponent with no row structure to exploit; compresses to ≈ 0.16 of original via the generic codec menu |
-| NVFP4 scale (FP8-E4M3) | `Order1ScaleAC` (per-row lag-1 arithmetic coding) | Mantissa bits give exploitable row autocorrelation that E8M0 lacks |
+| MXFP4 scale (`uint8`, E8M0) | `Order1ScaleAC` (per-row lag-1 arithmetic coding), per-plane trial-encode | Rows are autocorrelated: on gpt-oss-20b the entropy given the previous scale in the row is 1.20 bits, against 1.89 bits unconditioned |
+| NVFP4 scale (FP8-E4M3) | `Order1ScaleAC` (per-row lag-1 arithmetic coding) | Mantissa bits give exploitable row autocorrelation |
 | `int8`, `uint8`, `int16`, `int32`, `int64`, `bool` | Single stream | No byte split or bit reorder yet; whatever wins per-plane trial-encode on the raw bytes |
 
 MXFP4 / NVFP4 tensors are compressed as a pair: the packed FP4 weight

{ptwm-1.0.1 → ptwm-1.1.0}/README.md

@@ -314,8 +314,8 @@ fields; see its docstring for the full list.
 | `bfloat16` / `float16` | Bit reorder + 2-plane byte split | Exponent → plane 1 |
 | `float8_e4m3fn` / `float8_e5m2` | Bit reorder + 2-plane nibble split | Exponent → high nibble |
 | `float4_e2m1fn_x2` (weight nibbles) | Passthrough, per-plane trial-encode | `PerGroupCodebook` competes against Huffman / rANS on the nibble-packed byte stream |
-| MXFP4 scale (`uint8`, E8M0) | Passthrough, per-plane trial-encode | Pure 8-bit exponent with no row structure to exploit; compresses to ≈ 0.16 of original via the generic codec menu |
-| NVFP4 scale (FP8-E4M3) | `Order1ScaleAC` (per-row lag-1 arithmetic coding) | Mantissa bits give exploitable row autocorrelation that E8M0 lacks |
+| MXFP4 scale (`uint8`, E8M0) | `Order1ScaleAC` (per-row lag-1 arithmetic coding), per-plane trial-encode | Rows are autocorrelated: on gpt-oss-20b the entropy given the previous scale in the row is 1.20 bits, against 1.89 bits unconditioned |
+| NVFP4 scale (FP8-E4M3) | `Order1ScaleAC` (per-row lag-1 arithmetic coding) | Mantissa bits give exploitable row autocorrelation |
 | `int8`, `uint8`, `int16`, `int32`, `int64`, `bool` | Single stream | No byte split or bit reorder yet; whatever wins per-plane trial-encode on the raw bytes |
 
 MXFP4 / NVFP4 tensors are compressed as a pair: the packed FP4 weight

{ptwm-1.0.1 → ptwm-1.1.0}/crates/ptwm-core/src/codecs/arithmetic.rs

@@ -5,6 +5,7 @@
 //! planes).
 
 use crate::codec::{CodecId, Encoded, PlaneCodec};
+use crate::codecs::length_prefix;
 use crate::entropy::arithmetic::{
     Order0Adaptive, Order0Static, Order1Adaptive, decode_bytes, encode_bytes,
 };
@@ -12,22 +13,35 @@ use crate::error::PtwmCoreError;
 use crate::layout::PlaneLayout;
 use crate::types::descriptor::PlaneDescriptor;
 
-/// Absolute cap on the framed decoded length, mirroring `rans.rs`. Guards a
-/// hostile length prefix from driving a multi-GiB decode loop.
-const MAX_DECODED_LEN: usize = 1 << 30; // 1 GiB
-
 /// Prepend the true decoded length (u32 LE) so decode is self-delimiting.
 ///
+/// Fails when the decoder would refuse the length (see
+/// [`length_prefix::accepted`]); these coders have no raw fallback.
+///
 /// The container's `decode` receives a `decoded_len` derived from the
 /// *source-tensor* descriptor, which for byte-split planes is larger than the
 /// actual plane length. Self-delimiting codecs (Huffman, rANS, …) ignore that
 /// argument and recover the length from their own payload; the arithmetic
 /// coders do the same here rather than trusting `decoded_len`.
-pub(crate) fn frame_payload(decoded_len: usize, payload: &[u8]) -> Vec<u8> {
+pub(crate) fn frame_payload(
+    decoded_len: usize,
+    payload: &[u8],
+    codec: &'static str,
+) -> Result<Vec<u8>, PtwmCoreError> {
+    if !length_prefix::accepted(decoded_len, payload.len()) {
+        return Err(PtwmCoreError::CodecEncode {
+            codec,
+            msg: format!(
+                "decoded length {decoded_len} with {} encoded bytes exceeds the length-prefix limit",
+                payload.len()
+            ),
+        });
+    }
     let mut out = Vec::with_capacity(4 + payload.len());
+    // `accepted` guarantees the length fits the u32 prefix.
     out.extend_from_slice(&(decoded_len as u32).to_le_bytes());
     out.extend_from_slice(payload);
-    out
+    Ok(out)
 }
 
 /// Inverse of [`frame_payload`]: read the length prefix and return the rest.
@@ -42,13 +56,15 @@ pub(crate) fn unframe_payload<'a>(
         });
     }
     let n = u32::from_le_bytes([payload[0], payload[1], payload[2], payload[3]]) as usize;
-    if n > MAX_DECODED_LEN {
+    let body = &payload[4..];
+    // Guards a hostile length prefix from driving a multi-GiB decode loop.
+    if !length_prefix::accepted(n, body.len()) {
         return Err(PtwmCoreError::CodecDecode {
             codec,
             msg: format!("implausible decoded length {n}"),
         });
     }
-    Ok((n, &payload[4..]))
+    Ok((n, body))
 }
 
 /// Order-0 arithmetic coder with a serialized normalized table.
@@ -85,7 +101,11 @@ impl PlaneCodec for ArithmeticO0 {
             });
         }
         let mut model = Order0Static::fit(plane);
-        let payload = frame_payload(plane.len(), &encode_bytes(&mut model, plane));
+        let payload = frame_payload(
+            plane.len(),
+            &encode_bytes(&mut model, plane),
+            "arithmetic_o0",
+        )?;
         Ok(Encoded {
             state_bytes: model.serialize(),
             state_format_version: 1,
@@ -156,7 +176,8 @@ impl PlaneCodec for ArithmeticO0Adaptive {
         let payload = frame_payload(
             plane.len(),
             &encode_bytes(&mut Order0Adaptive::new(), plane),
-        );
+            "arithmetic_o0_adaptive",
+        )?;
         Ok(Encoded {
             state_bytes: Vec::new(),
             state_format_version: 0,
@@ -229,7 +250,8 @@ impl PlaneCodec for ArithmeticO1 {
         let payload = frame_payload(
             plane.len(),
             &encode_bytes(&mut Order1Adaptive::new(), plane),
-        );
+            "arithmetic_o1",
+        )?;
         Ok(Encoded {
             state_bytes: Vec::new(),
             state_format_version: 0,
@@ -419,8 +441,8 @@ mod tests {
         let data: Vec<u8> = (0..262144)
             .map(|i| match i % 16 {
                 0..=9 => 0x40u8,
-                10 | 11 | 12 => 0x41,
-                13 | 14 => 0x3F,
+                10..=12 => 0x41,
+                13..=14 => 0x3F,
                 _ => 0x42,
             })
             .collect();
@@ -435,4 +457,21 @@ mod tests {
             "arithmetic O0 ({ac_total}) must not exceed Huffman ({huff_total}) on a structured plane",
         );
     }
+
+    #[test]
+    fn unframe_rejects_a_short_payload_declaring_a_large_plane() {
+        let mut payload = length_prefix::SHORT_BODY_DECLARED_LEN
+            .to_le_bytes()
+            .to_vec();
+        payload.extend_from_slice(&[0u8; 64]);
+        assert!(unframe_payload(&payload, "arithmetic_o0").is_err());
+    }
+
+    #[test]
+    fn frame_and_unframe_agree_on_the_length() {
+        let framed = frame_payload(5, &[1, 2, 3], "arithmetic_o0").unwrap();
+        let (n, body) = unframe_payload(&framed, "arithmetic_o0").unwrap();
+        assert_eq!((n, body), (5, &[1u8, 2, 3][..]));
+        assert!(frame_payload(length_prefix::RATIO_FREE_LEN + 1, &[0], "arithmetic_o0").is_err());
+    }
 }

{ptwm-1.0.1 → ptwm-1.1.0}/crates/ptwm-core/src/codecs/huff_llm.rs

@@ -64,7 +64,7 @@ impl PlaneCodec for HuffLlm5Bit {
         _layout: &PlaneLayout,
     ) -> bool {
         // Skip tiny planes (three table headers don't amortize) and odd lengths.
-        plane.len() >= MIN_WORDS * 2 && plane.len() % 2 == 0
+        plane.len() >= MIN_WORDS * 2 && plane.len().is_multiple_of(2)
     }
 
     fn encode(
@@ -82,7 +82,7 @@ impl PlaneCodec for HuffLlm5Bit {
         // Empty or odd-length → raw store (still total). Short-circuit empty
         // before allocating `words`, since trial-encode hits this path on every
         // candidate.
-        if plane.is_empty() || plane.len() % 2 != 0 {
+        if plane.is_empty() || !plane.len().is_multiple_of(2) {
             return Ok(raw_store(plane));
         }
         let words: Vec<u16> = plane

{ptwm-1.0.1 → ptwm-1.1.0}/crates/ptwm-core/src/codecs/huffman.rs

@@ -57,10 +57,10 @@ impl PlaneCodec for Huffman {
         }
 
         let mut buf = vec![0u8; huffman_output_bound(plane.len())];
-        match huffman::compress_outcome(&mut buf, plane)? {
-            CompressOutcome::Encoded(n) => {
+        let outcome = huffman::compress_outcome(&mut buf, plane)?;
+        match (outcome, u32::try_from(plane.len())) {
+            (CompressOutcome::Encoded(n), Ok(orig_len)) => {
                 // TAG_HUF | orig_len (4 bytes LE) | huffman-encoded bytes
-                let orig_len = plane.len() as u32;
                 let mut payload = Vec::with_capacity(1 + 4 + n);
                 payload.push(TAG_HUF);
                 payload.extend_from_slice(&orig_len.to_le_bytes());
@@ -71,9 +71,10 @@ impl PlaneCodec for Huffman {
                     payload,
                 })
             }
-            _outcome => {
+            _ => {
                 // NotBeneficial / Incompressible / DstTooSmall /
-                // LenOverflow → store raw
+                // LenOverflow, or a plane longer than the u32 length
+                // prefix → store raw
                 let mut payload = Vec::with_capacity(1 + plane.len());
                 payload.push(TAG_RAW);
                 payload.extend_from_slice(plane);

ptwm-1.1.0/crates/ptwm-core/src/codecs/length_prefix.rs

@@ -0,0 +1,89 @@
+//! Acceptance rule for the decoded length a plane payload declares.
+//!
+//! rANS, tANS, and the arithmetic coders prefix their payload with the
+//! decoded length as a little-endian `u32`, and the decoder sizes its output
+//! (or its decode loop) from that prefix before reading the body. A corrupted
+//! or hostile prefix must not drive an arbitrarily large allocation, so the
+//! decoder checks it against [`accepted`]. Encoders apply the same rule before
+//! writing a prefix, so every plane they emit is one their decoder accepts.
+
+/// Decoded length accepted at any compression ratio.
+///
+/// These coders reach very high ratios on near-degenerate distributions (an
+/// all-zero 64 KiB plane encodes to about 30 bytes), so below this size the
+/// rule bounds the length alone.
+pub(crate) const RATIO_FREE_LEN: usize = 1 << 30; // 1 GiB
+
+/// Largest decoded-to-encoded length ratio accepted above [`RATIO_FREE_LEN`].
+///
+/// A payload that declares more than [`RATIO_FREE_LEN`] bytes must carry at
+/// least `1 / MAX_RATIO` of that length as encoded body, which bounds the
+/// allocation a short payload can request. Weight planes this large (a BF16
+/// embedding or output projection of a large-vocabulary model) compress far
+/// less than this.
+pub(crate) const MAX_RATIO: usize = 64;
+
+/// Whether a payload declaring `decoded_len` bytes from an encoded body of
+/// `body_len` bytes is accepted.
+///
+/// Lengths that do not fit the `u32` prefix are never accepted.
+pub(crate) fn accepted(decoded_len: usize, body_len: usize) -> bool {
+    u32::try_from(decoded_len).is_ok()
+        && (decoded_len <= RATIO_FREE_LEN || decoded_len <= body_len.saturating_mul(MAX_RATIO))
+}
+
+/// Bytes from a skewed distribution (about 2 bits per byte), long enough to
+/// exercise lengths above [`RATIO_FREE_LEN`] while staying far below
+/// [`MAX_RATIO`].
+#[cfg(test)]
+pub(crate) fn skewed_bytes(len: usize) -> Vec<u8> {
+    let mut x: u64 = 0x9E37_79B9_7F4A_7C15;
+    (0..len)
+        .map(|_| {
+            x ^= x << 13;
+            x ^= x >> 7;
+            x ^= x << 17;
+            x.trailing_zeros().min(15) as u8
+        })
+        .collect()
+}
+
+/// A payload body shorter than `1 / MAX_RATIO` of the 3 GiB it declares.
+#[cfg(test)]
+pub(crate) const SHORT_BODY_DECLARED_LEN: u32 = 3 << 30;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn any_ratio_is_accepted_up_to_the_ratio_free_length() {
+        assert!(accepted(0, 0));
+        assert!(accepted(RATIO_FREE_LEN, 1));
+    }
+
+    #[test]
+    fn a_large_plane_at_a_weight_like_ratio_is_accepted() {
+        // A BF16 embedding of a 128256-token, 8192-wide model, at the ratio
+        // rANS reached on it.
+        let decoded = 128_256 * 8192 * 2;
+        assert!(decoded > RATIO_FREE_LEN);
+        assert!(accepted(decoded, 1_611_325_931));
+    }
+
+    #[test]
+    fn a_short_body_cannot_declare_a_large_plane() {
+        let decoded = RATIO_FREE_LEN + 1;
+        assert!(!accepted(decoded, 16));
+        assert!(!accepted(decoded, decoded / MAX_RATIO - 1));
+        assert!(accepted(decoded, decoded.div_ceil(MAX_RATIO)));
+    }
+
+    #[test]
+    #[cfg(target_pointer_width = "64")]
+    fn lengths_beyond_the_u32_prefix_are_rejected() {
+        let too_long = u32::MAX as usize + 1;
+        assert!(!accepted(too_long, too_long));
+        assert!(accepted(u32::MAX as usize, u32::MAX as usize));
+    }
+}

{ptwm-1.0.1 → ptwm-1.1.0}/crates/ptwm-core/src/codecs/mod.rs

@@ -4,6 +4,7 @@ pub mod fpc;
 pub mod huff_llm;
 pub mod huffman;
 pub mod identity;
+pub(crate) mod length_prefix;
 pub mod neural_predictor;
 pub mod order1_arithmetic;
 pub mod order1_scale_ac;

{ptwm-1.0.1 → ptwm-1.1.0}/crates/ptwm-core/src/codecs/order1_arithmetic.rs

@@ -72,7 +72,11 @@ impl PlaneCodec for Order1Arithmetic {
             });
         }
         let mut model = Order1Static::fit(plane);
-        let payload = frame_payload(plane.len(), &encode_bytes(&mut model, plane));
+        let payload = frame_payload(
+            plane.len(),
+            &encode_bytes(&mut model, plane),
+            "order1_arithmetic",
+        )?;
         Ok(Encoded {
             state_bytes: model.serialize(),
             state_format_version: STATE_FORMAT_VERSION,

{ptwm-1.0.1 → ptwm-1.1.0}/crates/ptwm-core/src/codecs/order1_scale_ac.rs

@@ -453,16 +453,19 @@ impl PlaneCodec for Order1ScaleAC {
 
     fn accepts(&self, descriptor: &PlaneDescriptor) -> bool {
         // O1SAC requires byte-width Scale or GlobalScale planes with row layout
-        // AND an FP8 scale format (E4M3 or E5M2). The codec models per-row
-        // lag-1 PMFs over scale bytes — a structure that exists in FP8 scale
-        // distributions (mantissa bits give a continuous distribution with
-        // exploitable autocorrelation) but not in E8M0 scales, which are pure
-        // 8-bit exponents (no sign, no mantissa) used by MXFP4 block scales.
-        // Allow-listing E4M3/E5M2 keeps the codec inside its design domain;
-        // future scale formats need explicit vetting before being admitted.
+        // and a vetted scale format. The codec models per-row lag-1 PMFs over
+        // scale bytes. FP8 scales (E4M3, E5M2) carry that structure, and so do
+        // MXFP4's E8M0 block scales: across gpt-oss-20b's 597M E8M0 scales the
+        // entropy conditioned on the previous scale in the row is 1.20
+        // bits against 1.89 bits unconditioned. Trial encoding still picks the
+        // smallest codec per plane. Future scale formats need the same vetting
+        // before being admitted.
         let role_ok = match descriptor.role {
             Role::Scale { format } | Role::GlobalScale { format } => {
-                matches!(format, ScaleFormat::E4M3 | ScaleFormat::E5M2)
+                matches!(
+                    format,
+                    ScaleFormat::E4M3 | ScaleFormat::E5M2 | ScaleFormat::E8M0
+                )
             }
             _ => false,
         };
@@ -1081,10 +1084,8 @@ mod capability_tests {
     }
 
     #[test]
-    fn o1sac_rejects_e8m0_scale() {
-        // E8M0 (MXFP4 block scale) is a pure 8-bit exponent — structurally
-        // different from FP8 scales (E4M3 / E5M2) and outside O1SAC's design
-        // domain.
+    fn o1sac_accepts_e8m0_scale() {
+        // E8M0 (MXFP4 block scale) rows are autocorrelated like FP8 scale rows.
         let c = Order1ScaleAC;
         let d = descriptor(
             Role::Scale {
@@ -1094,11 +1095,11 @@ mod capability_tests {
             Layout::Rows { row_len: 32 },
             false,
         );
-        assert!(!c.accepts(&d));
+        assert!(c.accepts(&d));
     }
 
     #[test]
-    fn o1sac_rejects_e8m0_global_scale() {
+    fn o1sac_accepts_e8m0_global_scale() {
         let c = Order1ScaleAC;
         let d = descriptor(
             Role::GlobalScale {
@@ -1108,7 +1109,7 @@ mod capability_tests {
             Layout::Rows { row_len: 16 },
             false,
         );
-        assert!(!c.accepts(&d));
+        assert!(c.accepts(&d));
     }
 
     #[test]

{ptwm-1.0.1 → ptwm-1.1.0}/crates/ptwm-core/src/codecs/per_group_codebook.rs

@@ -405,10 +405,28 @@ impl PlaneCodec for PerGroupCodebook {
         CodecId::PerGroupCodebook
     }
 
+    /// Accept expanded FP4 value planes whose length divides into whole
+    /// groups.
+    ///
+    /// The codec models one nibble per byte, and `GROUP_SIZE` of 32 is one
+    /// MXFP4 block: the unit that shares a scale, and therefore the unit
+    /// worth giving its own codebook. `MxFp4Deinterleave` produces exactly
+    /// that, 32 single-nibble slots per block.
+    ///
+    /// Two exclusions are deliberate. A *packed* plane, two values per
+    /// byte, is declined rather than misread: reading one would take low
+    /// nibbles only and return them with the high half zeroed, silently
+    /// losing half the data. Such a plane must be deinterleaved first. And
+    /// a length that is not a whole number of groups is declined here
+    /// rather than failing inside `encode`, because dispatch drops the
+    /// whole candidate chain when a codec errors and packed FP4 has only
+    /// one chain to drop. Declining keeps an `encode` error meaning what it
+    /// should: an invariant was violated, not merely an unsuitable input.
     fn accepts(&self, descriptor: &PlaneDescriptor) -> bool {
-        descriptor.is_nibble_packed
+        !descriptor.is_nibble_packed
             && matches!(descriptor.role, Role::Value { .. })
             && descriptor.element_width == ElementWidth::Nibble
+            && (descriptor.length_bytes as usize).is_multiple_of(GROUP_SIZE)
     }
 
     fn priority_for(&self, descriptor: &PlaneDescriptor) -> i8 {
@@ -793,27 +811,27 @@ mod capability_tests {
     }
 
     #[test]
-    fn pgc_accepts_nibble_packed_value_nibble() {
+    fn pgc_accepts_expanded_value_nibble() {
         let c = PerGroupCodebook;
         let d = descriptor(
             Role::Value {
                 format: ValueFormat::Fp4E2m1,
             },
             ElementWidth::Nibble,
-            true,
+            false,
         );
         assert!(c.accepts(&d));
     }
 
     #[test]
-    fn pgc_rejects_not_nibble_packed() {
+    fn pgc_rejects_packed_plane() {
         let c = PerGroupCodebook;
         let d = descriptor(
             Role::Value {
                 format: ValueFormat::Fp4E2m1,
             },
             ElementWidth::Nibble,
-            false,
+            true,
         );
         assert!(!c.accepts(&d));
     }
@@ -826,7 +844,7 @@ mod capability_tests {
                 format: ScaleFormat::E4M3,
             },
             ElementWidth::Nibble,
-            true,
+            false,
         );
         assert!(!c.accepts(&d));
     }
@@ -839,7 +857,7 @@ mod capability_tests {
                 format: ValueFormat::Fp4E2m1,
             },
             ElementWidth::Byte,
-            true,
+            false,
         );
         assert!(!c.accepts(&d));
     }
@@ -852,7 +870,7 @@ mod capability_tests {
                 format: ValueFormat::Fp4E2m1,
             },
             ElementWidth::Nibble,
-            true,
+            false,
         );
         assert_eq!(c.priority_for(&d), 10);
     }
@@ -865,8 +883,131 @@ mod capability_tests {
                 format: ScaleFormat::E4M3,
             },
             ElementWidth::Nibble,
-            true,
+            false,
         );
         assert_eq!(c.priority_for(&d), i8::MIN);
     }
 }
+
+/// End-to-end coverage for the producer this codec is actually built for.
+///
+/// The suite previously exercised the codec only on hand-built planes. It
+/// never drove the op that supplies it in practice, which is how a
+/// descriptor mismatch between the two survived: `MxFp4Deinterleave`
+/// labelled its output nibble-packed while emitting one nibble per byte,
+/// and the codec's own contract expects the expanded form.
+#[cfg(test)]
+mod deinterleave_integration_tests {
+    use super::*;
+    use crate::transforms::mxfp4_deinterleave::MxFp4Deinterleave;
+    use crate::transforms::op::{Op, Plane};
+    use crate::types::descriptor::{Layout, PlaneDescriptor};
+    use crate::types::role::Role;
+
+    const BLOCK_BYTES: usize = 17;
+
+    /// OCP MXFP4 wire bytes: 16 packed-nibble bytes then one E8M0 scale.
+    fn mxfp4_blocks(n_blocks: usize, seed: u64) -> Vec<u8> {
+        let mut s = seed.wrapping_mul(0x9E37_79B9_7F4A_7C15) | 1;
+        let mut out = Vec::with_capacity(n_blocks * BLOCK_BYTES);
+        for b in 0..n_blocks {
+            for _ in 0..16 {
+                s ^= s << 13;
+                s ^= s >> 7;
+                s ^= s << 17;
+                // Skewed within a block, varying across blocks, so a
+                // per-block codebook has structure to find.
+                let lo = (s % 4 + (b as u64 % 3) * 4) as u8 & 0x0F;
+                let hi = ((s >> 8) % 4 + (b as u64 % 3) * 4) as u8 & 0x0F;
+                out.push(lo | (hi << 4));
+            }
+            out.push(0x80 | (b as u8 & 0x0F));
+        }
+        out
+    }
+
+    fn raw_descriptor(len: usize) -> PlaneDescriptor {
+        PlaneDescriptor {
+            role: Role::Raw,
+            element_width: ElementWidth::Byte,
+            length_bytes: len as u64,
+            layout: Layout::Flat,
+            derives_from_tensor: None,
+            residual_of: None,
+            is_nibble_packed: false,
+            vendor_bytes: vec![],
+        }
+    }
+
+    #[test]
+    fn codec_accepts_and_round_trips_the_deinterleaved_value_plane() {
+        let n_blocks = 8;
+        let raw = mxfp4_blocks(n_blocks, 11);
+        let op = MxFp4Deinterleave::new(32).unwrap();
+
+        let descs = op
+            .propagate_descriptors(&[raw_descriptor(raw.len())])
+            .unwrap();
+        let value_desc = descs[0].clone();
+
+        // One group per MXFP4 block is the whole premise of the codec.
+        assert_eq!(value_desc.length_bytes as usize, n_blocks * GROUP_SIZE);
+
+        let c = PerGroupCodebook;
+        assert!(
+            c.accepts(&value_desc),
+            "the codec must accept the plane its own producer emits: {value_desc:?}"
+        );
+
+        let planes = op
+            .forward(&[Plane::new(raw.clone(), raw_descriptor(raw.len())).unwrap()])
+            .unwrap();
+        let value_plane = planes[0].bytes.to_vec();
+        assert_eq!(value_plane.len(), n_blocks * GROUP_SIZE);
+        assert!(
+            value_plane.iter().all(|&b| b <= 0x0F),
+            "the value plane is one nibble per byte, so no byte exceeds 0x0F"
+        );
+
+        let enc = c.encode(&value_plane, None, &PlaneLayout::Flat).unwrap();
+        let dec = c
+            .decode(
+                enc.state_format_version,
+                &enc.state_bytes,
+                &enc.payload,
+                &PlaneLayout::Flat,
+                value_plane.len(),
+            )
+            .unwrap();
+        assert_eq!(
+            dec, value_plane,
+            "codec must be lossless on its own producer"
+        );
+    }
+
+    #[test]
+    fn codec_declines_a_genuinely_packed_plane_instead_of_halving_it() {
+        // Two values per byte. Reading this as one-nibble-per-byte would
+        // drop every high nibble, which is exactly the silent loss the
+        // `accepts` guard exists to prevent.
+        let mut d = raw_descriptor(64);
+        d.role = Role::Value {
+            format: crate::types::role::ValueFormat::Fp4E2m1,
+        };
+        d.element_width = ElementWidth::Nibble;
+        d.is_nibble_packed = true;
+        assert!(!PerGroupCodebook.accepts(&d));
+    }
+
+    #[test]
+    fn codec_declines_a_length_that_is_not_whole_groups() {
+        // Declined rather than failed in `encode`: packed FP4 has one
+        // candidate chain, and a codec error drops the chain entirely.
+        let mut d = raw_descriptor(GROUP_SIZE + 1);
+        d.role = Role::Value {
+            format: crate::types::role::ValueFormat::Fp4E2m1,
+        };
+        d.element_width = ElementWidth::Nibble;
+        assert!(!PerGroupCodebook.accepts(&d));
+    }
+}