Module fusion 

Hybrid result fusion. Deterministic vector/lexical fusion for library callers and Store::search_hybrid.

Store-owned hybrid pins both legs to one generation and delegates score validation, normalization, alpha policy, RRF fallback, termination, and FusionReport construction here. A hybrid query with no explicit store tier uses exact vector scores; explicit tiers retain their selected score provenance, including typed refusal of estimated scores.

See the local architecture-decision ledger.

Structs

DegenerateLeg

One reported fallback cause.

FusedHit

One fused hit with both transparent raw leg scores.

FusionOutcome

Fused top-k and its report.

FusionReport

Truthful deterministic report for one fusion.

HybridProvenance

Store-owned facts required before a bounded fusion stop is a certificate.

HybridQuery

Pure fusion parameters over already-executed legs.

LegBounds

Per-leg exact ranges supplied by bounded producers, validated by fusion.

LexicalBounds

Exact lexical-leg extremes for one bounded window.

LexicalCandidate

One ranked lexical candidate. BM25 is higher-is-better.

RuleSignals

Caller-computed deterministic query-shape facts.

VectorBounds

Exact vector-leg extremes for one bounded window.

VectorCandidate

One ranked vector candidate. Squared-L2 is lower-is-better.

Enums

CandidateCoverage

What a producer can prove about candidates outside its supplied window. This is independent of whether the supplied scores are exact.

DegenerateKind

Why min-max normalization was not defined for a leg.

FusionError

Typed rejection from the pure fusion seam.

FusionLeg

Leg named by validation and fallback reports.

FusionMethod

Fusion formula actually used.

FusionRule

Stable rule names emitted by the fusion report.

FusionTermination

How the widening loop completed.

LegFailureKind

Typed classification of a leg failure carried by FusionError::Leg.

ScorePrecision

Whether a vector score is safe to blend.

Constants

ALPHA_POLICY_VERSION

Version of the rule data interpreted by fusion reports. Version 2 (2026-08-26) turned the rules off by default on measured evidence.

DEFAULT_ALPHA

MEASURED (tasks/evidence/17-fusion.md, 2026-08-26, BEIR SciFact with Cohere embed-english-v3 vectors): the optimum of an eleven-point grid, nDCG@10 0.7642 against 0.7181 dense-only and 0.6917 lexical-only; the band within one point is 0.6..0.8. It coincides with the Bruch, TOIS 2024 literature prior the placeholder started from.

DEFAULT_MAX_ROUNDS

PLACEHOLDER – NOT YET MEASURED.

HYBRID_NORMALIZATION_POLICY_VERSION

Store score policy v1: fixed zero lower anchors, the validated vector norm enclosure and exact maximum live combined BM25 as upper anchors. Missing lexical membership is an explicit zero. An empty lexical leg gives vectors full weight; a zero vector enclosure scores every present vector as one. Store fusion uses these values even for equal or singleton lists. The pure complete-list and bounded fusion APIs retain their min-max/RRF semantics.

HYBRID_WINDOW_FLOOR

MEASURED (tasks/hybrid-search-optimization/PLAN.md §A.2, BEIR SciFact with Cohere embed-english-v3 vectors): with exact anchors and cross-filled windows, a 50-wide window reproduces the full-list fused top-10 in 300/300 judged queries and the stability bound proves it in 299/300. Twenty and thirty reproduce only 283 and 293. The engine’s own window measurement is recorded in tasks/evidence/R04-hybrid-window.md.

HYBRID_WINDOW_PER_K

PLACEHOLDER – NOT YET MEASURED.

LEXICAL_RULE_ALPHA

MEASURED HARMFUL AT EVERY CELL on BEIR SciFact (tasks/evidence/17-fusion.md): with rules on, this pair scores nDCG@10 0.7458 against the 0.7642 no-rule baseline, and no (threshold, rule_alpha) cell in a 28-cell sweep beat the baseline. The rules are therefore opt-in (HybridQuery::with_rules) and this value is retained only for a caller who has measured an identifier-heavy corpus of their own; it is not a quality claim.

RARE_DOCUMENT_FREQUENCY_THRESHOLD

A query token at or below this document frequency is considered rare. Measured with LEXICAL_RULE_ALPHA above: on SciFact the min-over-terms signal fires on 211 of 300 queries at this value because any out-of-vocabulary token trips it, so it does not isolate rare exact tokens there. Opt-in only; see LEXICAL_RULE_ALPHA.

RRF_K

PLACEHOLDER – NOT YET MEASURED.

Functions

execute_hybrid

Executes caller-owned legs and fuses only when both complete successfully.

fuse

Fuses two ranked, exactly-scored candidate lists on a caller-defined key.

fuse_bounded

Fuses two bounded windows plus their exact per-leg ranges.