fix(hpc): address #218 review — fidelity length-guard + edge_codec examples & decode asserts

- reliability: FidelityReport::compute returns a DEGENERATE report (zeros,
  rel_l2=1.0) on length mismatch instead of silently truncating to the shorter
  prefix (codex P2 + coderabbit Major) — consistent with the module's
  return-degenerate-not-panic convention; a dropped tail can't read as high fidelity.
- edge_codec: added runnable /// examples to the 6 remaining public methods
  (Codebook::assign/centroid, CoarseResidueCodec::encode/reconstruct,
  ProductQuantizer::encode/reconstruct) per all-public-APIs-need-examples.
- edge_codec: both reconstruct() decoders now assert the packed-code length
  (dim/2, m/2) so malformed input fails with a clear message instead of an
  out-of-bounds panic deep in unpack (coderabbit Major).

edge_codec doctests 4→10; reliability 5; unit tests green; clippy -D warnings clean.

https://claude.ai/code/session_01D2WSmezQBNC3bUdHuGfGmo

Author: claude

src/hpc/edge_codec.rs

@@ -130,6 +130,14 @@ impl Codebook {
 
     /// Index of the nearest centroid to `v` (scalar; identical result to the
     /// AMX `matmul_i8_to_i32` assignment path). Panics if `v.len() != dim`.
+    ///
+    /// # Examples
+    /// ```
+    /// use ndarray::hpc::edge_codec::Codebook;
+    /// let data = [0.0, 0.0, 9.0, 9.0]; // 2 points × dim 2
+    /// let cb = Codebook::train(&data, 2, 2, 2, 5, 1);
+    /// assert!(cb.assign(&[9.0, 9.0]) < cb.k as u32);
+    /// ```
     #[inline]
     pub fn assign(&self, v: &[f32]) -> u32 {
         assert_eq!(v.len(), self.dim);
@@ -146,6 +154,14 @@ impl Codebook {
     }
 
     /// Borrow centroid `c` as a slice.
+    ///
+    /// # Examples
+    /// ```
+    /// use ndarray::hpc::edge_codec::Codebook;
+    /// let data = [0.0, 0.0, 9.0, 9.0];
+    /// let cb = Codebook::train(&data, 2, 2, 2, 5, 1);
+    /// assert_eq!(cb.centroid(0).len(), 2);
+    /// ```
     #[inline]
     pub fn centroid(&self, c: usize) -> &[f32] {
         &self.centroids[c * self.dim..(c + 1) * self.dim]
@@ -245,6 +261,15 @@ impl CoarseResidueCodec {
     }
 
     /// Encode one vector to coarse index + packed residue nibbles.
+    ///
+    /// # Examples
+    /// ```
+    /// use ndarray::hpc::edge_codec::CoarseResidueCodec;
+    /// let data: Vec<f32> = (0..8 * 4).map(|i| (i % 5) as f32 - 2.0).collect();
+    /// let codec = CoarseResidueCodec::fit(&data, 8, 4, 4, 6, 1);
+    /// let code = codec.encode(&data[0..4]);
+    /// assert_eq!(code.residue.len(), 2); // dim/2 packed bytes
+    /// ```
     pub fn encode(&self, v: &[f32]) -> CoarseResidueCode {
         let dim = self.cb.dim;
         let index = self.cb.assign(v);
@@ -261,9 +286,20 @@ impl CoarseResidueCodec {
         }
     }
 
-    /// Reconstruct `centroid + dequantized residue`.
+    /// Reconstruct `centroid + dequantized residue`. Panics if `code.residue` is
+    /// not the expected `dim/2` packed bytes (guards malformed decode input).
+    ///
+    /// # Examples
+    /// ```
+    /// use ndarray::hpc::edge_codec::CoarseResidueCodec;
+    /// let data: Vec<f32> = (0..8 * 4).map(|i| (i % 5) as f32 - 2.0).collect();
+    /// let codec = CoarseResidueCodec::fit(&data, 8, 4, 4, 6, 1);
+    /// let v = codec.reconstruct(&codec.encode(&data[0..4]));
+    /// assert_eq!(v.len(), 4);
+    /// ```
     pub fn reconstruct(&self, code: &CoarseResidueCode) -> Vec<f32> {
         let dim = self.cb.dim;
+        assert_eq!(code.residue.len(), dim / 2, "residue must be dim/2 packed bytes");
         let c = self.cb.centroid(code.index as usize);
         let res = unpack_nibbles_signed(&code.residue, dim);
         (0..dim)
@@ -320,6 +356,14 @@ impl ProductQuantizer {
     }
 
     /// Encode one vector to `m/2` packed nibble bytes (16 bytes when `m = 32`).
+    ///
+    /// # Examples
+    /// ```
+    /// use ndarray::hpc::edge_codec::ProductQuantizer;
+    /// let data: Vec<f32> = (0..32 * 8).map(|i| ((i * 7 % 11) as f32) - 5.0).collect();
+    /// let pq = ProductQuantizer::fit(&data, 32, 8, 4, 6, 1);
+    /// assert_eq!(pq.encode(&data[0..8]).len(), 2); // m/2 bytes
+    /// ```
     pub fn encode(&self, v: &[f32]) -> Vec<u8> {
         let codes: Vec<i8> = (0..self.m)
             .map(|s| {
@@ -334,8 +378,19 @@ impl ProductQuantizer {
             .collect()
     }
 
-    /// Reconstruct by concatenating the selected sub-centroids.
+    /// Reconstruct by concatenating the selected sub-centroids. Panics if `code`
+    /// is not the expected `m/2` packed bytes (guards malformed decode input).
+    ///
+    /// # Examples
+    /// ```
+    /// use ndarray::hpc::edge_codec::ProductQuantizer;
+    /// let data: Vec<f32> = (0..32 * 8).map(|i| ((i * 7 % 11) as f32) - 5.0).collect();
+    /// let pq = ProductQuantizer::fit(&data, 32, 8, 4, 6, 1);
+    /// let v = pq.reconstruct(&pq.encode(&data[0..8]));
+    /// assert_eq!(v.len(), 8);
+    /// ```
     pub fn reconstruct(&self, code: &[u8]) -> Vec<f32> {
+        assert_eq!(code.len(), self.m / 2, "code must be m/2 packed bytes");
         let mut out = vec![0.0f32; self.m * self.sub_dim];
         for s in 0..self.m {
             let byte = code[s / 2];

src/hpc/reliability.rs

@@ -232,7 +232,13 @@ pub struct FidelityReport {
 }
 
 impl FidelityReport {
-    /// Compute every coefficient for `(truth, estimate)` (equal-length samples).
+    /// Compute every coefficient for `(truth, estimate)`.
+    ///
+    /// Mismatched lengths are a caller error and yield a **degenerate** report
+    /// (all coefficients `0.0`, `rel_l2 = 1.0`) rather than silently truncating to
+    /// the shorter prefix — consistent with the module's return-degenerate (never
+    /// panic, never hide) convention, so a dropped tail cannot masquerade as high
+    /// fidelity.
     ///
     /// # Examples
     /// ```
@@ -242,10 +248,27 @@ impl FidelityReport {
     /// let r = FidelityReport::compute(&truth, &est);
     /// assert!(r.pearson > 0.99 && r.spearman > 0.99);
     /// assert!(r.rel_l2 < 0.1);
+    /// // Mismatched lengths → degenerate (does NOT truncate-then-score):
+    /// let bad = FidelityReport::compute(&[1.0, 2.0, 100.0], &[1.0, 2.0]);
+    /// assert_eq!(bad.pearson, 0.0);
+    /// assert_eq!(bad.rel_l2, 1.0);
     /// ```
     pub fn compute(truth: &[f64], estimate: &[f64]) -> Self {
-        let n = truth.len().min(estimate.len());
-        let (t, e) = (&truth[..n], &estimate[..n]);
+        // Length mismatch is a caller bug: return a degenerate (all-zero,
+        // max-error) report rather than truncating to the shorter prefix, which
+        // could hide a dropped tail behind a falsely-high score.
+        if truth.len() != estimate.len() {
+            return FidelityReport {
+                pearson: 0.0,
+                spearman: 0.0,
+                icc: 0.0,
+                cronbach: 0.0,
+                rel_l2: 1.0,
+                cosine: 0.0,
+            };
+        }
+        let n = truth.len();
+        let (t, e) = (truth, estimate);
         let mut se = 0.0;
         let mut st = 0.0;
         let mut dot = 0.0;