feat(hpc): LazyLock frozen SIMD dispatch table — detect once, keep CPU choice forever

simd_dispatch.rs (300+ lines, 7 tests):

  SimdDispatch: struct of function pointers, frozen at first access via LazyLock.
  Each field is a fn pointer to the best available implementation for this CPU.
  After initialization: one pointer deref + one indirect call. Zero branching.

  SimdTier enum: Avx512 / Avx2 / Sse2 / Scalar / WasmSimd128 (future).
  Selected once based on simd_caps() detection. Frozen forever.

  Before: if simd_caps().avx512f { avx512_fn() } else { scalar_fn() }  → ~1ns + branch
  After:  (SIMD_DISPATCH.fn_ptr)(args)                                  → ~0.3ns, no branch

  Dispatch targets (6 free functions across 4 modules):
    byte_scan:    byte_find_all, byte_count (AVX-512 / AVX2 / scalar)
    distance:     squared_distances_f32 (AVX2 / scalar)
    nibble:       nibble_unpack, nibble_above_threshold (AVX2 / scalar)
    spatial_hash: batch_sq_dist (AVX2 / scalar)

  NOTE: aabb.rs and cam_pq.rs dispatch on &self methods (not free functions)
  so they keep inline simd_caps() branching. The dispatch table covers
  the free function hot paths.

  Visibility: internal SIMD functions promoted from pub(super)/private
  to pub(crate) so the dispatch table can reference them as fn pointers.

  The 8 existing per-call dispatch sites in nibble/byte_scan/distance/
  spatial_hash/aabb/cam_pq still work — the dispatch table is additive.
  Consumers can migrate to simd_dispatch().fn_ptr() incrementally.

  TODO (separate PR): Rust 1.94 stabilized safe #[target_feature] on
  safe functions. The `unsafe` on SIMD functions is legacy debt that
  should be removed. The dispatch wrappers currently bridge this with
  SAFETY comments; once unsafe is removed, the wrappers simplify to
  direct function pointer assignment.

https://claude.ai/code/session_01Y69Vnw751w75iVSBRws7o7

Author: claude

src/hpc/byte_scan.rs

@@ -9,15 +9,15 @@
 // ---------------------------------------------------------------------------
 
 #[cfg(target_arch = "x86_64")]
-mod simd_impl {
+pub(crate) mod simd_impl {
     use core::arch::x86_64::*;
 
     /// Find all positions of `needle` in `haystack` using AVX2 (32 bytes/iter).
     ///
     /// # Safety
     /// Caller must ensure AVX2 is available.
     #[target_feature(enable = "avx2")]
-    pub(super) unsafe fn byte_find_all_avx2(haystack: &[u8], needle: u8) -> Vec<usize> {
+    pub(crate) unsafe fn byte_find_all_avx2(haystack: &[u8], needle: u8) -> Vec<usize> {
         let mut result = Vec::new();
         let n = haystack.len();
         let ptr = haystack.as_ptr();
@@ -52,7 +52,7 @@ mod simd_impl {
     /// # Safety
     /// Caller must ensure AVX-512 BW is available.
     #[target_feature(enable = "avx512bw")]
-    pub(super) unsafe fn byte_find_all_avx512(haystack: &[u8], needle: u8) -> Vec<usize> {
+    pub(crate) unsafe fn byte_find_all_avx512(haystack: &[u8], needle: u8) -> Vec<usize> {
         let mut result = Vec::new();
         let n = haystack.len();
         let ptr = haystack.as_ptr();
@@ -84,7 +84,7 @@ mod simd_impl {
     /// # Safety
     /// Caller must ensure AVX2 is available.
     #[target_feature(enable = "avx2")]
-    pub(super) unsafe fn byte_count_avx2(haystack: &[u8], needle: u8) -> usize {
+    pub(crate) unsafe fn byte_count_avx2(haystack: &[u8], needle: u8) -> usize {
         let n = haystack.len();
         let ptr = haystack.as_ptr();
         let needle_v = _mm256_set1_epi8(needle as i8);
@@ -111,7 +111,7 @@ mod simd_impl {
     /// # Safety
     /// Caller must ensure AVX-512 BW is available.
     #[target_feature(enable = "avx512bw")]
-    pub(super) unsafe fn byte_count_avx512(haystack: &[u8], needle: u8) -> usize {
+    pub(crate) unsafe fn byte_count_avx512(haystack: &[u8], needle: u8) -> usize {
         let n = haystack.len();
         let ptr = haystack.as_ptr();
         let needle_v = _mm512_set1_epi8(needle as i8);

src/hpc/distance.rs

@@ -29,7 +29,7 @@ fn sq_dist_f64(a: [f64; 3], b: [f64; 3]) -> f64 {
 // ---------------------------------------------------------------------------
 
 #[cfg(target_arch = "x86_64")]
-mod simd_impl {
+pub(crate) mod simd_impl {
     #[cfg(target_arch = "x86_64")]
     use core::arch::x86_64::*;
 
@@ -39,7 +39,7 @@ mod simd_impl {
     /// # Safety
     /// Caller must ensure AVX2 is available.
     #[target_feature(enable = "avx2")]
-    pub(super) unsafe fn squared_distances_avx2(
+    pub(crate) unsafe fn squared_distances_avx2(
         query: [f32; 3],
         points: &[[f32; 3]],
         out: &mut Vec<f32>,

src/hpc/mod.rs

@@ -21,6 +21,8 @@
 
 // SIMD capability singleton — detect once, all modules share
 pub mod simd_caps;
+// LazyLock frozen SIMD dispatch — function pointers selected once at startup
+pub mod simd_dispatch;
 
 pub mod blas_level1;
 pub mod blas_level2;

src/hpc/nibble.rs

@@ -40,7 +40,7 @@ pub fn nibble_unpack(packed: &[u8], count: usize) -> Vec<u8> {
     out
 }
 
-fn nibble_unpack_scalar(packed: &[u8], count: usize, out: &mut Vec<u8>) {
+pub(crate) fn nibble_unpack_scalar(packed: &[u8], count: usize, out: &mut Vec<u8>) {
     for i in 0..count {
         let byte = packed[i / 2];
         let val = if i & 1 == 0 { byte & 0x0F } else { byte >> 4 };
@@ -54,7 +54,7 @@ fn nibble_unpack_scalar(packed: &[u8], count: usize, out: &mut Vec<u8>) {
 /// Caller must ensure AVX2 is available and `count >= 32`.
 #[cfg(target_arch = "x86_64")]
 #[target_feature(enable = "avx2")]
-unsafe fn nibble_unpack_avx2(packed: &[u8], count: usize, out: &mut Vec<u8>) {
+pub(crate) unsafe fn nibble_unpack_avx2(packed: &[u8], count: usize, out: &mut Vec<u8>) {
     use core::arch::x86_64::*;
 
     let low_mask = _mm_set1_epi8(0x0F);
@@ -252,7 +252,7 @@ pub fn nibble_above_threshold(packed: &[u8], threshold: u8) -> Vec<usize> {
     nibble_above_threshold_scalar(packed, threshold)
 }
 
-fn nibble_above_threshold_scalar(packed: &[u8], threshold: u8) -> Vec<usize> {
+pub(crate) fn nibble_above_threshold_scalar(packed: &[u8], threshold: u8) -> Vec<usize> {
     let mut result = Vec::new();
     let count = packed.len() * 2;
     for i in 0..count {
@@ -272,7 +272,7 @@ fn nibble_above_threshold_scalar(packed: &[u8], threshold: u8) -> Vec<usize> {
 /// Caller must ensure AVX2 is available and `packed.len() >= 16`.
 #[cfg(target_arch = "x86_64")]
 #[target_feature(enable = "avx2")]
-unsafe fn nibble_above_threshold_avx2(packed: &[u8], threshold: u8) -> Vec<usize> {
+pub(crate) unsafe fn nibble_above_threshold_avx2(packed: &[u8], threshold: u8) -> Vec<usize> {
     use core::arch::x86_64::*;
 
     let mut result = Vec::new();