fix(helix): address CodeRabbit review — NaN guard + f32 clamp epsilon

Two valid review findings on PR #459:

1. placement.rs: HemispherePoint::lift produced NaN for n >= total
   (u > 1 -> sqrt(1-u) = NaN). lift is public API, so an external caller
   got a silent NaN. Clamp u to <= 1.0 so out-of-range n saturates to the
   rim (r=1, y=0), matching the documented no-NaN contract. Added the
   lift_out_of_range_n_saturates_to_rim test.

2. simd.rs: the batch Fisher-Z clamp epsilon 1e-9 is below the f32 ULP
   near 1.0 (~1.19e-7), so 1.0 - 1e-9 rounded to 1.0f32 and the clamp was
   a no-op -- s = +/-1 produced ln(0) = -inf. Bumped EPS to 1e-6 (the f64
   Similarity::fisher_z keeps 1e-9). Added the
   batch_fisher_z_boundary_inputs_are_finite test (+/-1, out-of-range).

The third comment (ndarray::simd::U8x64 "missing") is a false positive:
the ndarray-hpc feature resolves ndarray to the AdaWorldAPI fork at
../../../ndarray (which provides ::simd), not crates.io ndarray 0.16.1 --
the feature builds and tests green. Added a Cargo.toml note documenting
the sibling-fork requirement.

63 unit + 6 doctests pass on both feature configs; clippy -D warnings and
rustfmt clean.

https://claude.ai/code/session_013rjF2Dvo1DnBACpbpYSffE

Author: claude

crates/helix/Cargo.toml

@@ -22,6 +22,11 @@ ndarray = { path = "../../../ndarray", optional = true, default-features = false
 default = []
 # Activate the ndarray-accelerated hot path (simd_ln_f32 / U8x64 batch kernels).
 # The always-present scalar path is used when this is disabled.
+#
+# NOTE: this feature resolves `ndarray` to the AdaWorldAPI fork at the sibling
+# path `../../../ndarray` (NOT crates.io `ndarray`, which has no `::simd` module).
+# It therefore requires that sibling repo to be checked out — the same convention
+# `lance-graph` core uses. The default build is zero-dep and needs none of this.
 ndarray-hpc = ["dep:ndarray"]
 
 [dev-dependencies]

crates/helix/src/placement.rs

@@ -60,8 +60,8 @@ impl HemispherePoint {
     /// # Arguments
     ///
     /// * `n` — zero-based residue index (0 ≤ n < total is the intended range;
-    ///   larger values are accepted and produce `r > 1`, which the Fisher-Z step
-    ///   will clip or reject).
+    ///   `n ≥ total` saturates to the rim — `u` is clamped to 1.0, giving
+    ///   `r = 1`, `y = 0` (a finite point, never NaN)).
     /// * `total` — the total number of residue slots N. Clamped to 1 if zero.
     ///
     /// # Examples
@@ -75,7 +75,7 @@ impl HemispherePoint {
     /// ```
     pub fn lift(n: usize, total: usize) -> Self {
         let total = total.max(1);
-        let u = (n as f64 + 0.5) / total as f64;
+        let u = ((n as f64 + 0.5) / total as f64).min(1.0);
         let r = u.sqrt();
         let y = (1.0 - u).sqrt();
         let azimuth = n as f64 * GOLDEN_RATIO;
@@ -252,6 +252,27 @@ mod tests {
         assert!((sum - 1.0).abs() < 1e-12, "r²+y² should be 1, got {sum}");
     }
 
+    // ── out-of-range n saturates to the rim (no NaN) ─────────────────────────
+
+    #[test]
+    fn lift_out_of_range_n_saturates_to_rim() {
+        // n ≥ total clamps u to 1.0 → r = 1, y = 0 (a finite rim point, not NaN).
+        let p = HemispherePoint::lift(10, 4);
+        assert!(
+            p.r.is_finite() && p.y.is_finite(),
+            "rim point must be finite"
+        );
+        assert!(
+            (p.r - 1.0).abs() < 1e-12,
+            "r should saturate to 1, got {}",
+            p.r
+        );
+        assert!(p.y.abs() < 1e-12, "y should saturate to 0, got {}", p.y);
+        // n == total is the boundary and must also be safe
+        let q = HemispherePoint::lift(4, 4);
+        assert!(q.r.is_finite() && q.y.is_finite());
+    }
+
     // ── cartesian: x² + z² = r² and overall unit sphere ────────────────────
 
     #[test]

crates/helix/src/simd.rs

@@ -12,10 +12,13 @@
 //! Both functions are correctness-equivalent across the two builds — the feature
 //! is a pure accelerator, never a behaviour change.
 
-const EPS: f32 = 1e-9;
+// f32 clamp guard. Must exceed the f32 ULP near 1.0 (≈1.19e-7) so that
+// `1.0 - EPS` is strictly < 1.0 in f32 — otherwise `ln(1 - s) = ln(0) = -inf`
+// leaks through for `s = ±1`. (The f64 `Similarity::fisher_z` can use 1e-9.)
+const EPS: f32 = 1e-6;
 
 /// Batch Fisher-Z `z = ½·(ln(1+s) − ln(1−s))` over `similarities` into `out`
-/// (each input clamped to `±(1 − 1e-9)`). `out.len()` must equal
+/// (each input clamped to `±(1 − 1e-6)`). `out.len()` must equal
 /// `similarities.len()`. (ndarray `simd_ln_f32` path.)
 #[cfg(feature = "ndarray-hpc")]
 pub fn batch_fisher_z(similarities: &[f32], out: &mut [f32]) {
@@ -117,6 +120,18 @@ mod tests {
         }
     }
 
+    #[test]
+    fn batch_fisher_z_boundary_inputs_are_finite() {
+        // ±1 and out-of-range inputs must clamp to a finite result — the f32 EPS
+        // must exceed the f32 ULP near 1.0, else ln(0) = -inf leaks through.
+        let s = [1.0f32, -1.0, 2.0, -2.0, 0.999_999, -0.999_999];
+        let mut out = vec![0f32; s.len()];
+        batch_fisher_z(&s, &mut out);
+        for (i, o) in out.iter().enumerate() {
+            assert!(o.is_finite(), "out[{i}] = {o} must be finite");
+        }
+    }
+
     #[test]
     fn batch_l1_u8_is_abs_diff() {
         let a: Vec<u8> = (0..130u16).map(|x| x as u8).collect();