feat(ruvector-graph): VectorPropertyIndex — RaBitQ-backed kNN over node properties (Phase 1 item #2)

[ruvnet]

Summary

Phase 1 item #2 from docs/research/rabitq-integration/05-roadmap.md. Adds a vector-keyed kNN index for graph nodes via direct-embed (Pattern 1) of ruvector-rabitq. Callers can now do "find the N node ids whose vector property is closest to query" without standing up a separate index crate.

let idx = VectorPropertyIndex::build(
    &graph,
    "embedding",
    VectorPropertyIndexConfig { seed: 42, rerank_factor: 20 },
)?;
let hits: Vec<(NodeId, f32)> = idx.knn(&query, k)?;

Behind the rabitq cargo feature, default-on. --no-default-features keeps the graph crate buildable without ruvector-rabitq.

Important determinism finding

DashMap iteration order is shard-dependent. Two builds in the same process can disagree on which NodeId lives at row 0. Without a fix this would silently break ADR-154's (seed, graph) → bit-identical codes guarantee across runs and shard-count changes.

Fix: VectorPropertyIndex::build sorts NodeIds before encoding. One O(n log n) string sort per build; row→NodeId mapping now stable across runs. Verified by byte_identical_query_results_for_same_seed.

Recall + memory at test sizes

• n=1k, dim=128, rerank_factor=20:
  • recall@10 = 1.000 vs brute-force (floor: 0.85)
  • codes / originals ratio = 0.176 (rotation matrix dominates at small n; asymptotically codes ≤ originals/16 + dim²·4)

Acceptance test

The roadmap's gate (100k × 768d, recall@10 ≥ 0.95, DRAM ≤ 1/16 f32) is shipped as a criterion bench at benches/vector_property_index.rs defaulting to n=2k. Override:

VECTOR_PROPERTY_INDEX_N=100000 VECTOR_PROPERTY_INDEX_DIM=768 \
  cargo bench -p ruvector-graph --features rabitq

No abstraction yet (deliberate)

The graph crate had no quantizer trait. Kept VectorPropertyIndex concrete (wraps RabitqPlusIndex directly). Phase 1 has one quantizer; an abstraction is unjustified now and easy to add in Phase 2 if a second backend joins.

Verification

• cargo build --workspace → clean
• cargo build -p ruvector-graph --no-default-features → clean
• cargo build -p ruvector-graph --features rabitq → clean
• cargo clippy --workspace --all-targets --no-deps -- -D warnings → clean
• cargo fmt --all --check → clean
• cargo test -p ruvector-graph --features rabitq → 142 pass (135 lib + 7 new integration)

7 new integration tests:

• build_and_query_returns_self_at_distance_zero
• recall_at_10_meets_floor_vs_brute_force
• byte_identical_query_results_for_same_seed (determinism)
• build_skips_nodes_without_target_property
• build_rejects_dim_mismatch
• len_matches_indexed_node_count
• empty_graph_yields_empty_index

Independent of the DiskANN stack

Branched from main (PR #380's merge 7a599b7c). No conflicts with the DiskANN PR chain (#383→#386). Different crate, different reviewer audience.

🤖 Generated with claude-flow