RescoreTopNQuery lets deleted documents take top-n slots, and IndexSearcher#count counts them

RescoreTopNQuery re-scores every match of an inner query with a DoubleValuesSource and keeps the best n. It collects those matches in rewrite straight from the inner Scorer, which by contract does not apply live docs, and neither of its two collection loops checks them. A deleted document that is still in its segment therefore competes for the n slots and can take one: the search returns fewer than n hits, or the wrong ones, and IndexSearcher#count counts the deleted document through the rewritten query's count shortcut. In the repro, 4 matches with the best one deleted and n=2 give [2] instead of [2, 1] and a count of 2, with no error. A kNN inner query is not affected; inner queries whose scorers return deleted documents are, including through the documented hybrid-search factory createLateInteractionQuery (TermQuery and MatchAllDocsQuery inner queries were run; boolean, range and other ordinary queries take the same two loops, read but not run). It has been in every release since the class was added in 10.3.0.

• Deleted but not merged away: deleteDocuments or updateDocument only clears the document's bit in its segment's live docs. Postings and scorers still return the document until a merge rewrites the segment; searches skip it because IndexSearcher hands the live docs to the bulk scorer (IndexSearcher.java:851-852).
• RescoreTopNQuery(query, valuesSource, n) (@lucene.experimental): runs query, re-scores each match with valuesSource, keeps the top n, and rewrites itself into a DocAndScoreQuery that matches exactly those n documents with their new scores.

1. rewrite (RescoreTopNQuery.java:68-88) creates the inner Weight (:72) and a HitQueue of size n (:73), then collects candidates in rescoreInline (:90-107, value sources that need scores) or rescoreWithPrefetch (:123-157, all others).
2. Both loops iterate weight.scorer(leaf).iterator() (:100-104, :139-149) and insert every document into the queue (rescoreInto, :221-228). Neither reads leaf.reader().getLiveDocs(), although Weight#scorer says: "The returned Scorer does not have LeafReader#getLiveDocs() applied, they need to be checked on top." (Weight.java:121-122).
3. A deleted document with a competitive value takes a queue slot and pushes out a live match.
4. The queue becomes a DocAndScoreQuery (:87). Searching it applies live docs again (IndexSearcher.java:851-852), so the deleted entry is dropped and fewer than n hits come back.
5. IndexSearcher#count uses Weight#count when it is not -1 (TotalHitCountCollector.java:47-52), and DocAndScoreQuery returns the number of stored entries (DocAndScoreQuery.java:192-195), deleted ones included, against "Counts the number of live documents that match" (Weight.java:182).

That count shortcut is correct for kNN, whose rewrite builds its candidates from live docs only (AbstractKnnVectorQuery.java:250-253).

One segment; docs 0 to m-1 match f:a (m = 4 unless the row says otherwise) with v = doc id; one more doc does not match. Main ea57360912ed:

A stage-by-stage probe of the first case: the inner iterator returns [0, 1, 2, 3(deleted)], the rewrite keeps docs 3 and 2, search returns [2], count returns 2. With a KnnFloatVectorQuery as the inner query the same index gives [2, 1] and 2. Independent verifiers also reproduced it through createLateInteractionQuery and createFullPrecisionRescorerQuery over a TermQuery, with the default IndexWriterConfig and an NRT reader after updateDocument, and in a randomized multi-segment check against a brute-force oracle (4 of 6 iterations mismatched).

• Who is exposed. Callers of RescoreTopNQuery with a non-kNN inner query, directly or through createLateInteractionQuery or createFullPrecisionRescorerQuery. createLateInteractionQuery is documented for exactly this: it "computes late interaction field similarity for the entire match-set of wrapped query ... This is typically useful in combining a query's results with other queries for hybrid search" (RescoreTopNQuery.java:310-313).
• Not exposed. A kNN inner query, the use the class was written for: its rewrite keeps only live docs. Run for KnnFloatVectorQuery; the other kNN queries share that rewrite (AbstractKnnVectorQuery.java:250-268, read but not run).
• Default settings. Ordinary deletes and updates, the default IndexWriterConfig, an NRT or a committed reader. Deletions are normal state: the default TieredMergePolicy works toward a target of at most 20% deleted documents as part of its merge selection (deletesPctAllowed = 20.0), so deletions routinely stay in segments until a merge rewrites them. RescoreTopNQuery itself is opt-in and @lucene.experimental.
• When. Whenever a deleted match would rank inside the top n by the rescore value; no scale is needed. How often that happens depends on the workload and was not measured. A merge that expunges the deletion makes it go away, so results can change after a background merge.
• What you see. No error. Fewer than n hits or a wrong top n, and an IndexSearcher#count higher than the number of hits by the number of deleted documents kept (at most n), even when the hits are right.
• Downstream. A code search found no use of RescoreTopNQuery in the main code of Elasticsearch, OpenSearch or Solr; the users found (an open Solr PR, neo4j, nrtsearch, zuliasearch, luceneutil) all wrap a kNN query. 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:<[2[, 1]] count=2> but was:<[2[]] count=2>
       org.junit.Assert.assertEquals(Assert.java:117)
       org.junit.Assert.assertEquals(Assert.java:146)
       org.apache.lucene.search.TestRescoreTopNDeletedDocs.testDeletedDocTakesTopNSlot(TestRescoreTopNDeletedDocs.java:53)

• The contracts. Class javadoc (RescoreTopNQuery.java:26-35): "re-scores another Query ... and cut-off the results at top N ... it can work with any type of Query". createLateInteractionQuery (:310-313): rescoring "the entire match-set of wrapped query ... for hybrid search". 10.3.0 CHANGES (GITHUB#14009, CHANGES.txt:1562-1563): "a new Query that can rescore other Query based on a generic DoubleValueSource and trim the results down to top N". Weight#scorer (Weight.java:121-122): live docs "need to be checked on top". Weight#count (Weight.java:182): "Counts the number of live documents that match".
• Lucene's own count shortcuts respect deletions. TermQuery's count returns docFreq only when the segment has no deletions and otherwise falls back (TermQuery.java:255-267).
• Made generic on purpose. In the #14009 review, vigyasharma asked whether it could be generalized "to rerank any query"; dungba88 replied "I changed the query to be generic" and later "API-wise there would be no such limitation". No comment in #14009, #14860, #14729, #16628 or #16705 mentions deletions or live docs.
• Untested case. The four upstream test classes never delete a document, and every functional test wraps a kNN query.
• Precedent. LUCENE-10040 (#11078), "Handle deletions in nearest vector search", fixed the same omission in the kNN rewrite in 2021.

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 class was designed to rerank kNN shortlists (#14009 is titled "Add Query for reranking KnnFloatVectorQuery with full-precision vectors", and a review comment says it "only applies to vector search queries right now, but in spirit is generic to all approx search queries"), and kNN rewrites already keep only live docs; the class is @lucene.experimental; n is documented as "the number of documents to find", so fewer than n hits could be read as allowed; and DocAndScoreQuery#count is correct for the input it is given.

Why it fails: the merged javadoc, the CHANGES entry and the PR author all say any query, and the late-interaction factory documents a non-kNN use over the whole match set; Weight#scorer puts the live-docs check on the caller, and RescoreTopNQuery is that caller (that note alone is not decisive, since some consumers such as QueryBitSetProducer deliberately see deleted documents; the query's documented meaning and the Weight#count contract are); more than n live matches exist and a deleted one displaces them, which the kNN rewrite avoids by collecting live docs only; IndexSearcher#count breaks the Weight#count contract outright (count 1 with 0 hits); and @lucene.experimental marks an unstable API, not permission to return wrong results. Every reviewer rated the intended argument weak. Verdict: a defect.

The two loops must apply the live docs that Weight#scorer leaves to its caller, and rewrite must cope with an empty result. One option was built and validated in a scratch worktree at ea57360912ed (removed afterwards); the others are untested.

In rescoreInline and rescoreWithPrefetch, read leaf.reader().getLiveDocs() once per segment and skip documents whose bit is clear, before the prefetch and the value read. After collection, return new MatchNoDocsQuery() when the queue is empty, as AbstractKnnVectorQuery does (AbstractKnnVectorQuery.java:153-155). +12 lines, RescoreTopNQuery.java only.

Bits liveDocs = leaf.reader().getLiveDocs();
while (iterator.nextDoc() != DocIdSetIterator.NO_MORE_DOCS) {
  int docId = iterator.docID();
  if (liveDocs != null && liveDocs.get(docId) == false) {
    continue; // deleted (or hidden) documents never become candidates
  }
  ... // unchanged: prefetch / rescoreInto
}

// in rewrite, after collection
if (queue.size() == 0) {
  return new MatchNoDocsQuery();
}

Trade-offs

• The guard is required. DocAndScoreQuery.createDocAndScoreQuery needs a non-empty topK (assert len > 0, then topK.scoreDocs[0], DocAndScoreQuery.java:123-125). With the live-docs skip alone, "every match is deleted" becomes an AssertionError (assertions on) or an ArrayIndexOutOfBoundsException (off) instead of a wrong count.
• Side effect, welcome but separate. The guard also stops the stock throw when the inner query matches nothing at all; a comment on apache/solr#4919 already reports that throw.
• Cost. At most one Bits.get per inner match, and only on segments with a live-docs mask (getLiveDocs() != null); elsewhere a null check. Deleted documents no longer cost a prefetch or a value read. No benchmark was run.
• Deprecated constructor. The guard uses the no-argument new MatchNoDocsQuery(), which is @Deprecated (MatchNoDocsQuery.java:39-40); :lucene:core:check -x test passed with it. For upstream, pass a reason as AbstractKnnVectorQuery does, for example new MatchNoDocsQuery("no live document matched the inner query"); that one-line change was not re-run.
• Informational count. The "visited" count handed to DocAndScoreQuery (originalCount) now counts live matches only.
• Rebase. Open draft #16847 (long doc ids) touches both files.

What the checks validated

• Stock: the test fails 4 of 5 through gradle with assertions on and with -Ptests.asserts=false.
• Patched, assertions on: TestRescoreTopN* (with the new test and the empty-inner probe), TestFilterReadersForwardVectorPrefetch, TestKnnFloatVectorQuery, TestKnnByteVectorQuery and *LateInteraction*: 11 classes, 109 tests, 0 failures, 2 skipped (@Nightly).
• Patched, assertions off: the same minus the two kNN query suites: 9 classes, 26 tests, 0 failures, 2 skipped (@Nightly). Patched with -Ptests.nightly=true: TestRescoreTopNQuery 6 of 6 pass.
• :lucene:core:check -x test passes (google-java-format, ecjLint, forbiddenApis); tidy did not change the fix.
• Standalone harness with the patched class: 5 of 5 pass with assertions on and off. With both parts, the getLiveDocs-masking probe passes 4 of 4, and a fact check re-ran the finder's, the verifiers' and the cross-model reviewers' tests with assertions on and off: all pass (finder 3/3, the independent reproduction 8/8, the intended-behaviour check 3/3 and its all-deleted probe 1/1, the reviewers 3/3 each). The earlier hunt runs of those tests used the finder's live-docs skip without the guard; the empty-result probes of the independent reproduction and the intended-behaviour check failed with it, which is why the guard was added.

Replace the Scorer#iterator loops by weight.bulkScorer(leaf).score(collector, liveDocs, 0, DocIdSetIterator.NO_MORE_DOCS) with a small LeafCollector that feeds the prefetch ring or the queue, the way IndexSearcher applies live docs.

Trade-offs

Keeps the accept-docs rule in one place and lets the inner query use its bulk scorer, but it is a larger change: the inline path needs the Scorable from setScorer for score-dependent value sources, and the prefetch ring must be driven from collect. Still needs the empty-queue guard and a null check on weight.bulkScorer(leaf), and it does not touch the separate SCORES observation (the inner weight is still created with COMPLETE_NO_SCORES).

Make the count honour live docs, or return -1 for segments with deletions, as TermQuery does.

Trade-offs

Fixes IndexSearcher#count only: the deleted document still takes a top-n slot, so the search still returns fewer than n hits or the wrong ones. DocAndScoreQuery.createDocAndScoreQuery is public, so any caller passing non-live documents gets the same count; the only in-tree callers are AbstractKnnVectorQuery (live documents only) and RescoreTopNQuery, so the issue is best scoped to RescoreTopNQuery.

State that the inner query must already exclude deleted documents.

Trade-offs

Contradicts the class javadoc ("any type of Query"), the CHANGES entry and the documented hybrid use of createLateInteractionQuery, and leaves the Weight#count contract broken.

Method: code reading (the hunt's non-formal tier).

• A hunt unit (2026-10-25) set out to show that every Weight#count returns -1 or the exact number of live matches, and that TotalHits never claims EQUAL_TO for a wrong count. Its plan listed Weight, TermQuery, PointRangeQuery, BooleanWeight, FieldExistsQuery, TotalHits, the total-hits collectors, IndexSearcher and IndexSortSortedNumericDocValuesRangeQuery; it did not name RescoreTopNQuery or DocAndScoreQuery.
• The finder, an AI tool, checked the BooleanWeight#count algebra with Z3 in bounded scopes (8 mutants killed) and bounded-exhaustively on the stock jar, and ran 240,000 differential count checks over random indexes with deletions; none of these covered this query.
• Separately it audited every Weight#count override and TotalHits producer by reading code. DocAndScoreQuery#count, fed by RescoreTopNQuery's rewrite, stood out; a JUnit on the stock jar then showed both the wrong top n and the wrong count.
• 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.