usearch 2.26.0 → 2.26.1

package/README.md

@@ -545,11 +545,11 @@ index = Index(ndim=ndim, metric=CompiledMetric(
 
 ```bibtex
 @software{Vardanian_USearch,
-doi = {10.5281/zenodo.7949416},
+doi = {10.5281/zenodo.7949415},
 author = {Vardanian, Ash},
 title = {{USearch by Unum Cloud}},
 url = {https://github.com/unum-cloud/USearch},
-version = {2.26.0},
+version = {2.26.1},
 year = {2026},
 }
 ```

package/cpp/test.cpp

@@ -1112,9 +1112,6 @@ template <typename key_at, typename slot_at> void test_strings() {
     }
 }
 
-/**
- * @brief Tests replacing and updating entries in index_dense_gt to ensure consistency after modifications.
- */
 /**
  *  @brief  Churns a tightly-reserved index, so `slot_lookup_` accumulates tombstones.
  *
@@ -1181,6 +1178,10 @@ template <typename key_at, typename slot_at> void test_slot_lookup_churn() {
         expect(copy.contains(key));
 }
 
+/**
+ *  @brief  Tests replacing and updating entries in `index_dense_gt`, to ensure consistency
+ *          after modifications.
+ */
 template <typename key_at, typename slot_at> void test_replacing_update() {
 
     using vector_key_t = key_at;
@@ -1427,6 +1428,67 @@ void test_load_after_metric_make() {
     std::remove(path);
 }
 
+/**
+ *  @brief  Feeds `view` a truncated index file.
+ *
+ *  The matrix dimensions and the node count come from the file itself, so a short file
+ *  describes a matrix and a level array that reach past the mapping. Both must be rejected
+ *  rather than walked, and a caller-supplied offset past the end must fail the same way.
+ */
+void test_view_of_truncated_file() {
+    std::printf("Testing view of a truncated index file\n");
+
+    using index_t = index_dense_gt<std::int64_t, std::uint32_t>;
+    std::size_t const dimensions = 64;
+    std::size_t const collection = 2048;
+    char const* path = "tmp_truncated.usearch";
+
+    metric_punned_t metric(dimensions, metric_kind_t::l2sq_k, scalar_kind<f32_t>());
+    index_t::state_result_t built = index_t::make(metric);
+    expect(built);
+    expect(built.index.try_reserve(collection));
+    std::vector<float> vector(dimensions);
+    for (std::size_t i = 0; i != collection; ++i) {
+        for (std::size_t d = 0; d != dimensions; ++d)
+            vector[d] = static_cast<float>((i * 31 + d) % 997) / 997.f;
+        expect(built.index.add(static_cast<std::int64_t>(i), vector.data()));
+    }
+    expect(built.index.save(path));
+
+    std::vector<char> prefix;
+    {
+        std::FILE* file = std::fopen(path, "rb");
+        expect(file != nullptr);
+        std::fseek(file, 0, SEEK_END);
+        long const bytes = std::ftell(file);
+        std::fseek(file, 0, SEEK_SET);
+        prefix.resize(static_cast<std::size_t>(bytes) / 8);
+        expect(std::fread(prefix.data(), 1, prefix.size(), file) == prefix.size());
+        std::fclose(file);
+    }
+    {
+        std::FILE* file = std::fopen(path, "wb");
+        expect(file != nullptr);
+        std::fwrite(prefix.data(), 1, prefix.size(), file);
+        std::fclose(file);
+    }
+
+    index_t::state_result_t viewed = index_t::make(metric);
+    expect(viewed);
+    serialization_result_t truncated = viewed.index.view(path);
+    expect(!truncated);
+    truncated.error.release();
+
+    // A caller-supplied offset past the end must fail the same way.
+    index_t::state_result_t offset_viewed = index_t::make(metric);
+    expect(offset_viewed);
+    serialization_result_t beyond = offset_viewed.index.view(memory_mapped_file_t(path), prefix.size() * 4);
+    expect(!beyond);
+    beyond.error.release();
+
+    std::remove(path);
+}
+
 int main(int, char**) {
     install_crash_handlers();
 
@@ -1523,5 +1585,6 @@ int main(int, char**) {
     test_filtered_search();
     test_isolate();
     test_load_after_metric_make();
+    test_view_of_truncated_file();
     return 0;
 }

package/include/usearch/index.hpp

@@ -9,7 +9,7 @@
 
 #define USEARCH_VERSION_MAJOR 2
 #define USEARCH_VERSION_MINOR 26
-#define USEARCH_VERSION_PATCH 0
+#define USEARCH_VERSION_PATCH 1
 
 // Inferring C++ version
 // https://stackoverflow.com/a/61552074
@@ -3970,6 +3970,10 @@ class index_gt {
                                                  : checked_size_overflow();
         if (!first_offset)
             return result.failed("Index is too large");
+        if (file.size() < first_offset.value) {
+            reset();
+            return result.failed("File is corrupted and can't fit the node levels");
+        }
         offsets[0u] = first_offset.value;
         for (std::size_t i = 1; i < header_size.value; ++i) {
             checked_size_result_t next_offset = checked_add(offsets[i - 1], node_bytes_(levels[i - 1]));

package/include/usearch/index_dense.hpp

@@ -1050,17 +1050,18 @@ class index_dense_gt {
      */
     bool try_reserve(index_limits_t limits) {
 
+        // Reserving is monotonic: reducing thread limits must not shrink member-addressed storage.
+        limits.members = (std::max)(limits.members, typed_->capacity());
+        limits.members = (std::max)(limits.members, vectors_lookup_.size());
+
         // The slot lookup system will generally prefer power-of-two sizes.
         if (config_.enable_key_lookups) {
             unique_lock_t lock(slot_lookup_mutex_);
             if (!slot_lookup_.try_reserve(limits.members))
                 return false;
-            limits.members = slot_lookup_.capacity();
         }
 
-        // Once the `slot_lookup_` grows, let's use its capacity as the new
-        // target for the `vectors_lookup_` to synchronize allocations and
-        // expensive index re-organizations.
+        // Hash-table load-factor slack does not need corresponding vector or graph slots.
         if (limits.members != vectors_lookup_.size()) {
             vectors_lookup_t new_vectors_lookup(limits.members);
             if (!new_vectors_lookup)
@@ -1358,6 +1359,11 @@ class index_dense_gt {
         if (!result)
             return result;
 
+        // `offset` is caller-supplied, so every `file.size() - offset` below would
+        // otherwise underflow into a huge span instead of failing.
+        if (offset > file.size())
+            return result.failed("File is corrupted and lacks matrix dimensions");
+
         // Infer the new index size
         std::uint64_t matrix_rows = 0;
         std::uint64_t matrix_cols = 0;
@@ -1383,7 +1389,12 @@ class index_dense_gt {
                 matrix_cols = dimensions[1];
                 offset += sizeof(dimensions);
             }
-            vectors_buffer = {file.data() + offset, static_cast<std::size_t>(matrix_rows * matrix_cols)};
+            // bound the vectors matrix span against the file (overflow-safe; offset <= file.size() holds here)
+            checked_size_result_t vectors_bytes =
+                checked_mul(static_cast<std::size_t>(matrix_rows), static_cast<std::size_t>(matrix_cols));
+            if (!vectors_bytes || file.size() - offset < vectors_bytes.value)
+                return result.failed("File is corrupted: vectors matrix exceeds file size");
+            vectors_buffer = {file.data() + offset, vectors_bytes.value};
             offset += vectors_buffer.size();
         }
 

package/package.json

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