Skip to content

v11.2.0 — Hybrid Runtime Integration (Phase 5.5.2)

Choose a tag to compare

View all tags
@Ruso-0 Ruso-0 released this 18 May 22:46
· 28 commits to master since this release
v11.2.0
b78409b

Added

  • Hybrid Runtime Integration: New nreki_navigate action="hybrid_search" exposes the Type Ledger semantic + BM25 lexical fusion (RRF) documented in the Phase 5 paper to the production MCP runtime. Previously only reachable via eval scripts.
  • src/bm25-engine.ts: BM25 lexical retrieval migrated from scripts/eval-phase5/runners/bm25-runner.ts. Standard Okapi (k1=1.5, b=0.75); code-aware tokenization (PascalCase / snake_case / camelCase decomposition, 2-char minimum). Lazy in-memory index built on first search(); invalidated on indexFile() / indexDirectory() mutations.
  • src/hybrid-engine.ts: Hybrid RRF engine. Calls NREKI semantic search + BM25 in parallel, fuses file rankings via Reciprocal Rank Fusion (k=60), deterministic tie-break by localeCompare. Returns unified results with source: "nreki" | "bm25" | "both" origin tracking.
  • Foveal compression on BM25-only files (Reto 5): Files surfaced exclusively by BM25 (≥100 lines) receive tfcCompress with a focus symbol extracted from the query.
  • NrekiEngine.getHybridEngine() + invalidateHybridIndex(): lazy-construction of the hybrid stack; BM25 cache auto-invalidates on indexFile() and indexDirectory().
  • BM25EngineOptions.excludedDirs: configurable directory exclusion. Default excludes node_modules, .git, .nreki, dist, build, coverage, .next, __pycache__, corpus, plus any dot-prefixed directory.
  • scripts/benchmark-hybrid-smoke.ts: reproducible dogfood smoke bench (action="search" vs action="hybrid_search").
  • docs/sprint-6.5-empirical.md: honest Sprint 6.5 empirical findings + N=99 PolyBench re-bench deferral disclosure.
  • 28 new tests: tests/bm25-engine.test.ts (16) + tests/hybrid-engine.test.ts (12). Full suite: 1384 pass.

Changed

  • nreki_navigate action enum: hybrid_search added to MCP schema + router. Existing 10 actions (search, fast_grep, definition, references, outline, map, prepare_refactor, orphan_oracle, type_shape, type_graph) preserved — backward compatible.

Empirical findings (honest)

  • Dogfood smoke (73 files, 8 queries): search recall 60% vs hybrid_search recall 60% (Δ=0pp). Hybrid pays 207% token overhead with no recall gain on this micro-corpus. Expected — Sprint 6.4 paper's +15pp FHR gain was measured on N=99 diverse external repos.
  • Sprint 6.5 N=99 PolyBench re-benchmark: DEFERRED. Reason: eval orchestrator needs re-plumbing to invoke production HybridEngine; multi-hour wall clock. Tracked as Sprint 6.5.1 in docs/sprint-6.5-empirical.md.

Architectural decision

"El mejor que se quede" — hybrid USES the underlying retrievers, does NOT replace them. Users still pick search for pure topological queries (lower tokens) and hybrid_search for accuracy-critical retrieval (≈3-5x tokens per Sprint 6.4 paper; dogfood shows up to ~3x).

Assets 2
Loading