feat(accel): runtime-dispatched int8 dot product

The int8-quantised HNSW index compared vectors with a scalar loop that
the compiler vectorised for the x86-64 baseline (SSE2), while the f32
path it was measured against goes through `clawhdf5-accel` and runs
AVX2. So the ~13% throughput cost recorded for `quantized_index` was a
missing kernel rather than a property of int8.

`clawhdf5_accel::dot_i8` adds a scalar fallback and an AVX2 path:
sign-extend each 16-byte half to i16, then `madd_epi16`, which
multiplies and sums adjacent pairs straight into i32 lanes. It is
dispatched through the same detected backend as the f32 kernels, and
the index now calls it.

Integer arithmetic, so the SIMD path must agree with scalar bit for
bit — tested at lengths that are and are not multiples of the block,
and at the -128 extreme for overflow.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

crates/clawhdf5-accel/src/lib.rs

@@ -122,6 +122,23 @@ pub fn dot_product(a: &[f32], b: &[f32]) -> f32 {
     }
 }
 
+/// Dot product of two `i8` slices, widened to `i32`.
+///
+/// The kernel behind int8-quantised vector search. Uses the AVX2 path
+/// whenever AVX2 is present — including on AVX-512 machines, where it is
+/// what the f32 kernels use too on a default build.
+pub fn dot_i8(a: &[i8], b: &[i8]) -> i32 {
+    match detect_backend() {
+        #[cfg(target_arch = "x86_64")]
+        // SAFETY: both variants imply AVX2 was detected at runtime (the
+        // AVX-512 backend is only selected on CPUs that also have AVX2).
+        Backend::Avx2 | Backend::Avx512 if is_x86_feature_detected!("avx2") => unsafe {
+            avx2::dot_i8(a, b)
+        },
+        _ => scalar::dot_i8(a, b),
+    }
+}
+
 /// Compute the L2 norm (magnitude) of a vector.
 pub fn vector_norm(v: &[f32]) -> f32 {
     dot_product(v, v).sqrt()
@@ -713,3 +730,42 @@ mod tests {
         }
     }
 }
+
+#[cfg(test)]
+mod dot_i8_tests {
+    use super::*;
+
+    fn codes(n: usize, seed: u64) -> Vec<i8> {
+        let mut state = seed;
+        (0..n)
+            .map(|_| {
+                state = state
+                    .wrapping_mul(6_364_136_223_846_793_005)
+                    .wrapping_add(1_442_695_040_888_963_407);
+                // Full range, including the extremes.
+                ((state >> 56) as u8) as i8
+            })
+            .collect()
+    }
+
+    #[test]
+    fn dispatched_kernel_matches_scalar_exactly() {
+        // Integer arithmetic: the SIMD path must agree bit for bit, at every
+        // length — including ones that are not multiples of the 32-byte block,
+        // which exercise the tail.
+        for len in [0, 1, 7, 31, 32, 33, 63, 64, 100, 384, 385, 1536] {
+            let a = codes(len, 1 + len as u64);
+            let b = codes(len, 1000 + len as u64);
+            assert_eq!(dot_i8(&a, &b), scalar::dot_i8(&a, &b), "len {len}");
+        }
+    }
+
+    #[test]
+    fn extremes_do_not_overflow() {
+        // -128 * -128 is the largest product; a long run of it must still fit.
+        let a = vec![-128i8; 4096];
+        assert_eq!(dot_i8(&a, &a), 4096 * 128 * 128);
+        let b = vec![127i8; 4096];
+        assert_eq!(dot_i8(&a, &b), -4096 * 128 * 127);
+    }
+}