HNSW: copy-on-write snapshots (snapshot series 01-10)

[kei-nan]

Summary

Adds copy-on-write (COW) snapshot support to HNSW, enabling lock-free reads over a consistent point-in-time view of the graph while writers continue to mutate it concurrently. Built up as a 10-step snapshot series:

1. 01 — block deep-copy primitive + design docs
2. 02 — rooted copy-on-write block storage (RootedCowStore<T>)
3. 03 — immutable snapshot handle + capture API
4. 04 — COW-aware insert path (snapshots survive concurrent writes)
5. 05 — lock-free KNN over a captured snapshot
6. 06 — snapshot-backed batch iterator (plain HNSW, opt-in)
7. 07 — tiered cursor captures-then-releases the main lock
8. 08 — concurrent-writer safety (lock-free block COW + atomic metadata)
9. 09 — swap-side reclaim horizon
10. 10 — repair COW-safety: run graph repair under live snapshots

Test plan

• New/updated unit tests: test_hnsw.cpp, test_hnsw_multi.cpp, test_hnsw_tiered.cpp, test_svs.cpp
• ~4,578 insertions across 29 files

🤖 Generated with Claude Code

---

Note

High Risk
Touches core HNSW graph storage, concurrent insert/delete/repair, and tiered swap GC; mistakes could cause use-after-free or consistency bugs, though the default path is unchanged and the feature is opt-in with heavy test coverage.

Overview
Adds an opt-in (useGraphSnapshotIterator) path where HNSW batch/KNN reads capture a point-in-time graph under a brief exclusive lock, then traverse without holding the index lock while inserts, deletes, and tiered GC continue.

Storage & COW: Replaces flat graphDataBlocks with rooted copy-on-write (GraphDataBlocks / RootedCowStore): contiguous block headers + refcounted buffers, generation-tagged clone decisions (SnapshotRegistry), and ElementGraphData::copyTo for per-block deep copies. MetaDataStore COWs metadata on resize; vectors are pinned via captured per-block pointers in HNSWGraphSnapshot.

Writers: Inserts/repair route through getGraphDataByInternalIdForWrite; repair COWs all touched nodes before per-node locks. Per-block forks publish with atomic CAS for concurrent tiered inserts. With no live snapshot, behavior stays in-place (no COW overhead).

Iteration: topKFromSnapshot, dedicated HNSWSnapshot_*_BatchIterator, and tiered snapshot_mode (capture under exclusive lock, release main lock for cursor lifetime). SWAP compaction is gated by maxVisibleCount() reclaim horizon so slots visible to snapshots are not recycled in place.

Extensive design docs, standalone prototypes, serializer updates, and unit/concurrency tests (including tiered snapshot stress). RediSearch cursor wiring, config caps, and range-query snapshots are documented as not yet in this PR.

^{Reviewed by Cursor Bugbot for commit 71bd317. Bugbot is set up for automated code reviews on this repo. Configure here.}

[jit-ci]

Hi, I’m Jit, a friendly security platform designed to help developers build secure applications from day zero with an MVS (Minimal viable security) mindset.

In case there are security findings, they will be communicated to you as a comment inside the PR.

Hope you’ll enjoy using Jit.

Questions? Comments? Want to learn more? Get in touch with us.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Reviewed by Cursor Bugbot for commit 71bd317. Configure here.}

[cursor]

Swap path skips graph COW

High Severity

SwapLastIdWithDeletedId and the start of removeAndSwap still rewrite neighbor link lists and incoming-edge sets through read-only graph accessors, so those blocks are mutated in place while a live graph snapshot may still be reading them. Inserts and repair were moved to COW-before-write, but swap compaction was not, so lock-free snapshot iteration can observe graph topology that diverges from capture time (including when tiered GC runs swaps above the reclaim horizon).

Additional Locations (1)

• src/VecSim/algorithms/hnsw/hnsw.h#L1894-L1910

 

^{Reviewed by Cursor Bugbot for commit 71bd317. Configure here.}

[cursor]

Plain swap ignores live snapshots

High Severity

Plain HNSW still calls removeAndSwap from synchronous delete paths without checking graphSnapshotActive() or the reclaim horizon, so a concurrent opt-in snapshot iterator can keep reading a slot while SwapLastIdWithDeletedId overwrites that id’s graph, vector, and metadata in place. Tiered swap jobs defer below-horizon ids, but the non-tiered path never gates compaction while snapshots are live.

 

^{Reviewed by Cursor Bugbot for commit 71bd317. Configure here.}

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}