usearch 2.26.1 → 2.26.3

package/numkong/cmake/toolchain-wasi.cmake

@@ -38,10 +38,23 @@ set(CMAKE_RANLIB "${WASI_SDK_PATH}/bin/llvm-ranlib${WASI_TOOL_SUFFIX}")
 set(CMAKE_SYSROOT "${WASI_SDK_PATH}/share/wasi-sysroot")
 set(CMAKE_FIND_ROOT_PATH "${WASI_SDK_PATH}")
 
+# Cross-runtime portable mode: build single-threaded with self-contained memory so the SAME `.wasm`
+# runs under node, wasmtime, AND wasmer (used by the cross-runtime kernel validation). Default OFF keeps
+# the threaded, host-imported-memory build that the full nk_test / nk_bench suites rely on.
+if (NK_WASI_PORTABLE)
+    set(NK_WASI_TARGET_ "wasm32-wasip1")
+    set(NK_WASI_THREADS_ "")
+    set(NK_WASI_MEMORY_ "")
+else ()
+    set(NK_WASI_TARGET_ "wasm32-wasip1-threads")
+    set(NK_WASI_THREADS_ "-pthread")
+    set(NK_WASI_MEMORY_ "-Wl,--import-memory -Wl,--export-memory -Wl,--shared-memory -Wl,--max-memory=2147483648")
+endif ()
+
 # WASM SIMD flags (same as Emscripten for consistency).
 set(WASM_SIMD_FLAGS "-msimd128 -mrelaxed-simd")
-set(CMAKE_C_FLAGS_INIT "${WASM_SIMD_FLAGS} --target=wasm32-wasip1-threads -pthread")
-set(CMAKE_CXX_FLAGS_INIT "${WASM_SIMD_FLAGS} --target=wasm32-wasip1-threads -pthread -fno-exceptions")
+set(CMAKE_C_FLAGS_INIT "${WASM_SIMD_FLAGS} --target=${NK_WASI_TARGET_} ${NK_WASI_THREADS_}")
+set(CMAKE_CXX_FLAGS_INIT "${WASM_SIMD_FLAGS} --target=${NK_WASI_TARGET_} ${NK_WASI_THREADS_} -fno-exceptions")
 
 # Optimization flags.
 set(CMAKE_C_FLAGS_RELEASE "-O3 -DNDEBUG")
@@ -49,15 +62,18 @@ set(CMAKE_CXX_FLAGS_RELEASE "-O3 -DNDEBUG")
 set(CMAKE_C_FLAGS_DEBUG "-O0 -g")
 set(CMAKE_CXX_FLAGS_DEBUG "-O0 -g")
 
-# Linker flags for WASI.
+# Linker flags for WASI (the imported/shared-memory group is empty in NK_WASI_PORTABLE mode).
 set(CMAKE_EXE_LINKER_FLAGS_INIT
     "-Wl,--allow-undefined \
-     -Wl,--import-memory -Wl,--export-memory \
-     -Wl,--shared-memory -Wl,--max-memory=2147483648 \
+     ${NK_WASI_MEMORY_} \
      -Wl,--export=main \
      -Wl,--export=_start"
 )
 
+# `wasm-ld` resolves `__global_base`, `__data_end`, and `__heap_base` only in a main module, so a `-shared`
+# WASI build cannot link. Seeded rather than forced, so `-D NK_BUILD_SHARED=ON` still overrides.
+set(NK_BUILD_SHARED OFF CACHE BOOL "Compile a dynamic library")
+
 # Do not look for programs in build-host directories.
 set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
 set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
@@ -75,3 +91,21 @@ endif ()
 
 message(STATUS "NumKong WASI: SIMD128 and Relaxed SIMD enabled")
 message(STATUS "NumKong WASI: Toolchain at ${WASI_SDK_PATH}")
+
+# Runtime that CTest invokes on each cross binary, so `ctest` runs the WASI tests cross-engine without a
+# wrapper script. wasmtime and wasmer execute a `.wasm` command directly; node uses the small WASI runner
+# in test/test-wasi.mjs. Relaxed-SIMD lowers differently per engine, so testing more than one matters.
+set(NK_WASM_RUNTIME "wasmtime" CACHE STRING "WASM runtime CTest uses for WASI tests (wasmtime, wasmer, or node)")
+if (NK_WASM_RUNTIME STREQUAL "wasmer")
+    find_program(NK_WASMER_EXE_ wasmer PATHS "$ENV{HOME}/.cargo/bin" "$ENV{HOME}/.wasmer/bin")
+    set(CMAKE_CROSSCOMPILING_EMULATOR "${NK_WASMER_EXE_};run")
+elseif (NK_WASM_RUNTIME STREQUAL "node")
+    find_program(NK_NODE_EXE_ node)
+    set(CMAKE_CROSSCOMPILING_EMULATOR
+        "${NK_NODE_EXE_};--experimental-wasi-unstable-preview1;${CMAKE_CURRENT_LIST_DIR}/../test/test-wasi.mjs"
+    )
+else ()
+    find_program(NK_WASMTIME_EXE_ wasmtime PATHS "$ENV{HOME}/.wasmtime/bin")
+    set(CMAKE_CROSSCOMPILING_EMULATOR "${NK_WASMTIME_EXE_}")
+endif ()
+message(STATUS "NumKong WASI: CTest runtime = ${NK_WASM_RUNTIME}")

package/numkong/include/README.md

@@ -1,7 +1,7 @@
 # NumKong for C and C++
 
 NumKong's native SDK is the reference surface for the project.
-The plain C ABI exposes every kernel family directly: dot products, dense distances, binary metrics, probability divergences, geospatial solvers, curved-space kernels, sparse intersections, mesh alignment, packed matrix multiplication, symmetric self-similarity, and late-interaction scoring.
+The plain C ABI exposes every kernel family directly: dot products, dense distances, binary metrics, probability divergences, geospatial solvers, curved-space kernels, sparse intersections, mesh alignment, packed matrix multiplication, symmetric self-similarity, late-interaction scoring, elementwise arithmetic, reductions, type conversions, scalar math, and trigonometry.
 The ABI is stable, versioned, and callable from any language that can load a shared library.
 There is no runtime overhead: no hidden thread pool, no implicit allocation, no garbage collector interaction.
 The C++ layer stays thin, typed, allocator-aware, and close enough to inline through, adding type-level result promotion and owning containers without hiding the dispatch model or the mixed-precision policy.
@@ -43,7 +43,7 @@ Packing handles internal layout itself and does not require caller-side alignmen
 
 ## Ecosystem Comparison
 
-| Feature                      | NumKong                                                                                                                             | [OpenBLAS](https://github.com/OpenMathLib/OpenBLAS)               | [Eigen](https://gitlab.com/libeigen/eigen)                                              |
+| Feature                      | NumKong                                                                                                                             | [OpenBLAS][openblas]                                              | [Eigen][eigen]                                                                          |
 | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
 | Operation families           | dots, distances, binary, probability, geospatial, curved, mesh, sparse, MaxSim, elementwise, reductions, cast, trig                 | dense linear algebra only                                         | dense LA, some reductions and elementwise                                               |
 | Precision                    | Sub-byte to Float64 dtypes; automatic widening per scalar type; Kahan-compensated summation; 0 ULP Float32/Float64 where applicable | Float32, Float64 only; same-type in/out; no compensated summation | Float16/BFloat16 partial; no Float8 or sub-byte; manual casts; no compensated summation |
@@ -52,6 +52,8 @@ Packing handles internal layout itself and does not require caller-side alignmen
 | Symmetric kernels, SYRK-like | skips duplicate pairs, up to 2x speedup for self-distance                                                                           | `SSYRK`/`DSYRK` for rank-k updates                                | `.selfadjointView` for rank-k updates                                                   |
 | Memory model                 | Caller-owned buffers; C++ adds `tensor<T,A>` with per-container allocators                                                          | Caller-managed buffers; no container abstraction                  | Lazy expression templates avoid most temporaries; `aligned_allocator` provided          |
 
+[openblas]: https://github.com/OpenMathLib/OpenBLAS
+[eigen]: https://gitlab.com/libeigen/eigen
 
 
 ## Installation
@@ -168,7 +170,7 @@ The higher-level templates use `result_type_ = typename in_type_::dot_result_t`
 The fast typed overloads are constrained so that overriding the result type away from the native policy can disable the specialized path and fall back to the more generic one.
 
 When `__cpp_lib_format >= 202110L` for the C++23 `<format>` header support, all NumKong scalar types provide `std::formatter` specializations with similar format specs to the traditional `float`.
-For the BFloat16 type, the output for `nk::f16_t::from_f32(3.14f)` will look like:
+For the Float16 type, the output for `nk::f16_t::from_f32(3.14f)` will look like:
 
 | Format spec | Output example       | Description                            |
 | ----------- | -------------------- | -------------------------------------- |
@@ -189,10 +191,10 @@ They include real, complex, packed-binary, mini-float, and mixed-precision forms
 ```c
 nk_f32c_t a[384];
 nk_f32c_t b[384];
-nk_f32_t out[2] = {0, 0};
+nk_f64c_t out = {0, 0};         // widened f32c → f64c output
 
-nk_dot_f32c(a, b, 384, out);  // complex inner product
-nk_vdot_f32c(a, b, 384, out); // conjugated variant, like numpy.vdot
+nk_dot_f32c(a, b, 384, &out);   // complex inner product
+nk_vdot_f32c(a, b, 384, &out);  // conjugated variant, like numpy.vdot
 ```
 
 For quantized retrieval pipelines, the storage format often matters more than the nominal math family.
@@ -231,15 +233,18 @@ nk_hamming_u1(a, b, 128 * 8, &hamming);
 nk_jaccard_u1(a, b, 128 * 8, &jaccard);
 ```
 
-Integer set Jaccard works on sorted arrays of integer identifiers.
+`nk_jaccard_u32` is a dense word-wise kernel rather than a sorted-set operation.
+It walks two arrays of `n` 32-bit words position by position and returns `1 - matches / n`.
 
 ```c
-nk_u32_t set_a[] = {1, 3, 5, 7, 9}, set_b[] = {3, 5, 8, 9, 10};
-nk_f32_t jaccard_sets = 0;
-nk_jaccard_u32(set_a, set_b, 5, &jaccard_sets); // |A ∩ B| / |A ∪ B|
-assert(jaccard_sets > 0.0f && jaccard_sets < 1.0f && "|A ∩ B| / |A ∪ B| should be in (0, 1)");
+nk_u32_t a[] = {1, 3, 5, 7, 9}, b[] = {1, 3, 5, 8, 10};
+nk_f32_t jaccard_words = 0;
+nk_jaccard_u32(a, b, 5, &jaccard_words); // 1 - matches / n
+assert(jaccard_words > 0.0f && jaccard_words < 1.0f && "3 of 5 words match");
 ```
 
+Sorted arrays of integer identifiers are handled by the sparse kernels instead, described below.
+
 ## Probability Metrics
 
 Probability kernels target divergences directly instead of making you rebuild them from scalar loops.
@@ -351,8 +356,8 @@ You can also use a more traditional syntax with member functions, also leveragin
 Similar to NumPy, but statically typed:
 
 ```cpp
-auto first_column = t[all, 1, slice];             // strided column view → {2, 5, 8}
-auto minimum_index = nk::argmin(first_column);    // index of the minimum in the second column
+auto second_column = t[all, 1, slice];            // strided column view → {2, 5, 8}
+auto minimum_index = nk::argmin(second_column);   // index of the minimum in the second column
 ```
 
 The view types are conceptually close to `std::mdspan` from C++23.
@@ -498,10 +503,11 @@ The native API covers `rmsd`, `kabsch`, and `umeyama`.
 nk_f32_t source[] = {0, 0, 0, 1, 0, 0, 0, 1, 0};
 nk_f32_t target[] = {0, 0, 0, 2, 0, 0, 0, 2, 0};
 nk_f32_t a_centroid[3], b_centroid[3], rotation[9];
-nk_f32_t scale = 0, rmsd = 0;
+nk_f32_t scale = 0;
+nk_f64_t rmsd = 0; // widened f32 → f64 output
 
 nk_umeyama_f32(source, target, 3, a_centroid, b_centroid, rotation, &scale, &rmsd);
-assert(rmsd < 1e-6f && "umeyama should recover exact alignment");
+assert(rmsd < 1e-6 && "umeyama should recover exact alignment");
 assert(scale > 1.99f && scale < 2.01f && "umeyama should recover 2x scale");
 ```
 
@@ -592,13 +598,14 @@ The main user-facing CMake options are:
 - `NK_BUILD_SHARED` builds a shared library, ON by default for standalone builds and OFF when included as a subdirectory.
 - `NK_BUILD_TEST` and `NK_BUILD_BENCH` enable precision tests and benchmarks respectively, both OFF by default.
 - `NK_DYNAMIC_DISPATCH=1` compiles all backends into one binary and selects at runtime via `nk_capabilities()`, recommended for shipping one binary across CPU generations.
+  It is a preprocessor definition rather than a CMake option, so pass it through the compiler flags.
 - `NK_COMPARE_TO_BLAS` and `NK_COMPARE_TO_MKL` link benchmarks against a system BLAS or Intel MKL, each accepting `AUTO`, `ON`, or `OFF` with `AUTO` as the default.
 
-The build enforces C99 for the C layer and C++23 for the C++ layer.
+The build enforces C99 for the C layer and C++20 for the C++ layer.
 
 ```sh
 cmake -B build -D CMAKE_BUILD_TYPE=Release -D NK_BUILD_TEST=ON
-cmake -B build -D NK_DYNAMIC_DISPATCH=1 -D NK_BUILD_BENCH=ON -D NK_COMPARE_TO_MKL=ON
+cmake -B build -D CMAKE_C_FLAGS="-DNK_DYNAMIC_DISPATCH=1" -D NK_BUILD_BENCH=ON -D NK_COMPARE_TO_MKL=ON
 ```
 
 ## Cross-Compilation

package/numkong/include/numkong/attention/sapphireamx.h

@@ -117,7 +117,7 @@ typedef struct {
  *  2. Polynomial approximation: exp(r) ≈ 1 + r + r²/2 + ... (degree 6)
  *  3. Reconstruction: exp(x) = 2ⁿ × exp(r)
  *
- *  @param x Input vector (16 floats)
+ *  @param x_f32x16 Input vector (16 floats)
  *  @return exp(x) for each element
  */
 NK_INTERNAL __m512 nk_exp_ps_avx512_(__m512 x_f32x16) {
@@ -169,7 +169,7 @@ NK_INTERNAL __m512 nk_exp_ps_avx512_(__m512 x_f32x16) {
  *
  *  Performance: ~12-15 cycles for 16 floats (vs ~18-22 for degree-6)
  *
- *  @param x Input vector (16 floats)
+ *  @param x_f32x16 Input vector (16 floats)
  *  @return exp(x) approximation
  */
 NK_INTERNAL __m512 nk_exp_ps_fast_avx512_(__m512 x_f32x16) {
@@ -475,10 +475,10 @@ NK_INTERNAL void nk_attention_softmax_update_(nk_attention_softmax_row_state_t *
  *  When processing a new KV block with larger scores, previous O accumulator
  *  needs rescaling: O = O × exp(oldₘₐₓ - newₘₐₓ)
  *
- *  @param output       Output accumulator [16][head_dim] in F32
- *  @param head_dim     Head dimension
- *  @param old_max      Previous running max per row (16 values)
- *  @param new_max      New running max per row (16 values)
+ *  @param output          Output accumulator [16][head_dim] in F32
+ *  @param head_dim        Head dimension
+ *  @param old_max_f32x16  Previous running max per row (16 values)
+ *  @param new_max_f32x16  New running max per row (16 values)
  */
 NK_INTERNAL void nk_attention_rescale_output_(nk_f32_t *output, nk_size_t head_dim, __m512 old_max_f32x16,
                                               __m512 new_max_f32x16) {

package/numkong/include/numkong/attention/sme.h

@@ -162,8 +162,8 @@ typedef struct {
  *  Uses Cody-Waite range reduction + Horner polynomial (degree 4).
  *  Accuracy: ~0.1% relative error, acceptable for softmax normalization.
  *
- *  @param pg Active predicate
- *  @param x Input vector
+ *  @param predicate_b32x Active predicate
+ *  @param x_f32x Input vector
  *  @return exp(x) approximation
  */
 NK_INTERNAL svfloat32_t nk_exp_f32_sve_(svbool_t predicate_b32x, svfloat32_t x_f32x) __arm_streaming {

package/numkong/include/numkong/capabilities.h

@@ -95,8 +95,8 @@
 #include "numkong/types.h" // `nk_u64_t`, `NK_DEFINED_LINUX_`
 
 #define NK_VERSION_MAJOR 7
-#define NK_VERSION_MINOR 6
-#define NK_VERSION_PATCH 0
+#define NK_VERSION_MINOR 8
+#define NK_VERSION_PATCH 1
 
 /**
  *  @brief  Removes compile-time dispatching, and replaces it with runtime dispatching.

package/numkong/include/numkong/cast/README.md

@@ -1,7 +1,8 @@
 # Type Conversions in NumKong
 
-NumKong implements bidirectional type conversions between all supported numeric formats through Float32 as a hub type.
-Conversions cover IEEE 754 floats (Float16, Float32, Float64), brain float (BFloat16), Float8 formats (e4m3, e5m2, e2m3, e3m2), and integers (Int8–Int64, UInt8–UInt64, packed i4x2/u4x2).
+NumKong implements bidirectional type conversions between all supported numeric formats through a wider hub type: `u64` when both sides are unsigned integers, `i64` when both sides are integers and at least one is signed, and `f64c` for everything else.
+The SIMD backends use a narrower Float32 hub for the subset of types they cover.
+Conversions cover IEEE 754 floats (Float16, Float32, Float64), brain float (BFloat16), Float8 formats (e4m3, e5m2, e2m3, e3m2), and integers (Int8–Int64, UInt8–UInt64, packed i4x2/u4x2, packed u1x8).
 All conversions use round-to-nearest-even (RNE) for narrowing and exact widening where the target format has sufficient range and precision.
 
 BFloat16 relates to Float32 by truncation with rounding:
@@ -77,16 +78,17 @@ Packed sub-byte conversions:
 
 ### Lookup Tables for Mini-Floats
 
-`nk_e4m3_to_f32_serial`, `nk_e5m2_to_f32_serial`, `nk_e2m3_to_f32_serial`, `nk_e3m2_to_f32_serial` use 256-entry precomputed lookup tables — each 8-bit input indexes directly into a Float32 result array.
-The reverse direction (`nk_f32_to_e4m3_serial`) uses clamping + rounding: clamp to format range, multiply by scale, round-to-nearest, cast to UInt8.
-SIMD backends (`nk_cast_haswell`, `nk_cast_skylake`) use `VPGATHERDD` to perform 8 or 16 simultaneous table lookups from the same 256-entry table.
-AVX-512 gathers on Skylake achieve ~3cy throughput per 16-element lookup vs ~8cy on Haswell for 8-element gathers.
+`nk_e5m2_to_f32_serial` indexes a 128-entry table with the 7-bit magnitude, and `nk_e2m3_to_f32_serial` and `nk_e3m2_to_f32_serial` index 32-entry tables with their 5-bit magnitudes, OR-ing the sign bit back in afterwards.
+`nk_e4m3_to_f32_serial` needs no table: the exponent and mantissa fields map onto Float32 with a bias shift of 120, and only the subnormal and the single NaN encoding are special-cased.
+The reverse direction (`nk_f32_to_e4m3_serial`) is bit manipulation with RNE rounding: NaN and infinity are mapped explicitly, subnormals below 2⁻⁶ are rounded through a `× 512` scale, and normals get their 23-bit mantissa rounded down to 3 bits.
+The SIMD backends do not gather from these tables.
+On x86 the Float8 paths ride the F16C converters described below, and NEON looks up Float16 high bytes with `VQTBL4` over a 128-byte table in `nk_e4m3x16_to_f16x8x2_neon_` and its siblings.
 
 ### BFloat16 as Truncated Float32
 
 `nk_bf16_to_f32_serial` zero-extends by left-shifting 16 bits — exact, no rounding error, single-cycle on all platforms.
 `nk_f32_to_bf16_serial` right-shifts with round-to-nearest-even: adds a rounding bias of `0x7FFF + ((bits >> 16) & 1)` before truncating, matching the IEEE 754 RNE tie-breaking rule.
-NEON backend uses `vreinterpretq_u16_u8` + `vzip` for zero-extension; Haswell uses `VPSLLD` / `VPSRLD` shifts.
+NEON backend uses `vmovl_u16` + `vshlq_n_u32` for zero-extension; Haswell uses `VPSLLD` / `VPSRLD` shifts.
 
 ### F16C Hardware Conversion
 

package/numkong/include/numkong/cast/loongsonasx.h

@@ -139,106 +139,114 @@ NK_INTERNAL __m128 nk_sqrt_f32x4_loongsonasx_(__m128 x_f32x4) {
 }
 
 /** @brief Angular from_dot: computes 1 − dot × rsqrt(query_sumsq × target_sumsq) for 4 pairs (LSX 128-bit f32). */
-NK_INTERNAL void nk_angular_through_f32_from_dot_loongsonasx_(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_loongsonasx_(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 = nk_xvreplgr2vr_s_128_(query_sumsq);
-    __m128 products_f32x4 = __lsx_vfmul_s(query_sumsq_f32x4, target_sumsqs.xmm_ps);
+    __m128 products_f32x4 = __lsx_vfmul_s(query_sumsq_f32x4, target_sumsqs_vec->xmm_ps);
     __m128 rsqrt_f32x4 = __lsx_vfrsqrt_s(products_f32x4);
     __m128 normalized_f32x4 = __lsx_vfmul_s(dots_f32x4, rsqrt_f32x4);
     __m128 one_f32x4 = nk_xvreplgr2vr_s_128_(1.0f);
     __m128 angular_f32x4 = __lsx_vfsub_s(one_f32x4, normalized_f32x4);
     __m128 zero_f32x4 = (__m128)__lsx_vreplgr2vr_w(0);
-    results->xmm_ps = __lsx_vfmax_s(angular_f32x4, zero_f32x4);
+    result_vec->xmm_ps = __lsx_vfmax_s(angular_f32x4, zero_f32x4);
 }
 
 /** @brief Euclidean from_dot: computes √(query_sumsq + target_sumsq − 2 × dot) for 4 pairs (LSX 128-bit f32). */
-NK_INTERNAL void nk_euclidean_through_f32_from_dot_loongsonasx_(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_loongsonasx_(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 = nk_xvreplgr2vr_s_128_(query_sumsq);
-    __m128 sum_sq_f32x4 = __lsx_vfadd_s(query_sumsq_f32x4, target_sumsqs.xmm_ps);
+    __m128 sum_sq_f32x4 = __lsx_vfadd_s(query_sumsq_f32x4, target_sumsqs_vec->xmm_ps);
     __m128 two_f32x4 = nk_xvreplgr2vr_s_128_(2.0f);
     // dist_sq = sum_sq − 2 × dots = -(2 × dots − sum_sq)
     __m128 dist_sq_f32x4 = __lsx_vfnmsub_s(two_f32x4, dots_f32x4, sum_sq_f32x4);
-    results->xmm_ps = nk_sqrt_f32x4_loongsonasx_(dist_sq_f32x4);
+    result_vec->xmm_ps = nk_sqrt_f32x4_loongsonasx_(dist_sq_f32x4);
 }
 
 /** @brief Angular from_dot for native f64: 1 − dot / √(query_sumsq × target_sumsq) for 4 pairs (LASX 256-bit). */
-NK_INTERNAL void nk_angular_through_f64_from_dot_loongsonasx_(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_loongsonasx_(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 = nk_xvfreplgr2vr_d_(query_sumsq);
-    __m256d products_f64x4 = __lasx_xvfmul_d(query_sumsq_f64x4, target_sumsqs.ymm_pd);
+    __m256d products_f64x4 = __lasx_xvfmul_d(query_sumsq_f64x4, target_sumsqs_vec->ymm_pd);
     __m256d sqrt_products_f64x4 = __lasx_xvfsqrt_d(products_f64x4);
     __m256d normalized_f64x4 = __lasx_xvfdiv_d(dots_f64x4, sqrt_products_f64x4);
     __m256d one_f64x4 = nk_xvfreplgr2vr_d_(1.0);
     __m256d angular_f64x4 = __lasx_xvfsub_d(one_f64x4, normalized_f64x4);
     __m256d zero_f64x4 = (__m256d)__lasx_xvreplgr2vr_d(0);
-    results->ymm_pd = __lasx_xvfmax_d(angular_f64x4, zero_f64x4);
+    result_vec->ymm_pd = __lasx_xvfmax_d(angular_f64x4, zero_f64x4);
 }
 
 /** @brief Euclidean from_dot for native f64: √(query_sumsq + target_sumsq − 2 × dot) for 4 pairs (LASX 256-bit). */
-NK_INTERNAL void nk_euclidean_through_f64_from_dot_loongsonasx_(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_loongsonasx_(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 = nk_xvfreplgr2vr_d_(query_sumsq);
-    __m256d sum_sq_f64x4 = __lasx_xvfadd_d(query_sumsq_f64x4, target_sumsqs.ymm_pd);
+    __m256d sum_sq_f64x4 = __lasx_xvfadd_d(query_sumsq_f64x4, target_sumsqs_vec->ymm_pd);
     __m256d two_f64x4 = nk_xvfreplgr2vr_d_(2.0);
     // dist_sq = sum_sq − 2 × dots = -(2 × dots − sum_sq)
     __m256d dist_sq_f64x4 = __lasx_xvfnmsub_d(two_f64x4, dots_f64x4, sum_sq_f64x4);
     __m256d zero_f64x4 = (__m256d)__lasx_xvreplgr2vr_d(0);
-    results->ymm_pd = __lasx_xvfsqrt_d(__lasx_xvfmax_d(dist_sq_f64x4, zero_f64x4));
+    result_vec->ymm_pd = __lasx_xvfsqrt_d(__lasx_xvfmax_d(dist_sq_f64x4, zero_f64x4));
 }
 
 /** @brief Angular from_dot for i32 accumulators: cast i32 → f32, rsqrt+NR, clamp. 4 pairs (LSX 128-bit). */
-NK_INTERNAL void nk_angular_through_i32_from_dot_loongsonasx_(nk_b128_vec_t dots, nk_i32_t query_sumsq,
-                                                              nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = __lsx_vffint_s_w(dots.xmm);
+NK_INTERNAL void nk_angular_through_i32_from_dot_loongsonasx_(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 = __lsx_vffint_s_w(dots_vec->xmm);
     __m128 query_sumsq_f32x4 = nk_xvreplgr2vr_s_128_((nk_f32_t)query_sumsq);
-    __m128 products_f32x4 = __lsx_vfmul_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs.xmm));
+    __m128 products_f32x4 = __lsx_vfmul_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs_vec->xmm));
     __m128 rsqrt_f32x4 = __lsx_vfrsqrt_s(products_f32x4);
     __m128 normalized_f32x4 = __lsx_vfmul_s(dots_f32x4, rsqrt_f32x4);
     __m128 one_f32x4 = nk_xvreplgr2vr_s_128_(1.0f);
     __m128 angular_f32x4 = __lsx_vfsub_s(one_f32x4, normalized_f32x4);
     __m128 zero_f32x4 = (__m128)__lsx_vreplgr2vr_w(0);
-    results->xmm_ps = __lsx_vfmax_s(angular_f32x4, zero_f32x4);
+    result_vec->xmm_ps = __lsx_vfmax_s(angular_f32x4, zero_f32x4);
 }
 
 /** @brief Euclidean from_dot for i32 accumulators: cast i32 → f32, then √(a² + b² − 2ab). 4 pairs (LSX 128-bit). */
-NK_INTERNAL void nk_euclidean_through_i32_from_dot_loongsonasx_(nk_b128_vec_t dots, nk_i32_t query_sumsq,
-                                                                nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = __lsx_vffint_s_w(dots.xmm);
+NK_INTERNAL void nk_euclidean_through_i32_from_dot_loongsonasx_(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 = __lsx_vffint_s_w(dots_vec->xmm);
     __m128 query_sumsq_f32x4 = nk_xvreplgr2vr_s_128_((nk_f32_t)query_sumsq);
-    __m128 sum_sq_f32x4 = __lsx_vfadd_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs.xmm));
+    __m128 sum_sq_f32x4 = __lsx_vfadd_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs_vec->xmm));
     __m128 two_f32x4 = nk_xvreplgr2vr_s_128_(2.0f);
     __m128 dist_sq_f32x4 = __lsx_vfnmsub_s(two_f32x4, dots_f32x4, sum_sq_f32x4);
-    results->xmm_ps = nk_sqrt_f32x4_loongsonasx_(dist_sq_f32x4);
+    result_vec->xmm_ps = nk_sqrt_f32x4_loongsonasx_(dist_sq_f32x4);
 }
 
 /** @brief Angular from_dot for u32 accumulators: cast u32 → f32, rsqrt+NR, clamp. 4 pairs (LSX 128-bit). */
-NK_INTERNAL void nk_angular_through_u32_from_dot_loongsonasx_(nk_b128_vec_t dots, nk_u32_t query_sumsq,
-                                                              nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = __lsx_vffint_s_w(dots.xmm);
+NK_INTERNAL void nk_angular_through_u32_from_dot_loongsonasx_(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 = __lsx_vffint_s_w(dots_vec->xmm);
     __m128 query_sumsq_f32x4 = nk_xvreplgr2vr_s_128_((nk_f32_t)query_sumsq);
-    __m128 products_f32x4 = __lsx_vfmul_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs.xmm));
+    __m128 products_f32x4 = __lsx_vfmul_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs_vec->xmm));
     __m128 rsqrt_f32x4 = __lsx_vfrsqrt_s(products_f32x4);
     __m128 normalized_f32x4 = __lsx_vfmul_s(dots_f32x4, rsqrt_f32x4);
     __m128 one_f32x4 = nk_xvreplgr2vr_s_128_(1.0f);
     __m128 angular_f32x4 = __lsx_vfsub_s(one_f32x4, normalized_f32x4);
     __m128 zero_f32x4 = (__m128)__lsx_vreplgr2vr_w(0);
-    results->xmm_ps = __lsx_vfmax_s(angular_f32x4, zero_f32x4);
+    result_vec->xmm_ps = __lsx_vfmax_s(angular_f32x4, zero_f32x4);
 }
 
 /** @brief Euclidean from_dot for u32 accumulators: cast u32 → f32, then √(a² + b² − 2ab). 4 pairs (LSX 128-bit). */
-NK_INTERNAL void nk_euclidean_through_u32_from_dot_loongsonasx_(nk_b128_vec_t dots, nk_u32_t query_sumsq,
-                                                                nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = __lsx_vffint_s_w(dots.xmm);
+NK_INTERNAL void nk_euclidean_through_u32_from_dot_loongsonasx_(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 = __lsx_vffint_s_w(dots_vec->xmm);
     __m128 query_sumsq_f32x4 = nk_xvreplgr2vr_s_128_((nk_f32_t)query_sumsq);
-    __m128 sum_sq_f32x4 = __lsx_vfadd_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs.xmm));
+    __m128 sum_sq_f32x4 = __lsx_vfadd_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs_vec->xmm));
     __m128 two_f32x4 = nk_xvreplgr2vr_s_128_(2.0f);
     __m128 dist_sq_f32x4 = __lsx_vfnmsub_s(two_f32x4, dots_f32x4, sum_sq_f32x4);
-    results->xmm_ps = nk_sqrt_f32x4_loongsonasx_(dist_sq_f32x4);
+    result_vec->xmm_ps = nk_sqrt_f32x4_loongsonasx_(dist_sq_f32x4);
 }
 
 #pragma endregion Vectorized From Dot Helpers

package/numkong/include/numkong/cast/serial.h

@@ -13,17 +13,6 @@
 extern "C" {
 #endif
 
-/*  Keep the serial conversions below actually scalar, regardless of build type.
- *  Without this, -O3 + LTO can vectorize or clone the serial kernels under AVX-512
- *  callers in dispatch_*.c, which wastes binary and breaks the nk_*_serial-as-scalar-oracle
- *  contract. See dots/serial.h. */
-#if defined(__clang__)
-#pragma clang attribute push(__attribute__((noinline)), apply_to = function)
-#elif defined(__GNUC__)
-#pragma GCC push_options
-#pragma GCC optimize("no-tree-vectorize", "no-tree-slp-vectorize", "no-ipa-cp-clone", "no-inline")
-#endif
-
 #pragma region Type Punned Loads and Stores
 
 /** @brief Type-agnostic 32-bit full load (scalar). */
@@ -563,6 +552,17 @@ NK_INTERNAL void nk_strided_load_b8x16_serial_(void const *src, nk_size_t stride
 
 #pragma endregion Type Punned Loads and Stores
 
+/*  Keep the serial conversions below actually scalar, regardless of build type.
+ *  Without this, -O3 + LTO can vectorize or clone the serial kernels under AVX-512
+ *  callers in dispatch_*.c, which wastes binary and breaks the nk_*_serial-as-scalar-oracle
+ *  contract. See dots/serial.h. */
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((noinline)), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC optimize("no-tree-vectorize", "no-tree-slp-vectorize", "no-ipa-cp-clone", "no-inline")
+#endif
+
 /**
  *  @brief Expands an `f16` (IEEE-754 16-bit) to a `float`.
  *
@@ -622,6 +622,12 @@ NK_PUBLIC void nk_f16_to_f32_serial(nk_f16_t const *src, nk_f32_t *dest) {
 #endif
 }
 
+#if defined(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
 /** @brief Load 4 × f16 from memory and upcast them to 4 × f32. */
 NK_INTERNAL void nk_load_f16x4_to_f32x4_serial_(void const *src, nk_b128_vec_t *dst) {
     nk_f16_t const *scalars = (nk_f16_t const *)src;
@@ -644,6 +650,13 @@ NK_INTERNAL void nk_partial_load_f16x4_to_f32x4_serial_(nk_f16_t const *src, nk_
     }
 }
 
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((noinline)), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC optimize("no-tree-vectorize", "no-tree-slp-vectorize", "no-ipa-cp-clone", "no-inline")
+#endif
+
 /**
  *  @brief Compresses a `float` to an `f16` (IEEE-754 16-bit).
  *
@@ -946,6 +959,12 @@ NK_PUBLIC void nk_f32_to_e4m3_serial(nk_f32_t const *src, nk_e4m3_t *dest) {
     *dest = (nk_e4m3_t)(sign | (exp_field << 3) | mant_field);
 }
 
+#if defined(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
 /**
  *  @brief Convert FP8 E4M3 to IEEE 754 half-precision float.
  *
@@ -1039,6 +1058,13 @@ NK_INTERNAL void nk_e5m2_to_f32_manual_(nk_e5m2_t const *src, nk_f32_t *dest) {
     *dest = conv.f;
 }
 
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((noinline)), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC optimize("no-tree-vectorize", "no-tree-slp-vectorize", "no-ipa-cp-clone", "no-inline")
+#endif
+
 NK_PUBLIC void nk_e5m2_to_f32_serial(nk_e5m2_t const *src, nk_f32_t *dest) {
     static nk_u32_t const lut[128] = {
         0x00000000, 0x37800000, 0x38000000, 0x38400000, // exp=0  sub
@@ -1181,6 +1207,12 @@ NK_PUBLIC void nk_f32_to_e5m2_serial(nk_f32_t const *src, nk_e5m2_t *dest) {
     *dest = (nk_e5m2_t)(sign | (exp_field << 2) | mant_field);
 }
 
+#if defined(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
 /**
  *  @brief Convert FP8 E5M2 to IEEE 754 half-precision float.
  *
@@ -1315,6 +1347,13 @@ NK_INTERNAL void nk_e2m3_to_f32_manual_(nk_e2m3_t const *src, nk_f32_t *dest) {
     *dest = conv.f;
 }
 
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((noinline)), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC optimize("no-tree-vectorize", "no-tree-slp-vectorize", "no-ipa-cp-clone", "no-inline")
+#endif
+
 NK_PUBLIC void nk_e2m3_to_f32_serial(nk_e2m3_t const *src, nk_f32_t *dest) {
     static nk_u32_t const lut[32] = {
         0x00000000, 0x3E000000, 0x3E800000, 0x3EC00000, 0x3F000000, 0x3F200000, 0x3F400000, 0x3F600000, // exp=0 sub
@@ -1415,6 +1454,12 @@ NK_PUBLIC void nk_f32_to_e2m3_serial(nk_f32_t const *src, nk_e2m3_t *dest) {
     *dest = (nk_e2m3_t)(sign | (exp_field << 3) | mant_field);
 }
 
+#if defined(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
 /**
  *  @brief Convert FP6 E3M2FN to IEEE 754 single-precision float.
  *
@@ -1452,6 +1497,13 @@ NK_INTERNAL void nk_e3m2_to_f32_manual_(nk_e3m2_t const *src, nk_f32_t *dest) {
     *dest = conv.f;
 }
 
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((noinline)), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC optimize("no-tree-vectorize", "no-tree-slp-vectorize", "no-ipa-cp-clone", "no-inline")
+#endif
+
 NK_PUBLIC void nk_e3m2_to_f32_serial(nk_e3m2_t const *src, nk_f32_t *dest) {
     static nk_u32_t const lut[32] = {
         0x00000000, 0x3D800000, 0x3E000000, 0x3E400000, // exp=0 sub
@@ -1557,6 +1609,12 @@ NK_PUBLIC void nk_f32_to_e3m2_serial(nk_f32_t const *src, nk_e3m2_t *dest) {
     *dest = (nk_e3m2_t)(sign | (exp_field << 2) | mant_field);
 }
 
+#if defined(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
 NK_INTERNAL void nk_f16_to_f64_serial(nk_f16_t const *x, nk_f64_t *y) {
     nk_f32_t f32;
     nk_f16_to_f32_serial(x, &f32);
@@ -1731,6 +1789,13 @@ NK_INTERNAL void nk_u64_to_bf16_serial(nk_u64_t const *x, nk_bf16_t *y) {
     nk_f32_to_bf16_serial(&f32, y);
 }
 
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((noinline)), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC optimize("no-tree-vectorize", "no-tree-slp-vectorize", "no-ipa-cp-clone", "no-inline")
+#endif
+
 /** @brief Convert a pair of i4 (4-bit signed integer, -8 to 7) nibbles into signed integers. */
 NK_PUBLIC void nk_i4x2_to_i8x2_serial(nk_i4x2_t const *src, nk_i8_t *dest) {
     nk_u8_t byte = *(nk_u8_t const *)src;
@@ -1776,6 +1841,12 @@ typedef union NK_MAY_ALIAS_ nk_scalar_buffer_t {
     nk_u8_t u8;
 } nk_scalar_buffer_t;
 
+#if defined(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
 /** @brief Reads a typed scalar from @p buf and writes the widened f64c into @p result.
  *  Real types set `.imag = 0`. Safe when @p result aliases @p buf (in-place conversion).
  *  @return 1 on success, 0 for unsupported types (sub-byte, unknown). */
@@ -2247,6 +2318,13 @@ NK_INTERNAL int nk_scalar_buffer_from_f64(nk_f64_t const *value, nk_scalar_buffe
 
 #pragma region Public API
 
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((noinline)), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC optimize("no-tree-vectorize", "no-tree-slp-vectorize", "no-ipa-cp-clone", "no-inline")
+#endif
+
 NK_PUBLIC void nk_cast_serial(void const *from, nk_dtype_t from_type, nk_size_t n, void *to, nk_dtype_t to_type) {
     if (from_type == to_type) {
         nk_size_t size_bits = nk_dtype_bits(from_type);