docs: state the mid-size resolver-pool gap and fix the pool-threshold comment

Merged
BO
7d ago
+54-5

The README no longer says the fork's resolver pool "engages the moment it pays for itself": it starts at 150,000 pending references, and in a 2026-10-12 sweep the single-threaded path below that was 6–51% slower than upstream on full-index wall time from about 20,000 references up.

What changes

  • README.md: the pool claim in the scaling section is corrected, and a paragraph under "Measured results" says the headline corpora are small or past the pool threshold, gives the mid-size gap (and Exposed's 6x) and links the table.
  • docs/benchmarks/fork-vs-upstream-node-bun-2026-10-12.md: new "Mid-size projects and the resolver pool" section with the sweep table for seven corpora (13.9k to 111k pending references), the memory trade-off, the statistical caveat (4 runs against 4 cannot reach the pre-declared p < 0.05, so the table shows whether run ranges are disjoint, chosen after the data) and what was not measured.
  • src/resolution/resolver-pool.ts: the minRefsForPool comment said the pool slowed a ~40k-reference repo; on the sweep host forcing it was faster at 37k–111k references and cost 53–108% more memory. Comment only; no threshold change.

Limits of the numbers

The sweep compared upstream 4f3eaf33 with the fork at ba4f7e38, before #488 and #489, which cut Exposed's default index time in separate runs by 31% and 16%. It was not repeated with them. The README's headline benchmark (upstream 6560052 against fork ce6120be) was not re-run either. Both are stated in the text.

Checks

__tests__/readme-sync.test.ts passes (6 tests). README rows checked: "Measured results" and the scaling paragraph (both edited); the full-index, sync and memory tables are untouched and still describe the 2026-10-12 headline run. CHANGELOG: not changed, docs and a comment only.

Summary by cubic

Corrects the README's claim that the resolver pool starts when it pays for itself: it starts at 150,000 pending references, and a 2026-10-12 sweep found the single-threaded path below that 6–51% slower than upstream on full-index wall time from about 20,000 references up. Adds the sweep table to the benchmark doc and rewrites the minRefsForPool comment to match the measurements.

Caveats on the numbers

  • The sweep predates #488 and #489, which cut Exposed's index time by 31% and 16% in separate runs; it was not repeated with them.
  • Four runs per arm cannot reach the pre-declared p < 0.05 (smallest possible p is 0.057), so the table reports whether run ranges are disjoint instead.
  • Docs and a comment only; no threshold change, and __tests__/readme-sync.test.ts passes.

Summary by CodeRabbit

  • Documentation
    • Added benchmark results comparing resolution speed and memory use across mid-sized projects, including slower results and inconclusive comparisons.
    • Clarified that resolution uses one thread below 150,000 pending references and that performance varies across project sizes and test conditions.
    • Documented benchmark limitations and noted later Exposed indexing improvements that were not included in a repeat sweep.