research(nightly): sparse k-NN graphs don't fix MinCutBounded RAG — Edmonds-Karp does not scale

[ruvnet]

Hypothesis

ADR-272's ruvector-bounded-rag::MinCutBounded retriever builds its inter-chunk similarity graph with a dense O(n²·d) all-pairs scan, measured as the dominant cost at scale (1.27s/query at n=3000). It named a pre-built k-NN graph as the unimplemented Phase 2 fix.

Given a synthetic clustered corpus of n chunks (n ∈ {200, 1000, 3000, 8000}),
when LSH-bucketed sparse k-NN graph construction replaces the dense
all-pairs scan in MinCutBounded's flow network,
then end-to-end retrieval latency at n=3000 should drop by at least 10x
relative to dense MinCutBounded,
subject to precision staying within 5 points of baseline and all tests
remaining green.

Set before any benchmark ran; not modified afterward.

What this PR does

1. Refactors MinCutRetriever's inline Edmonds-Karp solver into a reusable flow::source_side_partition (verified behaviour-preserving against the full pre-existing test suite).
2. Implements Candidate A: LSH-bucketed (SimHash) sparse edge discovery feeding the same solver — isolates graph construction as the one changed variable.
3. Implements Candidate B (added after measuring Candidate A's result, not before — see ADR for why this isn't goalpost-moving): mutual top-k degree capping, informed by diagnosing why Candidate A failed.
4. Extends the benchmark to 4 corpus sizes × 5 variants with real (not estimated) candidate-pair and edge-count instrumentation.
5. Documents the full research trail, root-cause diagnosis, and next experiment.

Architecture

flowchart TD
    Q[Query vector] --> SRC[source_cap]
    Q --> SINK[sink_cap]
    C[Corpus chunks] --> EDGES{Inter-chunk edge discovery}
    EDGES -->|Dense O(n^2)| DENSE[MinCutRetriever]
    EDGES -->|LSH, unbounded threshold| CANDA[Candidate A]
    EDGES -->|LSH + mutual top-k cap| CANDB[Candidate B]
    SRC --> FLOW[flow::source_side_partition]
    SINK --> FLOW
    DENSE --> FLOW
    CANDA --> FLOW
    CANDB --> FLOW
    FLOW --> PART[Source-side partition] --> RANK[Rank + truncate to budget] --> OUT[RetrievalResult]

Loading

Benchmark command

cargo run --release -p ruvector-bounded-rag --bin benchmark

Real results (release build, x86_64 Linux, Rust 1.97.0)

n	MinCutBounded (dense)	Candidate A (LSH threshold)	Candidate B (k-capped)
200	1,890.8 μs	1,692.4 μs (1.12x)	1,946.2 μs (0.97x)
1,000	59,155.7 μs	38,906.2 μs (1.52x)	34,719.5 μs (1.70x)
3,000	1,171,905.6 μs	1,036,383.4 μs (1.13x)	418,698.7 μs (2.80x)
8,000	SKIPPED (cliff)	SKIPPED (degrades like dense)	3,363,314.8 μs

Precision = 1.000 across every configuration, every n (no precision/latency tradeoff).

Candidate-pair reduction (construction cost, isolated): ~10.1–10.3x fewer pairs checked than dense all-pairs at every scale tested — this part of the hypothesis held cleanly.

Root cause: at n=8000, the unbounded threshold graph kept 97.5% of checked candidate pairs as edges (3.96M edges, max degree 1,278) — cheap discovery of a graph that's still dense end-to-end. Candidate B's degree cap fixes that number directly (provably ≤k edges/node, unit-tested), yet still scales ~quadratically (measured 8.03x cost from n=3000→8000 vs. 7.11x predicted from pure n² scaling) — pointing at the Edmonds-Karp solver's own iteration behavior on real-valued-capacity networks as the remaining bottleneck, not graph construction or edge count.

Acceptance result

REJECT the primary hypothesis (10x speedup not achieved by either candidate). Candidate B's 2.8x at n≤3000 is real, precision-neutral, and accepted as an available opt-in improvement — not as a fix for the scalability cliff, which remains open. Per the nightly process's own standard, a falsified hypothesis with honest, reproducible measurement is a successful run.

Darwin / Flywheel / MetaHarness

Checked before this run, not assumed: npx metaharness exists but is a project-scaffolding generator, not a research-orchestration layer over an existing repo; npx ruvector harness does not exist as a CLI; no Darwin/Flywheel subcommands were found anywhere in this repo's tooling. This repo's actual evolutionary memory is docs/research/nightly/ (34 prior reports) and docs/adr/ (380+ ADRs), which this PR reads from and extends in place of a dedicated Flywheel store. Recording this gap is itself retained evidence for future nightly runs.

Security review

No new attack surface: no I/O, no untrusted deserialization, no new dependencies. LSH's probabilistic completeness (a true edge can be missed) only makes the coherence boundary more conservative, never less — same failure direction as the existing seed_threshold fallback. No reward-hacking: no test weakened, no benchmark modified after seeing results, no acceptance threshold adjusted post-hoc.

Main limitations

• All corpora are synthetic Gaussian clusters; real corpora may have different topology.
• The solver-iteration-count diagnosis is by elimination and scaling-trend consistency, not direct instrumentation (named as the first step of the next experiment).

Production recommendation

Do not promote any min-cut variant as a replacement default yet. Candidate B (SparseKnnMinCutRetriever with max_degree set) is available today as an opt-in improvement for corpora ≤ ~3000 chunks. The scalability cliff for larger corpora remains open pending a capacity-aware max-flow solver (named as Candidate C in Next Experiment).

Docs

• Research report: docs/research/nightly/2026-10-02-sparse-knn-mincut-bounded-rag/README.md
• Gist: docs/research/nightly/2026-10-02-sparse-knn-mincut-bounded-rag/gist.md
• ADR: docs/adr/ADR-352-sparse-knn-mincut-bounded-rag.md

Test plan

• cargo test -p ruvector-bounded-rag --release — 21 passed (11 pre-existing unchanged, 2 new for flow.rs, 8 new for sparse_knn.rs), 1 doctest
• cargo clippy -p ruvector-bounded-rag --release --all-targets — clean
• cargo fmt -p ruvector-bounded-rag -- --check — clean
• cargo run --release -p ruvector-bounded-rag --bin benchmark — real output captured in the research report, not fabricated
• node scripts/adr-index.mjs --check — clean, ADR-352 registered

---

🤖 Generated with claude-flow

https://claude.ai/code/session_01TnnVP6MJ6ArMVDmJiqJ7Ak

---

Generated by Claude Code

[ruvnet]

CI status: Clippy (deny warnings) is red, but not on this PR's diff.

The failure is entirely in crates/rvAgent/rvagent-core (graph.rs, models.rs, subagent.rs) — a crate this PR never touches (this PR's 18 changed files are all under crates/ruvector-bounded-rag/, docs/, and .claude/helpers/). The error is:

error: this function has a `#[must_use]` attribute with no message, but returns a type already considered as `#[must_use]`
  --> crates/rvAgent/rvagent-core/src/graph.rs:53:15
   |
53 |   #[async_trait]
   | _______________^
54 | | pub trait ToolExecutor: Send + Sync {
...
= note: `-D clippy::double-must-use` implied by `-D warnings`

This is async-trait = "0.1" (pinned in crates/rvAgent/rvagent-core/Cargo.toml) expanding to a #[must_use]-annotated boxed-future return that a newer clippy stable now flags as redundant under -D warnings. The most recent successful run of this same workflow on main was 2026-09-21 (11 days ago, before today's toolchain resolution) — consistent with this surfacing from stable clippy drift rather than from any change in this PR. I didn't find an existing fix PR for it (searched for double_must_use rvagent-core).

I'm not pushing a fix into this PR for it: rvagent-core is unrelated to this PR's ruvector-bounded-rag research scope, and fixing it here would widen the PR into an unrelated crate. Proposed patch for whoever picks it up: either bump async-trait past the version that adds the redundant attribute, or add #[allow(clippy::double_must_use)] to the three trait definitions (ToolExecutor::execute, ChatModel::{complete,stream}, StreamingChatModel::stream_chunks, Subagent::run).

This PR's own code (ruvector-bounded-rag) is independently verified green: cargo test -p ruvector-bounded-rag --release (21 passed), cargo clippy -p ruvector-bounded-rag --release --all-targets (clean), cargo fmt -p ruvector-bounded-rag -- --check (clean) — all run locally before pushing, per the PR description's test plan.

---

Generated by Claude Code

[ruvnet]

CI status: Tests (core-and-rest) is also red, also not on this PR's diff.

The failure is a link error in ruvector-typesafe-train, unrelated to ruvector-bounded-rag:

rust-lld: error: undefined symbol: __isoc23_strtoll
>>> referenced by inference_session_utils.cc
>>>     ...libort_sys-a7cfa6381142eda4.rlib
error: could not compile `ruvector-typesafe-train` (lib)

__isoc23_strtoll is a glibc symbol only present in recent glibc releases that add ISO C23 numeric-parsing entry points. This is a prebuilt onnxruntime/ort_sys static library linking against a glibc version the runner's current toolchain/image doesn't provide (or vice versa) — a C/C++ ABI mismatch entirely outside this PR's diff (18 changed files, all under ruvector-bounded-rag, docs/, and .claude/helpers/; nothing touches ruvector-typesafe-train or any ONNX/ort dependency). I searched existing issues for __isoc23_strtoll/ort_sys and found none, so there's no existing fix to port.

Combined with the Clippy (deny warnings) failure already reported above (unrelated rvagent-core issue), this PR now has two independent, pre-existing CI breaks in crates it doesn't touch. I'm not attempting fixes for either here — both are outside ruvector-bounded-rag's scope and would require runner-image/toolchain or ort_sys dependency changes that belong in their own PRs.

This PR's own crate remains independently green (see test plan in the PR description). Keeping this PR watched; will act on anything that's actually in ruvector-bounded-rag, docs/research/nightly/, docs/adr/, or a merge conflict against main.

---

Generated by Claude Code