RescoreTopNQuery runs its inner query without scores, so a score-reading source gets no real score

RescoreTopNQuery(query, valuesSource, n) re-scores every match of query with valuesSource at rewrite time and keeps the best n. For a source whose needsScores() is true (DoubleValuesSource.SCORES, an expression such as _score * popularity, or a custom source) the class deliberately feeds the inner scorer's score into the source, but it creates the inner Weight with ScoreMode.COMPLETE_NO_SCORES, a mode in which "scores won't be available". What the source then reads depends on the inner query. A term query, or a boolean of term queries, gives 0: every rescored value is computed from 0, all matches tie, and the top n are simply the first n matches by doc id, so body:common OR body:rare rescored by SCORES with n=1 gives doc 0 at 0.0 instead of doc 9 at 0.90565. A phrase query gives 1.0 for every match, in the same doc-id order. A kNN inner query keeps its scores until the query cache's policy decides to cache the non-scoring inner query; from then on (the 5th identical search with UsageTrackingQueryCachingPolicy) the caching wrapper returns a constant score of 0 and the top 3 of 10 neighbours become the 3 lowest doc ids. In a hybrid kNN OR term inner query the term part of the score is lost. A normal IndexSearcher raises no error. The built-in full-precision vector and late-interaction sources do not read scores and are not affected. Every executed release since the class was added (10.3.0 to 10.5.2) and main have it; the fix is one conditional statement.

• RescoreTopNQuery(query, valuesSource, n) (@lucene.experimental, since 10.3.0): at rewrite time it runs query, computes valuesSource for every match, keeps the top n and rewrites itself into a DocAndScoreQuery holding those n documents and their new scores.
• Score-reading source: a DoubleValuesSource whose needsScores() is true, such as DoubleValuesSource.SCORES ("exposes a document's score"), an expression that binds _score, or a custom source. It receives the current match's score through DoubleValuesSource.fromScorer.
• Score mode: what a Weight must produce. COMPLETE visits every match with its score; COMPLETE_NO_SCORES visits every match "but scores won't be available" (ScoreMode.java:25-26).

1. rewrite (RescoreTopNQuery.java:68-88) always creates the inner Weight with indexSearcher.createWeight(rewritten, ScoreMode.COMPLETE_NO_SCORES, 1.0f) (:72).
2. A source with needsScores() true takes rescoreInline (:74-79; the comment says such a source "reads the inner scorer's score"), which hands it DoubleValuesSource.fromScorer(innerScorer) (:99, :230-236).
3. What score() returns on a non-scoring Weight is up to the query; COMPLETE_NO_SCORES promises no particular value. A non-scoring TermWeight uses a dummy SimScorer that returns 0f and is "not expected to be called since scores are not needed" (TermQuery.java:77-92); a boolean of terms reads 0 as well. A non-scoring PhraseWeight uses one that returns 1 (PhraseWeight.java:46-51). A kNN query rewrites to DocAndScoreQuery, which returns its stored scores in any mode (DocAndScoreQuery.java:244-245).
4. Every value goes into a size-n HitQueue (:221-228). When all values are equal (0 for term queries, 1.0 for a phrase query), the tie-break keeps the lower doc id (HitQueue.java:76-82): the top n are the first n matches in doc-id order.
5. kNN: IndexSearcher.createWeight puts only non-scoring Weights in the query cache (IndexSearcher.java:979-981); DocAndScoreQuery is cacheable (DocAndScoreQuery.java:273-275) and equal across repeats of the same kNN query on the same reader (:294-307). UsageTrackingQueryCachingPolicy caches a query at its 5th use (UsageTrackingQueryCachingPolicy.java:122-137), and on that very call LRUQueryCache returns ConstantScoreScorerSupplier(0f, ...) (LRUQueryCache.java:837-846). From the 5th search on every score is 0, while the entry stays in the cache for that reader (until eviction, clearQuery or clear, a new reader, or a replaced or disabled cache). Before the policy is asked, the cache also checks that the inner query is cacheable on the segment and that the index passes a worst-case size check (LRUQueryCache.java:792-807, :816); the lead-cost check at :850 only decides whether the entry is filled, and the scorer returns 0 either way.
6. On main IndexSearcher has no default cache (#14187, IndexSearcher.java:82-84), so the kNN form needs a cache the application sets; on 10.x the default LRUQueryCache caches segments of 10,000 or more documents (10.5.2 IndexSearcher.java:95-100, LRUQueryCache.java:167-177). A fully default 10.5.2 searcher, with no cache or policy set, flips at the 5th search too (executed by the fact check); the repro sets an explicit cache with the same caps and policy.

Main ea57360912ed, one segment. Lexical: docs 0-8 body = "common", doc 9 body = "rare"; plain search: doc 9 at 0.90565, docs 0-8 at 0.06663794. kNN: 12,000 docs with vector [1, i] (EUCLIDEAN), the 10 nearest to [1, 11999].

With the fix every row gives the expected result.

• Who is exposed. Callers of RescoreTopNQuery with a source whose needsScores() is true: DoubleValuesSource.SCORES, an expression that reads _score (for example "boost the text score by popularity and keep the top n for a later stage"), or a custom source.
• Term inner queries and booleans of them: wrong on every search, with any configuration (the source reads 0). A phrase inner query reads 1.0 for every match; other query types get whatever their non-scoring scorer returns.
• kNN inner queries: wrong once the query cache's policy caches the inner query: the 5th identical search with UsageTrackingQueryCachingPolicy; the 1st with an always-cache policy and a cache that accepts small segments. On 10.x IndexSearcher's default cache applies to segments of 10,000 or more documents (a fully default 10.5.2 searcher flips at the 5th search, executed); on main the cache is opt-in.
• Hybrid (kNN OR text): the text part of the score is lost on every search (run without a cache).
• Not exposed. The built-in factories createFullPrecisionRescorerQuery (float vectors, and on main also FLOAT16) and createLateInteractionQuery: their sources do not need scores. They are what the class was designed for and its only callers in Lucene's own code; how common each use is elsewhere is not known.
• Default settings. RescoreTopNQuery is opt-in and @lucene.experimental; nothing else needs a non-default setting: the lexical probe uses a default IndexWriterConfig (default codec, BM25) and a plain IndexSearcher, and a fully default 10.5.2 searcher shows the kNN form. No scale is needed for the lexical case (10 documents, n=1).
• What you see. No error with a normal IndexSearcher (the test framework's asserting searcher fails). Rescored scores of 0.0 (1.0 for a phrase inner query; 0 + something for a custom source: a score + 1 source returned 1.0) and, for a source that reads only the score, a top n that is the first n matches by doc id. The hits are always drawn from the inner query's matches. An application that applies a minimum score afterwards loses hits. For kNN, results depend on earlier identical searches that share the cache.
• Downstream. Known code users (neo4j, nrtsearch, zuliasearch, luceneutil, a Go port, an open Solr PR) use sources that do not read scores; a code search found no RescoreTopNQuery in the Elasticsearch, OpenSearch or Solr default branches. That fits the absence of reports, and says nothing about private code.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => org.junit.ComparisonFailure: expected:<[1:0.109832264]> but was:<[0:0.0]>
       org.junit.Assert.assertEquals(Assert.java:117)
       org.junit.Assert.assertEquals(Assert.java:146)
       org.apache.lucene.search.TestRescoreTopNQueryScoresSource.testScoresSourceSeesInnerScore(TestRescoreTopNQueryScoresSource.java:49)

• The contracts. Class javadoc (RescoreTopNQuery.java:26-31): "A Query that re-scores another Query with a DoubleValuesSource function and cut-off the results at top N ... it can work with any type of Query"; the constructor takes a generic DoubleValuesSource (:58). 10.3.0 CHANGES (CHANGES.txt:1562-1563): "rescore other Query based on a generic DoubleValueSource". DoubleValuesSource (DoubleValuesSource.java:43-46): "Scores may be used as a source for value calculations by wrapping a Scorer using fromScorer ... accessed using the SCORES DoubleValuesSource". ScoreMode.COMPLETE_NO_SCORES (ScoreMode.java:25): "scores won't be available".
• The class wires the score in on purpose. getDoubleValues passes fromScorer(innerScorer) exactly when the source needs scores (:230-236, since #14009), and #16705 added the inline path whose comment says such a source "reads the inner scorer's score" (:74-75).
• The rest of Lucene asks for scores. FunctionScoreQuery.createWeight uses COMPLETE when the outer search scores and its source needs scores, and skips the source when the outer search does not score (FunctionScoreQuery.java:109-122), so whenever it computes a score-reading source its inner Weight scores; TestFunctionScoreQuery.testScoreMode asserts COMPLETE for SCORES under a scoring outer search (:318-322). TestDoubleValuesSource picks vs.needsScores() ? COMPLETE : COMPLETE_NO_SCORES (:310-312). RescoreTopNQuery always computes its source, so the matching rule there is COMPLETE whenever the source needs scores.
• The test framework enforces it. AssertingWeight sets canScore = scoreMode.needsScores() and AssertingScorer.score() asserts it (AssertingWeight.java:74, AssertingScorer.java:125-126, LUCENE-6526). The finder's AssertingIndexSearcher probe fails there, called from RescoreTopNQuery.rescoreInline; the independent reproducer's own asserting probe fails the same way on main and passes with the fix.
• Untested case. Every upstream RescoreTopNQuery test uses sources that do not need scores. No PR thread (#14009, #14729, #16628, #16656, #16705) discusses the inner score mode; #16705 and #16656 describe the inline path as needed because fromScorer reads the scorer's current score.

The strongest case for "intended" (built by a devil's-advocate verifier and by an OpenAI GPT-5.6 reviewer arguing "works as designed"): the javadoc says "Unlike or FunctionScoreQuery, this Query will work even with the no-scoring ScoreMode" (:31-32, sic); the class is @lucene.experimental and was built for kNN reranking, where DocAndScoreQuery returns real scores in any mode; a non-scoring inner Weight skips similarity work and can be cached, a real optimization; and since LUCENE-6329 calling score() without scores is safe, so 0 could be read as an unspecified placeholder.

Why it fails: in the #14009 review the author, dungba88, explained that sentence (2025-06-13): "it does not depend on the score mode (FunctionScoreQuery will be a no-op if needsScores = false) and it also trim down the results to N. ... The nuance is important in cases where we don't need the overall score (using ConstantScoreQuery) but still want to rescore and trim down results in some sub-Query (like KnnFloatVectorQuery). It's heavily influenced by KnnFloatVectorQuery but API-wise there would be no such limitation." So the sentence is about the outer search, and the class was meant for any inner query. The comment does not discuss sources that read scores; their support comes from the code and the DoubleValuesSource contract: two sets of authors routed the inner score into these sources. LUCENE-6329 made such calls safe, not meaningful, and LUCENE-6526 added assertions that they do not happen; @lucene.experimental marks an unstable API, not permission to return wrong results; the optimization survives the fix for sources that do not read scores; and no javadoc, CHANGES or MIGRATE text restricts the source. Every reviewer rated the intended argument weak. Verdict: a defect.

The inner Weight must produce scores whenever the source reads them, whatever the outer search's score mode, because RescoreTopNQuery always computes the source at rewrite time. One option was built and validated in a scratch worktree at ea57360912ed (removed afterwards); the others are untested.

In rewrite, replace the fixed ScoreMode.COMPLETE_NO_SCORES at RescoreTopNQuery.java:72 by COMPLETE when valuesSource.needsScores(), whatever the outer search's score mode: unlike FunctionScoreQuery, which skips its source when the outer search does not score, RescoreTopNQuery always computes the source. COMPLETE, not TOP_SCORES, because the rewrite visits every match. +4/-1 lines, RescoreTopNQuery.java only.

// A value source that reads the inner query's score needs a Weight that produces scores.
ScoreMode innerScoreMode =
    valuesSource.needsScores() ? ScoreMode.COMPLETE : ScoreMode.COMPLETE_NO_SCORES;
Weight weight = indexSearcher.createWeight(rewritten, innerScoreMode, 1.0f);

Trade-offs

• The fast path stays. Sources that do not need scores (the built-in vector and late-interaction ones) keep COMPLETE_NO_SCORES, the prefetch path and query caching.
• Cost. Score-reading sources now pay for real scoring (for example BM25 per match), which is what they ask for. No benchmark was run.
• No caching for score-reading sources. IndexSearcher caches only non-scoring Weights, so their inner Weight is no longer cached; with the fix the probe showed the cache was never consulted and every search was right. The cached path could only ever return 0 scores, so nothing correct is lost.
• Nit (the adjudication's). rewrittenValueSource.needsScores() would be slightly more precise than valuesSource.needsScores(); the existing branch and getDoubleValues use valuesSource, so they differ only for a source whose rewrite changes needsScores(). See option B.
• Rebase. Open draft #16847 (long doc ids) edits this file but not this line.

What the checks validated

• Stock: the test fails 2 of 2 through gradle with assertions on, off and -Ptests.nightly=true, and 10 of 10 over 5 iterations of a second seed.
• Patched, assertions on and off: TestRescoreTopN* (with the new test), TestFilterReadersForwardVectorPrefetch, *LateInteraction* and TestDoubleValuesSource: 9 classes, 33 tests, 0 failures, 2 skipped (@Nightly) each.
• Patched, -Ptests.nightly=true: TestRescoreTopNQuery (with its 2 @Nightly tests) and the new test: 8 of 8. Patched, -Ptests.seed=5EED1234 -Ptests.iters=5: 10 of 10.
• Formatting: :lucene:core:tidy ran and succeeded (its log does not show whether it edited anything); :lucene:core:check -x test passes (google-java-format, ecjLint, forbiddenApis); google-java-format 1.37.0 --dry-run reports no change for the patched file or the test.
• Standalone harness with the patched class: 2 of 2 pass on main (assertions on and off); the same change on the 10.x file passes on 10.5.2 and 10.3.0. Earlier hunt runs of the same change: the independent reproducer's 7-test JUnit 7 of 7 (also on the adjudication's re-run with a new seed), its asserting-searcher probe, the security probe 4 of 4, and the finder's TestRescoreTopNQuery + TestRescoreTopNQueryPrefetch run 7 of 7. A phrase-query probe: with the fix the rescored phrase scores equal the plain ones.

Compute boolean needsScores = rewrittenValueSource.needsScores() once in rewrite and use it for the score mode, the inline/prefetch branch and getDoubleValues.

Trade-offs

Same behaviour for every in-tree source; more robust for a custom source whose rewrite changes needsScores(). A slightly larger diff (getDoubleValues reads the field valuesSource today).

Throw IllegalArgumentException in the constructor for a source whose needsScores() is true, or document that such sources are unsupported.

Trade-offs

Contradicts the generic DoubleValuesSource contract and the class's own inline path for these sources (#16705), and removes a natural use: combining the first-stage score with a field value, then keeping the top n.

Method: semi-formal (bounded translation validation, then a public-API JUnit).

• A hunt unit (2026-10-26) checks that Lucene's rescoring paths (RescoreTopNQuery, QueryRescorer, DoubleValuesSourceRescorer) compute what an independent reference computes, by bounded-exhaustive and random comparison on the stock jar.
• While writing the model, the finder, an AI tool, noticed that rewrite sends score-reading sources down a path that reads the inner score, yet creates the inner Weight with COMPLETE_NO_SCORES.
• The harness's RTN-scores scope then compared RescoreTopNQuery with a reference built from the inner query's COMPLETE-mode scores: all 586 non-empty trials of 600 differ, for an array-backed score-reading source and for DoubleValuesSource.SCORES, with assertions on and off (example: expected [0:0.89166296], actual [0:0.0]).
• A follow-up probe found the kNN form (right for 4 searches, then 0 once the query cache caches the inner Weight), and a public-API JUnit on the stock jars confirmed both.
• An independent reviewer from another model family (OpenAI GPT-5.6) then tried to refute it, verifiers and an adjudication confirmed it, and the history, prior-report and security checks followed.