usearch 2.26.1 → 2.26.2

package/numkong/include/numkong/set/serial.h

@@ -23,8 +23,7 @@
  *  nk_jaccard_u1x128_init_serial(&state_first);
  *  // ... stream through packed binary vectors ...
  *  nk_jaccard_u1x128_finalize_serial(&state_first, &state_second, &state_third, &state_fourth,
- *      query_popcount, target_popcount_a, target_popcount_b, target_popcount_c, target_popcount_d,
- *      total_dimensions, &results);
+ *      query_popcount, &target_popcounts_vec, total_dimensions, &result_vec);
  *  @endcode
  */
 #ifndef NK_SET_SERIAL_H
@@ -99,8 +98,8 @@ NK_INTERNAL void nk_jaccard_u1x128_update_serial(nk_jaccard_u1x128_state_serial_
 NK_INTERNAL void nk_jaccard_u1x128_finalize_serial( //
     nk_jaccard_u1x128_state_serial_t const *state_a, nk_jaccard_u1x128_state_serial_t const *state_b,
     nk_jaccard_u1x128_state_serial_t const *state_c, nk_jaccard_u1x128_state_serial_t const *state_d,
-    nk_f32_t query_popcount, nk_f32_t target_popcount_a, nk_f32_t target_popcount_b, nk_f32_t target_popcount_c,
-    nk_f32_t target_popcount_d, nk_size_t total_dimensions, nk_b128_vec_t *result) {
+    nk_f32_t query_popcount, nk_b128_vec_t const *target_popcounts_vec, nk_size_t total_dimensions,
+    nk_b128_vec_t *result_vec) {
     nk_unused_(total_dimensions);
 
     nk_f32_t intersection_a = (nk_f32_t)state_a->intersection_count;
@@ -108,15 +107,15 @@ NK_INTERNAL void nk_jaccard_u1x128_finalize_serial( //
     nk_f32_t intersection_c = (nk_f32_t)state_c->intersection_count;
     nk_f32_t intersection_d = (nk_f32_t)state_d->intersection_count;
 
-    nk_f32_t union_a = query_popcount + target_popcount_a - intersection_a;
-    nk_f32_t union_b = query_popcount + target_popcount_b - intersection_b;
-    nk_f32_t union_c = query_popcount + target_popcount_c - intersection_c;
-    nk_f32_t union_d = query_popcount + target_popcount_d - intersection_d;
+    nk_f32_t union_a = query_popcount + target_popcounts_vec->f32s[0] - intersection_a;
+    nk_f32_t union_b = query_popcount + target_popcounts_vec->f32s[1] - intersection_b;
+    nk_f32_t union_c = query_popcount + target_popcounts_vec->f32s[2] - intersection_c;
+    nk_f32_t union_d = query_popcount + target_popcounts_vec->f32s[3] - intersection_d;
 
-    result->f32s[0] = (union_a != 0) ? 1.0f - intersection_a / union_a : 0.0f;
-    result->f32s[1] = (union_b != 0) ? 1.0f - intersection_b / union_b : 0.0f;
-    result->f32s[2] = (union_c != 0) ? 1.0f - intersection_c / union_c : 0.0f;
-    result->f32s[3] = (union_d != 0) ? 1.0f - intersection_d / union_d : 0.0f;
+    result_vec->f32s[0] = (union_a != 0) ? 1.0f - intersection_a / union_a : 0.0f;
+    result_vec->f32s[1] = (union_b != 0) ? 1.0f - intersection_b / union_b : 0.0f;
+    result_vec->f32s[2] = (union_c != 0) ? 1.0f - intersection_c / union_c : 0.0f;
+    result_vec->f32s[3] = (union_d != 0) ? 1.0f - intersection_d / union_d : 0.0f;
 }
 
 typedef struct nk_hamming_u1x128_state_serial_t {
@@ -150,18 +149,18 @@ NK_INTERNAL void nk_hamming_u1x128_finalize_serial( //
 }
 
 /** @brief Hamming from_dot: computes pop_a + pop_b - 2*dot for 4 pairs (serial). */
-NK_INTERNAL void nk_hamming_u32x4_from_dot_serial_(nk_b128_vec_t dots, nk_u32_t query_pop, nk_b128_vec_t target_pops,
-                                                   nk_b128_vec_t *results) {
-    for (int i = 0; i < 4; ++i) results->u32s[i] = query_pop + target_pops.u32s[i] - 2 * dots.u32s[i];
+NK_INTERNAL void nk_hamming_u32x4_from_dot_serial_(nk_b128_vec_t const *dots_vec, nk_u32_t query_pop,
+                                                   nk_b128_vec_t const *target_pops_vec, nk_b128_vec_t *result_vec) {
+    for (int i = 0; i < 4; ++i) result_vec->u32s[i] = query_pop + target_pops_vec->u32s[i] - 2 * dots_vec->u32s[i];
 }
 
 /** @brief Jaccard from_dot: computes 1 - dot / (pop_a + pop_b - dot) for 4 pairs (serial). */
-NK_INTERNAL void nk_jaccard_f32x4_from_dot_serial_(nk_b128_vec_t dots, nk_u32_t query_pop, nk_b128_vec_t target_pops,
-                                                   nk_b128_vec_t *results) {
+NK_INTERNAL void nk_jaccard_f32x4_from_dot_serial_(nk_b128_vec_t const *dots_vec, nk_u32_t query_pop,
+                                                   nk_b128_vec_t const *target_pops_vec, nk_b128_vec_t *result_vec) {
     for (int i = 0; i < 4; ++i) {
-        nk_f32_t dot = (nk_f32_t)dots.u32s[i];
-        nk_f32_t union_val = (nk_f32_t)query_pop + (nk_f32_t)target_pops.u32s[i] - dot;
-        results->f32s[i] = (union_val != 0) ? 1.0f - dot / union_val : 0.0f;
+        nk_f32_t dot = (nk_f32_t)dots_vec->u32s[i];
+        nk_f32_t union_val = (nk_f32_t)query_pop + (nk_f32_t)target_pops_vec->u32s[i] - dot;
+        result_vec->f32s[i] = (union_val != 0) ? 1.0f - dot / union_val : 0.0f;
     }
 }
 

package/numkong/include/numkong/set/v128relaxed.h

@@ -202,18 +202,20 @@ NK_PUBLIC void nk_jaccard_u16_v128relaxed(nk_u16_t const *a, nk_u16_t const *b,
 #pragma region Binary Sets from Dot
 
 NK_INTERNAL void nk_hamming_u32x4_from_dot_v128relaxed_( //
-    nk_b128_vec_t dots, nk_u32_t query_pop, nk_b128_vec_t target_pops, nk_b128_vec_t *results) {
-    v128_t dots_u32x4 = dots.v128;
+    nk_b128_vec_t const *dots_vec, nk_u32_t query_pop, nk_b128_vec_t const *target_pops_vec,
+    nk_b128_vec_t *result_vec) {
+    v128_t dots_u32x4 = dots_vec->v128;
     v128_t query_u32x4 = wasm_u32x4_splat(query_pop);
-    v128_t target_u32x4 = target_pops.v128;
-    results->v128 = wasm_i32x4_sub(wasm_i32x4_add(query_u32x4, target_u32x4), wasm_i32x4_shl(dots_u32x4, 1));
+    v128_t target_u32x4 = target_pops_vec->v128;
+    result_vec->v128 = wasm_i32x4_sub(wasm_i32x4_add(query_u32x4, target_u32x4), wasm_i32x4_shl(dots_u32x4, 1));
 }
 
 NK_INTERNAL void nk_jaccard_f32x4_from_dot_v128relaxed_( //
-    nk_b128_vec_t dots, nk_u32_t query_pop, nk_b128_vec_t target_pops, nk_b128_vec_t *results) {
-    v128_t dot_f32x4 = wasm_f32x4_convert_u32x4(dots.v128);
+    nk_b128_vec_t const *dots_vec, nk_u32_t query_pop, nk_b128_vec_t const *target_pops_vec,
+    nk_b128_vec_t *result_vec) {
+    v128_t dot_f32x4 = wasm_f32x4_convert_u32x4(dots_vec->v128);
     v128_t query_f32x4 = wasm_f32x4_splat((nk_f32_t)query_pop);
-    v128_t target_f32x4 = wasm_f32x4_convert_u32x4(target_pops.v128);
+    v128_t target_f32x4 = wasm_f32x4_convert_u32x4(target_pops_vec->v128);
     v128_t union_f32x4 = wasm_f32x4_sub(wasm_f32x4_add(query_f32x4, target_f32x4), dot_f32x4);
 
     v128_t zero_f32x4 = wasm_f32x4_splat(0.0f);
@@ -223,7 +225,7 @@ NK_INTERNAL void nk_jaccard_f32x4_from_dot_v128relaxed_( //
 
     v128_t ratio_f32x4 = wasm_f32x4_div(dot_f32x4, safe_union_f32x4);
     v128_t jaccard_f32x4 = wasm_f32x4_sub(one_f32x4, ratio_f32x4);
-    results->v128 = wasm_i32x4_relaxed_laneselect(zero_f32x4, jaccard_f32x4, zero_mask_u32x4);
+    result_vec->v128 = wasm_i32x4_relaxed_laneselect(zero_f32x4, jaccard_f32x4, zero_mask_u32x4);
 }
 
 #pragma endregion Binary Sets from Dot

package/numkong/include/numkong/sets/icelake.h

@@ -14,6 +14,7 @@
 
 #include "numkong/set/icelake.h"
 #include "numkong/dots/icelake.h"
+#include "numkong/reduce/skylake.h" // `nk_reduce_add_f32x16_skylake_`
 
 #if defined(__cplusplus)
 extern "C" {

package/numkong/include/numkong/sparse/README.md

@@ -38,15 +38,15 @@ def sparse_dot(a_indices: np.ndarray, a_weights: np.ndarray,
 | `u16`      | `u64`       | 16-bit index intersection count              |
 | `u32`      | `u64`       | 32-bit index intersection count              |
 | `u64`      | `u64`       | 64-bit index intersection count              |
-| `u32+f32`  | `f32`       | Sparse dot with 32-bit indices, f32 weights  |
+| `u32+f32`  | `f64`       | Sparse dot with 32-bit indices, f32 weights  |
 | `u16+bf16` | `f32`       | Sparse dot with 16-bit indices, bf16 weights |
 
 ## Optimizations
 
 ### Adaptive Merge vs Galloping Search
 
-`nk_sparse_intersect_u32_serial` selects between linear merge and galloping (exponential) search based on length ratio: when `longer_length > 64 * shorter_length`, galloping search over the longer array is used.
-Linear merge advances two pointers in lockstep at $O(|A| + |B|)$ using branch-free conditional increments: `i += ai < bj; j += ai >= bj` — no branch misprediction penalty.
+`nk_sparse_intersect_u32_serial` selects between linear merge and galloping (exponential) search based on length ratio: when `longer_length >= 64 * shorter_length`, galloping search over the longer array is used.
+Linear merge advances two pointers in lockstep at $O(|A| + |B|)$ using branch-free conditional increments: `i += ai <= bj; j += ai >= bj` — no branch misprediction penalty.
 Galloping binary-searches the longer array for each element of the shorter at $O(|A| \cdot \log |B|)$: an exponential probe doubles the search range until the target is bracketed, then binary search narrows within.
 The crossover at 64x length ratio balances the per-element cost of binary search ($\log_2 |B|$ comparisons) against linear scan's single comparison per advance — the threshold was chosen empirically, as cache locality favors linear merge at moderate ratios.
 
@@ -56,7 +56,7 @@ The crossover at 64x length ratio balances the per-element cost of binary search
 The rotation approach uses `_mm512_shuffle_epi32` with permutation constants (`_MM_PERM_ADCB`, etc.) to cycle elements through comparison positions — contending for port 5 (~1cy per shuffle, ~3cy for `_mm512_alignr_epi32`).
 Match counts are extracted via `_mm_popcnt_u32` on the comparison masks, accumulating intersection size without materializing matched elements.
 Before each 16x16 comparison block, a fast overlap check (`a_max < b_min || b_max < a_min`) skips non-overlapping register loads entirely — critical for sparse workloads where most pairs have disjoint index ranges.
-No native `_mm512_2intersect_epi16` instruction exists in any x86 ISA — UInt16 intersection must convert indices to UInt32 before comparison, halving effective throughput.
+No native `_mm512_2intersect_epi16` instruction exists in any x86 ISA, so `nk_sparse_intersect_u16_icelake` runs the same rotate-and-compare pattern over 32 UInt16 lanes with `_mm512_alignr_epi32`.
 
 ### VP2INTERSECT on AMD Turin
 

package/numkong/include/numkong/sparse/icelake.h

@@ -26,6 +26,7 @@
 #if NK_TARGET_ICELAKE
 
 #include "numkong/types.h"
+#include "numkong/sparse/serial.h" // `nk_sparse_intersect_u16_serial`, `nk_sparse_intersect_u32_serial`
 
 #if defined(__cplusplus)
 extern "C" {

package/numkong/include/numkong/sparse/neon.h

@@ -13,6 +13,7 @@
 #if NK_TARGET_NEON
 
 #include "numkong/types.h"
+#include "numkong/sparse/serial.h" // `nk_sparse_intersect_u16_serial`, `nk_sparse_intersect_u32_serial`, `nk_sparse_intersect_u64_serial`
 
 #if defined(__cplusplus)
 extern "C" {

package/numkong/include/numkong/sparse/serial.h

@@ -16,7 +16,7 @@
 extern "C" {
 #endif
 
-#define nk_define_sparse_intersect_(input_type)                                                                      \
+#define nk_define_sparse_intersect_helpers_(input_type)                                                              \
     NK_INTERNAL nk_size_t nk_sparse_intersect_##input_type##_galloping_search_(                                      \
         nk_##input_type##_t const *array, nk_size_t start, nk_size_t length, nk_##input_type##_t val) {              \
         nk_size_t low = start;                                                                                       \
@@ -48,7 +48,9 @@ extern "C" {
             j += ai >= bj;                                                                                           \
         }                                                                                                            \
         return intersection_size;                                                                                    \
-    }                                                                                                                \
+    }
+
+#define nk_define_sparse_intersect_(input_type)                                                                      \
     NK_PUBLIC void nk_sparse_intersect_##input_type##_serial(                                                        \
         nk_##input_type##_t const *shorter, nk_##input_type##_t const *longer, nk_size_t shorter_length,             \
         nk_size_t longer_length, nk_##input_type##_t *result, nk_size_t *count) {                                    \
@@ -103,7 +105,12 @@ extern "C" {
         *product = weights_product;                                                                        \
     }
 
-/*  Keep the serial instantiations below actually scalar, regardless of build type.
+nk_define_sparse_intersect_helpers_(u16)
+nk_define_sparse_intersect_helpers_(u32)
+nk_define_sparse_intersect_helpers_(u64)
+
+/*  Keep the serial instantiations below actually scalar, regardless of build type. The search helpers
+ *  above stay outside: they are `always_inline`, which clang refuses to combine with a pushed `noinline`.
  *  See dots/serial.h for rationale. */
 #if defined(__clang__)
 #pragma clang attribute push(__attribute__((noinline)), apply_to = function)

package/numkong/include/numkong/sparse/turin.h

@@ -13,6 +13,7 @@
 #if NK_TARGET_TURIN
 
 #include "numkong/types.h"
+#include "numkong/sparse/serial.h" // `nk_sparse_intersect_u16_serial`, `nk_sparse_intersect_u32_serial`
 
 #if defined(__cplusplus)
 extern "C" {

package/numkong/include/numkong/spatial/README.md

@@ -43,20 +43,22 @@ def angular(a: np.ndarray, b: np.ndarray) -> float:
 
 ## Input & Output Types
 
-| Input Type | Output Type | Description                                    |
-| ---------- | ----------- | ---------------------------------------------- |
-| `f64`      | `f64`       | 64-bit IEEE 754 double precision               |
-| `f32`      | `f32`       | 32-bit IEEE 754 single precision               |
-| `f16`      | `f32`       | 16-bit IEEE 754 half precision, widened output |
-| `bf16`     | `f32`       | 16-bit brain float, widened output             |
-| `e5m2`     | `f32`       | 8-bit Float8: 5 exponent, 2 mantissa bits      |
-| `e4m3`     | `f32`       | 8-bit Float8: 4 exponent, 3 mantissa bits      |
-| `e3m2`     | `f32`       | 8-bit MX format: 3 exponent, 2 mantissa bits   |
-| `e2m3`     | `f32`       | 8-bit MX format: 2 exponent, 3 mantissa bits   |
-| `i8`       | `f32`       | 8-bit signed integers                          |
-| `u8`       | `f32`       | 8-bit unsigned integers                        |
-| `i4`       | `f32`       | 4-bit signed integers, packed nibble pairs     |
-| `u4`       | `f32`       | 4-bit unsigned integers, packed nibble pairs   |
+| Input Type | Output Type | Description                                      |
+| ---------- | ----------- | ------------------------------------------------ |
+| `f64`      | `f64`       | 64-bit IEEE 754 double precision                 |
+| `f32`      | `f64`       | 32-bit IEEE 754 single precision, widened output |
+| `f16`      | `f32`       | 16-bit IEEE 754 half precision, widened output   |
+| `bf16`     | `f32`       | 16-bit brain float, widened output               |
+| `e5m2`     | `f32`       | 8-bit Float8: 5 exponent, 2 mantissa bits        |
+| `e4m3`     | `f32`       | 8-bit Float8: 4 exponent, 3 mantissa bits        |
+| `e3m2`     | `f32`       | 8-bit MX format: 3 exponent, 2 mantissa bits     |
+| `e2m3`     | `f32`       | 8-bit MX format: 2 exponent, 3 mantissa bits     |
+| `i8`       | `f32`       | 8-bit signed integers                            |
+| `u8`       | `f32`       | 8-bit unsigned integers                          |
+| `i4`       | `f32`       | 4-bit signed integers, packed nibble pairs       |
+| `u4`       | `f32`       | 4-bit unsigned integers, packed nibble pairs     |
+
+The integer `nk_sqeuclidean_*` kernels are the exception: `i8`, `u8`, `i4`, and `u4` return an exact `u32` count of squared differences, while `nk_euclidean_*` and `nk_angular_*` return `f32`.
 
 ## Optimizations
 
@@ -69,12 +71,11 @@ The single-pass design is essential because reading two vectors of length $n$ on
 
 ### Reciprocal Square Root with Newton-Raphson Refinement
 
-`nk_angular_f32_haswell`, `nk_angular_f64_haswell`, `nk_angular_f32_neon`, `nk_angular_f64_neon` compute the final normalization via in-hardware reciprocal square root estimates refined by Newton-Raphson iteration.
+`nk_angular_f16_haswell`, `nk_angular_i8_haswell`, `nk_angular_e4m3_skylake`, `nk_angular_f32_neon`, `nk_angular_f64_neon` compute the final normalization via in-hardware reciprocal square root estimates refined by Newton-Raphson iteration.
 The iteration formula is $x_{n+1} = x_n \cdot (3 - d \cdot x_n^2) / 2$, where $d$ is the value whose reciprocal square root is needed.
-NEON `vrsqrte` + `vrsqrts` performs one refinement step, reaching roughly 22 bits of precision.
-Haswell `VRSQRT14` provides $2^{-14}$ relative error and one Newton-Raphson step doubles the precision to approximately 28 bits.
-Skylake `VRSQRT28` achieves $2^{-28}$ accuracy directly, eliminating the need for a refinement step entirely.
-This reciprocal square root is needed for both euclidean distance ($\sqrt{d}$ via $d \cdot \text{rsqrt}(d)$) and angular distance ($1/\sqrt{a^2} \cdot 1/\sqrt{b^2}$).
+NEON `vrsqrte_f32` + `vrsqrts_f32` runs two refinement steps for Float32, and `vrsqrteq_f64` + `vrsqrtsq_f64` runs three for Float64.
+Haswell `VRSQRTPS` starts from ~12 bits (1.5 x $2^{-12}$ relative error) and one Newton-Raphson step roughly doubles that; Skylake `VRSQRT14PS` starts from $2^{-14}$ and refines the same way.
+The Float32 and Float64 angular kernels on x86 do not take this path at all: they accumulate in Float64 and finish with an exact `VSQRTPD`, because a refined 14-bit estimate is still far short of a 52-bit mantissa.
 
 ### Absolute Differences for Integer Types
 
@@ -90,12 +91,12 @@ abs_diff = _mm256_or_si256(_mm256_subs_epu8(bias_a, bias_b), _mm256_subs_epu8(bi
 For unsigned `u8`, the same saturating subtract trick works without the XOR bias.
 The absolute differences are then zero-extended via `VPUNPCKLBW`/`VPUNPCKHBW` (1 cycle, cheaper than `VPMOVZXBW`) and squared+accumulated via `VPMADDWD`, which computes $d_i^2 + d_{i+1}^2$ in one instruction.
 
-### Masked Neumaier Compensation on Skylake
+### Masked Dot2 Compensation on Skylake
 
-`nk_sqeuclidean_f64_skylake` uses `VGETEXP`-based Neumaier TwoSum inside AVX-512 masked loops.
-The mask register tracks which lanes are active, handling tail elements when the vector length is not a multiple of the SIMD width.
-The compensation term accumulates the low-order rounding errors from each addition, and because the mask propagates through both the main sum and the compensation update, even the final partial iteration maintains full Neumaier accuracy.
-This avoids the need for a separate scalar tail loop that would otherwise lose the compensated error tracking.
+`nk_angular_f64_skylake` and `nk_angular_f64_haswell` run the Ogita-Rump-Oishi Dot2 error-free transformation on the cross-product accumulator, which is the only one of the three that can suffer cancellation; the two self-products $\|a\|^2$ and $\|b\|^2$ have no negative terms and use a plain FMA.
+Each step recovers the rounding error of both the product and the sum, and folds them into a separate compensation accumulator that is added back once at the end.
+Tail elements are handled by a masked load that zero-fills the inactive lanes, so the same compensated body runs on the final partial iteration — no scalar tail loop that would lose the error tracking.
+`nk_sqeuclidean_f64_skylake` needs none of this: squared differences are non-negative, so a plain `VFMADD231PD` chain suffices.
 
 ## Performance
 

package/numkong/include/numkong/spatial/alder.h

@@ -31,7 +31,8 @@
 #include "numkong/dot/alder.h"      // VEX compat macros + dpbusd helpers
 #include "numkong/scalar/haswell.h" // `nk_f32_sqrt_haswell`
 #include "numkong/reduce/haswell.h"
-#include "numkong/cast/serial.h" // `nk_partial_load_b8x32_serial_`
+#include "numkong/spatial/haswell.h" // `nk_angular_normalize_f32_haswell_`
+#include "numkong/cast/serial.h"     // `nk_partial_load_b8x32_serial_`
 
 #if defined(__cplusplus)
 extern "C" {

package/numkong/include/numkong/spatial/haswell.h

@@ -55,91 +55,99 @@ NK_INTERNAL __m128 nk_rsqrt_f32x4_haswell_(__m128 x) {
 NK_INTERNAL __m128 nk_sqrt_f32x4_haswell_(__m128 x) { return _mm_sqrt_ps(_mm_max_ps(x, _mm_setzero_ps())); }
 
 /** @brief Angular from_dot: computes 1 − dot × rsqrt(query_sumsq × target_sumsq) for 4 pairs. */
-NK_INTERNAL void nk_angular_through_f32_from_dot_haswell_(nk_b128_vec_t dots, nk_f32_t query_sumsq,
-                                                          nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = dots.xmm_ps;
+NK_INTERNAL void nk_angular_through_f32_from_dot_haswell_(nk_b128_vec_t const *dots_vec, nk_f32_t query_sumsq,
+                                                          nk_b128_vec_t const *target_sumsqs_vec,
+                                                          nk_b128_vec_t *result_vec) {
+    __m128 dots_f32x4 = dots_vec->xmm_ps;
     __m128 query_sumsq_f32x4 = _mm_set1_ps(query_sumsq);
-    __m128 products_f32x4 = _mm_mul_ps(query_sumsq_f32x4, target_sumsqs.xmm_ps);
+    __m128 products_f32x4 = _mm_mul_ps(query_sumsq_f32x4, target_sumsqs_vec->xmm_ps);
     __m128 rsqrt_f32x4 = nk_rsqrt_f32x4_haswell_(products_f32x4);
     __m128 normalized_f32x4 = _mm_mul_ps(dots_f32x4, rsqrt_f32x4);
     __m128 angular_f32x4 = _mm_sub_ps(_mm_set1_ps(1.0f), normalized_f32x4);
-    results->xmm_ps = _mm_max_ps(angular_f32x4, _mm_setzero_ps());
+    result_vec->xmm_ps = _mm_max_ps(angular_f32x4, _mm_setzero_ps());
 }
 
 /** @brief Euclidean from_dot: computes √(query_sumsq + target_sumsq − 2 × dot) for 4 pairs. */
-NK_INTERNAL void nk_euclidean_through_f32_from_dot_haswell_(nk_b128_vec_t dots, nk_f32_t query_sumsq,
-                                                            nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = dots.xmm_ps;
+NK_INTERNAL void nk_euclidean_through_f32_from_dot_haswell_(nk_b128_vec_t const *dots_vec, nk_f32_t query_sumsq,
+                                                            nk_b128_vec_t const *target_sumsqs_vec,
+                                                            nk_b128_vec_t *result_vec) {
+    __m128 dots_f32x4 = dots_vec->xmm_ps;
     __m128 query_sumsq_f32x4 = _mm_set1_ps(query_sumsq);
-    __m128 sum_sq_f32x4 = _mm_add_ps(query_sumsq_f32x4, target_sumsqs.xmm_ps);
+    __m128 sum_sq_f32x4 = _mm_add_ps(query_sumsq_f32x4, target_sumsqs_vec->xmm_ps);
     __m128 dist_sq_f32x4 = _mm_fnmadd_ps(_mm_set1_ps(2.0f), dots_f32x4, sum_sq_f32x4);
-    results->xmm_ps = nk_sqrt_f32x4_haswell_(dist_sq_f32x4);
+    result_vec->xmm_ps = nk_sqrt_f32x4_haswell_(dist_sq_f32x4);
 }
 
 /** @brief Angular from_dot for native f64: 1 − dot / √(query_sumsq × target_sumsq) for 4 pairs. */
-NK_INTERNAL void nk_angular_through_f64_from_dot_haswell_(nk_b256_vec_t dots, nk_f64_t query_sumsq,
-                                                          nk_b256_vec_t target_sumsqs, nk_b256_vec_t *results) {
-    __m256d dots_f64x4 = dots.ymm_pd;
+NK_INTERNAL void nk_angular_through_f64_from_dot_haswell_(nk_b256_vec_t const *dots_vec, nk_f64_t query_sumsq,
+                                                          nk_b256_vec_t const *target_sumsqs_vec,
+                                                          nk_b256_vec_t *result_vec) {
+    __m256d dots_f64x4 = dots_vec->ymm_pd;
     __m256d query_sumsq_f64x4 = _mm256_set1_pd(query_sumsq);
-    __m256d products_f64x4 = _mm256_mul_pd(query_sumsq_f64x4, target_sumsqs.ymm_pd);
+    __m256d products_f64x4 = _mm256_mul_pd(query_sumsq_f64x4, target_sumsqs_vec->ymm_pd);
     __m256d sqrt_products_f64x4 = _mm256_sqrt_pd(products_f64x4);
     __m256d normalized_f64x4 = _mm256_div_pd(dots_f64x4, sqrt_products_f64x4);
     __m256d angular_f64x4 = _mm256_sub_pd(_mm256_set1_pd(1.0), normalized_f64x4);
-    results->ymm_pd = _mm256_max_pd(angular_f64x4, _mm256_setzero_pd());
+    result_vec->ymm_pd = _mm256_max_pd(angular_f64x4, _mm256_setzero_pd());
 }
 
 /** @brief Euclidean from_dot for native f64: √(query_sumsq + target_sumsq − 2 × dot) for 4 pairs. */
-NK_INTERNAL void nk_euclidean_through_f64_from_dot_haswell_(nk_b256_vec_t dots, nk_f64_t query_sumsq,
-                                                            nk_b256_vec_t target_sumsqs, nk_b256_vec_t *results) {
-    __m256d dots_f64x4 = dots.ymm_pd;
+NK_INTERNAL void nk_euclidean_through_f64_from_dot_haswell_(nk_b256_vec_t const *dots_vec, nk_f64_t query_sumsq,
+                                                            nk_b256_vec_t const *target_sumsqs_vec,
+                                                            nk_b256_vec_t *result_vec) {
+    __m256d dots_f64x4 = dots_vec->ymm_pd;
     __m256d query_sumsq_f64x4 = _mm256_set1_pd(query_sumsq);
-    __m256d sum_sq_f64x4 = _mm256_add_pd(query_sumsq_f64x4, target_sumsqs.ymm_pd);
+    __m256d sum_sq_f64x4 = _mm256_add_pd(query_sumsq_f64x4, target_sumsqs_vec->ymm_pd);
     __m256d dist_sq_f64x4 = _mm256_fnmadd_pd(_mm256_set1_pd(2.0), dots_f64x4, sum_sq_f64x4);
-    results->ymm_pd = _mm256_sqrt_pd(_mm256_max_pd(dist_sq_f64x4, _mm256_setzero_pd()));
+    result_vec->ymm_pd = _mm256_sqrt_pd(_mm256_max_pd(dist_sq_f64x4, _mm256_setzero_pd()));
 }
 
 /** @brief Angular from_dot for i32 accumulators: cast to f32, rsqrt+NR, clamp. 4 pairs. */
-NK_INTERNAL void nk_angular_through_i32_from_dot_haswell_(nk_b128_vec_t dots, nk_i32_t query_sumsq,
-                                                          nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = _mm_cvtepi32_ps(dots.xmm);
+NK_INTERNAL void nk_angular_through_i32_from_dot_haswell_(nk_b128_vec_t const *dots_vec, nk_i32_t query_sumsq,
+                                                          nk_b128_vec_t const *target_sumsqs_vec,
+                                                          nk_b128_vec_t *result_vec) {
+    __m128 dots_f32x4 = _mm_cvtepi32_ps(dots_vec->xmm);
     __m128 query_sumsq_f32x4 = _mm_set1_ps((nk_f32_t)query_sumsq);
-    __m128 products_f32x4 = _mm_mul_ps(query_sumsq_f32x4, _mm_cvtepi32_ps(target_sumsqs.xmm));
+    __m128 products_f32x4 = _mm_mul_ps(query_sumsq_f32x4, _mm_cvtepi32_ps(target_sumsqs_vec->xmm));
     __m128 rsqrt_f32x4 = nk_rsqrt_f32x4_haswell_(products_f32x4);
     __m128 normalized_f32x4 = _mm_mul_ps(dots_f32x4, rsqrt_f32x4);
     __m128 angular_f32x4 = _mm_sub_ps(_mm_set1_ps(1.0f), normalized_f32x4);
-    results->xmm_ps = _mm_max_ps(angular_f32x4, _mm_setzero_ps());
+    result_vec->xmm_ps = _mm_max_ps(angular_f32x4, _mm_setzero_ps());
 }
 
 /** @brief Euclidean from_dot for i32 accumulators: cast to f32, then √(a² + b² − 2ab). 4 pairs. */
-NK_INTERNAL void nk_euclidean_through_i32_from_dot_haswell_(nk_b128_vec_t dots, nk_i32_t query_sumsq,
-                                                            nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = _mm_cvtepi32_ps(dots.xmm);
+NK_INTERNAL void nk_euclidean_through_i32_from_dot_haswell_(nk_b128_vec_t const *dots_vec, nk_i32_t query_sumsq,
+                                                            nk_b128_vec_t const *target_sumsqs_vec,
+                                                            nk_b128_vec_t *result_vec) {
+    __m128 dots_f32x4 = _mm_cvtepi32_ps(dots_vec->xmm);
     __m128 query_sumsq_f32x4 = _mm_set1_ps((nk_f32_t)query_sumsq);
-    __m128 sum_sq_f32x4 = _mm_add_ps(query_sumsq_f32x4, _mm_cvtepi32_ps(target_sumsqs.xmm));
+    __m128 sum_sq_f32x4 = _mm_add_ps(query_sumsq_f32x4, _mm_cvtepi32_ps(target_sumsqs_vec->xmm));
     __m128 dist_sq_f32x4 = _mm_fnmadd_ps(_mm_set1_ps(2.0f), dots_f32x4, sum_sq_f32x4);
-    results->xmm_ps = nk_sqrt_f32x4_haswell_(dist_sq_f32x4);
+    result_vec->xmm_ps = nk_sqrt_f32x4_haswell_(dist_sq_f32x4);
 }
 
 /** @brief Angular from_dot for u32 accumulators: cast to f32, rsqrt+NR, clamp. 4 pairs. */
-NK_INTERNAL void nk_angular_through_u32_from_dot_haswell_(nk_b128_vec_t dots, nk_u32_t query_sumsq,
-                                                          nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = _mm_cvtepi32_ps(dots.xmm);
+NK_INTERNAL void nk_angular_through_u32_from_dot_haswell_(nk_b128_vec_t const *dots_vec, nk_u32_t query_sumsq,
+                                                          nk_b128_vec_t const *target_sumsqs_vec,
+                                                          nk_b128_vec_t *result_vec) {
+    __m128 dots_f32x4 = _mm_cvtepi32_ps(dots_vec->xmm);
     __m128 query_sumsq_f32x4 = _mm_set1_ps((nk_f32_t)query_sumsq);
-    __m128 products_f32x4 = _mm_mul_ps(query_sumsq_f32x4, _mm_cvtepi32_ps(target_sumsqs.xmm));
+    __m128 products_f32x4 = _mm_mul_ps(query_sumsq_f32x4, _mm_cvtepi32_ps(target_sumsqs_vec->xmm));
     __m128 rsqrt_f32x4 = nk_rsqrt_f32x4_haswell_(products_f32x4);
     __m128 normalized_f32x4 = _mm_mul_ps(dots_f32x4, rsqrt_f32x4);
     __m128 angular_f32x4 = _mm_sub_ps(_mm_set1_ps(1.0f), normalized_f32x4);
-    results->xmm_ps = _mm_max_ps(angular_f32x4, _mm_setzero_ps());
+    result_vec->xmm_ps = _mm_max_ps(angular_f32x4, _mm_setzero_ps());
 }
 
 /** @brief Euclidean from_dot for u32 accumulators: cast to f32, then √(a² + b² − 2ab). 4 pairs. */
-NK_INTERNAL void nk_euclidean_through_u32_from_dot_haswell_(nk_b128_vec_t dots, nk_u32_t query_sumsq,
-                                                            nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = _mm_cvtepi32_ps(dots.xmm);
+NK_INTERNAL void nk_euclidean_through_u32_from_dot_haswell_(nk_b128_vec_t const *dots_vec, nk_u32_t query_sumsq,
+                                                            nk_b128_vec_t const *target_sumsqs_vec,
+                                                            nk_b128_vec_t *result_vec) {
+    __m128 dots_f32x4 = _mm_cvtepi32_ps(dots_vec->xmm);
     __m128 query_sumsq_f32x4 = _mm_set1_ps((nk_f32_t)query_sumsq);
-    __m128 sum_sq_f32x4 = _mm_add_ps(query_sumsq_f32x4, _mm_cvtepi32_ps(target_sumsqs.xmm));
+    __m128 sum_sq_f32x4 = _mm_add_ps(query_sumsq_f32x4, _mm_cvtepi32_ps(target_sumsqs_vec->xmm));
     __m128 dist_sq_f32x4 = _mm_fnmadd_ps(_mm_set1_ps(2.0f), dots_f32x4, sum_sq_f32x4);
-    results->xmm_ps = nk_sqrt_f32x4_haswell_(dist_sq_f32x4);
+    result_vec->xmm_ps = nk_sqrt_f32x4_haswell_(dist_sq_f32x4);
 }
 
 NK_INTERNAL nk_f64_t nk_angular_normalize_f64_haswell_(nk_f64_t ab, nk_f64_t a2, nk_f64_t b2) {

package/numkong/include/numkong/spatial/icelake.h

@@ -437,7 +437,8 @@ nk_angular_i4_icelake_cycle:
     nk_i64_t ax_sum = _mm512_reduce_add_epi64(ax_sum_i64x8);
     nk_i64_t bx_sum = _mm512_reduce_add_epi64(bx_sum_i64x8);
     nk_i32_t ab_raw = _mm512_reduce_add_epi32(ab_i32x16);
-    nk_i32_t ab = ab_raw - 8 * (nk_i32_t)(ax_sum + bx_sum) + 64 * (nk_i32_t)n;
+    // Accumulate the bias correction in i64: `64 * n` and `8 * (∑ax + ∑bx)` overflow i32 around n ≈ 2^25.
+    nk_i64_t ab = (nk_i64_t)ab_raw - 8 * (ax_sum + bx_sum) + 64 * (nk_i64_t)n;
 
     nk_size_t n_bytes_total = nk_size_divide_round_up_(n, 2);
     nk_i32_t norm_excess = 128 * (nk_i32_t)(nk_size_round_up_to_multiple_(n_bytes_total, 64) - n_bytes_total);