FunctionScoreQuery's max score is 0 when it wraps a TermQuery, so a BooleanQuery around it can skip the best hit

FunctionScoreQuery(q, DoubleValuesSource.fromLongField(f)) scores each match of q by the value of f; its score() is the value times the boost and never reads q's score. Since #16431 (main, 2026-08-22) its scorer also reports a per-block maximum score so that top-k search can skip blocks, computed as innerMaxScore * valueMaxScore * boost. Because the field source does not need scores, the wrapped query was weighted with COMPLETE_NO_SCORES, and a TermQuery weighted that way reports a max score of 0. So on a field with a doc-values skip index every block with a finite bound claims 0, and a BooleanQuery that uses the function query as a scoring clause can stop scoring the documents only that clause makes competitive: in the repro, search(query, 1) returns doc 0 (4.6875415) instead of doc 4999 (100). No released version is affected.

• Block-max pruning. For top-k search, each scoring clause reports, for a range of documents, the highest score any of them can have (Scorer#getMaxScore). Once the collector knows the k-th best score so far, the searcher skips ranges whose bounds cannot beat it, without scoring their documents.
• Skip index. NumericDocValuesField.indexedField(name, value) adds a doc-values skip index: the minimum and maximum value per interval of documents. #16431 uses it to bound FunctionScoreQuery's scores per block.
• Unscored wrapped query. FunctionScoreQuery needs its wrapped query only to pick the matching documents when the value source does not read scores, so it creates the wrapped query's weight with ScoreMode.COMPLETE_NO_SCORES ("scores won't be available").

1. createWeight weights the wrapped query with COMPLETE_NO_SCORES unless the caller and the source both need scores (FunctionScoreQuery.java:109-117). Every field source (fromLongField, fromIntField, fromFloatField, fromDoubleField, fromField) does not need scores.
2. A TermQuery weighted that way gets a dummy SimScorer that returns 0f, "not expected to be called since scores are not needed" (TermQuery.java:77-91). Its max score is 0.0.
3. score() returns (float) (value * boost) for a non-negative value, else 0 (FunctionScoreQuery.java:243-252). The wrapped score is never read.
4. getMaxScore(upTo) returns innerMaxScore * valueMaxScore * boost with innerMaxScore = in.getMaxScore(upTo) (:262-269). valueMaxScore is the skip index's maximum for the range (1.0 for docs 0-4998, 100.0 for doc 4999 in the repro), so the bound is 0.0 for both ranges, i.e. wherever the skip index gives a finite bound (a range past the current interval gets +Infinity). Without a skip index the value bound is +Infinity and the method returns +Infinity, which is why the skip index is part of the trigger.
5. search(query, n) asks for TOP_SCORES from the start and counts the first 1,000 hits exactly; after that it raises the minimum competitive score to just above the lowest score in its top-n queue, the best score so far for n = 1 (IndexSearcher.java:100, TopScoreDocCollector.java:58-59, :154-170): 4.687542 after hit 1,001. MaxScoreBulkScorer then treats every clause whose summed bounds stay below that as non-essential and only iterates essential clauses (MaxScoreBulkScorer.java:494-510). From doc 4096 on, the function clause claims 0.0 and body:b, which has no documents left there, counts as 0 (:441-442); the sum, 0.0, is below 4.687542, so nothing in docs 4096-4999 is scored. The 4096 is the bulk scorer's inner window (INNER_WINDOW_SIZE = 1 << 12, :28): docs 0-4095 had been filled before the threshold was reached.
6. A top-level FunctionScoreQuery alone is not pruned: its FilterScorer inherits the no-op setMinCompetitiveScore (Scorable.java:45-54). Its exposed getMaxScore is still 0.

An instrumented run of the repro index on main (assertions on and off) shows: doc 0 scores 1.0 + 3.6875415 = 4.6875415, docs 1-4998 score 1.0, doc 4999 scores 100.0; the function scorer's getMaxScore is 0.0 for docs 0-4998 and for doc 4999; setMinCompetitiveScore(4.687542) after 1,001 collected hits; collection stops after 4,096 documents; search(query, 1) returns doc 0, and search(query, 3) docs 0, 1 and 2, all with total hits "4096+". With the finder's fix the bounds are 1.0 and 100.0 and search(query, 1) returns doc 4999 while still counting only "4097+" hits, so pruning still skips docs 4096-4998 (not benchmarked).

• Who is exposed. All of: unreleased main (11.0.0-SNAPSHOT) since #16431; a numeric doc-values field with a skip index; a score-independent field source with a finite bound; a wrapped query whose unscored max score is below 1; and the function query as a scoring clause of a BooleanQuery under the default search(query, n).
• Wrapped queries. A TermQuery reports 0. The finder's randomized differential also lost top hits with a ConstantScoreQuery and with BooleanQuery disjunctions and conjunctions of terms as the wrapped query. MatchAllDocsQuery reports 1 and is not affected.
• Compositions. A SHOULD clause next to another clause failed in every executed index shape. A MUST clause next to another scoring MUST clause failed in two independent tests, but whether it fails depends on how scoring windows line up with skip-index intervals.
• Default or opt-in. The search side is all default (IndexSearcher, BM25, search(query, n)). The repro opts into a skip index on the value field, a schema-time choice, and forces one segment (forceMerge(1)) to keep the index shape fixed. The skip index is exactly what #16431's speed-up relies on (CHANGES.txt: "Block-Max WAND dynamic score skipping in FunctionScoreQuery and DoubleValuesSource using DocValuesSkipper"), so the exposed applications are those that adopt the new feature as advertised and also use the query shape above.
• Scale. A few thousand documents suffice (5,000 in the repro; 8,203 and 10,000 in the reviewers' tests); the exposed bound is 0 at any size for every finite skip-index bound. The values are ordinary non-negative integers.
• Not affected. A caller that needs no scores (then createWeight returns the wrapped weight itself, FunctionScoreQuery.java:118-120); boostByValue and boostByQuery (their source needs scores, so the bound stays +Infinity); a top-level FunctionScoreQuery alone (right hits, wrong exposed bound); fields without a skip index; every released version.
• What the damage looks like. Silent in the plain repro (only a test that wraps the inner query itself in AssertingQuery fails an assertion): the returned hits are real matches with correct scores, but the best ones are missing, and the total hit count is the usual lower bound ("4096+").

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: top hit (returned score 4.5970817) expected:<4096> but was:<0>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:647)
       org.apache.lucene.queries.function.TestFunctionScoreQueryBooleanTopHit.testTopHitWithSkipIndexedValueField(TestFunctionScoreQueryBooleanTopHit.java:67)

• Contracts. Scorer#getMaxScore: "Return the maximum score that documents between the last target that this iterator was shallow-advanced to included and upTo included" (Scorer.java:75-79). Scorable#setMinCompetitiveScore: the scorer "may safely ignore all documents whose score is less than the given minScore" (Scorable.java:45-54); doc 4999 scores 100 and was ignored at 4.687542. IndexSearcher: "The TopDocs#scoreDocs array is always accurate however" (IndexSearcher.java:59-64). DoubleValues#getMaxScore: "the maximum score that documents ... can produce" (DoubleValues.java:55-61), i.e. the value bound already is the score bound.
• The test framework enforces it. AssertingScorer asserts score <= getMaxScore(docID()) (AssertingScorer.java:130), CheckHits.checkTopScores asserts score <= maxScore (CheckHits.java:766), and AssertingScorer asserts that scores are needed when advanceShallow or getMaxScore is called (:100, :116; LUCENE-8314), so asking the unscored wrapped scorer for bounds is itself off-contract.
• Same-PR tests. testMaxScoreDelegationWithDocValuesSkipper (>= 5000f), testMaxScoreMonotonicDecreasingFunction (>= 1000f) and testCustomHomemadeIncreasingAndDecreasingFunction (>= 22.3f) all wrap a TermQuery and expect a bound of at least the largest value, but only when a skip index exists, and none of their fields has one (TestFunctionScoreQuery.java:385-420, :484-487, :583-586). With the field switched to indexedField (plus forceMerge(1) and upTo = maxDoc - 1), all three fail on main, e.g. "Expected maxScore >= 1000f but got 0.0", and pass with the fix.
• Review history. The #16431 review (19 comments, 14 inline comments, 15 reviews) discussed value monotonicity, naming and constant functions; nobody mentioned the wrapped query's factor or its unscored weight. Before #16431 the bound was always +Infinity, which is correct; 10.5.2 still returns the right hit.
• Legal trigger. NumericDocValuesField.indexedField, the field sources, FunctionScoreQuery and BooleanQuery are public and not experimental, and nothing documents a limitation.

The strongest case for "intended": the product is deliberate. A comment in testConstantLambdaMonotonicity says the bound is "(5.0 * innerMaxScore)" (TestFunctionScoreQuery.java:705-707), and the unscored wrapped weight is deliberate too: it saves work and testScoreMode requires it (:303-323).

Why it fails: both choices can be deliberate and still not combine. score() never multiplies by the wrapped score, so with an unscored TermQuery the comment's own formula gives 5.0 * 0 = 0, below the 5.0 the test's documents score. Three assertions in the same PR expect a bound of at least the largest value with a TermQuery; they simply never ran. No javadoc, CHANGES or MIGRATE.md text restricts the query to a top-level position, to MatchAllDocsQuery, or to fields without a skip index, and the default search(query, 1) returns the wrong hit. Verdict: a defect (the cross-model review, the intended-behaviour check and the adjudication). Scope, not intent: a top-level function query returns the right hits, and the MUST + MUST case depends on window alignment.

Three variants were run; all fix the repro. They differ in what they do with the unscored wrapped scorer and with score-reading sources. A regression test for the PR is in the first option's notes. A over B is clear; A over C is a judgement about custom score-reading sources.

innerScores = valueSource.needsScores(); when false, advanceShallow returns the value source's boundary and getMaxScore multiplies by 1 instead of the wrapped scorer's max score. Score-reading sources (boostByValue, boostByQuery, DoubleValuesSource.SCORES) keep today's behaviour. Regression test: the test above as a new class, and six skip-index tests of #16431 in TestFunctionScoreQuery switched to a skip-indexed, single-segment field (NumericDocValuesField.indexedField, forceMerge(1); getMaxScore(maxDoc - 1) in five of them), which makes its three dead assertions live.

final boolean innerScores = valueSource.needsScores();
// advanceShallow
int scoreShallow = scores.advanceShallow(target);
if (innerScores == false) {
  return scoreShallow;
}
return Math.min(in.advanceShallow(target), scoreShallow);
// getMaxScore, after the +Infinity check
float innerMaxScore = innerScores ? in.getMaxScore(upTo) : 1f;
return innerMaxScore * valueMaxScore * boost;

Trade-offs

• The decision reads the rewritten source's needsScores(), while createWeight used the original source's; they agree for every source in Lucene, but passing the inner score mode into the weight would make the link explicit.
• The live #16431 assertions need forceMerge(1): they read only the first leaf, and with a random seed (513883939B3B8CD) newIndexWriterConfig() made several segments, so one failed even with the fix. upTo = maxDoc lies past the last document and always yields +Infinity since #16697, hence maxDoc - 1.

What the checks validated

• Standalone harness, patched class on the stock jars: this repro 2/2 (assertions on and off), the finder's repro 3/3, the independent reproduction's tests 6/6 (on and off), the GPT-5.6 reviewers' tests 4/4 each, the intended-behaviour check's class 5/5 including its AssertingQuery probe.
• gradle, scratch worktree of ea57360912ed with the fix's test changes: without the fix 5 tests fail (this repro's 2, the 3 live #16431 assertions); with it :lucene:queries:test reports 514 tests, 0 failures (5-6 skipped) for seeds 513883939B3B8CD and DEADBEEF (assertions on and off) and two random seeds: six logged runs (a seventh is recorded without its log; the fact check re-ran two more); :lucene:queries:check -x test passes (google-java-format, ecjLint, forbiddenApis).
• The diagram probe with the finder's variant (same bounds here): bounds 1.0 and 100.0; search(query, 1) returns doc 4999 and still counts only "4097+" hits.

float innerMaxScore = valueSource.needsScores() ? in.getMaxScore(upTo) : 1f; and nothing else.

Trade-offs

advanceShallow still calls the unscored wrapped scorer, which AssertingScorer.advanceShallow rejects (assert canScore): the intended-behaviour check's AssertingQuery probe fails 1 of 5 with it. Only visible with assertions on and when the wrapped query is itself an AssertingQuery (newSearcher does not do that: the test above under newSearcher passes 10 of 10 with this option), but a reviewer will likely ask for the first option.

What the checks validated

The finder's repro 3/3, the independent reproducer's tests through an equivalent one-line variant of the change (its root-cause shadow), the GPT-5.6 reviewers' tests, upstream TestFunctionScoreQuery 17/17 and TestDoubleValuesSource 11/11; the registry re-run 3/3.

advanceShallow returns scores.advanceShallow(target) and getMaxScore returns valueMaxScore * boost, following score() and the DoubleValues#getMaxScore javadoc literally.

Trade-offs

For a score-reading source with a finite bound it trusts the source's own bound instead of multiplying. No source in Lucene reports a finite bound while needing scores (only FieldValuesSource computes a finite bound in core, and it needs no scores; DoubleValues.withDefault only delegates), so the change is invisible today but is a semantic decision for custom sources.

What the checks validated

This repro 2/2, the intended-behaviour check's class 5/5, :lucene:queries:test 514/514 for two seeds (assertions on and off).

Method: semi-formal (a hunt unit, function queries and block-max pruning, 2026-10-26).

• Model. Writing the model's file:line table for FunctionScoreQuery's scorer showed that getMaxScore multiplies by in.getMaxScore(upTo) while score() never reads the wrapped score, and that createWeight weights the wrapped query without scores for field sources.
• SMT. z3 4.12.2 and cvc5 1.4.2 (floating-point theory; versions as declared by the hunt and printed by the installed solvers) found the bound unsound when the wrapped max score is 0 (query Q1a: sat). The 0 was an input taken from reading TermQuery, so this step checked the arithmetic, not where the 0 comes from.
• Differential. A randomized harness compared TOP_SCORES with exhaustive top-k for k = 1, 10, 50 and checked score <= getMaxScore over random indexes: 3,946 mismatching top-k query configurations on stock main (450 complete indexes), 554 with this fix alone (450); the remaining mismatches have other causes; one job each of the first two levels was cut by the job timeout; none without a skip index or for boostByValue/boostByQuery.
• Repro. A directed public-API JUnit then failed on the stock main jars with assertions on and off. A cross-model refute review (OpenAI GPT-5.6) reproduced it with its own tests before the candidate was written.