Improve HNSW concurrency: shared locks for read-only paths

[benoitdion]

Describe the changes in the pull request

• Upgrade per-node neighborsGuard from std::mutex to std::shared_mutex to allow concurrent read access during search operations.
• Add lockNodeLinksShared/unlockNodeLinksShared methods and use them in all read-only paths: processCandidate, processCandidate_RangeSearch, greedySearchLevel, replaceEntryPoint, safeCollectAllNodeIncomingNeighbors, repairNodeConnections (read phases), getHNSWElementNeighbors, and the batch iterator. Write paths (mutuallyConnectNewElement, revisitNeighborConnections, mutuallyUpdateForRepairedNode) retain exclusive locks.
• Make getElementIds const-correct across the HNSW class hierarchy.
• Remove unused include.

lock audit:

Function	Lock type	Rationale
processCandidate	shared	Read-only: reads numLinks, getLinkAtPos, computes distances
processCandidate_RangeSearch	shared	Read-only: same pattern as above
greedySearchLevel	shared	Read-only: reads neighbors to find closest node
replaceEntryPoint	shared	Read-only: reads neighbors to find non-deleted replacement EP
safeCollectAllNodeIncomingNeighbors	shared	Read-only: copyLinks, getIncomingEdges, getNumLinks, getLinkAtPos
repairNodeConnections (first two sections)	shared	Read-only: collecting neighbor candidates before the actual repair
getHNSWElementNeighbors	shared	Read-only: debug API, reads neighbors
scanGraphInternal (batch iterator)	shared	Read-only: traversing neighbors for batch iteration
revisitNeighborConnections (lines 861/899)	exclusive	Write: setLinkAtPos, appendLink, setNumLinks, mutuallyRemoveNeighborAtPos
mutuallyConnectNewElement (lines 929–966)	exclusive	Write: appendLink, ordered lock acquisition to avoid deadlock
mutuallyUpdateForRepairedNode (lines 1386–1451)	exclusive	Write: setLinkAtPos, setNumLinks, newIncomingUnidirectionalEdge

Mark if applicable

• This PR introduces API changes
• This PR introduces serialization changes

---

Note

Medium Risk
Touches core HNSW locking and neighbor update logic; while intended to increase concurrency and avoid deadlocks, any mistake could introduce races or hangs under parallel insert/search/delete workloads.

Overview
Improves HNSW per-node concurrency by upgrading ElementGraphData::neighborsGuard to std::shared_mutex and switching search/debug/batch-iteration neighbor traversals to shared (read) locks via new RAII helpers (nodeLinksSharedGuard/nodeLinksGuard).

Refactors write/update paths to use RAII unique_lock ownership, release/reacquire locks in sorted node-id order to reduce deadlock risk (including de-duplicating the lock list), and makes getElementIds const across the HNSW class hierarchy; also removes an unused <iostream> include.

^{Written by Cursor Bugbot for commit d586ab0. This will update automatically on new commits. Configure here.}

[CLAassistant]

All committers have signed the CLA.

[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.

[codecov]

Codecov Report

❌ Patch coverage is 97.33333% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.10%. Comparing base (5e08d77) to head (d586ab0).

Files with missing lines	Patch %	Lines
src/VecSim/algorithms/hnsw/hnsw.h	97.22%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #904      +/-   ##
==========================================
- Coverage   97.12%   97.10%   -0.02%     
==========================================
  Files         129      129              
  Lines        7500     7488      -12     
==========================================
- Hits         7284     7271      -13     
- Misses        216      217       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[JoanFM]

should we actually use lock_guards here?

[JoanFM]

same here?

[JoanFM]

In general, can we try to aim for having lock guards for more safety?

[benoitdion]

cursor review

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

[cursor]

Unused exclusive guard helpers added

Low Severity

nodeLinksGuard(ElementGraphData*) and nodeLinksGuard(idType) are introduced but never used, while write paths lock neighborsGuard directly. This leaves dead locking APIs in hnsw.h, which increases maintenance overhead and can cause future lock behavior to diverge between helpers and call sites.

Additional Locations (1)

• src/VecSim/algorithms/hnsw/hnsw.h#L488-L498