fix(hpc/blocked_grid): UB — overlapping &mut [T] in GridBlockMut (codex P1×2)

Codex review on PR #158 flagged two P1 soundness bugs:

1. `BaseBlockIterMut::next()` yields `GridBlockMut` instances carrying
   `data: &'a mut [T]` slices over the strided block footprint
   (`[start..start + (BR-1)*padded_cols + BC]`). For grids with multiple
   block columns, adjacent column blocks' slices overlap heavily — e.g.,
   on a 64×128 padded grid with 64×64 blocks, block (0,0) covers
   `data[0..8128]` and block (0,1) covers `data[64..8192]`. Two such
   `&mut [T]` simultaneously live = UB.

2. `TierBlockIterMut::next()` yields `GridSuperBlockMut` instances with
   `data: *mut T` set to `data_ptr.add(row_origin * padded_cols)` —
   col_origin doesn't enter the offset, so adjacent super-blocks in the
   same row receive IDENTICAL raw pointers spanning the full row slab.
   `base_blocks_mut()` then materialized strided `&mut [T]` from these
   colliding super-block pointers, propagating the UB.

Both bugs trace to the same root cause: `GridBlockMut::data` stored
a strided `&'a mut [T]` slice that referenced cells outside the block's
own column range. Adjacent column blocks fundamentally share rows that
interleave in memory; no contiguous `&mut [T]` can describe a block
without aliasing siblings.

Fix: change `GridBlockMut::data` from `&'a mut [T]` to `*mut T` + add
`data_len: usize` for bounds checking. The struct's new aliasing
invariant (documented in the type-level docstring) is: `data` is NEVER
converted to a wide `&mut [T]`; cell access happens exclusively through
`row_mut(r)`, which materializes `&mut [T]` of length BC starting at
the block's own `(row_origin + r, col_origin)`. Across blocks, these
per-row materializations target disjoint cells (each block owns its
own `[col_origin, col_origin + BC)` column range), so no two live
`&mut [T]` ever alias.

Also:
- `GridBlockMut::from_raw` is now `unsafe fn` with documented caller
  contract (raw pointer + length + per-block column-disjoint invariant)
- Added `unsafe impl Send + Sync` for `GridBlockMut<T: Send/Sync>`
  matching the existing pattern on `BaseBlockIterMut` / `GridSuperBlockMut`
- Renamed `GridBlockMut::padded_cols` pub(crate) accessor to
  `padded_cols_stride` for naming consistency with `GridBlock`
  (resolves a PR-X3.1 housekeeping item early)
- Replaced `data_mut() -> &mut [T]` pub(crate) accessor with
  `data_ptr() -> *mut T` + `data_len() -> usize`. The wide-slice
  accessor was the materialization vehicle for the UB.
- Updated `iter.rs::row_mut` to materialize via `slice::from_raw_parts_mut`
  with a debug_assert bounds check and verbatim SAFETY comment
- Updated `super_block.rs::base_blocks_mut` to pass raw pointer + length
  to the new unsafe `from_raw` (no intermediate strided slice)
- Updated `super_block.rs::tier_mut_2_mutation_visible` test to use
  `row_mut(0)[0]` instead of the removed `data_mut()` accessor

All 5 gates still green:
- cargo check: PASS
- cargo test --lib hpc::blocked_grid: 111/111 PASS
- cargo test --doc hpc::blocked_grid: 79/79 PASS
- cargo fmt --check: clean
- cargo clippy -D warnings: clean

Codex audit gap noted for PR-X3.1: future audits need a SAFETY-claim
verification gate that simulates adversarial iterator usage (e.g.,
collect all yielded items into a Vec before consuming any) to catch
this class of latent UB that passes type-checking but violates the
aliasing model.

Author: claude

src/hpc/blocked_grid/base.rs

@@ -448,19 +448,54 @@ impl<'a, T, const BR: usize, const BC: usize> GridBlock<'a, T, BR, BC> {
 /// assert_eq!(blk.block_row(), 0);
 /// assert_eq!(blk.block_col(), 0);
 /// ```
+/// Mutable view of a `BR × BC` base block.
+///
+/// # Aliasing invariant
+///
+/// `GridBlockMut` stores a raw `*mut T` pointer + `data_len` rather than a
+/// `&'a mut [T]` slice. The strided layout of base blocks means adjacent
+/// column blocks share rows that interleave in memory (block (r, c) and
+/// block (r, c+1) on the same block-row overlap by `(BR-1)*padded_cols + BC -
+/// BC = (BR-1)*padded_cols` cells if represented as a single strided slice).
+/// A strided `&mut [T]` would be unsound when two such blocks coexist (as
+/// `BaseBlockIterMut` allows when callers `.next()` multiple times before
+/// dropping prior items).
+///
+/// Soundness is preserved by **never materializing a `&mut [T]` over the
+/// strided footprint**. Cell access goes through [`row_mut`] which produces
+/// `&mut [T]` of length BC only — exactly one logical row of the block.
+/// Across blocks, row materializations target disjoint cell ranges (each
+/// block owns its own `[col_origin, col_origin + BC)` column range on the
+/// shared physical rows), so no two simultaneous `&mut [T]` ever alias.
+///
+/// [`row_mut`]: GridBlockMut::row_mut
 pub struct GridBlockMut<'a, T, const BR: usize, const BC: usize> {
     block_row: usize,
     block_col: usize,
     row_origin: usize,
     col_origin: usize,
     padded_cols: usize,
-    /// Points to the element at `(row_origin, col_origin)` in the parent grid's
-    /// flat storage. Length is `BR * padded_cols` minus the trailing gap
-    /// (covers the last block row up to the final cell).
-    data: &'a mut [T],
+    /// Raw pointer to cell `(row_origin, col_origin)` in the parent grid's
+    /// flat storage. See the type-level aliasing invariant — `data` is
+    /// **never** converted to a `&mut [T]` that covers the strided footprint.
+    data: *mut T,
+    /// Number of elements addressable from `data`. Equals
+    /// `(BR - 1) * padded_cols + BC` for non-zero BR (or 0 if BR is 0),
+    /// clamped to the parent grid's remaining storage. Used for bounds
+    /// checking; the slice is never materialized at this full length.
+    data_len: usize,
     _marker: PhantomData<&'a mut T>,
 }
 
+// SAFETY: `GridBlockMut` holds a raw pointer that the issuing iterator
+// (`BaseBlockIterMut` or `GridSuperBlockMut::base_blocks_mut`) creates from a
+// single `&'a mut BlockedGrid` borrow. The aliasing invariant documented on
+// the struct guarantees that simultaneously-live `GridBlockMut`s never
+// materialize overlapping `&mut [T]` slices, so cross-thread Send/Sync are
+// safe under T: Send / T: Sync.
+unsafe impl<'a, T: Send, const BR: usize, const BC: usize> Send for GridBlockMut<'a, T, BR, BC> {}
+unsafe impl<'a, T: Sync, const BR: usize, const BC: usize> Sync for GridBlockMut<'a, T, BR, BC> {}
+
 impl<'a, T, const BR: usize, const BC: usize> GridBlockMut<'a, T, BR, BC> {
     /// Construct a `GridBlockMut` from a mutable grid reference and block coordinates.
     ///
@@ -475,21 +510,26 @@ impl<'a, T, const BR: usize, const BC: usize> GridBlockMut<'a, T, BR, BC> {
     pub fn from_grid(grid: &'a mut BlockedGrid<T, BR, BC>, block_row: usize, block_col: usize) -> Self {
         let row_origin = block_row * BR;
         let col_origin = block_col * BC;
-        let start = row_origin * grid.padded_cols + col_origin;
-        let end = if BR == 0 {
-            start
-        } else {
-            start + (BR - 1) * grid.padded_cols + BC
-        };
-        let end = end.min(grid.data.len());
         let padded_cols = grid.padded_cols;
+        let start = row_origin * padded_cols + col_origin;
+        let raw_len = if BR == 0 { 0 } else { (BR - 1) * padded_cols + BC };
+        let data_len = raw_len.min(grid.data.len().saturating_sub(start));
+        // SAFETY: `start` is within `grid.data.len()` because the iterator
+        // (or direct caller) gates `(block_row, block_col)` to valid block
+        // coordinates. `data_len` is clamped to the remaining storage. The
+        // raw pointer is offset from a unique `&'a mut BlockedGrid` borrow;
+        // although adjacent column-block raw pointers cover overlapping
+        // strided regions, the struct's aliasing invariant (see GridBlockMut
+        // doc) ensures no `&mut [T]` is ever materialized over the overlap.
+        let data = unsafe { grid.data.as_mut_ptr().add(start) };
         Self {
             block_row,
             block_col,
             row_origin,
             col_origin,
             padded_cols,
-            data: &mut grid.data[start..end],
+            data,
+            data_len,
             _marker: PhantomData,
         }
     }
@@ -542,30 +582,47 @@ impl<'a, T, const BR: usize, const BC: usize> GridBlockMut<'a, T, BR, BC> {
         self.col_origin
     }
 
-    /// Access internal mutable data slice (intra-crate seam used by `iter.rs`
-    /// / `compute.rs`). `pub(crate)` — not exposed downstream since callers
-    /// should go through `GridBlockMut::row_mut`, which enforces the BR
-    /// bound.
-    pub(crate) fn data_mut(&mut self) -> &mut [T] {
+    /// Raw data pointer (intra-crate seam used by `iter.rs::row_mut`). Returns
+    /// a `*mut T` that callers MUST NOT convert to a wide `&mut [T]` covering
+    /// the block's strided footprint — see the type-level aliasing invariant.
+    /// The only sound use is `unsafe { slice::from_raw_parts_mut(ptr.add(r *
+    /// padded_cols_stride()), BC) }` for `r < BR`, which `row_mut` performs.
+    pub(crate) fn data_ptr(&mut self) -> *mut T {
         self.data
     }
 
-    /// Access padded_cols stride (intra-crate seam — see `data_mut` note).
-    /// NOTE: Named `padded_cols` (not `padded_cols_stride` as on `GridBlock`)
-    /// for back-compat with `iter.rs`'s `row_mut` impl. Naming consistency is
-    /// queued as PR-X3.1 housekeeping.
-    pub(crate) fn padded_cols(&self) -> usize {
+    /// Number of elements addressable from `data_ptr` (intra-crate seam used
+    /// for debug-build bounds checks in `row_mut`).
+    pub(crate) fn data_len(&self) -> usize {
+        self.data_len
+    }
+
+    /// Access padded_cols stride (intra-crate seam — see `data_ptr` note).
+    /// NOTE: Named `padded_cols_stride` to match `GridBlock`. The
+    /// previous `padded_cols` name is gone (Q-X3.1 housekeeping resolved
+    /// in this commit).
+    pub(crate) fn padded_cols_stride(&self) -> usize {
         self.padded_cols
     }
 
     /// Construct a `GridBlockMut` directly from raw components.
     ///
-    /// Used by super_block.rs (worker A3) to construct mutable base-block views
-    /// inside a super-block without needing `T: Copy`.  The caller is responsible
-    /// for ensuring that `data` is a valid exclusive sub-slice of the parent
-    /// grid's flat storage with the correct `padded_cols` stride.
-    pub(super) fn from_raw(
-        data: &'a mut [T], block_row: usize, block_col: usize, row_origin: usize, col_origin: usize, padded_cols: usize,
+    /// Used by super_block.rs (worker A3) to construct mutable base-block
+    /// views inside a super-block without needing `T: Copy`.
+    ///
+    /// # Safety
+    ///
+    /// The caller must guarantee that:
+    /// - `data` points to a valid element in the parent grid's flat storage
+    /// - `data_len` is the number of elements addressable from `data` (equal to
+    ///   `(BR - 1) * padded_cols + BC` for non-zero BR, clamped to the remaining
+    ///   storage)
+    /// - `data` and `data_len` together cover the strided footprint of one
+    ///   `BR × BC` block; no other live `GridBlockMut` will materialize an
+    ///   overlapping `&mut [T]` over the same physical cells
+    pub(super) unsafe fn from_raw(
+        data: *mut T, data_len: usize, block_row: usize, block_col: usize, row_origin: usize, col_origin: usize,
+        padded_cols: usize,
     ) -> Self {
         Self {
             block_row,
@@ -574,6 +631,7 @@ impl<'a, T, const BR: usize, const BC: usize> GridBlockMut<'a, T, BR, BC> {
             col_origin,
             padded_cols,
             data,
+            data_len,
             _marker: PhantomData,
         }
     }

src/hpc/blocked_grid/iter.rs

@@ -305,9 +305,29 @@ impl<'a, T, const BR: usize, const BC: usize> GridBlockMut<'a, T, BR, BC> {
     /// ```
     pub fn row_mut(&mut self, r: usize) -> &mut [T] {
         debug_assert!(r < BR, "row {} out of block range {}", r, BR);
-        let stride = self.padded_cols();
+        let stride = self.padded_cols_stride();
         let start = r * stride;
-        &mut self.data_mut()[start..start + BC]
+        debug_assert!(
+            start + BC <= self.data_len(),
+            "row materialization {} extends past data_len {}",
+            start + BC,
+            self.data_len()
+        );
+        let ptr = self.data_ptr();
+        // SAFETY: This is the SOLE materialization site for a `&mut [T]` over
+        // a `GridBlockMut`'s storage. The slice has length BC and starts at
+        // `(row_origin + r, col_origin)`, covering exactly one logical row of
+        // the block (cells `[col_origin, col_origin + BC)`). This range is
+        // **disjoint** from any other live `GridBlockMut`'s row materialization
+        // because:
+        //   - Adjacent column-block rows (same physical grid row, different
+        //     block_col) have non-overlapping `[col_origin, col_origin + BC)`
+        //     intervals.
+        //   - Adjacent row-block rows (different block_row) target different
+        //     physical grid rows entirely.
+        // The bounds check above confirms `start + BC <= data_len`, ensuring
+        // the pointer arithmetic stays within the parent grid's allocation.
+        unsafe { std::slice::from_raw_parts_mut(ptr.add(start), BC) }
     }
 }
 

src/hpc/blocked_grid/super_block.rs

@@ -295,26 +295,26 @@ impl<'a, T, const BR: usize, const BC: usize, const N: usize> GridSuperBlockMut<
                 let abs_col_origin = col_origin_abs + local_bc * BC;
 
                 let start = local_br * BR * padded_cols + abs_col_origin;
-                let end = if BR == 0 {
-                    start
-                } else {
-                    start + (BR - 1) * padded_cols + BC
-                };
-                let end = end.min(data_len);
-
-                // SAFETY: Each (local_br, local_bc) pair accesses a
-                // non-overlapping sub-region of the super-block's data buffer.
-                // Base blocks within the N×N super-block occupy disjoint
-                // row ranges (local_br selects which BR-row group) and disjoint
-                // column positions within each row (local_bc selects which BC
-                // column group).  The iterator yields them one at a time, so
-                // the caller cannot hold two simultaneous mutable borrows to
-                // the same data.  `data_ptr` is valid for `data_len` elements
-                // — guaranteed by `TierBlockIterMut` which derives it from the
-                // grid's `Vec<T>`.
-                let slice = unsafe { std::slice::from_raw_parts_mut(data_ptr.add(start), end - start) };
-
-                GridBlockMut::from_raw(slice, abs_block_row, abs_block_col, abs_row_origin, abs_col_origin, padded_cols)
+                let raw_len = if BR == 0 { 0 } else { (BR - 1) * padded_cols + BC };
+                let block_data_len = raw_len.min(data_len.saturating_sub(start));
+
+                // SAFETY: data_ptr was issued by TierBlockIterMut from a
+                // unique `&'a mut BlockedGrid` borrow; data_len elements from
+                // data_ptr are within the grid's allocation. (start,
+                // block_data_len) stays within those bounds. We pass the raw
+                // pointer (not a materialized slice) to GridBlockMut::from_raw
+                // because the strided footprint of adjacent column-blocks
+                // overlaps in memory — GridBlockMut's aliasing invariant
+                // ensures `&mut [T]` is only ever materialized per-row via
+                // `row_mut`, where each block's column range [col_origin,
+                // col_origin+BC) is disjoint from siblings.
+                let block_data = unsafe { data_ptr.add(start) };
+                unsafe {
+                    GridBlockMut::from_raw(
+                        block_data, block_data_len, abs_block_row, abs_block_col, abs_row_origin, abs_col_origin,
+                        padded_cols,
+                    )
+                }
             })
         })
     }
@@ -804,11 +804,9 @@ mod tests {
             // Write via base_blocks_mut: set first cell of first base block.
             for mut blk in sb.base_blocks_mut() {
                 if blk.block_row() == sr * 2 && blk.block_col() == sc * 2 {
-                    // Use base_blocks_mut raw data — access via data_mut()
-                    let d = blk.data_mut();
-                    if !d.is_empty() {
-                        d[0] = sentinel;
-                    }
+                    // Materialize one row slice (sound — see GridBlockMut
+                    // aliasing invariant); write cell 0.
+                    blk.row_mut(0)[0] = sentinel;
                     break;
                 }
             }