PiPNN 1/6: extract shared RobustPrune

[weiyaoluo (SeliMeli)]

Purpose

This PR extracts the private Vamana RobustPrune selection loop. PiPNN can reuse this loop in a later PR.

The change adds no public API. It does not change Vamana pruning behavior.

Main changes

• graph::internal::prune::robust_prune now owns the alpha-round selection loop.
• The function accepts one nearest-first cache of source distances and candidate vectors.
• A debug assertion checks cache order with the canonical neighbor distance ordering.
• DiskANNIndex::occlude_list still sorts candidates, loads vectors, maps IDs, and applies saturation.
• State updates, alpha rounds, and unsafe checks retain their original logic.

Preserved behavior

• Candidate order remains unchanged.
• Excluded candidates remain positional None entries.
• Alpha progression and prune-kind behavior remain unchanged.
• Saturation order and duplicate handling remain unchanged.
• Provider errors remain in occlude_list.

Review order

1. Review diskann/src/graph/internal/prune.rs.
2. Compare the extracted loop with the old loop in index.rs.
3. Review the call site in DiskANNIndex::occlude_list.
4. Confirm that preparation, ID mapping, and saturation remain outside the extracted function.

Validation

• All diskann library tests pass.
• All-target Clippy passes with -Dwarnings.
• Existing Vamana prune scenarios pass.

Stack

Stack 1/6. #1287 adds PiPNN numerical kernels.

[Copilot]

Pull request overview

This PR extracts Vamana’s reusable RobustPrune alpha-round occlusion state machine into a new allocation-free kernel (graph/internal/robust_prune.rs) while keeping Vamana-specific scratch space, provider error handling, and adapter logic in graph/internal/vamana_prune.rs. The DiskANNIndex::occlude_list path is updated to prepare “available-only” candidates for the shared kernel, then translate selected positions back to IDs and apply optional saturation.

Changes:

• Introduces internal::robust_prune as a provider-independent RobustPrune kernel over prepared candidates + reusable per-candidate state.
• Moves Vamana-owned scratch/context and ranked provider error types into internal::vamana_prune with co-located tests.
• Refactors graph/index.rs::occlude_list to: validate bounds → prepare available candidates → call shared kernel → write adjacency → saturate from available-only candidates.

Reviewed changes

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

Show a summary per file

File	Description
diskann/src/graph/internal/vamana_prune.rs	Adds Vamana-owned scratch/context + provider error ranking and Vamana integration tests.
diskann/src/graph/internal/robust_prune.rs	Adds allocation-free RobustPrune kernel + pure state-machine tests.
diskann/src/graph/internal/prune.rs	Removes the previous combined prune implementation/state.
diskann/src/graph/internal/mod.rs	Rewires internal modules to expose robust_prune and vamana_prune.
diskann/src/graph/index.rs	Switches pruning implementation to prepare candidates and call the shared robust_prune kernel; updates saturation behavior to be available-only.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

❌ Patch coverage is 98.70130% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 91.55%. Comparing base (16c7451) to head (6bf2139).
⚠️ Report is 13 commits behind head on main.

Files with missing lines	Patch %	Lines
diskann/src/graph/internal/prune.rs	98.50%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1315      +/-   ##
==========================================
+ Coverage   91.26%   91.55%   +0.28%     
==========================================
  Files         517      522       +5     
  Lines       98511    99553    +1042     
==========================================
+ Hits        89910    91146    +1236     
+ Misses       8601     8407     -194     

Flag	Coverage Δ
miri	91.55% <98.70%> (+0.28%)	⬆️
unittests	91.23% <98.70%> (+0.28%)	⬆️

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

Files with missing lines	Coverage Δ
diskann/src/graph/index.rs	96.48% <100.00%> (-0.04%)	⬇️
diskann/src/graph/internal/prune.rs	85.04% <98.50%> (+22.54%)	⬆️

... and 91 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)]

This PR would have been easy to review, but at nontrivially regresses internal documentation and comments. For such important internal algorithms, please avoid changing comments unnecessarily, particularly when unsafe is involved.

Please restore the deleted or altered comments, making only the necessary updates for the new location. Also, please avoid renaming variables when just moving code around. A simpler diff stands on its own.

[weiyaoluo (SeliMeli)]

Addressed review in c2e6be62:

• kept module and existing types in graph::internal::prune;
• restored original loop comments, variable terminology, and checked-index unsafe justifications;
• changed the helper boundary to &SortedNeighbors so source-distance ordering is enforced by the existing type;
• added local pool/cache/state length checks before unchecked mutation;
• retained Vamana preparation, ID mapping, saturation, errors, and alpha behavior unchanged.

Validation: 311 diskann library tests, all-target Clippy, LSP diagnostics, and git diff --check pass.

[weiyaoluo (SeliMeli)]

Local IAI-Callgrind check against main (16c7451f):

• triangle 750→64: instructions +0.27259%, estimated cycles +0.29260%;
• occluding+saturation 750→64: instructions -0.01482%, estimated cycles +0.01124%.

Measured under WSL2 with the archived local regression fixture; no submitted benchmark target. Full record: experiments/pipnn_local_regression/2026-08-07-wrapper-simplification-callgrind.md in the local analysis workspace.

[weiyaoluo (SeliMeli)]

All review threads now point to superseded lines. The final extraction keeps the helper in graph::internal::prune, accepts SortedNeighbors, restores the original loop/state/unsafe comments and existing debug_assert! sequence, and adds no assertions or pruning behavior changes. I am resolving the outdated threads.

[Wei Wu (wuw92)]

LGTM. Since it is intended to be a focused extraction, I would keep the implementation as close to the original as possible and simplify the PR description.

[Mark Hildebrand (hildebrandmw)]

One more small suggestion. Thanks!