RescoreTopNQuery passes negative values through as negative scores, so a top-k BooleanQuery that ORs it with another clause returns no hits

RescoreTopNQuery (experimental, new in 10.3.0) rescores another query's matches with a DoubleValuesSource and keeps the top n. It stores each value as the score as it is, so a negative value becomes a negative score and a negative max score, although Lucene requires non-negative scores (LUCENE-7996) and FunctionScoreQuery maps negative values to 0. When the query is a SHOULD clause of a top-k BooleanQuery, MaxScoreBulkScorer starts with a minimum competitive score of 0; if the clauses' max scores add up to less than 0, it treats every clause as non-essential and skips the window, and here every window of the segment. One document with v = -2, OR MatchAllDocsQuery: search(q, 10) returns 0 hits while count(q) is 1, with no error, default configuration, assertions on or off, in every release from 10.3.0 to 10.6.0 and on main.

1. RescoreTopNQuery.rewrite fills a HitQueue of size n through rescoreInto and returns DocAndScoreQuery.createDocAndScoreQuery(reader, topDocs, 0) (RescoreTopNQuery.java:68-91).
2. rescoreInto inserts new ScoreDoc(docBase + docId, (float) values.doubleValue()) with no clamp; only a missing value becomes 0 (:224-231). The value -2 becomes the score -2.
3. DocAndScoreQuery takes maxScore = topK.scoreDocs[0].score (DocAndScoreQuery.java:125) and reports it from getMaxScore (:239-240): -2.
4. search(q, 10) collects with ScoreMode.TOP_SCORES, and for two SHOULD clauses BooleanScorerSupplier builds a MaxScoreBulkScorer (BooleanScorerSupplier.java:315-328), whose minimum competitive score starts at 0 (SimpleScorable.java:24).
5. partitionScorers marks clauses non-essential while their running max-score sum stays below that threshold (MaxScoreBulkScorer.java:494-511): -2 < 0, then -2 + 1 = -1 < 0. Every clause is non-essential, it returns false (:515-516), and the window is skipped as "No matches in this window" (:133-137). The max score is the same for every window, so the whole segment is skipped.

• One document, v = -2: count(q) = 1, search(q, 10) = 0 hits, totalHits 0. Collected exhaustively (TopScoreDocCollectorManager(10, Integer.MAX_VALUE)), the same query returns the document with score -1.0.
• 10 documents, v = -2 to -11: 0 of 10 hits, while exhaustive collection returns all 10 (nine at +1.0).
• A hybrid query, TermQuery OR RescoreTopNQuery(same TermQuery, fromLongField("v"), 1), 3 matching documents with v = -2, -3, -4: 0 of 3 hits.
• Expressions as the source: -age and ln(age / 100000) give 0 of 10 hits.
• Two segments, {-2, -3} and {-5, -6}, n = 1: 2 of 4 hits. Only the segment that holds the kept document loses its hits; a segment without one has no scorer for the rescored clause (DocAndScoreQuery.java:198-200).
• n > 1 with mixed signs, OR MatchAllDocsQuery: values {5, -2} with n = 2 give 0 of 2 hits, {5, 3, -2} with n = 3 give 0 of 3; with n = 2 the -2 is not kept and all 3 are returned. The clause's max score is the first entry of the kept set in heap order, its lowest value.

• If the max-score sum is still at or above 0 (for example a constant -1 OR MatchAllDocsQuery), the search reaches ScorerUtil.minRequiredScore at a threshold of 0 and, with assertions off, never returns; with assertions on it throws AssertionError "All clauses are essential if minCompetitiveScore is equal to zero". That loop is a separate bug with its own fix site (LFV-1016).
• With minimumNumberShouldMatch 2 over three SHOULD clauses, WANDScorer throws IllegalArgumentException "Scores must be positive or null" (WANDScorer.java:69-71).
• The query alone, or as a MUST or FILTER clause, returns the right hits, with negative scores.

• Who is hit. Callers of RescoreTopNQuery with a non-vector values source that can be negative, used as a SHOULD clause of a top-k BooleanQuery. With n = 1 the kept value has to be negative; with n > 1 one negative value among the n kept documents is enough, because the clause's max score is scoreDocs[0].score (DocAndScoreQuery.java:125) and rewrite fills scoreDocs in heap order (RescoreTopNQuery.java:83-87), so it is the lowest kept value: values {5, -2} with n = 2 give 0 of 2 hits. That is the use the class was built for: the #14009 author described "a hybrid search where KnnFloatVectorQuery and TermQuery (amongst others) are combined into a single BooleanQuery", and the late-interaction factory's javadoc says it is "typically useful in combining a query's results with other queries for hybrid search" (RescoreTopNQuery.java:313-315).
• Who is not. The built-in vector-similarity sources (full precision, float16, late interaction) are non-negative by construction. The query alone, or as a MUST or FILTER clause, returns the right hits.
• Default vs opt-in. Default IndexWriterConfig, codec and IndexSearcher; the trigger is the opt-in, @lucene.experimental query (RescoreTopNQuery.java:34) with a non-vector source.
• Scale. In a single-segment index every matching document disappears; in the tested two-segment index the segment that holds the kept document loses both its hits, and totalHits is wrong too. In general a window is skipped when its clauses' max scores add up to less than the minimum competitive score; at 0 or more, the separate LFV-1016 loop applies instead. No exception or warning, assertions on or off.
• How likely. Rare: every public user of the query that was found uses vector similarities. The failure does not depend on chance: the same index and query give 0 hits every time (10 of 10 derived seeds).

The test indexes one document with NumericDocValuesField("v", -2) in a ByteBuffersDirectory and runs search(q, 10) with q = SHOULD RescoreTopNQuery(MatchAllDocsQuery.INSTANCE, DoubleValuesSource.fromLongField("v"), 1) + SHOULD MatchAllDocsQuery.INSTANCE. Deterministic, single thread, no random data (it failed on 10 of 10 derived seeds). It uses a plain IndexSearcher on purpose, to keep it deterministic: through newSearcher the test still fails, but the randomized searcher sometimes takes another scorer path (in 200 seeds with -ea, 198 returned 0 hits and 2 threw IllegalArgumentException "Scores must be positive or null" from WANDScorer; no AssertionError, because no score is computed). On 10.3.x replace MatchAllDocsQuery.INSTANCE with new MatchAllDocsQuery() (the constant first appears in 10.4.0); that port fails the same way.

TestRescoreTopNQueryNegativeValues > testDisjunctionReturnsAllMatches FAILED
    java.lang.AssertionError: expected:<1> but was:<0>
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:45D837F95F0A64BE]:0)
        at org.junit.Assert.fail(Assert.java:89)
        at org.junit.Assert.failNotEquals(Assert.java:835)
        at org.junit.Assert.assertEquals(Assert.java:647)
        at org.junit.Assert.assertEquals(Assert.java:633)
        at org.apache.lucene.search.TestRescoreTopNQueryNegativeValues.testDisjunctionReturnsAllMatches(TestRescoreTopNQueryNegativeValues.java:47)
1 test completed, 1 failed

# the same with -Ptests.asserts=false; with the recommended fix the test passes

• The rule. lucene/CHANGES.txt:6636: "LUCENE-7996: Queries are now required to produce positive scores." lucene/MIGRATE.md:1368-1375: "Scorers are no longer allowed to produce negative scores" and "FunctionScoreQuery maps negative values to 0." The test framework asserts it (AssertingScorer.java:131): with AssertingIndexSearcher and -ea, the rescored clause alone fails with AssertionError: -2.0.
• Lucene clamps caller-supplied values itself. FunctionScoreQuery maps a negative value or NaN to 0 (FunctionScoreQuery.java:243-251), and TestFunctionScoreQuery.testTruncateNegativeScores (:236-253) checks it on one document with NumericDocValuesField("foo", -2) and fromLongField. In the LUCENE-7996 thread (#9044) romseygeek asked "could we just set the score to 0?", and jpountz answered with a patch: "New patch that maps negative scores to 0. The explanation says when this happens so that this change is not too trappy." In the same disjunction, FunctionScoreQuery over the same source returns the hit.
• The class invites this use. Its javadoc says it re-scores "with a DoubleValuesSource function", "can work with any type of Query" and compares it with FunctionScoreQuery (RescoreTopNQuery.java:26-32); the constructor checks only n >= 1 (:58-61); CHANGES calls the source "generic" (CHANGES.txt:1595-1596); hybrid use is advertised (:313-315).
• Two collections disagree. Exhaustive collection returns the document, top-k returns nothing; CheckHits.doCheckTopScores requires them to be equal (CheckHits.java:700-709).
• History. Earlier built-in negative-score paths were fixed as bugs: #11184, #12342 / #12727, #13356, #16139. The upstream RescoreTopNQuery tests use constant(0), SCORES over a kNN query's scores and vector similarities, so no test value is negative, and they never put the query in a BooleanQuery; no comment on #14009 or #16926 discusses value ranges.

The strongest case for "works as designed": the class is experimental and was built to rescore vector shortlists, whose similarities are non-negative; MIGRATE.md tells authors of custom queries to keep "their score formula" non-negative, so a negative values source is the caller's mistake; and negative values carry ranking information (for example -distance), so passing them through is a choice.

Why it fails: RescoreTopNQuery is Lucene's own query, and the caller only passes a values source through a public constructor; for that exact shape LUCENE-7996 chose to clamp inside Lucene; the query is advertised for generic sources and hybrid use, where sorting by the function instead is not an option; nothing documents or checks the precondition; and the failure is silent and far from its cause. Even if negative values are declared illegal, the silent 0-hit result needs a check or a clamp. The ranking point is real, which is why the recommended fix keeps the selection on the raw values. Verdict: not intended, a defect.

Options A and B were applied in a scratch worktree of 645d4fe14a20 and run with gradle (the worktree was removed after the runs). Options C and D were not built. Whichever is chosen removes this query as a trigger of a separate ScorerUtil.minRequiredScore loop (LFV-1016) but does not fix that loop.

+5 lines in RescoreTopNQuery.rewrite, in the loop that copies the queue into scoreDocs (RescoreTopNQuery.java:83-87): a kept document whose value is not above 0 gets score 0.

for (ScoreDoc topDoc : queue) {
  // The top n are chosen by raw value, but scores must not be negative (LUCENE-7996): like
  // FunctionScoreQuery, report negative values and NaN as 0
  if ((topDoc.score > 0) == false) {
    topDoc.score = 0;
  }
  scoreDocs[i++] = topDoc;
}

Trade-offs

• Keeps the documented meaning (the top n of the values source) and meets the non-negative rule; the max score handed to DocAndScoreQuery can no longer be negative. > 0 also maps -0.0 and NaN to +0.
• Kept documents with negative values all score 0, so their relative order no longer shows in the combined score (as with FunctionScoreQuery). NaN values, which Float.compare orders above every number in the HitQueue, are still kept first, then reported as 0.
• Cost: one branch per kept document, outside the per-candidate loop. No benchmark was run.

What the checks validated

• Gradle, stock 645d4fe14a20: the repro fails with assertions on and off.
• Gradle with the fix (seed DEADBEEF): the repro, the selection probe below and TestRescoreTopNQuery, TestRescoreTopNQueryPrefetch, TestRescoreTopNQueryFloat16Prefetch, TestFilterReadersForwardVectorPrefetch and TestKnnFloatVectorQuery: 7 classes, 58 tests (56 of them upstream), 0 failures, 2 @Nightly skipped. With assertions off, the repro and the TestRescoreTopNQuery* suites: 10 tests, 0 failures. TestRescoreTopNQuery with -Ptests.nightly=true: 7 of 7 pass. checkGoogleJavaFormat passes.
• Shadowed into the stock main jars: the two-segment probe returns 4 of 4 hits, and a 7-case control probe (including the hybrid TermQuery case) passes 7 of 7.
• A selection probe (v = -4, -3, -2, n = 1) keeps doc 2, the best value, with score 0.0.
• n > 1 with mixed signs (values {5, -2}, n = 2; {5, 3, -2}, n = 3), shadowed: every document is returned.

In rescoreInto (RescoreTopNQuery.java:224-231): value >= 0 ? (float) value : 0f.

if (values.advanceExact(docId)) {
  double value = values.doubleValue();
  // Scores must not be negative (LUCENE-7996): like FunctionScoreQuery, map negative values and
  // NaN to 0
  queue.insertWithOverflow(new ScoreDoc(docBase + docId, value >= 0 ? (float) value : 0f));
} else {
  queue.insertWithOverflow(new ScoreDoc(docBase + docId, 0f));
}

Trade-offs

• Mirrors FunctionScoreQuery line for line, and also fixes the repro.
• All negative values tie at 0 before the top n are chosen, so the HitQueue keeps the lowest doc ids instead of the best values: with v = -4, -3, -2 and n = 1 it keeps doc 0 (the worst value) where stock and option B keep doc 2. A -distance rescore would keep arbitrary documents. -0.0 passes through.

What the checks validated

Gradle: the repro, the selection probe and the TestRescoreTopNQuery* suites, 11 tests, 0 failures, 2 @Nightly skipped. The hunt's earlier checks validated it too (with the upstream TestRescoreTopNQuery* tests, 7 run, 0 failed).

Throw during rewrite when a value is below 0 (or NaN), and document the range on the constructor.

Trade-offs

Loud and explicit, but breaks callers whose sources are legitimately negative (log-probabilities, -distance) and who only need the selection. A maintainer may still prefer it for an experimental API.

The factory has been public on main and branch_11x since #16686 (DocAndScoreQuery.java:121-125; package-private on branch_10_6); a check there covers every producer at once.

Trade-offs

Changes a public factory's contract and does not apply to 10.x as it is; the kNN producers already emit non-negative scores.

Method: non-formal (sibling analysis of an upstream fix plus executed probes; the finder tagged it semi-formal; this page classes it by the first signal).

• Hunt planners read upstream fix #16926 (empty inner results, 2026-10-28) and listed the other inputs RescoreTopNQuery never checks. For negative values an executed public-API probe on main 645d4fe14a20 showed both 0 hits and a hang.
• An AI finder reduced it to a JUnit and ran a differential harness on the stock jars: 39 value producers x 10 BooleanQuery shapes x 2 indexes x k in {1, 10}, 1,560 cases, with termination, hit count and the exhaustive top k as the oracle. Result: 94 hangs, 128 zero-hit results, 56 IllegalArgumentExceptions and 392 cases with negative scores only; all 520 non-negative controls pass, and with the clamp all 1,440 RescoreTopNQuery cases pass. An SMT check (Z3 and cvc5) covered the sibling minRequiredScore loop.
• The 0-hit disjunction was then reduced to the one-document test. So this is a find from targeted probing, confirmed by execution, not a blind discovery by a tool.