usearch 2.25.3 → 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.25.3},
+version = {2.26.1},
 year = {2026},
 }
 ```

package/cpp/test.cpp

@@ -1113,7 +1113,74 @@ 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.
+ *
+ *  Removals leave tombstones that probes must walk past. If they are never reclaimed the
+ *  table runs out of empty slots, probes can no longer terminate, and live keys go missing:
+ *  `remove` reports nothing removed while `contains` still finds the key. Copying such a
+ *  table must rebuild the probe chains, not reproduce the slot layout.
+ */
+template <typename key_at, typename slot_at> void test_slot_lookup_churn() {
+    constexpr std::size_t live_count = 128;
+    constexpr std::size_t churn_count = live_count * 8;
+    constexpr std::size_t dimensions = 4;
+
+    using index_punned_t = index_dense_gt<key_at, slot_at>;
+    metric_punned_t metric(dimensions, metric_kind_t::cos_k);
+
+    std::random_device seed_source;
+    std::mt19937 generator(seed_source());
+    std::uniform_real_distribution<float> distribution(0.0, 1.0);
+    using vector_of_vectors_t = std::vector<std::vector<float>>;
+
+    vector_of_vectors_t vector_of_vectors(live_count + churn_count);
+    for (auto& vector : vector_of_vectors) {
+        vector.resize(dimensions);
+        std::generate(vector.begin(), vector.end(), [&] { return distribution(generator); });
+    }
+
+    index_punned_t index = index_punned_t::make(metric);
+
+    // Reserve tightly, so the churn below exhausts the empty slots
+    index.reserve(live_count * 3);
+
+    std::vector<key_at> live_keys;
+    std::size_t added = 0;
+    for (; added < live_count; ++added) {
+        index.add(static_cast<key_at>(added), vector_of_vectors[added].data());
+        live_keys.push_back(static_cast<key_at>(added));
+    }
+
+    // Every iteration frees one slot and immediately reuses it
+    for (std::size_t idx = 0; idx < churn_count; ++idx, ++added) {
+        key_at victim = live_keys[idx % live_count];
+        expect(index.contains(victim));
+        expect_eq(index.remove(victim).completed, 1);
+        expect(!index.contains(victim));
+        index.add(static_cast<key_at>(added), vector_of_vectors[added].data());
+        live_keys[idx % live_count] = static_cast<key_at>(added);
+    }
+
+    // Every live key stays reachable and the size never drifts
+    expect_eq(index.size(), live_count);
+    for (key_at key : live_keys)
+        expect(index.contains(key));
+
+    // Copying a table that still holds tombstones must not strand live keys
+    expect_eq(index.remove(live_keys.back()).completed, 1);
+    live_keys.pop_back();
+
+    auto copy_result = index.copy();
+    expect(copy_result);
+    index_punned_t& copy = copy_result.index;
+    expect_eq(copy.size(), live_keys.size());
+    for (key_at key : live_keys)
+        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() {
 
@@ -1361,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();
 
@@ -1450,8 +1578,13 @@ int main(int, char**) {
         test_sets<std::int64_t, slot32_t>(set_size, 20, 30);
     test_strings<std::int64_t, slot32_t>();
 
+    std::printf("Testing key lookups under churn\n");
+    test_slot_lookup_churn<std::int64_t, std::uint32_t>();
+    test_slot_lookup_churn<std::int64_t, uint40_t>();
+
     test_filtered_search();
     test_isolate();
     test_load_after_metric_make();
+    test_view_of_truncated_file();
     return 0;
 }

package/include/usearch/index.hpp

@@ -8,8 +8,8 @@
 #define UNUM_USEARCH_HPP
 
 #define USEARCH_VERSION_MAJOR 2
-#define USEARCH_VERSION_MINOR 25
-#define USEARCH_VERSION_PATCH 3
+#define USEARCH_VERSION_MINOR 26
+#define USEARCH_VERSION_PATCH 1
 
 // Inferring C++ version
 // https://stackoverflow.com/a/61552074
@@ -1277,6 +1277,31 @@ template <typename element_at> struct hash_gt {
     std::size_t operator()(element_at const& element) const noexcept { return std::hash<element_at>{}(element); }
 };
 
+/**
+ *  @brief  SplitMix64 finalizer, used to scatter integer keys before masking.
+ *
+ *  On libstdc++ and libc++ `std::hash` is the identity for integers. Our open-addressing
+ *  tables mask that hash into a power-of-2 slot count and probe linearly until an @b empty
+ *  slot, so consecutive keys land in adjacent slots and merge into one contiguous run.
+ *  Both insertions and lookups then scan that run end-to-end, which is quadratic overall:
+ *  a dense ascending key range collapses insertion throughput by three orders of magnitude.
+ *  Mixing costs ~20ns per key and is dwarfed by the graph traversal in `add`.
+ */
+template <> struct hash_gt<std::uint64_t> {
+    std::size_t operator()(std::uint64_t const& element) const noexcept {
+        std::uint64_t x = element;
+        x = (x ^ (x >> 30u)) * 0xBF58476D1CE4E5B9ULL;
+        x = (x ^ (x >> 27u)) * 0x94D049BB133111EBULL;
+        return static_cast<std::size_t>(x ^ (x >> 31u));
+    }
+};
+
+template <> struct hash_gt<std::int64_t> {
+    std::size_t operator()(std::int64_t const& element) const noexcept {
+        return hash_gt<std::uint64_t>{}(static_cast<std::uint64_t>(element));
+    }
+};
+
 template <> struct hash_gt<uint40_t> {
     std::size_t operator()(uint40_t const& element) const noexcept { return std::hash<std::size_t>{}(element); }
 };
@@ -3945,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/include/usearch/index_plugins.hpp

@@ -3746,6 +3746,8 @@ class flat_hash_multi_set_gt {
     char* data_ = nullptr;
     std::size_t buckets_ = 0;
     std::size_t populated_slots_ = 0;
+    /// @brief  Number of tombstones (slots marked deleted but not yet reclaimed)
+    std::size_t deleted_slots_ = 0;
     /// @brief  Number of slots
     std::size_t capacity_slots_ = 0;
 
@@ -3781,6 +3783,34 @@ class flat_hash_multi_set_gt {
         }
     }
 
+    /**
+     *  @brief  Copies every live entry of @p source into the freshly zeroed @p target.
+     *
+     *  Tombstones are never carried over, so probe chains must be rebuilt from the hash
+     *  rather than reproduced slot-for-slot: a live entry displaced past a tombstone by
+     *  linear probing would otherwise become unreachable once that tombstone reads empty.
+     *  The target holds no tombstones, so an unpopulated slot is always a free slot.
+     */
+    void rehash_into(char* source, std::size_t source_slots, char* target, std::size_t target_slots) const noexcept {
+        hash_t hasher;
+        for (std::size_t i = 0; i != source_slots; ++i) {
+            slot_ref_t source_slot = slot_ref(source, i);
+            if (!(source_slot.header.populated & source_slot.mask) || (source_slot.header.deleted & source_slot.mask))
+                continue;
+
+            std::size_t target_index = hasher(source_slot.element) & (target_slots - 1);
+            while (true) {
+                slot_ref_t target_slot = slot_ref(target, target_index);
+                if (!(target_slot.header.populated & target_slot.mask)) {
+                    new (&target_slot.element) element_t(source_slot.element);
+                    target_slot.header.populated |= target_slot.mask;
+                    break;
+                }
+                target_index = (target_index + 1) & (target_slots - 1);
+            }
+        }
+    }
+
   public:
     std::size_t size() const noexcept { return populated_slots_; }
     std::size_t capacity() const noexcept { return capacity_slots_ * 2u / 3u; }
@@ -3805,22 +3835,15 @@ class flat_hash_multi_set_gt {
         if (!data_)
             usearch_raise_runtime_error("failed memory allocation");
 
-        // Copy metadata
+        // Copy metadata. Only live entries are rehashed below, so the copy has no tombstones.
         buckets_ = other.buckets_;
         populated_slots_ = other.populated_slots_;
+        deleted_slots_ = 0;
         capacity_slots_ = other.capacity_slots_;
 
         // Initialize new buckets to empty
         std::memset(data_, 0, buckets_ * bytes_per_bucket());
-
-        // Copy elements and bucket headers
-        for (std::size_t i = 0; i < capacity_slots_; ++i) {
-            slot_ref_t old_slot = other.slot_ref(i);
-            if ((old_slot.header.populated & old_slot.mask) && !(old_slot.header.deleted & old_slot.mask)) {
-                slot_ref_t new_slot = slot_ref(i);
-                populate_slot(new_slot, old_slot.element);
-            }
-        }
+        rehash_into(other.data_, other.capacity_slots_, data_, capacity_slots_);
     }
 
     flat_hash_multi_set_gt& operator=(flat_hash_multi_set_gt const& other) {
@@ -3848,22 +3871,15 @@ class flat_hash_multi_set_gt {
         if (!data_)
             usearch_raise_runtime_error("failed memory allocation");
 
-        // Copy metadata
+        // Copy metadata. Only live entries are rehashed below, so the copy has no tombstones.
         buckets_ = other.buckets_;
         populated_slots_ = other.populated_slots_;
+        deleted_slots_ = 0;
         capacity_slots_ = other.capacity_slots_;
 
         // Initialize new buckets to empty
         std::memset(data_, 0, buckets_ * bytes_per_bucket());
-
-        // Copy elements and bucket headers
-        for (std::size_t i = 0; i < capacity_slots_; ++i) {
-            slot_ref_t old_slot = other.slot_ref(i);
-            if ((old_slot.header.populated & old_slot.mask) && !(old_slot.header.deleted & old_slot.mask)) {
-                slot_ref_t new_slot = slot_ref(i);
-                populate_slot(new_slot, old_slot.element);
-            }
-        }
+        rehash_into(other.data_, other.capacity_slots_, data_, capacity_slots_);
 
         return *this;
     }
@@ -3880,6 +3896,7 @@ class flat_hash_multi_set_gt {
         if (data_)
             std::memset(data_, 0, buckets_ * bytes_per_bucket());
         populated_slots_ = 0;
+        deleted_slots_ = 0;
     }
 
     void reset() noexcept {
@@ -3889,11 +3906,19 @@ class flat_hash_multi_set_gt {
         data_ = nullptr;
         buckets_ = 0;
         populated_slots_ = 0;
+        deleted_slots_ = 0;
         capacity_slots_ = 0;
     }
 
+    /**
+     *  @brief  Grows the table to fit @p capacity live entries, reclaiming tombstones.
+     *
+     *  Tombstones are reclaimed even when no growth is requested. They only ever stop
+     *  being created once reclaimed, and a table with no empty slot left cannot
+     *  terminate a probe, silently stranding live entries.
+     */
     bool try_reserve(std::size_t capacity) noexcept {
-        if (capacity <= this->capacity())
+        if (capacity <= this->capacity() && deleted_slots_ == 0)
             return true;
 
         // Calculate new sizes
@@ -3913,7 +3938,15 @@ class flat_hash_multi_set_gt {
         checked_size_result_t new_slots = checked_mul(new_buckets_checked.value, slots_per_bucket());
         if (!new_slots)
             return false;
-        checked_size_result_t new_bytes = checked_mul(new_buckets_checked.value, bytes_per_bucket());
+
+        // Never shrink: reclaiming tombstones alone needs no more than the current capacity
+        std::size_t target_buckets = new_buckets_checked.value;
+        std::size_t target_slots = new_slots.value;
+        if (target_slots < capacity_slots_) {
+            target_buckets = buckets_;
+            target_slots = capacity_slots_;
+        }
+        checked_size_result_t new_bytes = checked_mul(target_buckets, bytes_per_bucket());
         if (!new_bytes)
             return false;
 
@@ -3924,36 +3957,15 @@ class flat_hash_multi_set_gt {
 
         // Initialize new buckets to empty
         std::memset(new_data, 0, new_bytes.value);
-
-        // Rehash and copy existing elements to new_data
-        hash_t hasher;
-        for (std::size_t i = 0; i < capacity_slots_; ++i) {
-            slot_ref_t old_slot = slot_ref(i);
-            if ((~old_slot.header.populated & old_slot.mask) | (old_slot.header.deleted & old_slot.mask))
-                continue;
-
-            // Rehash
-            std::size_t hash_value = hasher(old_slot.element);
-            std::size_t new_slot_index = hash_value & (new_slots.value - 1);
-
-            // Linear probing to find an empty slot in new_data
-            while (true) {
-                slot_ref_t new_slot = slot_ref(new_data, new_slot_index);
-                if (!(new_slot.header.populated & new_slot.mask) || (new_slot.header.deleted & new_slot.mask)) {
-                    populate_slot(new_slot, std::move(old_slot.element));
-                    new_slot.header.populated |= new_slot.mask;
-                    break;
-                }
-                new_slot_index = (new_slot_index + 1) & (new_slots.value - 1);
-            }
-        }
+        rehash_into(data_, capacity_slots_, new_data, target_slots);
 
         // Deallocate old data and update pointers and sizes
         if (data_)
             allocator_t{}.deallocate(data_, buckets_ * bytes_per_bucket());
         data_ = new_data;
-        buckets_ = new_buckets_checked.value;
-        capacity_slots_ = new_slots.value;
+        buckets_ = target_buckets;
+        capacity_slots_ = target_slots;
+        deleted_slots_ = 0;
 
         return true;
     }
@@ -4082,6 +4094,7 @@ class flat_hash_multi_set_gt {
                     // Found a match, mark as deleted
                     slot.header.deleted |= slot.mask;
                     --populated_slots_;
+                    ++deleted_slots_;
                     popped_value = slot.element;
                     return true; // Successfully removed
                 }
@@ -4117,6 +4130,7 @@ class flat_hash_multi_set_gt {
                     // Found a match, mark as deleted
                     slot.header.deleted |= slot.mask;
                     --populated_slots_;
+                    ++deleted_slots_;
                     ++count; // Increment count of elements removed
                 }
             } else {
@@ -4247,8 +4261,10 @@ class flat_hash_multi_set_gt {
     }
 
     bool try_emplace(element_t const& element) noexcept {
-        // Check if we need to resize
-        if (populated_slots_ * 3u >= capacity_slots_ * 2u)
+        // Both live entries and tombstones consume slots a probe must walk past, so the
+        // load factor counts them together. Under churn the live count alone stays flat
+        // and would never trigger the rehash that reclaims the tombstones.
+        if ((populated_slots_ + deleted_slots_) * 3u >= capacity_slots_ * 2u)
             if (!try_reserve(populated_slots_ + 1))
                 return false;
 
@@ -4260,7 +4276,9 @@ class flat_hash_multi_set_gt {
         while (true) {
             slot_ref_t slot = slot_ref(slot_index);
             if ((~slot.header.populated & slot.mask) | (slot.header.deleted & slot.mask)) {
-                // Found an empty or deleted slot
+                // Found an empty or deleted slot; reusing a tombstone reclaims it.
+                // Read the tombstone bit before `populate_slot` clears it.
+                deleted_slots_ -= (slot.header.deleted & slot.mask) != 0;
                 populate_slot(slot, element);
                 ++populated_slots_;
                 return true;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "2.25.3",
+    "version": "2.26.1",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ash Vardanian (https://ashvardanian.com/)",
     "license": "Apache 2.0",
@@ -14,7 +14,7 @@
         "email": "info@unum.cloud"
     },
     "engines": {
-        "node": ">=20"
+        "node": ">=22"
     },
     "files": [
         "binding.gyp",