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): rank the memtable's bounded candidates by the page key too (#191)
xerj-org5f048cbc0e6c
diff --git a/engine/crates/xerj-engine/src/index.rs b/engine/crates/xerj-engine/src/index.rsindex 2b03a93f0..84a779b56 100644--- a/engine/crates/xerj-engine/src/index.rs+++ b/engine/crates/xerj-engine/src/index.rs@@ -11836,6 +11836,39 @@ impl Index {worst}+ /// Reduce `hits` to the best `cap` under the SAME comparator the final page+ /// sort uses (`score DESC, seq_no ASC, _id ASC` — `index.rs:16222-16228`),+ /// and return the surviving cap-th `(score, seq_no, _id)` page key.+ ///+ /// #191 — every bounded collector in `search` trims through here, so+ /// admission and final ordering can never drift apart: a `size:5` page is+ /// the first five of a `size:1000` one whatever order the walk visited the+ /// documents in.+ #[allow(clippy::type_complexity)]+ fn trim_page_to_cap(+ &self,+ hits: Vec<Hit>,+ cap: usize,+ ) -> (Vec<Hit>, Option<(f32, u64, String)>) {+ let mut decorated: Vec<(u64, Hit)> = hits+ .into_iter()+ .map(|h| (self.lookup_seq_no(&h.id).unwrap_or(u64::MAX), h))+ .collect();+ decorated.sort_by(|a, b| {+ b.1.score+ .partial_cmp(&a.1.score)+ .unwrap_or(std::cmp::Ordering::Equal)+ .then_with(|| a.0.cmp(&b.0))+ .then_with(|| a.1.id.cmp(&b.1.id))+ });+ decorated.truncate(cap);+ let worst = decorated+ .last()+ .map(|(seq, h)| (h.score, *seq, h.id.clone()));+ let kept = decorated.into_iter().map(|(_, h)| h).collect();+ (kept, worst)+ }+/// Look up the latest `seq_no` for a document by id via the version/// map. Returns `None` when the doc is unknown or tombstoned.///@@ -13501,6 +13534,26 @@ impl Index {// memtable and a segment (possible during a flush race). We prefer// the first appearance (which is usually the memtable, i.e. the// newest version).+ //+ // #191 — the `materialisation_limit` bound here is a plain FIFO cut,+ // and it is only CORRECT because every arm that feeds it upholds one+ // of two invariants:+ //+ // * `AllDocIds` / `DocValuesHits` — the memtable already narrowed+ // its candidates to the globally best `limit` by `(seq_no, _id)`+ // (`ShardedFtsMemtable::narrow_to_page`), so the FIFO never+ // truncates at all; and+ // * `FtsHits` — the memtable returns its hits already sorted by the+ // full page key (`sort_hits_by_page_key`), so the first `limit`+ // ARE the page. This matters on the ghost-window path, which asks+ // the memtable for every hit rather than a bounded prefix.+ //+ // The brute-scan arm upholds neither (it walks shards in index order),+ // so it does NOT route post-cap admissions through here — see the+ // `DocsForScan` arm. Before #191 the FIFO was applied to unordered+ // input and the surviving tied documents were decided by shard-walk+ // order: `size:5` and `size:1000` disagreed on a 600-document+ // all-tied memtable.macro_rules! admit_hit {($hit:expr) => {{total_count += 1;@@ -13616,7 +13669,11 @@ impl Index {/// The `u64` is the UNCOLLECTED matching-doc remainder (bounded/// fused-bool path); it still counts toward `hits.total`.DocValuesHits(Vec<(String, usize)>, u64),- DocsForScan(Vec<(String, Arc<Value>)>), // doc_id + shared source for term-level scan+ /// `(seq_no, doc_id, shared source)` for a term-level brute scan.+ /// #191 — `seq_no` rides along so the bounded collector can rank a+ /// document it reaches after filling the cap against the page it+ /// already holds; shard-concatenation order is not arrival order.+ DocsForScan(Vec<(u64, String, Arc<Value>)>),}// Search the memtable (unflushed docs only). Flushed docs are searched@@ -13796,7 +13853,7 @@ impl Index {// the heap is full (NOT the id-only snapshot,// whose per-doc deep clone cost ~1 s/query at a// 1 M-doc memtable).- None => MemSnapshot::DocsForScan(mem.all_docs_with_sources_arc()),+ None => MemSnapshot::DocsForScan(mem.all_docs_with_seq_arc()),}} else {let (ids, total) = mem.doc_ids_bounded(materialisation_limit);@@ -13880,7 +13937,7 @@ impl Index {} else {// Brute per-doc scan — same authority the size>0// path falls back to; `doc_matches_query` semantics.- MemSnapshot::DocsForScan(mem.all_docs_with_sources_arc())+ MemSnapshot::DocsForScan(mem.all_docs_with_seq_arc())}} else if let Some((hits, total)) = (|| {// Fused columnar term/range/bool: ONE position walk@@ -13934,7 +13991,7 @@ impl Index {// query (plus a second per-doc clone for `_id`// injection below) was the single hottest search-side// cost in the read-under-write thread dumps.- let docs: Vec<(String, Arc<Value>)> = mem.all_docs_with_sources_arc();+ let docs: Vec<(u64, String, Arc<Value>)> = mem.all_docs_with_seq_arc();MemSnapshot::DocsForScan(docs)}} else {@@ -14100,7 +14157,15 @@ impl Index {let query_may_read_id: bool = serde_json::to_string(query).map(|s| s.contains("_id") || s.contains("Ids") || s.contains("ids")).unwrap_or(true);- for (doc_id, source) in docs {+ // #191 — the cap-th page key the bounded collector currently+ // holds, recomputed only when it can have changed (the moment+ // the collector first fills, and after every trim). A stale+ // value is always a WEAKER threshold than the truth — it admits+ // more than strictly necessary, never less — which is the safe+ // direction, the same argument the segment walk's `page_worst`+ // relies on.+ let mut scan_worst: Option<(f32, u64, String)> = None;+ for (seq_no, doc_id, source) in docs {let matched = if let QueryNode::Ids { values } = query {values.iter().any(|v| v == doc_id.as_str())} else if !query_may_read_id || source.get("_id").is_some() {@@ -14121,13 +14186,31 @@ impl Index {// Materialise (score + owned source) ONLY when the// hit can actually enter the bounded collector /// top-N heap; everything else is a bare count.- // Identical outcome to unconditionally building the- // Hit: `admit_hit!` drops post-cap hits anyway.+ //+ // #191 — "can enter" is no longer "the collector still+ // has room". This walk visits shards in index order+ // and each shard in arrival order, so it is NOT a+ // globally arrival-ordered walk: a document reached+ // after the cap is full can still hold a smaller+ // `seq_no` than the page's worst hit and therefore win+ // the tie-break against it. Admit exactly those as+ // well — one `u64` compare against `scan_worst`, no+ // extra source clone for the ones that lose — and let+ // the trim below put the collector back at the cap by+ // the final comparator. Documents that lose on+ // `seq_no` but would have won on SCORE are still+ // dropped here; that is pre-existing (they were dropped+ // outright before) and is recorded under Residual risk.+ let competitive = all_hits.len() < materialisation_limit || {+ if scan_worst.is_none() {+ scan_worst = self.worst_page_key(&all_hits);+ }+ scan_worst.as_ref().is_some_and(|w| seq_no < w.1)+ };if count_only {total_count += 1;} else if sort_topk.is_some()- || (all_hits.len() < materialisation_limit- && !seen_ids.contains(&doc_id))+ || (competitive && !seen_ids.contains(&doc_id)){// Field-sorted: pre-clone primary-key rejection.// Once the heap is full, a doc whose PRIMARY@@ -14147,7 +14230,7 @@ impl Index {}}let score = score_doc(&source, &doc_id);- admit_hit!(Hit {+ let hit = Hit {id: doc_id,score,source: (*source).clone(),@@ -14156,7 +14239,30 @@ impl Index {highlight: None,matched_queries: Vec::new(),passage: None,- });+ };+ if sort_topk.is_some() {+ admit_hit!(hit);+ } else {+ // `admit_hit!`'s FIFO bound would throw the+ // post-cap admissions above straight back+ // away, so this arm collects them itself and+ // trims by the page comparator once the+ // overflow reaches 2×cap — the same eager-trim+ // shape the segment walk uses.+ total_count += 1;+ if !seen_ids.contains(&hit.id) {+ seen_ids.insert(hit.id.clone());+ all_hits.push(hit);+ if all_hits.len() > materialisation_limit.saturating_mul(2) {+ let (kept, worst) = self.trim_page_to_cap(+ std::mem::take(&mut all_hits),+ materialisation_limit,+ );+ all_hits = kept;+ scan_worst = worst;+ }+ }+ }} else {total_count += 1;}@@ -14165,6 +14271,18 @@ impl Index {}}+ // #191 — normalise the memtable contribution back to exactly the cap+ // before the segment walk starts, so every downstream stage sees the+ // documented shape (`all_hits` holds the best `materialisation_limit`+ // by the final comparator). Only the brute-scan arm can overshoot —+ // it admits post-cap documents that outrank the page it holds — and+ // only up to 2×cap before its own eager trim fires.+ if sort_topk.is_none() && all_hits.len() > materialisation_limit {+ let (kept, _worst) =+ self.trim_page_to_cap(std::mem::take(&mut all_hits), materialisation_limit);+ all_hits = kept;+ }+// --- Segment search ---// `snap` is captured ABOVE the memtable arms (see the point-in-time// capture ORDER comment there): segment snapshot strictly before the@@ -15177,31 +15295,8 @@ impl Index {Vec<Hit>,Option<(f32, u64, String)>,) {- let mut decorated: Vec<(u64, Hit)> = hits- .into_iter()- .map(|h| {- (- self.lookup_seq_no(&h.id)- .unwrap_or(u64::MAX),- h,- )- })- .collect();- decorated.sort_by(|a, b| {- b.1.score- .partial_cmp(&a.1.score)- .unwrap_or(std::cmp::Ordering::Equal)- .then_with(|| a.0.cmp(&b.0))- .then_with(|| a.1.id.cmp(&b.1.id))- });- decorated.truncate(materialisation_limit);- let worst = decorated- .last()- .map(|(seq, h)| (h.score, *seq, h.id.clone()));- let kept =- decorated.into_iter().map(|(_, h)| h).collect();- (kept, worst)- };+ self.trim_page_to_cap(hits, materialisation_limit)+ };for sh in &seg_hits {// `seg_hits` descends by score, so once// a hit's score is STRICTLY below thediff --git a/engine/crates/xerj-engine/src/memtable.rs b/engine/crates/xerj-engine/src/memtable.rsindex 0005b41fa..cc7346b8f 100644--- a/engine/crates/xerj-engine/src/memtable.rs+++ b/engine/crates/xerj-engine/src/memtable.rs@@ -23,6 +23,33 @@ use xerj_fts::bm25::Bm25Scorer;pub struct MemtableHit {pub doc_id: String,pub score: f32,+ /// WAL `seq_no` of the buffered document (`u64::MAX` when it can't be+ /// resolved). #191 — the memtable's bounded FTS materialisation has to+ /// truncate under the SAME total order the final page sort uses+ /// (`score DESC, seq_no ASC, _id ASC`); score alone leaves the survivors+ /// of a tie decided by shard-walk order, which is not arrival order.+ pub seq_no: u64,+}++/// Order `hits` by the page key XERJ's final sort uses: `score DESC`, then+/// `seq_no ASC` (arrival order — the `_doc` analogue), then `_id ASC`+/// (`index.rs:16222-16228`).+///+/// #191 — any bounded materialisation must truncate under the SAME total order+/// the page is finally sorted by, otherwise the documents that survive a tie+/// are decided by whatever order the walk happened to visit them in. Lucene+/// makes the same comparator total for the same reason+/// (`HitQueue.lessThan` breaks an equal score by the smaller doc id,+/// `lucene/core/src/java/org/apache/lucene/search/HitQueue.java:76-82`);+/// approach only, no code taken.+fn sort_hits_by_page_key(hits: &mut [MemtableHit]) {+ hits.sort_unstable_by(|a, b| {+ b.score+ .partial_cmp(&a.score)+ .unwrap_or(std::cmp::Ordering::Equal)+ .then_with(|| a.seq_no.cmp(&b.seq_no))+ .then_with(|| a.doc_id.cmp(&b.doc_id))+ });}#[cfg(test)]@@ -829,17 +856,49 @@ impl ShardedFtsMemtable {/// on every request — ~1 s per query at a 300 k-doc memtable under/// sustained bulk load (the `mem_admit` phase of the read-under-write/// breakdown).+ /// #191 — reduce per-shard bounded candidates to the globally best `limit`+ /// under the order the final page sort uses.+ ///+ /// Every hit these paths produce carries the SAME score (`1.0` for the+ /// id-only and doc-values collectors; a top-level `constant_score` rewrites+ /// them all to the wrapper's boost), so the page order reduces to+ /// `(seq_no ASC, _id ASC)` — the tail of `(score DESC, seq_no ASC, _id ASC)`+ /// at `index.rs:16222-16228`.+ ///+ /// Returns the surviving cap-th `seq_no` as the next shard's cutoff, so the+ /// walk can stop cloning ids that can no longer reach the page.+ fn narrow_to_page<T>(cands: &mut Vec<(u64, String, T)>, limit: usize) -> u64 {+ if cands.len() <= limit {+ return u64::MAX;+ }+ cands.sort_unstable_by(|a, b| a.0.cmp(&b.0).then_with(|| a.1.cmp(&b.1)));+ cands.truncate(limit);+ cands.last().map_or(u64::MAX, |c| c.0)+ }+pub fn doc_ids_bounded(&self, limit: usize) -> (Vec<String>, u64) {- let mut out: Vec<String> = Vec::with_capacity(limit.min(4096));+ // #191 — this used to fill greedily from shard 0 (`limit - out.len()`+ // of room for each later shard), so an index whose memtable held more+ // than `limit` documents returned "shard 0's first `limit` ids", not+ // "the `limit` earliest-arriving ids". Shard assignment is by doc-id+ // hash (and by BATCH for bulk), so that set is neither arrival order+ // nor stable, and `size:5` stopped being a prefix of `size:1000` on an+ // all-tied corpus. Bound each shard independently and keep the global+ // best `limit` by `(seq_no, _id)` instead.+ let mut cands: Vec<(u64, String, ())> = Vec::with_capacity(limit.min(4096));let mut total: u64 = 0;+ let mut cutoff = u64::MAX;for s in &self.shards {let g = s.read();total += g.doc_count() as u64;- if out.len() < limit {- out.extend(g.doc_ids_up_to(limit - out.len()));- }+ cands.extend(+ g.ranked_ids_up_to(limit, cutoff)+ .into_iter()+ .map(|(q, id)| (q, id, ())),+ );+ cutoff = Self::narrow_to_page(&mut cands, limit);}- (out, total)+ (cands.into_iter().map(|(_, id, ())| id).collect(), total)}/// Return every (doc_id, source) pair. Aggregates across all@@ -863,6 +922,22 @@ impl ShardedFtsMemtable {out}+ /// `(seq_no, doc_id, source_arc)` for every buffered document.+ ///+ /// #191 — the brute per-doc scan's bounded collector has to decide whether+ /// a document it reaches AFTER filling the cap still belongs on the page.+ /// Shards are concatenated in index order, which is not arrival order, so+ /// that decision needs the document's arrival `seq_no`. Carrying it in the+ /// snapshot costs 8 bytes per entry and saves a `VersionMap` hash lookup+ /// per match on the hottest memtable read path.+ pub fn all_docs_with_seq_arc(&self) -> Vec<(u64, String, Arc<Value>)> {+ let mut out = Vec::new();+ for s in &self.shards {+ out.extend(s.read().all_docs_with_seq_arc());+ }+ out+ }+/// Columnar-filtered twin of `all_docs_with_sources_arc`: materialise ONLY/// the `(doc_id, source_arc)` pairs matching `preds` (a pure conjunction of/// Term/Range predicates), so a filtered `size:0` aggregation folds@@ -1294,11 +1369,12 @@ impl ShardedFtsMemtable {field_boosts,));}- all.sort_by(|a, b| {- b.score- .partial_cmp(&a.score)- .unwrap_or(std::cmp::Ordering::Equal)- });+ // #191 — the cross-shard merge sorts by the FULL page key, not by score+ // alone. Score alone leaves ties in shard-concatenation order, so+ // `truncate(limit)` kept "the tied documents that happen to live in the+ // lowest-numbered shards" rather than the earliest-arriving ones, and a+ // `size:5` page stopped being a prefix of a `size:1000` one.+ sort_hits_by_page_key(&mut all);// A doc_id lives in exactly ONE shard, so `all` has no duplicates:// its pre-truncation length IS the exact global match count when// `shard_limit == usize::MAX` (a lower bound otherwise).@@ -1482,19 +1558,28 @@ impl ShardedFtsMemtable {if preds.is_empty() {return None;}- let mut out: Vec<(String, usize)> = Vec::new();+ // #191 — bound each shard independently and keep the global best+ // `limit` by `(seq_no, _id)`; `limit - out.len()` starved every shard+ // after the first, so the page was "shard 0's first `limit` matches".+ let mut cands: Vec<(u64, String, usize)> = Vec::new();let mut total: u64 = 0;for s in &self.shards {let g = s.read();if g.doc_count() == 0 {continue;}- let room = limit.saturating_sub(out.len());- let (mut hits, t) = g.doc_values_bool_hits(preds, room)?;- out.append(&mut hits);+ let (hits, t) = g.doc_values_bool_hits(preds, limit)?;+ cands.extend(+ hits.into_iter()+ .map(|(id, pos)| (g.seq_no_at(pos), id, pos)),+ );total += t;+ Self::narrow_to_page(&mut cands, limit);}- Some((out, total))+ Some((+ cands.into_iter().map(|(_, id, pos)| (id, pos)).collect(),+ total,+ ))}/// Columnar per-value counts for one field across all shards, for the@@ -1597,23 +1682,30 @@ impl ShardedFtsMemtable {value: &str,limit: usize,) -> Option<(Vec<(String, usize)>, u64)> {- let mut out: Vec<(String, usize)> = Vec::new();+ let mut cands: Vec<(u64, String, usize)> = Vec::new();let mut total: u64 = 0;let mut any_hit = false;for s in &self.shards {let g = s.read();- // Step 1: bound the id clone to the remaining global window;- // the total is still exact per shard. Mirrors- // `doc_values_bool_query`.- let room = limit.saturating_sub(out.len());- if let Some((mut hits, t)) = g.doc_values_term_query(field, value, room) {+ // Step 1: bound the id clone per shard; the total is still exact+ // per shard. Mirrors `doc_values_bool_query`. #191 — the bound+ // used to be the REMAINING global window, which handed the whole+ // page to shard 0.+ if let Some((hits, t)) = g.doc_values_term_query(field, value, limit) {any_hit = true;- out.append(&mut hits);+ cands.extend(+ hits.into_iter()+ .map(|(id, pos)| (g.seq_no_at(pos), id, pos)),+ );total += t;+ Self::narrow_to_page(&mut cands, limit);}}if any_hit {- Some((out, total))+ Some((+ cands.into_iter().map(|(_, id, pos)| (id, pos)).collect(),+ total,+ ))} else {None}@@ -1625,20 +1717,28 @@ impl ShardedFtsMemtable {values: &[String],limit: usize,) -> Option<(Vec<(String, usize)>, u64)> {- let mut out: Vec<(String, usize)> = Vec::new();+ // #191 — per-shard bound + global `(seq_no, _id)` narrowing, as in+ // `doc_values_term_query`.+ let mut cands: Vec<(u64, String, usize)> = Vec::new();let mut total: u64 = 0;let mut any_hit = false;for s in &self.shards {let g = s.read();- let room = limit.saturating_sub(out.len());- if let Some((mut hits, t)) = g.doc_values_terms_query(field, values, room) {+ if let Some((hits, t)) = g.doc_values_terms_query(field, values, limit) {any_hit = true;- out.append(&mut hits);+ cands.extend(+ hits.into_iter()+ .map(|(id, pos)| (g.seq_no_at(pos), id, pos)),+ );total += t;+ Self::narrow_to_page(&mut cands, limit);}}if any_hit {- Some((out, total))+ Some((+ cands.into_iter().map(|(_, id, pos)| (id, pos)).collect(),+ total,+ ))} else {None}@@ -1709,20 +1809,28 @@ impl ShardedFtsMemtable {lt: Option<f64>,limit: usize,) -> Option<(Vec<(String, usize)>, u64)> {- let mut out: Vec<(String, usize)> = Vec::new();+ // #191 — per-shard bound + global `(seq_no, _id)` narrowing, as in+ // `doc_values_term_query`.+ let mut cands: Vec<(u64, String, usize)> = Vec::new();let mut total: u64 = 0;let mut any_hit = false;for s in &self.shards {let g = s.read();- let room = limit.saturating_sub(out.len());- if let Some((mut hits, t)) = g.doc_values_range_query(field, gte, gt, lte, lt, room) {+ if let Some((hits, t)) = g.doc_values_range_query(field, gte, gt, lte, lt, limit) {any_hit = true;- out.append(&mut hits);+ cands.extend(+ hits.into_iter()+ .map(|(id, pos)| (g.seq_no_at(pos), id, pos)),+ );total += t;+ Self::narrow_to_page(&mut cands, limit);}}if any_hit {- Some((out, total))+ Some((+ cands.into_iter().map(|(_, id, pos)| (id, pos)).collect(),+ total,+ ))} else {None}@@ -2623,18 +2731,27 @@ impl FtsMemtable {let mut hits: Vec<MemtableHit> = scores.into_iter()- .map(|(doc_id, score)| MemtableHit {- doc_id: doc_id.to_string(),- score,+ .map(|(doc_id, score)| {+ // #191 — carry the arrival order with the hit. `scores` is a+ // HashMap, so without it the pre-truncation order of an+ // all-tied hit set is the hash iteration order: the surviving+ // documents changed from run to run.+ let seq_no = self+ .doc_id_index+ .get(&doc_id)+ .map_or(u64::MAX, |&pos| self.seq_no_at(pos));+ MemtableHit {+ doc_id: doc_id.to_string(),+ score,+ seq_no,+ }}).collect();- // Sort by score descending.- hits.sort_by(|a, b| {- b.score- .partial_cmp(&a.score)- .unwrap_or(std::cmp::Ordering::Equal)- });+ // Sort by the FULL page key (score DESC, seq_no ASC, `_id` ASC) — the+ // comparator `index.rs:16222-16228` applies to the final page — so a+ // truncation at `limit` keeps exactly the documents that page would.+ sort_hits_by_page_key(&mut hits);hits.truncate(limit);hits}@@ -2664,6 +2781,37 @@ impl FtsMemtable {self.docs.iter().take(n).map(|e| e.doc_id.clone()).collect()}+ /// The WAL `seq_no` of the document at shard-local position `pos`+ /// (`u64::MAX` when the position is out of range).+ ///+ /// #191 — the bounded memtable paths must rank candidates ACROSS shards+ /// by the same key the final page sort uses, and `seq_no` is that key's+ /// tie-break. Positions are only comparable within a shard; `seq_no` is+ /// global.+ pub fn seq_no_at(&self, pos: usize) -> u64 {+ self.docs.get(pos).map_or(u64::MAX, |e| e.seq_no)+ }++ /// `(seq_no, doc_id)` for the first `n` buffered documents, stopping early+ /// once an entry's `seq_no` exceeds `cutoff`.+ ///+ /// #191 — `docs` is append-ordered and `remove` preserves that order, so a+ /// shard's entries ascend by `seq_no`: once one entry is past the caller's+ /// running cap-th key, so is every entry after it, and neither needs its+ /// `doc_id` cloned. That early break is what keeps the per-shard bound+ /// (which replaced a greedy "fill from shard 0" walk) from multiplying the+ /// id clones by the shard count.+ pub fn ranked_ids_up_to(&self, n: usize, cutoff: u64) -> Vec<(u64, String)> {+ let mut out = Vec::new();+ for e in self.docs.iter().take(n) {+ if e.seq_no > cutoff {+ break;+ }+ out.push((e.seq_no, e.doc_id.clone()));+ }+ out+ }+/// Resolve a MemEntry's source Value — if `source` is Null but/// `source_bytes` is non-empty, lazily parse the bytes. This is/// the M5.11 deferred-parse path used by `insert_raw_bytes_with_seq`.@@ -2709,6 +2857,14 @@ impl FtsMemtable {.collect()}+ /// `seq_no`-carrying twin of [`Self::all_docs_with_sources_arc`] (#191).+ pub fn all_docs_with_seq_arc(&self) -> Vec<(u64, String, Arc<Value>)> {+ self.docs+ .iter()+ .map(|e| (e.seq_no, e.doc_id.clone(), Self::resolve_source_arc(e)))+ .collect()+ }+/// Return the full original source JSON for a document by ID./// O(1) doc lookup via `doc_id_index` (maintained by every insert //// remove path), with a linear-scan fallback in case an entry is everdiff --git a/engine/crates/xerj-engine/tests/tied_score_page_order.rs b/engine/crates/xerj-engine/tests/tied_score_page_order.rsindex 7b248ba81..6101dd730 100644--- a/engine/crates/xerj-engine/tests/tied_score_page_order.rs+++ b/engine/crates/xerj-engine/tests/tied_score_page_order.rs@@ -214,21 +214,35 @@ async fn tie_straddling_a_page_boundary_resolves_the_same_way_at_every_size() {/// The same property with an UNFLUSHED tail — the shape a live index is in/// between flushes, and the one a paginating client hits most often.///-/// The corpus is deliberately larger than the collector's 256-hit floor-/// (`materialisation_limit = (from + size + 100).max(256)`; the `from + size`-/// narrowing applies only to an EMPTY memtable, so a mixed fixture always-/// pays the floor plus 100 hits of slack). A smaller mixed fixture proves-/// nothing at all: the whole corpus fits under the cap, the bounded collector-/// never truncates, and every page agrees trivially.+/// Sizing this fixture takes two conditions at once, and an earlier revision+/// of this test met neither. With `materialisation_limit = (from + size ++/// 100).max(256)` and the flushed documents arriving FIRST (so they own the+/// low `seq_no`s and the head of every page):///-/// Honest scope: unlike the two tests above, this one PASSED on the pre-fix-/// engine in the runs we measured — the 100-hit slack means truncation only-/// ever reached documents past the prefixes asserted here, so the pre-fix-/// walk got away with dropping whichever segment it reached last. It earns-/// its place as a REGRESSION guard, not a reproducer: the fix changes both-/// the segment walk order and the per-segment headroom, and the memtable-/// (which seeds the collector past its cap before the first segment is even-/// opened) is where a mistake in either would surface first.+/// 1. the UNFLUSHED batch must be larger than the cap, or the memtable hands+/// up every buffered hit and its bound is never exercised; and+/// 2. some asserted page position must actually LAND on a memtable+/// document — i.e. `size` must exceed the flushed count — while (1) still+/// holds, which bounds `flushed < size < unflushed - 100`.+///+/// 40 flushed + 300 unflushed satisfies both across `size` 41…199. The+/// original 320 flushed + 40 unflushed satisfied neither: 40 buffered hits+/// never reached a 256-hit cap, so the memtable collector could not truncate,+/// and every page position asserted (`size` ≤ 359, against 320 flushed+/// documents) was answered from segments. That test passed before the fix and+/// after it, and would have kept passing however broken the memtable path+/// became. Measured on this fixture at the pre-repair commit, `size` 60, 100+/// and 150 each returned a non-prefix page for all three shapes below.+///+/// `constant_score` is deliberately NOT one of the shapes here, and that is a+/// known gap rather than an oversight: on a MIXED corpus its bounded page+/// contains only memtable documents (`size:1` returns `mem0000` where the full+/// page starts `seg0000`) because the segment walk is skipped once the+/// collector is already full. That reproduces identically before and after+/// this change — it is a separate, pre-existing defect in the segment-side+/// early-out, not the memtable bound under test here — and it is why this PR+/// says `Refs #191` rather than `Fixes #191`. The memtable-only test below+/// does cover `constant_score`, which is the path this change fixes.#[tokio::test]async fn tied_scores_page_the_same_way_with_an_unflushed_memtable() {let dir = TempDir::new().unwrap();@@ -237,8 +251,8 @@ async fn tied_scores_page_the_same_way_with_an_unflushed_memtable() {let idx = engine.get_index("mixed").unwrap();let mut inserted = Vec::new();- for batch in 0..4 {- for i in 0..80 {+ for batch in 0..2 {+ for i in 0..20u32 {let id = format!("seg{batch}{i:03}");idx.index_document(Some(id.clone()),@@ -250,8 +264,10 @@ async fn tied_scores_page_the_same_way_with_an_unflushed_memtable() {}idx.flush().await.unwrap();}- // Deliberately NOT flushed — these stay in the memtable.- for i in 0..40 {+ // Deliberately NOT flushed — these stay in the memtable, and there are+ // more of them than any cap the sizes below imply, so the memtable-side+ // bound is the thing under test.+ for i in 0..300 {let id = format!("mem{i:03}");idx.index_document(Some(id.clone()),@@ -261,7 +277,7 @@ async fn tied_scores_page_the_same_way_with_an_unflushed_memtable() {.unwrap();inserted.push(id);}- let total = inserted.len() as u64; // 360 > the 256 floor+ let total = inserted.len() as u64; // 340: 40 flushed + 300 unflushedfor (label, q) in [("match", json!({"match": {"body": "listpack"}})),@@ -276,14 +292,120 @@ async fn tied_scores_page_the_same_way_with_an_unflushed_memtable() {"{label}: an all-tied page must come back in arrival order, \segment documents before memtable ones");- // Sizes on both sides of the 256 floor.- for size in [1usize, 5, 50, 255, 256, 257, 300, 359] {+ // Every one of these implies a cap below 300, so the memtable is+ // always truncating; the ones past 40 are the ones whose page actually+ // contains buffered documents.+ for size in [1usize, 5, 41, 60, 100, 150, 199] {+ let p = idx.search(&req(0, size, &q)).await.unwrap();+ assert_eq!(+ page_ids(&p.hits),+ full_ids[..size],+ "{label}: size:{size} page disagrees with the full materialisation"+ );+ }+ }+}++/// #191's most natural reproduction, and the one the PR originally shipped+/// without: index N identical documents and page them BEFORE the flush.+///+/// Nothing here has been written to a segment, so every collector decision is+/// made on the memtable side. That side bounds its materialisation twice over+/// — the sharded memtable caps each shard's contribution, and `admit_hit!`+/// caps the merged result — and neither bound used to rank candidates by the+/// page key. A `ShardedFtsMemtable` holds 16 independent shards, a document+/// lands in one by id hash (a whole bulk batch by its FIRST id's hash), and+/// the query path walks them in INDEX order while filling a global budget.+/// So the page was "the tied documents that happen to live in the+/// lowest-numbered shards", which is neither arrival order nor stable.+///+/// Measured pre-fix, release, 600 byte-identical documents (every score bit+/// pattern `1065353216`, an exact tie), for `match`, `term`, `match_all` AND+/// `constant_score` alike:+///+/// ```text+/// size:5 → ["m0000", "m0001", "m0004", "m0005", "m0008"]+/// size:1000 → ["m0000", "m0001", "m0002", "m0003", "m0004"], …+/// ```+///+/// Each shape reaches a different memtable collector, which is why all four+/// are asserted: `match` takes the scored FTS merge, `term` the columnar+/// doc-values walk, `match_all` the bounded id list, and `constant_score` the+/// brute per-document scan.+#[tokio::test]+async fn tied_scores_page_the_same_way_with_no_flush_at_all() {+ let dir = TempDir::new().unwrap();+ let engine = make_engine(&dir);+ engine.create_index("memonly", Schema::empty()).unwrap();+ let idx = engine.get_index("memonly").unwrap();++ // Comfortably past the 256-hit floor. `size:300` implies a 400-hit cap+ // and so still truncates; `size:599` implies 699 and does not, which is+ // why the full page below is a complete materialisation to compare+ // against.+ let mut inserted = Vec::new();+ for i in 0..600 {+ let id = format!("m{i:04}");+ idx.index_document(+ Some(id.clone()),+ json!({"body": "listpack encoding", "kind": "same"}),+ )+ .await+ .unwrap();+ inserted.push(id);+ }++ for (label, q) in [+ ("match", json!({"match": {"body": "listpack"}})),+ ("term", json!({"term": {"kind": "same"}})),+ ("match_all", json!({"match_all": {}})),+ (+ "constant_score",+ json!({"constant_score": {"filter": {"match_all": {}}}}),+ ),+ ] {+ let full = idx.search(&req(0, 1000, &q)).await.unwrap();+ let full_ids = page_ids(&full.hits);+ assert_eq!(full.total.value, 600, "{label}: every doc matches");++ // The tie really is exact — otherwise the test proves nothing.+ let scores: Vec<f32> = full.hits.iter().map(|h| h.score).collect();+ assert!(+ scores.windows(2).all(|w| w[0].to_bits() == w[1].to_bits()),+ "{label}: fixture must produce an EXACT tie, got {:?}",+ &scores[..5]+ );+ assert_eq!(+ full_ids, inserted,+ "{label}: an all-tied memtable page must come back in arrival order"+ );++ // Sizes on both sides of the 256 floor. Measured pre-fix, `size` 5,+ // 50 and 300 each returned a page drawn from the low-numbered shards+ // for all four shapes; `size:1` happened to survive, because the+ // globally-first document also lived in a shard the truncated walk+ // reached.+ for size in [1usize, 2, 5, 50, 255, 256, 257, 300, 599] {let p = idx.search(&req(0, size, &q)).await.unwrap();assert_eq!(page_ids(&p.hits),full_ids[..size],"{label}: size:{size} page disagrees with the full materialisation");+ assert_eq!(+ p.total.value, 600,+ "{label}: size:{size} total must stay exact"+ );+ }++ // Paging one hit at a time reproduces the same order.+ for from in [0usize, 1, 254, 255, 256, 300] {+ let p = idx.search(&req(from, 1, &q)).await.unwrap();+ assert_eq!(+ page_ids(&p.hits),+ full_ids[from..from + 1],+ "{label}: from:{from} size:1 disagrees with the full materialisation"+ );}}}