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.

docs(search): hybrid ties are ordered by arrival (#940)

xerj-org85b5fa4ca43c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 16a4a91c7..6834fe86f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,6 +26,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
exposes the same two parameters. Raised by @Vinz2168 from a shared-memory
agent integration where neither single mode was enough.
+### Fixed
+
+- **A `hybrid` query returns the same page on every run and after a
+ restart** ([#940](https://github.com/xerj-org/xerj/issues/940)).
+ `fusion: "rrf"` and `fusion: "linear"` drained their accumulator from a
+ hash map into a score-only sort, so documents with an identical fused
+ score came back in hash-iteration order, which is seeded per process.
+ Under RRF such ties are structural (one leg's rank *r* and the other
+ leg's rank *r* score the same), and on BEIR SciFact 21 of 40 queries
+ changed their top 10 after a restart on unchanged data. Fused results now
+ use the order every score-ranked page uses since #270: score descending,
+ then arrival (`_seq_no`), then `_id`; a NaN fused score sorts last
+ instead of making the sort panic. Measured on the fixed build, lexical
+ embedder: the 300 SciFact test queries (1,509 tied adjacent pairs in
+ their top 100) returned identical result lists across a flush and two
+ restarts. The hybrid recipe's worked example was also re-run and its
+ numbers reconciled with the current engine.
+
## [1.0.0-rc.74] - 2026-09-08
### Added
diff --git a/content/answers/reciprocal-rank-fusion-when-to-use.md b/content/answers/reciprocal-rank-fusion-when-to-use.md
index 81479edca..019e54b30 100644
--- a/content/answers/reciprocal-rank-fusion-when-to-use.md
+++ b/content/answers/reciprocal-rank-fusion-when-to-use.md
@@ -35,6 +35,10 @@ faq:
a: "Use `linear` when you want one signal to dominate and the score scales are comparable. On our 8 judged queries linear scored 0.4583 against 0.4167 for `rrf`."
- q: "Does RRF find documents neither list returned?"
a: "No. Reciprocal Rank Fusion reorders the union of the input lists. On the query `car` both judged synonyms were missing from both lists and stayed missing."
+ - q: "In what order does XERJ return documents with the same fused score?"
+ a: "In arrival order. A tie is broken by the order the documents were indexed, then by `_id`, the same rule every score-ranked page uses. The page is the same on every run and after a restart."
+ - q: "Why did my hybrid results change order after a restart?"
+ a: "Before issue #940 a tied fused score followed hash-map iteration order, which changes from one process to the next. On BEIR SciFact that changed the top 10 of 21 of 40 queries. A tie is now ordered by arrival, so the order no longer changes."
- q: "Can XERJ learn the fusion weights?"
a: "No. `fusion: \"learned\"` is rejected with an HTTP 400 at parse time. XERJ offers `rrf` and `linear` only."
---
@@ -85,7 +89,11 @@ Two documents that hold mirrored positions receive the same fused score. Our cap
| `d04` | 1 → 1/61 | 2 → 1/62 | 0.0325225 | 0.032522473 |
| `d10` | deeper than rank 3 | 3 → 1/63 | 0.0312576 | 0.031257633 |
-Both tied documents carry the identical fused score in the response, and XERJ placed `d08` first.
+Both tied documents carry the identical fused score in the response, and this capture placed `d08` first. The capture predates issue #940. At that time a tie followed hash-map iteration order, so the same request could return `d04` first after a restart.
+
+A tie is now ordered by arrival. The fused score comes first, then the order the documents were indexed (`_seq_no`, the Elasticsearch `_doc` order), then `_id`. That is the same rule every score-ranked page in XERJ uses. The page is the same on every run, after a restart, and before or after a flush. Listing the sub-queries in another order does not change an equal-weight result.
+
+Ties are frequent under this rule. A document at rank r in only one list and a document at rank r in only the other list both score `weight / (k + r)`. Over the 300 BEIR SciFact test queries on the lexical default, our run of the fixed build returned 1,509 adjacent pairs with identical fused scores in the top 100. The order of all 300 result lists was identical across a flush and two restarts.
The third row is worth reading closely. The score 0.031257633 for `d10` equals 1/63 plus 1/65. Fusion therefore credited a BM25 position deeper than the 3 hits that the size-3 BM25 response showed.
diff --git a/docs/recipes/hybrid-search.md b/docs/recipes/hybrid-search.md
index 030045d29..5eaf75f7a 100644
--- a/docs/recipes/hybrid-search.md
+++ b/docs/recipes/hybrid-search.md
@@ -74,9 +74,9 @@ The user's intent in both modalities: text `"reset password"`, vector
**Pure BM25** — `{"match": {"title": "reset password"}}`:
```
-d1 score=0.5754 Reset your password
-d3 score=0.2877 Password complexity and rotation policy
-d5 score=0.2877 Change your account password
+d1 score=2.2742 Reset your password
+d5 score=0.5784 Change your account password
+d3 score=0.5300 Password complexity and rotation policy
```
It **misses d2** entirely — "Regain entry to a locked-out account" has no
@@ -124,9 +124,9 @@ Real response (trimmed to `title`, printed verbatim by the script):
"max_score": 0.03279,
"hits": [
{ "_id": "d1", "_score": 0.03279, "_source": { "title": "Reset your password" } },
- { "_id": "d5", "_score": 0.03175, "_source": { "title": "Change your account password" } },
- { "_id": "d3", "_score": 0.01613, "_source": { "title": "Password complexity and rotation policy" } },
- { "_id": "d2", "_score": 0.01613, "_source": { "title": "Regain entry to a locked-out account" } }
+ { "_id": "d5", "_score": 0.032, "_source": { "title": "Change your account password" } },
+ { "_id": "d2", "_score": 0.01613, "_source": { "title": "Regain entry to a locked-out account" } },
+ { "_id": "d3", "_score": 0.01587, "_source": { "title": "Password complexity and rotation policy" } }
]
}
}
@@ -134,10 +134,10 @@ Real response (trimmed to `title`, printed verbatim by the script):
**d2** (only kNN found it) and **d3** (only BM25 found it) are now *both*
on the page, and **d1** — the doc that matched on *both* keyword and
-vector — is still ranked #1. Watch **d5**: neither BM25 nor kNN ranks it
-better than #3, yet because *both* signals agree on it, fusion promotes
-it to **#2** — ahead of d3 and d2, each of which is strong in only one
-modality. That's the whole point: fusion rewards agreement between the
+vector — is still ranked #1. Watch **d5**: BM25 ranks it #2 and kNN
+ranks it #3 — first in neither — yet because *both* signals agree on it,
+fusion keeps it at **#2**, ahead of d2 and d3, each of which only one
+modality found. That's the whole point: fusion rewards agreement between the
two signals while still admitting the strong single-signal hits that
either method alone would have dropped.
@@ -151,15 +151,16 @@ sees it. Fusion ranks the *union* of the sub-query hits, nothing more.
`"fusion": "rrf"` uses Reciprocal Rank Fusion: each sub-query contributes
`weight / (k + rank)` for a doc (default `k = 60`, `rank` is 1-based),
summed across sub-queries. It ranks by *position*, not raw score, so
-BM25's `~0.5` scores and kNN's `~0.99` cosines never have to be
+BM25's `0.5`–`2.3` scores and kNN's `~0.99` cosines never have to be
normalized onto a common scale — a persistent headache when you fuse two
systems yourself. The scores above fall straight out of this formula:
- **d1** is rank 1 in *both* lists → `1/(60+1) + 1/(60+1) = 0.03279`.
-- **d5** is rank 3 in *both* lists → `1/63 + 1/63 = 0.03175`, still beating
- either single-list hit because two contributions stack.
-- **d3** and **d2** each appear in *one* list at rank 2 → `1/(60+2) =
- 0.01613` apiece — an exact tie.
+- **d5** is rank 2 in the BM25 list and rank 3 in the kNN list →
+ `1/62 + 1/63 = 0.03200`, still beating either single-list hit because
+ two contributions stack.
+- **d2** is rank 2 in the kNN list only → `1/(60+2) = 0.01613`.
+- **d3** is rank 3 in the BM25 list only → `1/(60+3) = 0.01587`.
Other `fusion` options:
@@ -201,19 +202,17 @@ PASS kNN alone MISSES d3 (password policy: topic vector too far)
PASS Hybrid surfaces BOTH d2 and d3 in a single query
PASS d1 (keyword + vector match) still ranks #1 under fusion
-BM25 ids : ['d1', 'd3', 'd5']
+BM25 ids : ['d1', 'd5', 'd3']
kNN ids : ['d1', 'd2', 'd5']
Hybrid ids: ['d1', 'd5', 'd2', 'd3']
OK
```
-The four assertions and the scores are deterministic; the BM25 and kNN
-id lists are stable, and the hybrid list always starts `['d1', 'd5', …]`.
-The **only** run-to-run wobble is the last two ids — **d3 and d2 tie at
-exactly `0.01613`**, so they swap freely between positions #3 and #4
-(across a dozen runs we saw both `d2, d3` and `d3, d2`). The recipe's
-point — that d2 and d3 both appear and d1 stays #1 — holds every time.
+The four assertions, the scores and all three id lists are
+deterministic: the same request returns the same page on every run and
+after a restart. That holds for tied scores too — see the note on ties
+below.
## Notes & limits
@@ -224,12 +223,19 @@ point — that d2 and d3 both appear and d1 stays #1 — holds every time.
- **Score scales differ by fusion.** RRF returns small fused scores
(`0.016–0.033` here) — compare docs *within* a response, not against
BM25/cosine absolutes.
-- **Tie ordering is not guaranteed** for docs with identical fused scores.
- d3 and d2 both score exactly `0.01613` here (each is a single rank-2 hit
- in one sub-query), and they genuinely swap between positions #3 and #4
- from one run to the next — we observed both orders across a dozen runs.
- Set membership — the point of this recipe — is stable; the order *among
- exact ties* is not.
+- **Tied fused scores are ordered by arrival.** Under RRF ties are
+ common: a document found only by one leg at rank *r* and a document
+ found only by the other leg at rank *r* score exactly the same
+ (`1/(k+r)` each), and so do two documents at swapped ranks (1,2) and
+ (2,1). XERJ orders a tie the way it orders every score-ranked page:
+ fused `_score` descending, then the order the documents were indexed
+ (`_seq_no`, the ES `_doc` order), then `_id`. The page is the same on
+ every run and after a restart, whether the documents are still in
+ memory or already flushed, so `from`/`size` paging does not skip or
+ repeat a document at a page boundary, and listing the legs in another
+ order does not reorder an equal-weight request. Before
+ [#940](https://github.com/xerj-org/xerj/issues/940) a tie followed
+ hash-map iteration order, which changed from one process to the next.
- **Vector quality is your embeddings' job.** This recipe supplies
vectors directly for a deterministic demo. For real semantic recall,
generate `dense_vector` values with a production embedding model, or
diff --git a/landing/answers/reciprocal-rank-fusion-when-to-use.html b/landing/answers/reciprocal-rank-fusion-when-to-use.html
index bcfb5639f..99e918e2b 100644
--- a/landing/answers/reciprocal-rank-fusion-when-to-use.html
+++ b/landing/answers/reciprocal-rank-fusion-when-to-use.html
@@ -296,7 +296,9 @@
<tr><td><code class="inline">d10</code></td><td>deeper than rank 3</td><td>3 → 1/63</td><td>0.0312576</td><td>0.031257633</td></tr>
</tbody>
</table>
- <p>Both tied documents carry the identical fused score in the response, and XERJ placed <code class="inline">d08</code> first.</p>
+ <p>Both tied documents carry the identical fused score in the response, and this capture placed <code class="inline">d08</code> first. The capture predates issue #940. At that time a tie followed hash-map iteration order, so the same request could return <code class="inline">d04</code> first after a restart.</p>
+ <p>A tie is now ordered by arrival. The fused score comes first, then the order the documents were indexed (<code class="inline">_seq_no</code>, the Elasticsearch <code class="inline">_doc</code> order), then <code class="inline">_id</code>. That is the same rule every score-ranked page in XERJ uses. The page is the same on every run, after a restart, and before or after a flush. Listing the sub-queries in another order does not change an equal-weight result.</p>
+ <p>Ties are frequent under this rule. A document at rank r in only one list and a document at rank r in only the other list both score <code class="inline">weight / (k + r)</code>. Over the 300 BEIR SciFact test queries on the lexical default, our run of the fixed build returned 1,509 adjacent pairs with identical fused scores in the top 100. The order of all 300 result lists was identical across a flush and two restarts.</p>
<p>The third row is worth reading closely. The score 0.031257633 for <code class="inline">d10</code> equals 1/63 plus 1/65. Fusion therefore credited a BM25 position deeper than the 3 hits that the size-3 BM25 response showed.</p>
<h2>When Reciprocal Rank Fusion helps</h2>
<p>Reciprocal Rank Fusion helps when the two lists disagree and both are partly right. On the restart question, BM25 alone put an irrelevant document first and kNN alone put a judged-relevant document first. The fused list kept the judged-relevant document in position 1.</p>
@@ -321,6 +323,10 @@
<p>Use <code class="inline">linear</code> when you want one signal to dominate and the score scales are comparable. On our 8 judged queries linear scored 0.4583 against 0.4167 for <code class="inline">rrf</code>.</p>
<h3>Does RRF find documents neither list returned?</h3>
<p>No. Reciprocal Rank Fusion reorders the union of the input lists. On the query <code class="inline">car</code> both judged synonyms were missing from both lists and stayed missing.</p>
+ <h3>In what order does XERJ return documents with the same fused score?</h3>
+ <p>In arrival order. A tie is broken by the order the documents were indexed, then by <code class="inline">_id</code>, the same rule every score-ranked page uses. The page is the same on every run and after a restart.</p>
+ <h3>Why did my hybrid results change order after a restart?</h3>
+ <p>Before issue #940 a tied fused score followed hash-map iteration order, which changes from one process to the next. On BEIR SciFact that changed the top 10 of 21 of 40 queries. A tie is now ordered by arrival, so the order no longer changes.</p>
<h3>Can XERJ learn the fusion weights?</h3>
<p>No. <code class="inline">fusion: "learned"</code> is rejected with an HTTP 400 at parse time. XERJ offers <code class="inline">rrf</code> and <code class="inline">linear</code> only.</p>
<h2>Related</h2>
diff --git a/landing/answers/reciprocal-rank-fusion-when-to-use.md b/landing/answers/reciprocal-rank-fusion-when-to-use.md
index d733b3bab..c7f4ef7c5 100644
--- a/landing/answers/reciprocal-rank-fusion-when-to-use.md
+++ b/landing/answers/reciprocal-rank-fusion-when-to-use.md
@@ -94,7 +94,11 @@ Two documents that hold mirrored positions receive the same fused score. Our cap
| `d04` | 1 → 1/61 | 2 → 1/62 | 0.0325225 | 0.032522473 |
| `d10` | deeper than rank 3 | 3 → 1/63 | 0.0312576 | 0.031257633 |
-Both tied documents carry the identical fused score in the response, and XERJ placed `d08` first.
+Both tied documents carry the identical fused score in the response, and this capture placed `d08` first. The capture predates issue #940. At that time a tie followed hash-map iteration order, so the same request could return `d04` first after a restart.
+
+A tie is now ordered by arrival. The fused score comes first, then the order the documents were indexed (`_seq_no`, the Elasticsearch `_doc` order), then `_id`. That is the same rule every score-ranked page in XERJ uses. The page is the same on every run, after a restart, and before or after a flush. Listing the sub-queries in another order does not change an equal-weight result.
+
+Ties are frequent under this rule. A document at rank r in only one list and a document at rank r in only the other list both score `weight / (k + r)`. Over the 300 BEIR SciFact test queries on the lexical default, our run of the fixed build returned 1,509 adjacent pairs with identical fused scores in the top 100. The order of all 300 result lists was identical across a flush and two restarts.
The third row is worth reading closely. The score 0.031257633 for `d10` equals 1/63 plus 1/65. Fusion therefore credited a BM25 position deeper than the 3 hits that the size-3 BM25 response showed.
@@ -144,6 +148,14 @@ Use `linear` when you want one signal to dominate and the score scales are compa
No. Reciprocal Rank Fusion reorders the union of the input lists. On the query `car` both judged synonyms were missing from both lists and stayed missing.
+### In what order does XERJ return documents with the same fused score?
+
+In arrival order. A tie is broken by the order the documents were indexed, then by `_id`, the same rule every score-ranked page uses. The page is the same on every run and after a restart.
+
+### Why did my hybrid results change order after a restart?
+
+Before issue #940 a tied fused score followed hash-map iteration order, which changes from one process to the next. On BEIR SciFact that changed the top 10 of 21 of 40 queries. A tie is now ordered by arrival, so the order no longer changes.
+
### Can XERJ learn the fusion weights?
No. `fusion: "learned"` is rejected with an HTTP 400 at parse time. XERJ offers `rrf` and `linear` only.
diff --git a/landing/docs/recipes/hybrid-search.html b/landing/docs/recipes/hybrid-search.html
index c4fa4a3fc..923ffcc00 100644
--- a/landing/docs/recipes/hybrid-search.html
+++ b/landing/docs/recipes/hybrid-search.html
@@ -265,9 +265,9 @@
<h3>3. Watch each modality fail on its own</h3>
<p><strong>Pure BM25</strong> — <code class="inline">{"match": {"title": "reset password"}}</code>:</p>
-<pre class="code">d1 score=0.5754 Reset your password
-d3 score=0.2877 Password complexity and rotation policy
-d5 score=0.2877 Change your account password</pre>
+<pre class="code">d1 score=2.2742 Reset your password
+d5 score=0.5784 Change your account password
+d3 score=0.5300 Password complexity and rotation policy</pre>
<p>It <strong>misses d2</strong> entirely — "Regain entry to a locked-out account" has no shared keywords, so it can never be a BM25 hit.</p>
<p><strong>Pure kNN</strong> — <code class="inline">{"knn": {"field": "vec", "query_vector": [...], "k": 3}}</code>, showing the 3 nearest:</p>
<pre class="code">d1 score=0.9994 Reset your password
@@ -298,21 +298,22 @@ d5 score=0.9942 Change your account password</pre>
"max_score": 0.03279,
"hits": [
{ "_id": "d1", "_score": 0.03279, "_source": { "title": "Reset your password" } },
- { "_id": "d5", "_score": 0.03175, "_source": { "title": "Change your account password" } },
- { "_id": "d3", "_score": 0.01613, "_source": { "title": "Password complexity and rotation policy" } },
- { "_id": "d2", "_score": 0.01613, "_source": { "title": "Regain entry to a locked-out account" } }
+ { "_id": "d5", "_score": 0.032, "_source": { "title": "Change your account password" } },
+ { "_id": "d2", "_score": 0.01613, "_source": { "title": "Regain entry to a locked-out account" } },
+ { "_id": "d3", "_score": 0.01587, "_source": { "title": "Password complexity and rotation policy" } }
]
}
}</pre>
- <p><strong>d2</strong> (only kNN found it) and <strong>d3</strong> (only BM25 found it) are now <em>both</em> on the page, and <strong>d1</strong> — the doc that matched on <em>both</em> keyword and vector — is still ranked #1. Watch <strong>d5</strong>: neither BM25 nor kNN ranks it better than #3, yet because <em>both</em> signals agree on it, fusion promotes it to <strong>#2</strong> — ahead of d3 and d2, each of which is strong in only one modality. That's the whole point: fusion rewards agreement between the two signals while still admitting the strong single-signal hits that either method alone would have dropped.</p>
+ <p><strong>d2</strong> (only kNN found it) and <strong>d3</strong> (only BM25 found it) are now <em>both</em> on the page, and <strong>d1</strong> — the doc that matched on <em>both</em> keyword and vector — is still ranked #1. Watch <strong>d5</strong>: BM25 ranks it #2 and kNN ranks it #3 — first in neither — yet because <em>both</em> signals agree on it, fusion keeps it at <strong>#2</strong>, ahead of d2 and d3, each of which only one modality found. That's the whole point: fusion rewards agreement between the two signals while still admitting the strong single-signal hits that either method alone would have dropped.</p>
<p>Only <strong>four</strong> docs come back, not five: d4 ("How to bake sourdough bread") is in <em>neither</em> sub-query's result set — it shares no keywords and its topic vector falls outside the kNN <code class="inline">k:3</code> cutoff — so RRF never sees it. Fusion ranks the <em>union</em> of the sub-query hits, nothing more.</p>
<h2>How the fusion works</h2>
- <p><code class="inline">"fusion": "rrf"</code> uses Reciprocal Rank Fusion: each sub-query contributes <code class="inline">weight / (k + rank)</code> for a doc (default <code class="inline">k = 60</code>, <code class="inline">rank</code> is 1-based), summed across sub-queries. It ranks by <em>position</em>, not raw score, so BM25's <code class="inline">~0.5</code> scores and kNN's <code class="inline">~0.99</code> cosines never have to be normalized onto a common scale — a persistent headache when you fuse two systems yourself. The scores above fall straight out of this formula:</p>
+ <p><code class="inline">"fusion": "rrf"</code> uses Reciprocal Rank Fusion: each sub-query contributes <code class="inline">weight / (k + rank)</code> for a doc (default <code class="inline">k = 60</code>, <code class="inline">rank</code> is 1-based), summed across sub-queries. It ranks by <em>position</em>, not raw score, so BM25's <code class="inline">0.5</code>–<code class="inline">2.3</code> scores and kNN's <code class="inline">~0.99</code> cosines never have to be normalized onto a common scale — a persistent headache when you fuse two systems yourself. The scores above fall straight out of this formula:</p>
<ul>
<li><strong>d1</strong> is rank 1 in <em>both</em> lists → <code class="inline">1/(60+1) + 1/(60+1) = 0.03279</code>.</li>
- <li><strong>d5</strong> is rank 3 in <em>both</em> lists → <code class="inline">1/63 + 1/63 = 0.03175</code>, still beating either single-list hit because two contributions stack.</li>
- <li><strong>d3</strong> and <strong>d2</strong> each appear in <em>one</em> list at rank 2 → <code class="inline">1/(60+2) = 0.01613</code> apiece — an exact tie.</li>
+ <li><strong>d5</strong> is rank 2 in the BM25 list and rank 3 in the kNN list → <code class="inline">1/62 + 1/63 = 0.03200</code>, still beating either single-list hit because two contributions stack.</li>
+ <li><strong>d2</strong> is rank 2 in the kNN list only → <code class="inline">1/(60+2) = 0.01613</code>.</li>
+ <li><strong>d3</strong> is rank 3 in the BM25 list only → <code class="inline">1/(60+3) = 0.01587</code>.</li>
</ul>
<p>Other <code class="inline">fusion</code> options:</p>
<ul>
@@ -338,19 +339,19 @@ PASS kNN alone MISSES d3 (password policy: topic vector too far)
PASS Hybrid surfaces BOTH d2 and d3 in a single query
PASS d1 (keyword + vector match) still ranks #1 under fusion
-BM25 ids : ['d1', 'd3', 'd5']
+BM25 ids : ['d1', 'd5', 'd3']
kNN ids : ['d1', 'd2', 'd5']
Hybrid ids: ['d1', 'd5', 'd2', 'd3']
OK</pre>
- <p>The four assertions and the scores are deterministic; the BM25 and kNN id lists are stable, and the hybrid list always starts <code class="inline">['d1', 'd5', …]</code>. The <strong>only</strong> run-to-run wobble is the last two ids — <strong>d3 and d2 tie at exactly <code class="inline">0.01613</code></strong>, so they swap freely between positions #3 and #4 (across a dozen runs we saw both <code class="inline">d2, d3</code> and <code class="inline">d3, d2</code>). The recipe's point — that d2 and d3 both appear and d1 stays #1 — holds every time.</p>
+ <p>The four assertions, the scores and all three id lists are deterministic: the same request returns the same page on every run and after a restart. That holds for tied scores too — see the note on ties below.</p>
<p>See the full runnable example — <a href="https://github.com/xerj-org/xerj/blob/main/docs/examples/hybrid-search/hybrid_search.py">docs/examples/hybrid-search/hybrid_search.py</a> on GitHub.</p>
<h2>Notes &amp; limits</h2>
<ul>
<li><strong><code class="inline">knn</code> in a query scores every doc that has the field</strong>, ranked by cosine; <code class="inline">size</code> (or <code class="inline">from</code>+<code class="inline">size</code>) is the cutoff the user sees. So <code class="inline">k:3</code> plus <code class="inline">size:3</code> means "show the 3 nearest." For a hard candidate cap independent of <code class="inline">size</code>, keep <code class="inline">k</code> small — it's carried on the sub-query.</li>
<li><strong>Score scales differ by fusion.</strong> RRF returns small fused scores (<code class="inline">0.016–0.033</code> here) — compare docs <em>within</em> a response, not against BM25/cosine absolutes.</li>
- <li><strong>Tie ordering is not guaranteed</strong> for docs with identical fused scores. d3 and d2 both score exactly <code class="inline">0.01613</code> here (each is a single rank-2 hit in one sub-query), and they genuinely swap between positions #3 and #4 from one run to the next — we observed both orders across a dozen runs. Set membership — the point of this recipe — is stable; the order <em>among exact ties</em> is not.</li>
+ <li><strong>Tied fused scores are ordered by arrival.</strong> Under RRF ties are common: a document found only by one leg at rank <em>r</em> and a document found only by the other leg at rank <em>r</em> score exactly the same (<code class="inline">1/(k+r)</code> each), and so do two documents at swapped ranks (1,2) and (2,1). XERJ orders a tie the way it orders every score-ranked page: fused <code class="inline">_score</code> descending, then the order the documents were indexed (<code class="inline">_seq_no</code>, the ES <code class="inline">_doc</code> order), then <code class="inline">_id</code>. The page is the same on every run and after a restart, whether the documents are still in memory or already flushed, so <code class="inline">from</code>/<code class="inline">size</code> paging does not skip or repeat a document at a page boundary, and listing the legs in another order does not reorder an equal-weight request. Before <a href="https://github.com/xerj-org/xerj/issues/940">#940</a> a tie followed hash-map iteration order, which changed from one process to the next.</li>
<li><strong>Vector quality is your embeddings' job.</strong> This recipe supplies vectors directly for a deterministic demo. For real semantic recall, generate <code class="inline">dense_vector</code> values with a production embedding model, or use a <code class="inline">semantic_text</code> field with an external <code class="inline">inference_id</code>.</li>
</ul>