usearch 2.26.1 → 2.26.3

package/numkong/swift/README.md

@@ -43,7 +43,7 @@ Packing handles internal layout itself.
 
 ## Ecosystem Comparison
 
-| Feature                      | NumKong                                                                                                                | Accelerate/vDSP                                                   | [MLX](https://github.com/ml-explore/mlx)                           |
+| Feature                      | NumKong                                                                                                                | Accelerate/vDSP                                                   | [MLX][mlx]                                                         |
 | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------ |
 | Operation families           | dots, distances, binary, geospatial, MaxSim                                                                            | dots, distances, FFT, some BLAS                                   | matmul, elementwise, reductions, FFT                               |
 | Precision                    | BFloat16 through sub-byte — Float8, Float6, packed bits; automatic widening; Kahan summation; 0 ULP in Float32/Float64 | Float32/Float64, limited Float16; no auto-widening; IEEE defaults | Float16/BFloat16/Float32; no Float8 or sub-byte; backend-dependent |
@@ -53,6 +53,8 @@ Packing handles internal layout itself.
 | Collection-based API         | works with any `RandomAccessCollection` conforming type                                                                | pointer-based vDSP functions                                      | `MLXArray`-based                                                   |
 | Memory model                 | caller-owned buffers; `Tensor`/`PackedMatrix` own their storage                                                        | caller-managed via `UnsafePointer`                                | graph-managed; implicit allocation and caching                     |
 
+[mlx]: https://github.com/ml-explore/mlx
+
 ## Installation
 
 Add NumKong to `Package.swift`:
@@ -74,7 +76,7 @@ Then add the product to your target:
 )
 ```
 
-The root package manifest already exposes the `NumKong` and `CNumKong` targets.
+The root package manifest already exposes the `NumKong` and `CNumKongDispatch` library products.
 Xcode package integration uses the same URL.
 
 ## Collection-Based Dot Products
@@ -415,7 +417,7 @@ let haversine = haversine(aLat: libertyLat, aLon: libertyLon, bLat: bigBenLat, b
 
 The low-level `UnsafeBufferPointer` static methods on `Float64` and `Float32` remain available for zero-copy use cases.
 
-## Runtime Capabilities and Thread Configuration
+## Runtime Capabilities
 
 Capability detection is exposed directly for diagnostics and tests:
 

package/numkong/test/README.md

@@ -70,10 +70,10 @@ Foreign flag mapping for muscle-memory compatibility:
 
 Each kernel is assigned a __comparison family__ that determines which error metrics are reported and what constitutes failure.
 Families are defined in `test.hpp` as `comparison_family_t`.
-All floating-point families report `max_abs`, `max_rel`, `mean_ulp`, `max_ulp`, and `exact` match counts; some also add `mean_abs` or `mean_rel`.
+All floating-point families report `max_abs`, `max_rel`, and `mean_ulp`; most also report `max_ulp` and `exact` match counts, and some substitute `mean_abs` or `mean_rel`.
 
 - __`exact_k`__ — integer and binary metrics: Hamming, Jaccard, set intersections, integer min/max.
-  Reports `max_dist`, `mean_dist`, `mismatch`, `exact`.
+  Reports `max_dist`, `mean_dist`, `max_abs`, `mismatch`, `exact`.
   Fails on any `max_dist > 0`.
 - __`narrow_arithmetic_k`__ — elementwise float ops: sum, scale, blend, fma, sin, cos, atan, cast.
   Fails on `max_ulp > NK_ULP_THRESHOLD_{F32,F16,BF16}`.
@@ -139,7 +139,7 @@ The toolchain files configure memory limits appropriate for each target:
 | ------ | -------------- | ---------- | ------------- | ------------------ |
 | wasm32 | 64 MB          | 2 GB       | 32-bit        | 3.1.27+            |
 | wasm64 | 256 MB         | 16 GB      | 64-bit        | 3.1.35+            |
-| WASI   | —              | 256 MB     | 32-bit        | —                  |
+| WASI   | —              | 2 GB       | 32-bit        | —                  |
 
 All three targets enable `-msimd128` and `-mrelaxed-simd` automatically.
 Stack size is 5 MB across all Emscripten targets.
@@ -156,7 +156,7 @@ For up-to-date engine support, see [WebAssembly Roadmap](https://webassembly.org
 
 ### Cross-Compilation
 
-NumKong ships 8 toolchain files in `cmake/` for cross-compiling to non-native targets.
+NumKong ships 11 toolchain files in `cmake/` for cross-compiling to non-native targets.
 Tests run transparently under QEMU via `CMAKE_CROSSCOMPILING_EMULATOR`.
 Set `NK_IN_QEMU=1` to relax half-precision accuracy thresholds under emulation.
 

package/numkong/test/test-wasi.mjs

@@ -0,0 +1,17 @@
+// Minimal WASI command runner: `node --experimental-wasi-unstable-preview1 run-wasi.mjs <module.wasm> [args...]`
+// Lets CTest use node as a cross-runtime engine for the portable WASI tests, alongside wasmtime and wasmer
+// (see cmake/toolchain-wasi.cmake, NK_WASM_RUNTIME=node). Node cannot execute a bare `.wasm` from the CLI,
+// so this thin wrapper instantiates it with a WASI import object and forwards the process exit code.
+import { readFileSync } from 'node:fs';
+import { WASI } from 'node:wasi';
+import { argv, exit } from 'node:process';
+
+const modulePath = argv[2];
+if (!modulePath) {
+    console.error('usage: node --experimental-wasi-unstable-preview1 run-wasi.mjs <module.wasm> [args...]');
+    exit(2);
+}
+const wasi = new WASI({ version: 'preview1', args: argv.slice(2), returnOnExit: true });
+const module = new WebAssembly.Module(readFileSync(modulePath));
+const instance = new WebAssembly.Instance(module, wasi.getImportObject());
+exit(wasi.start(instance));

package/numkong/test/test_each.cpp

@@ -6,7 +6,8 @@
  */
 
 #include "test.hpp"
-#include "numkong/each.hpp" // `nk::sum`, `nk::scale`, `nk::blend`, `nk::fma`
+#include "numkong/each.hpp"          // `nk::sum`, `nk::scale`, `nk::blend`, `nk::fma`
+#include "numkong/trigonometry.hpp"  // `nk::try_sin`, `nk::try_cos`, `nk::try_atan` wrappers
 
 template <typename scalar_type_, typename generator_type_>
 typename scalar_type_::scale_t random_coef(generator_type_ &gen) {
@@ -150,9 +151,37 @@ error_stats_t test_fma(typename scalar_type_::fma_kernel_t kernel) {
     return stats;
 }
 
+/**
+ *  @brief Smoke-test for the tensor-shaped trig wrappers (`nk::try_sin`/`cos`/`atan`).
+ *  Runs allocating + into-span variants on a small zero tensor — just exercises the dispatch
+ *  paths, not the numerical accuracy (the latter is covered by the kernel tests above).
+ */
+template <typename value_type_>
+void test_tensor_trig_for_type() {
+    using tensor_t = nk::tensor<value_type_>;
+    auto a = tensor_t::try_zeros({4, 8});
+    auto out = tensor_t::try_zeros({4, 8});
+    auto av = a.view();
+
+    { [[maybe_unused]] auto r = nk::try_sin<value_type_>(av); }
+    { [[maybe_unused]] auto r = nk::try_cos<value_type_>(av); }
+    { [[maybe_unused]] auto r = nk::try_atan<value_type_>(av); }
+    { [[maybe_unused]] bool ok = nk::sin<value_type_>(av, out.span()); }
+    { [[maybe_unused]] bool ok = nk::cos<value_type_>(av, out.span()); }
+    { [[maybe_unused]] bool ok = nk::atan<value_type_>(av, out.span()); }
+}
+
 void test_each() {
     error_stats_section_t check("Elementwise Operations");
 
+    // Tensor-shaped trig wrappers (float-capable types).
+    test_tensor_trig_for_type<nk::f32_t>();
+    test_tensor_trig_for_type<nk::f64_t>();
+    test_tensor_trig_for_type<nk::f16_t>();
+    test_tensor_trig_for_type<nk::bf16_t>();
+    std::printf("  trig (4 types):               OK\n");
+
+
 #if NK_DYNAMIC_DISPATCH
     // Dynamic dispatch - only test the dispatcher itself
     check("each_scale_f32", test_scale<f32_t>, nk_each_scale_f32);

package/numkong/test/test_each.py

@@ -405,7 +405,7 @@ def test_add_multiply_noncontiguous(dtype: str, kernel, capability: str):
         if mismatch_count:
             collect_warnings(f"NumPy overflow in ({a.dtype} {operator} {b.dtype} -> {output_dtype})", stats)
 
-        # out= with nk.Tensor buffer (same-dtype only, to avoid cast complexity)
+        # out= with nk.Tensor buffer; differing dtypes are covered by test_strided_out_with_dtype_change
         if first_dtype == second_dtype == output_dtype and inplace_numkong.ndim == 1:
             out_nk = nk.zeros(inplace_numkong.shape, dtype=output_dtype)
             ret = simd_kernel(a, b, out=out_nk)
@@ -754,3 +754,76 @@ def test_blend_known(ndim: int, dtype: str, capability: str):
     result = list(nk.blend(a, b, alpha=2.0, beta=3.0))
     for i in range(ndim):
         assert abs(result[i] - expected) < NK_ATOL, f"blend[{i}] = {result[i]}, expected {expected}"
+
+
+@pytest.mark.skipif(not numpy_available, reason="NumPy is not installed")
+@pytest.mark.parametrize("kernel", ["add", "multiply"])
+@pytest.mark.parametrize("second_is_scalar", [True, False], ids=["scalar_b", "array_b"])
+@pytest.mark.parametrize("capability", possible_capabilities)
+def test_strided_out_with_dtype_change(kernel: str, second_is_scalar: bool, capability: str):
+    """A strided `out` of a differing dtype must be scattered, not packed over its neighbours.
+
+    The scalar and array forms of `b` select different implementations, and each of
+    `add`/`multiply` has its own pair, so this covers all four writeback paths.
+    """
+    keep_one_capability(capability)
+    simd_kernel = getattr(nk, kernel)
+    first = np.arange(6, dtype=np.int16)
+    second = 5 if second_is_scalar else np.arange(6, dtype=np.int16)
+    expected = first + second if kernel == "add" else first * second
+
+    # Column 0 of a 2-column array: same shape as the input, stride of two float64s.
+    surrounding = np.zeros((6, 2), dtype=np.float64)
+    simd_kernel(first, second, out=surrounding[:, 0])
+    assert_allclose(surrounding[:, 0], expected.astype(np.float64), atol=NK_ATOL, rtol=NK_RTOL)
+    assert not surrounding[:, 1].any(), "writeback spilled into the neighbouring column"
+
+    # Reversed view exercises the negative-stride path.
+    reversed_out = np.zeros(6, dtype=np.float64)[::-1]
+    simd_kernel(first, second, out=reversed_out)
+    assert_allclose(reversed_out, expected.astype(np.float64), atol=NK_ATOL, rtol=NK_RTOL)
+
+    # A packed `out` must still take the single bulk-cast path.
+    contiguous_out = np.zeros(6, dtype=np.float64)
+    simd_kernel(first, second, out=contiguous_out)
+    assert_allclose(contiguous_out, expected.astype(np.float64), atol=NK_ATOL, rtol=NK_RTOL)
+
+
+@pytest.mark.skipif(not numpy_available, reason="NumPy is not installed")
+@pytest.mark.parametrize("kernel", ["add", "multiply"])
+def test_strided_out_multidimensional(kernel: str):
+    """Rank-2 and rank-3 outputs cover both a fully scattered tail and a partially packed one."""
+    simd_kernel = getattr(nk, kernel)
+
+    # Rank 2, innermost dimension strided: no contiguous tail at all.
+    first = np.arange(12, dtype=np.int16).reshape(3, 4)
+    expected = first + 2 if kernel == "add" else first * 2
+    surrounding = np.zeros((3, 4, 2), dtype=np.float64)
+    simd_kernel(first, 2, out=surrounding[:, :, 0])
+    assert_allclose(surrounding[:, :, 0], expected.astype(np.float64), atol=NK_ATOL, rtol=NK_RTOL)
+    assert not surrounding[:, :, 1].any(), "writeback spilled into the neighbouring column"
+
+    # Rank 3 with a packed innermost pair: recursion plus a bulk slice per row.
+    first = np.arange(24, dtype=np.int16).reshape(2, 6, 2)
+    expected = first + 3 if kernel == "add" else first * 3
+    surrounding = np.zeros((2, 6, 4), dtype=np.float64)
+    simd_kernel(first, 3, out=surrounding[:, :, 0:2])
+    assert_allclose(surrounding[:, :, 0:2], expected.astype(np.float64), atol=NK_ATOL, rtol=NK_RTOL)
+    assert not surrounding[:, :, 2:].any(), "writeback spilled past the requested columns"
+
+
+@pytest.mark.skipif(not numpy_available, reason="NumPy is not installed")
+@pytest.mark.parametrize(
+    "dtype,distinct_values",
+    [pytest.param("uint4", 8, id="uint4"), pytest.param("int4", 8, id="int4"), pytest.param("uint1", 2, id="uint1")],
+)
+def test_packed_out_requires_contiguity(dtype: str, distinct_values: int):
+    """Sub-byte dtypes have no per-value byte stride, so only a packed `out` can be filled."""
+    first = np.arange(8, dtype=np.uint8) % distinct_values
+
+    packed_out = nk.zeros(first.shape, dtype=dtype)
+    nk.add(first, 0, out=packed_out)
+    assert_allclose(np.asarray(nk.astype(packed_out, "uint8")), first, atol=NK_ATOL, rtol=NK_RTOL)
+
+    with pytest.raises(ValueError, match="C-contiguous"):
+        nk.add(first[:4], 0, out=nk.zeros(first.shape, dtype=dtype)[::2])

package/numkong/test/test_reduce.cpp

@@ -62,9 +62,60 @@ error_stats_t test_reduce_minmax(typename input_type_::reduce_minmax_kernel_t ke
     return stats;
 }
 
+/**
+ *  @brief Smoke-test for the vector-shaped reduction wrappers (`nk::moments`/`minmax`/`sum`/...).
+ *  Exercises every accessor variant on a small random vector. Numerical accuracy of the
+ *  underlying kernels is validated by `test_reduce_moments` / `test_reduce_minmax` above.
+ */
+template <typename value_type_>
+void test_vector_reductions_for_type() {
+    auto v = make_vector<value_type_>(32);
+    std::mt19937 generator(42);
+    fill_random(generator, v);
+    auto view = nk::vector_view<value_type_>(v.values_data(), static_cast<std::size_t>(v.size()));
+
+    { [[maybe_unused]] auto r = nk::moments(view); }
+    { [[maybe_unused]] auto r = nk::minmax(view); }
+    { [[maybe_unused]] auto r = nk::sum(view); }
+    { [[maybe_unused]] auto r = nk::min(view); }
+    { [[maybe_unused]] auto r = nk::max(view); }
+    { [[maybe_unused]] auto r = nk::argmin(view); }
+    { [[maybe_unused]] auto r = nk::argmax(view); }
+}
+
+/**
+ *  @brief Golden-value test for the vector-shaped reduction wrappers.
+ */
+inline void test_vector_reductions_correctness() {
+    nk::f32_t data[] = {nk::f32_t(1), nk::f32_t(2), nk::f32_t(3), nk::f32_t(4), nk::f32_t(5)};
+    auto view = nk::vector_view<nk::f32_t>(data, std::size_t {5});
+
+    auto m = nk::moments(view);
+    assert(m.sum.raw_ == 15.0 && "vector moments sum");
+    assert(m.sumsq.raw_ == 55.0 && "vector moments sumsq");
+
+    auto mm = nk::minmax(view);
+    assert(mm.min_value.raw_ == 1.0f && "vector min");
+    assert(mm.max_value.raw_ == 5.0f && "vector max");
+    assert(mm.min_index == 0 && "vector argmin");
+    assert(mm.max_index == 4 && "vector argmax");
+}
+
 void test_reduce() {
     error_stats_section_t check("Reductions");
 
+    // Tensor- and vector-shaped wrapper smoke tests (independent of ISA dispatch).
+    test_vector_reductions_for_type<nk::f32_t>();
+    test_vector_reductions_for_type<nk::f64_t>();
+    test_vector_reductions_for_type<nk::f16_t>();
+    test_vector_reductions_for_type<nk::bf16_t>();
+    test_vector_reductions_for_type<nk::i8_t>();
+    test_vector_reductions_for_type<nk::u8_t>();
+    std::printf("  vector reductions (6 types):  OK\n");
+
+    test_vector_reductions_correctness();
+    std::printf("  vector reductions correct:    OK\n");
+
 #if NK_DYNAMIC_DISPATCH
     check("reduce_moments_f32", test_reduce_moments<f32_t>, nk_reduce_moments_f32, nk_reduce_moments_f32_serial);
     check("reduce_moments_f64", test_reduce_moments<f64_t>, nk_reduce_moments_f64, nk_reduce_moments_f64_serial);

package/numkong/test/test_tensor.cpp

@@ -679,21 +679,6 @@ void test_tensor_ops_for_type() {
     }
 }
 
-template <typename value_type_>
-void test_tensor_trig_for_type() {
-    using tensor_t = nk::tensor<value_type_>;
-    auto a = tensor_t::try_zeros({4, 8});
-    auto out = tensor_t::try_zeros({4, 8});
-    auto av = a.view();
-
-    { [[maybe_unused]] auto r = nk::try_sin<value_type_>(av); }
-    { [[maybe_unused]] auto r = nk::try_cos<value_type_>(av); }
-    { [[maybe_unused]] auto r = nk::try_atan<value_type_>(av); }
-    { [[maybe_unused]] bool ok = nk::sin<value_type_>(av, out.span()); }
-    { [[maybe_unused]] bool ok = nk::cos<value_type_>(av, out.span()); }
-    { [[maybe_unused]] bool ok = nk::atan<value_type_>(av, out.span()); }
-}
-
 template <typename value_type_>
 void test_tensor_symmetric_for_type() {
     using tensor_t = nk::tensor<value_type_>;
@@ -761,37 +746,6 @@ void test_custom_allocator_try_fns() {
     { auto r = nk::try_sum<nk::f32_t, 8, sum_alloc_t>(av, 0); }
 }
 
-template <typename value_type_>
-void test_vector_reductions_for_type() {
-    auto v = make_vector<value_type_>(32);
-    std::mt19937 generator(42);
-    fill_random(generator, v);
-    auto view = nk::vector_view<value_type_>(v.values_data(), static_cast<std::size_t>(v.size()));
-
-    { [[maybe_unused]] auto r = nk::moments(view); }
-    { [[maybe_unused]] auto r = nk::minmax(view); }
-    { [[maybe_unused]] auto r = nk::sum(view); }
-    { [[maybe_unused]] auto r = nk::min(view); }
-    { [[maybe_unused]] auto r = nk::max(view); }
-    { [[maybe_unused]] auto r = nk::argmin(view); }
-    { [[maybe_unused]] auto r = nk::argmax(view); }
-}
-
-void test_vector_reductions_correctness() {
-    nk::f32_t data[] = {nk::f32_t(1), nk::f32_t(2), nk::f32_t(3), nk::f32_t(4), nk::f32_t(5)};
-    auto view = nk::vector_view<nk::f32_t>(data, std::size_t {5});
-
-    auto m = nk::moments(view);
-    assert(m.sum.raw_ == 15.0 && "vector moments sum");
-    assert(m.sumsq.raw_ == 55.0 && "vector moments sumsq");
-
-    auto mm = nk::minmax(view);
-    assert(mm.min_value.raw_ == 1.0f && "vector min");
-    assert(mm.max_value.raw_ == 5.0f && "vector max");
-    assert(mm.min_index == 0 && "vector argmin");
-    assert(mm.max_index == 4 && "vector argmax");
-}
-
 template <typename from_type_, typename to_type_>
 void test_cast_for_types() {
     auto src = make_vector<from_type_>(64);
@@ -884,12 +838,7 @@ void test_tensor_ops() {
     test_packed_tensor_fail_closed_views();
     std::printf("  tensor fail-closed views:     OK\n");
 
-    // Trig (float-capable types)
-    test_tensor_trig_for_type<nk::f32_t>();
-    test_tensor_trig_for_type<nk::f64_t>();
-    test_tensor_trig_for_type<nk::f16_t>();
-    test_tensor_trig_for_type<nk::bf16_t>();
-    std::printf("  trig (4 types):               OK\n");
+    // (Trig wrappers moved to test_each.cpp — they are elementwise operations.)
 
     // Symmetric distances
     test_tensor_symmetric_for_type<nk::f32_t>();
@@ -919,17 +868,7 @@ void test_tensor_ops() {
     test_custom_allocator_try_fns();
     std::printf("  custom allocator try_fns:     OK\n");
 
-    // Vector-level reductions
-    test_vector_reductions_for_type<nk::f32_t>();
-    test_vector_reductions_for_type<nk::f64_t>();
-    test_vector_reductions_for_type<nk::f16_t>();
-    test_vector_reductions_for_type<nk::bf16_t>();
-    test_vector_reductions_for_type<nk::i8_t>();
-    test_vector_reductions_for_type<nk::u8_t>();
-    std::printf("  vector reductions (6 types):  OK\n");
-
-    test_vector_reductions_correctness();
-    std::printf("  vector reductions correct:    OK\n");
+    // (Vector-level reduction wrappers moved to test_reduce.cpp.)
 
     // Cast wrapper
     test_cast_for_types<nk::f32_t, nk::f16_t>();

package/numkong/test/test_tensor.py

@@ -102,6 +102,99 @@ KERNELS_TENSOR: dict[str, tuple[Callable, Callable, Callable | None]] = {
 }
 
 
+@pytest.mark.skipif(not numpy_available, reason="NumPy is not installed")
+def test_astype_accepts_ndarray_without_tensor_copy():
+    """Top-level astype converts an N-D NumPy buffer while preserving its shape."""
+    source = np.arange(24, dtype=np.uint8).reshape(2, 3, 4)
+
+    result = nk.astype(source, "float32")
+
+    assert result.shape == source.shape
+    assert result.dtype == "float32"
+    assert_allclose(np.asarray(result), source.astype(np.float32))
+
+
+@pytest.mark.skipif(not numpy_available, reason="NumPy is not installed")
+def test_astype_writes_to_caller_owned_output():
+    """Top-level astype converts directly into a matching caller-owned buffer and returns it."""
+    source = np.arange(12, dtype=np.float32).reshape(3, 4) + 0.75
+    output = np.empty(source.shape, dtype=np.uint8)
+
+    assert nk.astype(source, "uint8", out=output) is output
+    assert_allclose(output, source.astype(np.uint8))
+
+
+@pytest.mark.skipif(not numpy_available, reason="NumPy is not installed")
+@pytest.mark.parametrize("dtype", ["bfloat16", "uint4"])
+def test_astype_writes_to_tensor_output(dtype):
+    """A NumKong Tensor names dtypes NumPy cannot express, so it must be accepted as `out`."""
+    source = np.arange(8, dtype=np.uint8)
+    output = nk.empty(source.shape, dtype=dtype)
+
+    assert nk.astype(source, dtype, out=output) is output
+    np.testing.assert_array_equal(np.asarray(nk.astype(output, "uint8")), source)
+
+
+@pytest.mark.skipif(not numpy_available, reason="NumPy is not installed")
+def test_astype_linearizes_strided_input():
+    """Top-level astype accepts a non-contiguous input buffer."""
+    source = np.arange(48, dtype=np.int16).reshape(2, 3, 8)[:, ::-1, ::2]
+
+    result = nk.astype(source, "float32")
+
+    assert result.shape == source.shape
+    assert_allclose(np.asarray(result), source.astype(np.float32))
+
+
+@pytest.mark.skipif(not numpy_available, reason="NumPy is not installed")
+def test_astype_float_to_integer_policy():
+    """Float-to-integer casts round ties to even, saturate, and map NaN to zero."""
+    source = np.array([-np.inf, -127.5, -0.5, 0.5, 1.5, 126.5, np.inf, np.nan], dtype=np.float64)
+
+    result = nk.astype(source, "int8")
+
+    np.testing.assert_array_equal(np.asarray(result), np.array([-128, -128, 0, 0, 2, 126, 127, 0], dtype=np.int8))
+
+
+@pytest.mark.skipif(not numpy_available, reason="NumPy is not installed")
+def test_astype_round_trips_through_packed_dtype():
+    """Top-level astype preserves logical values when a packed Tensor is used in between."""
+    source = np.arange(8, dtype=np.uint8)
+
+    packed = nk.astype(source, "uint4")
+    result = nk.astype(packed, "uint8")
+
+    assert packed.dtype == "uint4"
+    np.testing.assert_array_equal(np.asarray(result), source)
+
+
+@pytest.mark.skipif(not numpy_available, reason="NumPy is not installed")
+def test_astype_validates_output_shape_dtype_and_layout():
+    """Top-level astype requires an exact, C-contiguous output buffer."""
+    source = np.arange(24, dtype=np.uint8).reshape(2, 3, 4)
+
+    with pytest.raises(ValueError, match="shapes don't match"):
+        nk.astype(source, "float32", out=np.empty((2, 3, 3), dtype=np.float32))
+    with pytest.raises(TypeError, match="expected"):
+        nk.astype(source, "float32", out=np.empty(source.shape, dtype=np.float64))
+    with pytest.raises(ValueError, match="C-contiguous"):
+        nk.astype(source, "float32", out=np.empty((4, 3, 2), dtype=np.float32).transpose(2, 1, 0))
+
+    readonly = np.empty(source.shape, dtype=np.float32)
+    readonly.flags.writeable = False
+    with pytest.raises((ValueError, BufferError, TypeError)):
+        nk.astype(source, "float32", out=readonly)
+
+
+@pytest.mark.skipif(not numpy_available, reason="NumPy is not installed")
+def test_astype_rejects_overlapping_output():
+    """Top-level astype rejects an output buffer that aliases its input."""
+    source = np.arange(12, dtype=np.float32)
+
+    with pytest.raises(ValueError, match="must not overlap"):
+        nk.astype(source, "float32", out=source)
+
+
 def test_pointers_availability():
     """Tests the availability of pre-compiled functions for compatibility with USearch."""
     assert nk.pointer_to_sqeuclidean("float64") != 0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "2.26.1",
+    "version": "2.26.3",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ash Vardanian (https://ashvardanian.com/)",
     "license": "Apache 2.0",