AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
fix(search): hybrid fusion orders tied scores by arrival, not by hash iteration (#940)
xerj-orgc9fcd4bb19dd
diff --git a/engine/crates/xerj-engine/src/index.rs b/engine/crates/xerj-engine/src/index.rsindex 55a4ead28..e0aadbbfd 100644--- a/engine/crates/xerj-engine/src/index.rs+++ b/engine/crates/xerj-engine/src/index.rs@@ -15103,10 +15103,14 @@ impl Index {}}- // Apply fusion.+ // Apply fusion. A tied fused score is broken by arrival order, the+ // same `seq_no ASC, _id ASC` every other score-ranked page uses+ // (#270/#940) — resolved through the version map once per distinct+ // fused document, which is at most `legs × per_query_topk` lookups.+ let seq_no_of = |id: &str| self.lookup_seq_no(id).unwrap_or(u64::MAX);let fused = match fusion {- xerj_query::ast::FusionStrategy::Rrf { k } => fuse_rrf(&sub_results, k),- xerj_query::ast::FusionStrategy::Linear => fuse_linear(&sub_results),+ xerj_query::ast::FusionStrategy::Rrf { k } => fuse_rrf(&sub_results, k, &seq_no_of),+ xerj_query::ast::FusionStrategy::Linear => fuse_linear(&sub_results, &seq_no_of),// Defense in depth: the parser already rejects `fusion: learned`// with a 400 (see xerj-query parser.rs::parse_hybrid), so this// arm is unreachable via the ES API. Fail loud rather than@@ -35857,64 +35861,156 @@ fn replace_direct_knn_with_pinned(q: &QueryNode, pinned: &QueryNode) -> QueryNod// ── Hybrid fusion helpers ────────────────────────────────────────────────────//// Both fuse_rrf and fuse_linear take a slice of (hits, weight) pairs and-// return a single Vec<Hit> sorted by combined score descending. The same-// doc_id appearing across multiple lists collapses to one Hit; the source-// is taken from the first list that produced it (sub-lists may differ on-// what they materialise, e.g. a kNN list returns the full source while-// a BM25 list with `_source: false` returns null — first non-null wins).+// return a single Vec<Hit> in the fused order below. The same doc_id+// appearing across multiple lists collapses to one Hit; the source is taken+// from the first list that produced it (sub-lists may differ on what they+// materialise, e.g. a kNN list returns the full source while a BM25 list+// with `_source: false` returns null — first non-null wins).+//+// THE FUSED ORDER (#940) is the ONE total order every score-ranked page in+// this engine uses (#270, `Index::sort_hits_page_order`):+//+// fused score DESC, seq_no ASC (arrival — ES `_doc`), _id ASC+//+// Ties are structural under RRF, not an edge case: a document found only by+// leg A at rank r and one found only by leg B at rank r both score exactly+// `w/(k+r)`, and two documents at swapped ranks (1,2)/(2,1) both score+// `1/(k+1) + 1/(k+2)`. The accumulator used to be a `HashMap` drained+// straight into a score-only stable sort, so every such tie came out in+// hash-iteration order — and `std`'s `RandomState` is seeded per process,+// so the same request on the same data returned a different page after a+// restart. Measured on BEIR SciFact (issue #940): 32 of 40 queries changed+// order and 21 of 40 changed their top 10, with identical hit sets.+//+// Why arrival order and not a rank-derived key. The issue floated "best leg+// rank, then `_id`". On the commonest tie — the symmetric (1,2)/(2,1) pair —+// every rank-derived key ties as well, so that rule bottoms out in "the+// earlier-listed leg wins": reordering the legs of an equal-weight request+// would reorder its results, and RRF is supposed to be symmetric in its+// legs. Arrival order has no such dependence on how the request is spelled,+// and it means a caller learns one tie rule for the whole engine, not two.+//+// Lucene resolves the same problem the same way. `TopDocs.rrf` has this+// exact shape — a `HashMap` accumulator copied into a list and sorted — and+// is deterministic only because its comparator is total: score descending,+// then doc ID, then shard index+// (`lucene/core/src/java/org/apache/lucene/search/TopDocs.java:410-422`,+// Apache-2.0). Lucene's doc ID is its arrival order, i.e. what `seq_no` is+// here. Approach only; no code is shared.++/// One fused candidate: the accumulated score plus the arrival `seq_no` that+/// breaks a tied score (see THE FUSED ORDER above).+struct FusedEntry {+ score: f32,+ /// Resolved once per distinct document, when it is first seen — not per+ /// comparison. `u64::MAX` for a document the version map no longer+ /// knows, the same "unknown sorts last" `sort_hits_page_order` uses.+ seq_no: u64,+ hit: Hit,+}++/// Shared accumulator for both combiners: folds one leg's contribution for+/// one document into `entries`.+///+/// `entries` is a `Vec` indexed through `slot_by_id` rather than a+/// `HashMap<String, _>` drained by iteration, so the map is only ever used+/// for lookup and nothing about the output can depend on hash order.+fn fuse_accumulate(+ entries: &mut Vec<FusedEntry>,+ slot_by_id: &mut HashMap<String, usize>,+ contrib: f32,+ h: &Hit,+ seq_no_of: &dyn Fn(&str) -> u64,+) {+ match slot_by_id.get(&h.id) {+ Some(&slot) => {+ let existing = &mut entries[slot];+ existing.score += contrib;+ // Take a non-null source from a later list if the first had+ // `_source: false`.+ if existing.hit.source.is_null() && !h.source.is_null() {+ existing.hit.source = h.source.clone();+ }+ }+ None => {+ let mut hit = h.clone();+ hit.score = 0.0; // overwritten with the fused score on output+ slot_by_id.insert(h.id.clone(), entries.len());+ entries.push(FusedEntry {+ score: contrib,+ seq_no: seq_no_of(&h.id),+ hit,+ });+ }+ }+}++/// Sort fused candidates into THE FUSED ORDER and stamp the fused score.+///+/// The score key is NaN-safe on purpose. A NaN can reach `fuse_linear` from+/// a scripted leg (`(NaN - lo) / span`), and `partial_cmp(..).unwrap_or(Equal)`+/// over a slice containing one is not a total order — `sort_by` is allowed to+/// panic on that, and the release profile is `panic = "abort"`. A NaN score+/// sorts LAST, as the worst possible score, instead of wherever the sort+/// happened to leave it. For every other value this is the same comparison+/// `sort_hits_page_order` makes.+fn fuse_finish(mut entries: Vec<FusedEntry>) -> Vec<Hit> {+ fn key(score: f32) -> f32 {+ if score.is_nan() {+ f32::NEG_INFINITY+ } else {+ score+ }+ }+ entries.sort_by(|a, b| {+ key(b.score)+ .total_cmp(&key(a.score))+ .then_with(|| a.seq_no.cmp(&b.seq_no))+ .then_with(|| a.hit.id.cmp(&b.hit.id))+ });+ entries+ .into_iter()+ .map(|e| {+ let mut h = e.hit;+ h.score = e.score;+ h+ })+ .collect()+}/// RRF (reciprocal-rank-fusion) combiner. Each doc d in list i at/// 1-based rank r_i contributes `weight_i / (k + r_i)` to its/// combined score. The smoothing constant k defaults to 60 (ES //// OpenSearch / TREC convention) and is small enough that the top-/// few ranks still dominate.-fn fuse_rrf(sub_results: &[(Vec<Hit>, f32)], k: u32) -> Vec<Hit> {+/// few ranks still dominate. Output is in THE FUSED ORDER (#940);+/// `seq_no_of` resolves a document's arrival `seq_no` for the tie-break.+fn fuse_rrf(+ sub_results: &[(Vec<Hit>, f32)],+ k: u32,+ seq_no_of: &dyn Fn(&str) -> u64,+) -> Vec<Hit> {let kf = k as f32;- // doc_id → (combined_score, picked_hit). Picked Hit is mutated to- // carry the fused score on output.- let mut accum: HashMap<String, (f32, Hit)> = HashMap::new();+ let mut entries: Vec<FusedEntry> = Vec::new();+ let mut slot_by_id: HashMap<String, usize> = HashMap::new();for (hits, weight) in sub_results {for (rank_zero_based, h) in hits.iter().enumerate() {let rank = (rank_zero_based + 1) as f32;let contrib = weight / (kf + rank);- match accum.get_mut(&h.id) {- Some(existing) => {- existing.0 += contrib;- // Take a non-null source from the second list if the- // first had _source: false.- if existing.1.source.is_null() && !h.source.is_null() {- existing.1.source = h.source.clone();- }- }- None => {- let mut hit = h.clone();- hit.score = 0.0; // will overwrite from combined- accum.insert(h.id.clone(), (contrib, hit));- }- }+ fuse_accumulate(&mut entries, &mut slot_by_id, contrib, h, seq_no_of);}}- let mut combined: Vec<Hit> = accum- .into_iter()- .map(|(_, (score, mut h))| {- h.score = score;- h- })- .collect();- combined.sort_by(|a, b| {- b.score- .partial_cmp(&a.score)- .unwrap_or(std::cmp::Ordering::Equal)- });- combined+ fuse_finish(entries)}/// Linear combiner. Within each sub-list, normalise scores to [0,1]/// via min-max (constant-score lists collapse to all-zero), then sum/// weight × normalised across lists. Cheaper than RRF; sensitive to-/// score outliers.-fn fuse_linear(sub_results: &[(Vec<Hit>, f32)]) -> Vec<Hit> {- let mut accum: HashMap<String, (f32, Hit)> = HashMap::new();+/// score outliers. Output is in THE FUSED ORDER (#940) — a constant-score+/// leg contributes 0.0 to every document it returns, so whole lists tie+/// here, not just pairs.+fn fuse_linear(sub_results: &[(Vec<Hit>, f32)], seq_no_of: &dyn Fn(&str) -> u64) -> Vec<Hit> {+ let mut entries: Vec<FusedEntry> = Vec::new();+ let mut slot_by_id: HashMap<String, usize> = HashMap::new();for (hits, weight) in sub_results {// Min-max normalise within this sub-list.let (mut lo, mut hi) = (f32::INFINITY, f32::NEG_INFINITY);@@ -35934,34 +36030,10 @@ fn fuse_linear(sub_results: &[(Vec<Hit>, f32)]) -> Vec<Hit> {0.0};let contrib = weight * norm;- match accum.get_mut(&h.id) {- Some(existing) => {- existing.0 += contrib;- if existing.1.source.is_null() && !h.source.is_null() {- existing.1.source = h.source.clone();- }- }- None => {- let mut hit = h.clone();- hit.score = 0.0;- accum.insert(h.id.clone(), (contrib, hit));- }- }+ fuse_accumulate(&mut entries, &mut slot_by_id, contrib, h, seq_no_of);}}- let mut combined: Vec<Hit> = accum- .into_iter()- .map(|(_, (score, mut h))| {- h.score = score;- h- })- .collect();- combined.sort_by(|a, b| {- b.score- .partial_cmp(&a.score)- .unwrap_or(std::cmp::Ordering::Equal)- });- combined+ fuse_finish(entries)}/// Detect a semantic query (parser node `QueryNode::SemanticSearch`)@@ -52715,3 +52787,176 @@ mod pinned_knn_fts_892_tests {);}}++/// #940 — the fused order is total, and a function of the leg lists and the+/// documents' arrival order alone.+///+/// These drive `fuse_rrf`/`fuse_linear` directly, so they exercise the+/// accumulator on every call — the per-index result cache that made repeated+/// in-process requests look stable in the issue's own runs is not in the way.+#[cfg(test)]+mod hybrid_fused_order_tests {+ use super::*;++ fn hit(id: &str, score: f32) -> Hit {+ Hit {+ id: id.to_string(),+ score,+ source: serde_json::json!({ "id": id }),+ seq_no: None,+ version: None,+ sort: Vec::new(),+ explain: None,+ highlight: None,+ matched_queries: Vec::new(),+ passage: None,+ }+ }++ fn ids(hits: &[Hit]) -> Vec<&str> {+ hits.iter().map(|h| h.id.as_str()).collect()+ }++ /// Arrival order used by every test here: the trailing number of the id,+ /// scrambled against `_id` order on purpose (`doc-10` arrives before+ /// `doc-9` but sorts after it as a string) so a test cannot pass by+ /// tying on `_id` alone.+ fn arrival(id: &str) -> u64 {+ id.rsplit('-').next().unwrap().parse().unwrap()+ }++ /// Two disjoint legs of equal weight: the document at rank r of leg A and+ /// the one at rank r of leg B both score exactly `1/(60+r)`. Twelve+ /// structural ties — under the old `HashMap` drain the chance that one+ /// call returns them all in arrival order is 2^-12, and the chance that+ /// 64 calls agree with each other is nil.+ fn disjoint_legs() -> Vec<(Vec<Hit>, f32)> {+ // Leg A holds the ODD arrivals, leg B the EVEN ones, each already in+ // rank order. Scores inside a leg are distinct, as a real leg's are.+ let a: Vec<Hit> = (0..12)+ .map(|r| hit(&format!("doc-{}", 2 * r + 1), 9.0 - r as f32 * 0.5))+ .collect();+ let b: Vec<Hit> = (0..12)+ .map(|r| hit(&format!("doc-{}", 2 * r), 0.99 - r as f32 * 0.01))+ .collect();+ vec![(a, 1.0), (b, 1.0)]+ }++ #[test]+ fn rrf_structural_ties_resolve_by_arrival_order_on_every_call() {+ let legs = disjoint_legs();+ // Rank r → the even arrival (leg B) precedes the odd one (leg A):+ // doc-0, doc-1, doc-2, … — NOT the `_id` order, which would put+ // doc-10 ahead of doc-2.+ let expected: Vec<String> = (0..24).map(|n| format!("doc-{n}")).collect();+ for call in 0..64 {+ let fused = fuse_rrf(&legs, 60, &arrival);+ assert_eq!(+ ids(&fused),+ expected.iter().map(String::as_str).collect::<Vec<_>>(),+ "call {call}: tied fused scores must come back in arrival order"+ );+ // The ties are exact — otherwise this test proves nothing.+ for pair in fused.chunks(2) {+ assert_eq!(+ pair[0].score.to_bits(),+ pair[1].score.to_bits(),+ "fixture must produce EXACT ties, got {} vs {}",+ pair[0].score,+ pair[1].score+ );+ }+ }+ }++ /// The symmetric pair the issue names: two documents at swapped ranks+ /// (1,2)/(2,1) both score `1/61 + 1/62`.+ #[test]+ fn rrf_swapped_rank_pair_resolves_by_arrival_order() {+ let legs = vec![+ (vec![hit("doc-7", 3.0), hit("doc-4", 2.0)], 1.0),+ (vec![hit("doc-4", 0.9), hit("doc-7", 0.8)], 1.0),+ ];+ for _ in 0..64 {+ let fused = fuse_rrf(&legs, 60, &arrival);+ assert_eq!(fused[0].score.to_bits(), fused[1].score.to_bits());+ assert_eq!(ids(&fused), ["doc-4", "doc-7"]);+ }+ }++ /// RRF with equal weights is symmetric in its legs, so listing the legs+ /// in the other order must not change the page. This is the property a+ /// rank-derived tie-break ("the earlier-listed leg wins") cannot keep.+ #[test]+ fn rrf_order_does_not_depend_on_how_the_request_lists_its_legs() {+ let legs = disjoint_legs();+ let mut swapped = legs.clone();+ swapped.reverse();+ assert_eq!(+ ids(&fuse_rrf(&legs, 60, &arrival)),+ ids(&fuse_rrf(&swapped, 60, &arrival))+ );+ }++ /// Two documents sharing an arrival key (both unknown to the version map+ /// → `u64::MAX`) still order — by `_id`.+ #[test]+ fn rrf_falls_through_to_id_when_arrival_is_unknown() {+ let legs = vec![+ (vec![hit("zeta", 1.0)], 1.0),+ (vec![hit("alpha", 1.0)], 1.0),+ ];+ for _ in 0..64 {+ let fused = fuse_rrf(&legs, 60, &|_| u64::MAX);+ assert_eq!(ids(&fused), ["alpha", "zeta"]);+ }+ }++ /// `fuse_linear` had the same accumulator and the same score-only sort. A+ /// constant-score leg normalises to 0.0 for every document it returns, so+ /// the whole list ties.+ #[test]+ fn linear_constant_score_leg_resolves_by_arrival_order_on_every_call() {+ let constant: Vec<Hit> = [5, 11, 2, 9, 10, 3, 8, 1]+ .iter()+ .map(|n| hit(&format!("doc-{n}"), 1.0))+ .collect();+ let legs = vec![(constant, 1.0)];+ for call in 0..64 {+ let fused = fuse_linear(&legs, &arrival);+ assert!(fused.iter().all(|h| h.score == 0.0));+ assert_eq!(+ ids(&fused),+ ["doc-1", "doc-2", "doc-3", "doc-5", "doc-8", "doc-9", "doc-10", "doc-11"],+ "call {call}"+ );+ }+ }++ /// A NaN leg score must neither abort the sort nor float to the top of+ /// the page (`f32::total_cmp` alone would rank a positive NaN FIRST).+ #[test]+ fn linear_nan_score_sorts_last_and_does_not_panic() {+ let legs = vec![(+ vec![hit("doc-1", 4.0), hit("doc-2", f32::NAN), hit("doc-3", 1.0)],+ 1.0,+ )];+ let fused = fuse_linear(&legs, &arrival);+ assert_eq!(ids(&fused), ["doc-1", "doc-3", "doc-2"]);+ assert!(fused[2].score.is_nan());+ }++ /// Fusion still fuses: a document both legs rank highly beats one that+ /// only one leg found, and duplicates collapse to one hit.+ #[test]+ fn rrf_still_ranks_by_fused_score_first() {+ let legs = vec![+ (vec![hit("doc-9", 3.0), hit("doc-1", 2.0)], 1.0),+ (vec![hit("doc-9", 0.9), hit("doc-2", 0.8)], 1.0),+ ];+ let fused = fuse_rrf(&legs, 60, &arrival);+ assert_eq!(ids(&fused), ["doc-9", "doc-1", "doc-2"]);+ assert!(fused[0].score > fused[1].score);+ assert_eq!(fused[1].score.to_bits(), fused[2].score.to_bits());+ }+}diff --git a/engine/crates/xerj-engine/tests/hybrid_fused_order_is_stable.rs b/engine/crates/xerj-engine/tests/hybrid_fused_order_is_stable.rsnew file mode 100644index 000000000..ad80de884--- /dev/null+++ b/engine/crates/xerj-engine/tests/hybrid_fused_order_is_stable.rs@@ -0,0 +1,320 @@+//! Regression test for #940 — a `hybrid` page must be a function of the index,+//! not of the process that served it.+//!+//! Tied fused scores are structural under RRF, not an edge case: a document+//! found only by leg A at rank r and one found only by leg B at rank r both+//! score exactly `w/(k+r)`. `fuse_rrf`/`fuse_linear` used to accumulate into a+//! `HashMap` and drain it into a score-only stable sort, so every such tie+//! came out in hash-iteration order, and `std`'s `RandomState` is seeded per+//! process. Measured on BEIR SciFact (issue #940): after a restart on+//! unchanged data 32 of 40 queries changed order and 21 of 40 changed their+//! top 10, with identical hit sets.+//!+//! The order asserted here is the ONE total order every score-ranked page+//! uses (#270): `score DESC, seq_no ASC (arrival), _id ASC`.+//!+//! Two things this test is careful about:+//!+//! * **The result cache.** `Index::query_cache` is keyed by+//! `(query hash, dataset version)`, so a repeated request is served from+//! it without re-running fusion — which is why the issue's own in-process+//! repeats looked stable. It is cleared before every search below; a test+//! that did not would pass against the broken code.+//! * **`_id` order is not arrival order.** Documents are written in a+//! scrambled order, so a fix that tied on `_id` alone — or any order that+//! merely happened to be repeatable — fails the arrival assertion.++use std::collections::HashMap;+use std::sync::Arc;++use serde_json::{json, Value};+use tempfile::TempDir;+use xerj_common::config::Config;+use xerj_common::types::Schema;+use xerj_engine::index::Index;+use xerj_engine::Engine;+use xerj_query::parse_request;++const INDEX: &str = "hy940";+/// Documents per leg. Each rank r in 0..PER_LEG yields one exact tie pair.+const PER_LEG: usize = 12;+/// Tokens per document — constant, so BM25's length normalisation is the+/// same for every document and the score is a function of `tf` alone.+const DOC_LEN: usize = 16;++fn make_engine(dir: &TempDir) -> Engine {+ let mut config = Config::default();+ config.server.data_dir = dir.path().to_str().unwrap().to_string();+ Engine::new(config).expect("engine::new")+}++fn hybrid(fusion: Value) -> Value {+ json!({+ "hybrid": {+ "queries": [+ { "query": { "match": { "body": "alpha" } }, "weight": 1.0 },+ { "query": { "match": { "body": "beta" } }, "weight": 1.0 }+ ],+ "fusion": fusion+ }+ })+}++fn rrf() -> Value {+ hybrid(json!({ "type": "rrf", "k": 60 }))+}++fn linear() -> Value {+ hybrid(json!("linear"))+}++/// `word` repeated `tf` times, padded with a filler token to `DOC_LEN`.+fn body(word: &str, tf: usize) -> String {+ let mut tokens = vec![word; tf];+ tokens.resize(DOC_LEN, "filler");+ tokens.join(" ")+}++/// A symmetric two-leg corpus: `a-<r>` holds "alpha" `PER_LEG - r` times and+/// `b-<r>` holds "beta" the same number of times, so inside each leg the+/// scores are DISTINCT and strictly decreasing in r (the leg's rank order+/// owes nothing to any tie-break), while across legs `a-<r>` and `b-<r>`+/// sit at the same rank and tie exactly after fusion.+///+/// Written in a scrambled order. Returns id → arrival position.+async fn symmetric_corpus(idx: &Arc<Index>) -> HashMap<String, usize> {+ let mut ids: Vec<(String, String)> = Vec::new();+ for r in 0..PER_LEG {+ ids.push((format!("a-{r:02}"), body("alpha", PER_LEG - r)));+ ids.push((format!("b-{r:02}"), body("beta", PER_LEG - r)));+ }+ // A fixed permutation (multiplication by 7 is a bijection mod 24), so+ // arrival order agrees with neither `_id` order nor rank order — and+ // within a tie pair it is `a` first for some ranks and `b` first for+ // others.+ let n = ids.len();+ let mut arrival = HashMap::new();+ for pos in 0..n {+ let (id, text) = ids[(pos * 7 + 5) % n].clone();+ idx.index_document(Some(id.clone()), json!({ "body": text }))+ .await+ .unwrap();+ arrival.insert(id, pos);+ }+ assert_eq!(arrival.len(), n, "the permutation must visit every document");+ arrival+}++/// One uncached hybrid search → `(id, score bits)` per hit.+async fn page(idx: &Arc<Index>, from: usize, size: usize, q: &Value) -> Vec<(String, u32)> {+ idx.query_cache.clear();+ let req = parse_request(&json!({ "from": from, "size": size, "query": q })).unwrap();+ let res = idx.search(&req).await.unwrap();+ res.hits+ .into_iter()+ .map(|h| (h.id, h.score.to_bits()))+ .collect()+}++/// Inside every run of bit-identical scores, hits must be in arrival order.+fn assert_ties_are_in_arrival_order(+ label: &str,+ hits: &[(String, u32)],+ arrival: &HashMap<String, usize>,+) {+ for w in hits.windows(2) {+ if w[0].1 == w[1].1 {+ assert!(+ arrival[&w[0].0] < arrival[&w[1].0],+ "{label}: {} and {} tie on score but are not in arrival order \+ (arrived {} and {}) — full page: {hits:?}",+ w[0].0,+ w[1].0,+ arrival[&w[0].0],+ arrival[&w[1].0],+ );+ }+ }+}++/// The page RRF must return for `symmetric_corpus`: rank by rank, and inside+/// each rank's tie pair the document that arrived first.+fn expected_rrf_order(arrival: &HashMap<String, usize>) -> Vec<String> {+ let mut out = Vec::new();+ for r in 0..PER_LEG {+ let mut pair = [format!("a-{r:02}"), format!("b-{r:02}")];+ pair.sort_by_key(|id| arrival[id]);+ out.extend(pair);+ }+ out+}++fn ids_of(hits: &[(String, u32)]) -> Vec<String> {+ hits.iter().map(|(id, _)| id.clone()).collect()+}++/// Everything a paginating client relies on, checked against one open index.+async fn assert_fused_pages(label: &str, idx: &Arc<Index>, arrival: &HashMap<String, usize>) {+ let n = 2 * PER_LEG;+ let expected = expected_rrf_order(arrival);++ // ── RRF ──────────────────────────────────────────────────────────────+ let full = page(idx, 0, n, &rrf()).await;+ assert_eq!(full.len(), n, "{label}: both legs fully retrieved");+ // The fixture really does tie at every rank — otherwise this test would+ // pass against the broken code and prove nothing.+ for (r, pair) in full.chunks(2).enumerate() {+ assert_eq!(+ pair[0].1, pair[1].1,+ "{label}: rank {r} must be an EXACT fused tie, got {pair:?}"+ );+ }+ assert_eq!(+ ids_of(&full),+ expected,+ "{label}: tied fused scores must resolve by arrival order"+ );++ // Re-running fusion must reproduce the page. 32 uncached repeats: under+ // the old per-map `RandomState` the 12 tie pairs agreed between two runs+ // with probability 2^-12.+ for run in 0..32 {+ assert_eq!(+ page(idx, 0, n, &rrf()).await,+ full,+ "{label}: uncached repeat {run} returned a different page"+ );+ }++ // Every bounded page is a prefix of the full page …+ for size in 1..=n {+ assert_eq!(+ page(idx, 0, size, &rrf()).await,+ full[..size],+ "{label}: size:{size} disagrees with the full page"+ );+ }+ // … and walking it with `from` reproduces it, including the pages whose+ // boundary falls INSIDE a tie pair (every odd `from`). `from + size`+ // stays under the 50-deep leg window, so every page fuses the same legs.+ for size in [1usize, 3, 5] {+ let mut walked = Vec::new();+ let mut from = 0;+ while from < n {+ walked.extend(page(idx, from, size, &rrf()).await);+ from += size;+ }+ assert_eq!(walked, full, "{label}: paging by {size} reorders the corpus");+ }++ // ── Linear ───────────────────────────────────────────────────────────+ // Same accumulator, same defect. The legs are symmetric, so min-max+ // normalisation maps `a-<r>` and `b-<r>` to the same value and they tie+ // here too; the assertion is the general one so it does not depend on+ // that.+ let lin = page(idx, 0, n, &linear()).await;+ assert_eq!(lin.len(), n, "{label}: linear retrieves both legs");+ assert_ties_are_in_arrival_order(&format!("{label}/linear"), &lin, arrival);+ assert!(+ lin.windows(2).any(|w| w[0].1 == w[1].1),+ "{label}: the linear fixture is expected to tie somewhere, got {lin:?}"+ );+ for run in 0..32 {+ assert_eq!(+ page(idx, 0, n, &linear()).await,+ lin,+ "{label}: linear uncached repeat {run} returned a different page"+ );+ }+}++/// Flushed data: the page is the same before the restart, after it, and after+/// the one after that.+#[tokio::test]+async fn hybrid_page_survives_restarts_on_flushed_data() {+ let dir = TempDir::new().unwrap();+ let arrival;+ let before;+ {+ let engine = make_engine(&dir);+ engine.create_index(INDEX, Schema::empty()).unwrap();+ let idx = engine.get_index(INDEX).unwrap();+ arrival = symmetric_corpus(&idx).await;+ idx.flush().await.unwrap();+ assert_fused_pages("flushed", &idx, &arrival).await;+ before = (+ page(&idx, 0, 2 * PER_LEG, &rrf()).await,+ page(&idx, 0, 2 * PER_LEG, &linear()).await,+ );+ drop(idx);+ drop(engine);+ }+ for restart in 1..=3 {+ let engine = make_engine(&dir);+ let idx = engine.get_index(INDEX).unwrap();+ let label = format!("flushed/restart-{restart}");+ assert_fused_pages(&label, &idx, &arrival).await;+ let after = (+ page(&idx, 0, 2 * PER_LEG, &rrf()).await,+ page(&idx, 0, 2 * PER_LEG, &linear()).await,+ );+ assert_eq!(after, before, "{label}: page changed across a restart");+ drop(idx);+ drop(engine);+ }+}++/// Unflushed data: after the restart the documents come back through WAL+/// replay into the memtable, a different read path from the segments above.+#[tokio::test]+async fn hybrid_page_survives_restarts_on_unflushed_data() {+ let dir = TempDir::new().unwrap();+ let arrival;+ let before;+ {+ let engine = make_engine(&dir);+ engine.create_index(INDEX, Schema::empty()).unwrap();+ let idx = engine.get_index(INDEX).unwrap();+ arrival = symmetric_corpus(&idx).await;+ assert_fused_pages("memtable", &idx, &arrival).await;+ before = page(&idx, 0, 2 * PER_LEG, &rrf()).await;+ drop(idx);+ drop(engine);+ }+ for restart in 1..=2 {+ let engine = make_engine(&dir);+ let idx = engine.get_index(INDEX).unwrap();+ let label = format!("memtable/restart-{restart}");+ assert_fused_pages(&label, &idx, &arrival).await;+ assert_eq!(+ page(&idx, 0, 2 * PER_LEG, &rrf()).await,+ before,+ "{label}: page changed across a restart"+ );+ drop(idx);+ drop(engine);+ }+}++/// A flush in the middle moves half the corpus to segments. Arrival order is+/// a property of the documents, not of where they are stored, so the page+/// must not notice.+#[tokio::test]+async fn hybrid_page_does_not_depend_on_where_the_documents_are_stored() {+ let dir = TempDir::new().unwrap();+ let engine = make_engine(&dir);+ engine.create_index(INDEX, Schema::empty()).unwrap();+ let idx = engine.get_index(INDEX).unwrap();+ let arrival = symmetric_corpus(&idx).await;++ let in_memtable = page(&idx, 0, 2 * PER_LEG, &rrf()).await;+ idx.flush().await.unwrap();+ let in_segments = page(&idx, 0, 2 * PER_LEG, &rrf()).await;++ assert_eq!(ids_of(&in_memtable), expected_rrf_order(&arrival));+ assert_eq!(+ ids_of(&in_segments),+ ids_of(&in_memtable),+ "a flush reordered a hybrid page"+ );+}