8000 fix(engine): hybrid total reports Eq at the exact per_query_topk boundary (#594) by xerj-org · Pull Request #617 · xerj-org/xerj · GitHub
[go: up one dir, main page]

Skip to content

fix(engine): hybrid total reports Eq at the exact per_query_topk boundary (#594) - #617

Merged
xerj-org merged 1 commit into
mainfrom
fix/594-hybrid-total-boundary-eq
Aug 22, 2026
Merged

xerj-org merged 1 commit into
mainfrom
fix/594-hybrid-total-boundary-eq

Conversation

@xerj-org
Copy link
Copy Markdown
Owner

What

The #569 capped→gte fix tripped fused_count_capped on sub_result.hits.len() >= per_query_topk. A hybrid sub-leg with exactly per_query_topk real matches (and none beyond) fills a full page, so the fused total was reported relation: gte even though it is exactly known — where ES reports eq. The value was always correct and "≥ value" held (safe direction), so this was a mild precision regression, deferred from #593 as NON_BLOCKING.

Fix (index.rs, 3 hunks)

  1. Fetch per_query_topk + 1 per leg as a probe.
  2. Trip capped only when a leg returned > per_query_topk hits (the probe found a (per_query_topk+1)th match), or its own exact total exceeds the cap, or its own count is already a lower bound.
  3. Trim the probe hit back to per_query_topk before fusion, so the fused ranking and the returned page are byte-identical — only total.relation at the exact boundary changes.

A leg with exactly per_query_topk matches returns per_query_topk hits → not capped → Eq, restoring ES parity at the boundary.

Verification (rustc 1.97.1)

  • Both hunks load-bearing: without the +1 probe the > check would falsely report Eq for a genuinely-capped leg (the 256-doc test); without > the boundary reports Gte (the new 50-doc test).
  • Fail-before: reverting >→>= flips the new hybrid_reports_eq_at_the_exact_per_query_topk_boundary test to TotalHits { value: 50, relation: Gte }.
  • hybrid/fusion queries report a fusion-depth-capped hits.total as relation:eq (false exact count) #569 tests unchanged (256-doc → Gte, 6-doc → Eq).
  • fmt --all --check ✓ (exit-checked), clippy --workspace --all-targets -- -D warnings ✓, full cargo test -p xerj-engine → 1044 passed / 0 failed.

Closes #594.

@cl
8000
a-bot cla-bot Bot added the cla-signed label Aug 22, 2026
@xerj-org
Copy link
Copy Markdown
Owner Author

Verification — 3 skeptics, verdicts verbatim (HEAD 62303a3). 3/3 NON_BLOCKING — but reworking on the evidence lens's finding.

correctness — NON_BLOCKING

All 3 hybrid_reports tests pass. Ranking/page byte-identical (probe trimmed before fusion). Capped leg still Gte (256→51 hits→>50). Boundary correct (exactly-50→Eq value 50). Fail-before verified (reverting the hunks → Gte value 50). Strict boundary-only precision refinement.

regression — NON_BLOCKING

diff = exactly index.rs (+76/-7). Full suite EXIT=0, 1044 passed / 0 failed. #569 tests unchanged (256→Gte, 6→Eq). truncate(per_query_topk) restores the exact pre-change list before fusion → pagination unaffected. One extra hit/leg, trimmed; no measurable regression.

evidence — NON_BLOCKING (with a finding)

Fail-before #1 (core fix) CONFIRMED load-bearing: reverting >→>= flips the boundary test to Gte value 50. Fail-before #2 FALSIFIED — the +1 probe is NOT load-bearing: reverting only saturating_add(1)→per_query_topk keeps the 256-doc capped test passing (still Gte), because total.value >= hits.len() always, so the OR'd sub_result.total.value > per_query_topk already trips on a capped leg regardless of the probe. Hunks 1 (+1 fetch) and 3 (trim) are redundant belt-and-suspenders; the commit-message claim overstates them. Behavior is correct; recommend dropping hunks 1+3 or fixing the rationale — does not block merge.

Action: the evidence lens is right. Rather than ship redundant code + a misleading claim, I'm simplifying to the minimal load-bearing change (fix the boundary over-trigger; rely on the leg's own total.value/relation for capping — the alternative the issue itself offered) and rewriting the commit rationale to match. Re-verifying the simplified revision.

…dary (#594)

The #569 capped→`gte` fix tripped `fused_count_capped` on
`sub_result.hits.len() >= per_query_topk`. A hybrid sub-leg with EXACTLY
`per_query_topk` real matches (and none beyond) fills a full page, so that arm
reported `relation: gte` even though the fused total is exactly known — where
ES reports `eq`. The `value` was always correct and "≥ value" held (safe
direction), so it was a mild precision regression, deferred from #593 as
NON_BLOCKING.

The leg's own `total.value` / `total.relation` is the load-bearing capping
signal, and it is already consulted here (`total.value > per_query_topk ||
relation == Gte`, from #569): a genuinely-capped leg has `total.value >
per_query_topk` (or `Gte`), while a leg with exactly `per_query_topk` matches
reports `total.value == per_query_topk` with `Eq`. So the only defect was the
`hits.len() >= per_query_topk` arm over-triggering at the boundary. Change it to
`> per_query_topk`: a full page no longer implies capped, and the exact-boundary
leg stays `Eq`, restoring ES parity. (This is the "consult each leg's exact
total.value" alternative the issue itself offered — no over-fetch needed.)

The `hits.len() > per_query_topk` arm is now a cheap defensive guard: it never
fires for `size == per_query_topk` (a leg cannot return more than requested),
but it catches any future leg that over-returns without a matching total. Since
`total.value >= hits.len()` always, it is subsumed by the `total.value` arm for
every real leg — an earlier revision's extra `per_query_topk + 1` probe fetch
(+ trim) was therefore redundant and has been dropped.

Fail-before: reverting the capped check `>` → `>=` flips the new
`hybrid_reports_eq_at_the_exact_per_query_topk_boundary` test (50 docs, kNN
k=256) to `TotalHits { value: 50, relation: Gte }`. The #569 tests are unchanged
(256-doc → Gte via `total.value`, 6-doc → Eq). Full `cargo test -p xerj-engine`
green.

Closes #594.
@xerj-org
Copy link
Copy Markdown
Owner Author

Round-2 verification (SIMPLIFIED revision e2bf5d7) — 3 skeptics, 8000 verdicts verbatim. 3/3 NON_BLOCKING.

correctness — NON_BLOCKING

Diff = one-line >=→> on the hits.len() arm + the new boundary test; #569 tests untouched. With fetch size: per_query_topk, the hits.len() > per_query_topk arm is dead (a leg can't return more than requested) — capping rests on total.value > per_query_topk || relation == Gte, which is size-independent (FTS/term count all matches into total.value or Gte; kNN bounded by k). No leg undercounts total.value while claiming Eq. All 3 hybrid tests green; fail-before flips ONLY the boundary test to Gte value 50. No refutation.

evidence / fail-before — NON_BLOCKING

One changed line; fetch per_query_topk, no +1. Fail-before proven on 1.97.1: >→>= → new test TotalHits { value: 50, relation: Gte }; restore → Eq/50. Test non-vacuous (50 docs = per_query_topk, kNN k=256, total.value==50 Eq). #569 capped test (256→Gte) carried by total.value > per_query_topk, NOT any probe — confirms total.value is the real signal and the dropped +1 probe was genuinely redundant. Commit rationale is accurate (names total.value load-bearing; probe removed). No remnant anywhere.

regression — NON_BLOCKING

Diff = exactly index.rs (+70/-5). Full cargo test -p xerj-engine exit 0: 1044 passed, 0 failed, 23 ignored. #569 tests pass (256→Gte, 6→Eq); new boundary test passes (50→Eq). Fetch size: per_query_topk, no saturating_add(1)/truncate in the run_hybrid region. total.value >= hits.len() invariant → any genuinely-capped leg still trips condition 2/3, so relaxing >=→> only changes the exact boundary. No under-report path introduced.

Gate: 3/3 NON_BLOCKING. Merging on all-checks-green + CLEAN.

@xerj-org
xerj-org merged commit 073b08d into main Aug 22, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

hybrid total: exact-boundary reports gte where eq is possible (fetch per_query_topk+1 to disambiguate)

1 participant

0