Skip to content

armgit / xerj

Public Imported from GitHub
0

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.

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.rs
index 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.rs
new file mode 100644
index 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"
+ );
+}