[diskann-garnet] Implement continue_search()

[Jack Moffitt (metajack)]

Implements continue_search() in the Garnet FFI.

The buffers for ids that Garnet passes may be insufficient since external IDs are user-provided byte strings of arbitrary length. The distances buffer will always be correctly sized. In the case the id buffer is too small, a Continuation is boxed and returned, which can be used by potentially repeated calls to continue_search() to retrieve the rest of the results.

This set up is used all the search_X FFI methods. It is not used in random_members() since due to how other things are handled with that it can just use multiple calls to get more random members if needed.

[Copilot]

Pull request overview

This PR implements continue_search() for the Garnet FFI by introducing an overflow/continuation mechanism to safely return variable-length external IDs when the caller-provided ID buffer is too small. It extends the existing search FFI surface to return a continuation pointer for subsequent calls, updates neighbor queries to use max_degree(), and bumps the diskann-garnet package version.

Changes:

• Add Continuation and implement continue_search() to drain overflowed search results across multiple FFI calls.
• Extend SearchResults to track k and store overflow IDs/distances when output buffers can’t fit all results.
• Wire continuation out-parameters through search_vector, search_element, and search_neighbors, and update/extend tests accordingly; bump version to 5.0.1.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
diskann-garnet/src/provider.rs	Exposes max_degree() from the provider for neighbor retrieval sizing.
diskann-garnet/src/lib.rs	Implements Continuation + continue_search(), adds overflow handling to SearchResults, and updates FFI search functions to return continuation pointers.
diskann-garnet/src/ffi_tests.rs	Updates FFI tests to use the new continuation out-parameter and adds coverage for continuation being written.
diskann-garnet/src/ffi_recall_tests.rs	Updates recall tests to pass and clean up continuation pointers.
diskann-garnet/src/dyn_index.rs	Extends DynIndex with max_degree() and plumbs it to the provider.
diskann-garnet/diskann-garnet.nuspec	Bumps NuGet package version to 5.0.1.
diskann-garnet/Cargo.toml	Bumps crate version to 5.0.1.
Cargo.lock	Updates locked version for diskann-garnet to 5.0.1.

Suppressed comments (4)

diskann-garnet/src/lib.rs:941

• search_element does not initialize/validate the continuation out-parameter. On success without overflow it currently never writes to it (caller must pre-initialize), and on error returns it can leave the out-parameter stale/uninitialized.

    let index = unsafe { &*index_ptr.cast::<Index>() };
    let id_bytes = unsafe { slice::from_raw_parts(id_data, id_len) };
    let id = GarnetId::from(id_bytes);
    let ctx = Context::new(ctx);

diskann-garnet/src/lib.rs:1021

• continue_search only writes new_continuation when more results remain. If the continuation is exhausted, the out-parameter is left untouched, so callers that don't pre-initialize it may treat garbage as a live pointer (double-free/UB). Also, slice::from_raw_parts_mut is invoked unconditionally, which is UB if a C caller passes a null pointer with a 0 length (a common FFI pattern).

    if continuation.is_null() || new_continuation.is_null() {
        return -1;
    }

    let output_ids = unsafe { slice::from_raw_parts_mut(output_ids, output_ids_len) };

diskann-garnet/src/lib.rs:850

• search_vector writes through the continuation out-parameter on success, but it is never validated and it is not initialized on early-return error paths (e.g., failed interpret_vector). This can segfault if Garnet passes a null out-parameter, and it can leave the caller with an uninitialized/stale continuation pointer on errors.

This issue also appears in the following locations of the same file:

• line 937
• line 1017
• line 1176

    continuation: *mut *mut c_void,
) -> i32 {
    let index = unsafe { &*index_ptr.cast::<Index>() };

    let v = if let Some(v) = interpret_vector(index.quant_type, &vector_data, vector_len) {

diskann-garnet/src/lib.rs:1179

• search_neighbors can return -1 before it ever writes to the continuation out-parameter (e.g., if neighbors() fails), and it doesn't validate the out-parameter before writing on success. This can leave callers with stale/uninitialized continuation pointers or cause a segfault if a null out-parameter is passed.

    let index = unsafe { &*index_ptr.cast::<Index>() };
    let ctx = Context::new(ctx);
    let id_bytes = unsafe { slice::from_raw_parts(id_data, id_len) };
    let id = GarnetId::from(id_bytes);

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

❌ Patch coverage is 94.14226% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.56%. Comparing base (158126e) to head (c9641a3).
⚠️ Report is 11 commits behind head on main.

Files with missing lines	Patch %	Lines
diskann-garnet/src/lib.rs	93.83%	14 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1357      +/-   ##
==========================================
+ Coverage   91.55%   92.56%   +1.00%     
==========================================
  Files         521      522       +1     
  Lines      100371   101105     +734     
==========================================
+ Hits        91898    93586    +1688     
+ Misses       8473     7519     -954     

Flag	Coverage Δ
miri	92.56% <94.14%> (+1.00%)	⬆️
unittests	92.50% <94.14%> (+1.26%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
diskann-garnet/src/dyn_index.rs	80.86% <100.00%> (+1.05%)	⬆️
diskann-garnet/src/provider.rs	79.01% <100.00%> (-0.12%)	⬇️
diskann-garnet/src/lib.rs	94.31% <93.83%> (-0.29%)	⬇️

... and 100 files with indirect coverage changes

🚀 New features to boost your workflow:

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

[Mark Hildebrand (hildebrandmw)]

Thanks Jack - just a few small API questions!

[Magdalen Dobson Manohar (magdalendobson)]

Low stakes feedback but I think that continue_search and Continuation are potentially confusing names. They may make people think that DiskANN is doing more search in a paged search manner. Could we workshop a bit on naming, maybe something like continue_buffering and BufferContinuation?

[Jack Moffitt (metajack)]

Good suggestion. I've renamed it to overflow_results and Overflow.