FunctionRangeQuery scores raw negative values, so a minimumShouldMatch query can drop a document whose value is -Infinity

FunctionRangeQuery (lucene/queries) matches documents whose function value lies in a range and scores each match with the value itself: ValueSourceScorer.score() returns floatVal(doc) and maps NaN and -Infinity to -Float.MAX_VALUE. LUCENE-7996 (8.0.0) made negative scores illegal and changed FunctionQuery's identical code to return 0, but did not touch ValueSourceScorer, whose comment still says "(same as FunctionQuery, but no qWeight)". So negative values give negative scores in TopDocs and explain. Since 10.1.0 it also loses hits: top-k search of a pure-SHOULD BooleanQuery with minimumNumberShouldMatch >= 2 runs on WANDScorer, which rejects a candidate whose scaled score is below the minimum competitive score of 0. An ordinary negative score rounds to 0 there and survives; -Float.MAX_VALUE does not, so a matching document whose value is -Infinity is missing from search(q, n), whose total (exact here, with fewer than 1,000 matches) is too low while count(q) is right. Two documents and the default IndexWriterConfig, codec and IndexSearcher are enough. A one-line clamp fixes it.

1. The score is the raw value. ValueSourceScorer.java:84-92: float score = values.floatVal(disi.docID()); then return score > Float.NEGATIVE_INFINITY ? score : -Float.MAX_VALUE; with the comments "(same as FunctionQuery, but no qWeight)" and "Current Lucene priority queues can't handle NaN and -Infinity, so map to -Float.MAX_VALUE". getMaxScore returns Float.POSITIVE_INFINITY (:94-97).
2. FunctionQuery clamps. FunctionQuery.java:130-137: if (val >= 0 == false) { // this covers NaN as well ... returns 0 (:132).
3. Matching is separate and correct. FunctionRangeQuery.java:168-174 builds the scorer with FunctionValues.getRangeScorer; for a double field that is DoubleDocValues.java:87-147, where an open lower bound becomes Double.NEGATIVE_INFINITY (:95-96) and the match test is docVal >= l && docVal <= u (:116). So -Infinity matches, NaN never does.
4. Routing. For this pure-SHOULD query under ScoreMode.TOP_SCORES with minShouldMatch > 1, BooleanScorerSupplier.java:315-322 declines the bulk scorers ("Fall back to BS2/WANDScorer") and :589-590 builds a WANDScorer. IndexSearcher.search(q, n) is TOP_SCORES (IndexSearcher.java:100, :599; TopScoreDocCollector.java:58).
5. Scaling. WANDScorer compares scores as scaled longs. The scale comes from the sum of the clauses' max scores (WANDScorer.java:186-193); the range clause's +Infinity gives scalingFactor(+Infinity) = scalingFactor(MAX_VALUE) - 1 (:66, :74-75), that is 2^-105, and scaled scores are rounded up (:104).
6. The check. WANDScorer.java:333-344 scales the summed score of the clauses that match the candidate and loops while (scaledLeadScore < minCompetitiveScore || freq < minShouldMatch), returning false once scaledLeadScore + tailMaxScore < minCompetitiveScore; the threshold starts at 0 (:163). With assertions on, scaleMaxScore trips assert maxScore >= 0 (:92) first.

Doc 0 scores -3.4028235E38 + 0.31506687 (body:a). Scaled by 2^-105 that is about -8.4 million, far below 0, so WANDScorer rejects it. A score of -5 scales to about -1e-31, which rounds up to 0, so it survives with assertions off: the -5.0 control document is returned in every run that completes, 30 of 33 (score -4.837875 in the four-document check on 10.5.0); the three stock runs with assertions on throw at WANDScorer.java:92 first and return nothing. The boundary is a summed (lead) score of about -2^105 (about -4.06e31): a finite value of -1e32 is dropped and -1e31 is kept.

An exhaustive search, TopScoreDocCollectorManager(10, Integer.MAX_VALUE) (COMPLETE, TopScoreDocCollector.java:58-59), returns both documents: doc 1 = 1.3150668, doc 0 = -3.4028235E38. On this two-document index it does not run on WANDScorer: with minShouldMatch > 1 the cost threshold is maxDoc / 3 = 0, which the clauses meet (BooleanScorerSupplier.java:212-230), and optionalBulkScorer() declines only under TOP_SCORES (:315-322), so it returns a BooleanScorer (:331-337), which has no minimum-competitive-score check (an executed probe prints BooleanScorer for COMPLETE and WANDScorer for TOP_SCORES). A COMPLETE search that does reach WANDScorer also skips the check (WANDScorer.java:194-196, :334). explain gives doc 0 (abridged) "-3.4028235E38 = sum of: -3.4028235E38 = frange(double(d)):[* TO *] (-Infinity = double(d)=-Infinity), 0.31506687 = weight(body:a in 0)". FunctionQuery(d) alone scores doc 0 as 0.0.

At scale: 20,000 documents in 8 segments, 574 with value -Infinity; the same query shape returned 11,532 of 11,893 matches, reported as exactly "11532 hits", and searchAfter paging skipped the same 361 documents, all valued -Infinity (main and 10.5.2).

One document with d = -5.0 and FunctionRangeQuery(d, [-10, 10]): the score is -5.0 in TopDocs and explain, where FunctionQuery(d) scores 0.0. In a disjunction, a document that matches tag:x and the range clause scores -4.9171267, below its tag:x-only score 0.082873434. LuceneTestCase.newSearcher rejects the score (AssertingScorer.java:131), and on 8.0.0 to 10.0.0 a top-k search with assertions on throws in core TopScoreDocCollector.

• Who. Users of FunctionRangeQuery (an @lucene.experimental class) as a scoring clause, not in a FILTER clause or a ConstantScoreQuery, over a value source that can be negative. Solr's frange uses its own constant-scoring query; Elasticsearch and OpenSearch do not reference FunctionRangeQuery, getRangeScorer or ValueSourceScorer (read-only code search, 2026-10-26).
• Negative scores (8.0.0 on). Negative scores in TopDocs and explain; matching the range clause can lower a document's score below that of a document that matches only the other clause; Lucene's own asserting test searcher rejects the score, so downstream test suites that use it can fail; on 8.0.0 to 10.0.0 any top-k search with assertions on throws in core TopScoreDocCollector.
• Lost hits (10.1.0 on). Silent wrong results: the -Infinity document is missing from top-k and from searchAfter paging, and an exact totalHits is too low while count() is right. No exception with assertions off. On 10.1.0 to 10.4.0 only sparse SHOULD clauses or a query nested in a conjunction reach WANDScorer; since 10.5.0 dense top-level queries such as the two-document repro do too.
• What it takes. A stored -Infinity (for example the log of 0), or a finite value low enough that the document's summed score is at or below about -2^105 (about -4e31; in the tested shapes a field value of about that size); a range that admits it (an open or -Infinity lower bound; a lower bound such as -10 excludes -Infinity); and the scored query as a SHOULD clause of a minimumNumberShouldMatch >= 2 query that reaches WANDScorer (shown for the pure-SHOULD, sparse and nested shapes). NaN cannot trigger it: it fails every range test.
• What it does not do. Which documents match never changes: count(), FILTER, MUST_NOT and ConstantScoreQuery uses were correct in all 17 probe shapes, and in the probe every omitted result was a document valued -Infinity; no document with a non-negative score was omitted. A -Infinity document scores about -3.4e38 (near the lowest finite float), so it would have ranked at the end; with the default 1,000-hit counting threshold it shows in short result lists, in an exact total, or when paging to the end.
• How likely: contrived. Three unusual conditions must hold at once.

ByteBuffersDirectory, the default codec pinned so the seed cannot pick another one, a plain IndexSearcher that runs the one leaf on the calling thread; nothing random. Three SHOULD clauses are needed, because with two, "at least 2" is a plain conjunction and WANDScorer is not used; the open lower bound is needed, because with a lower bound of -10 the -Infinity document does not match. The test asserts only the lost hit; the negative score is the cause, shown by the assertion that fires with assertions on and by the fix making the test pass.

Release jars: the test fails on 10.5.0 and 10.6.0 (assertions on and off) and passes on 10.4.0, where this dense shape still ran on BooleanScorer; on 10.0.0 and 9.12.3 it passes with assertions off and, with assertions on, hits the old core negative-score check in TopScoreDocCollector.

Regression test: this same test; it passes with the recommended fix and fits as one more method of the existing TestFunctionRangeQuery.

cp $REPRO/TestFunctionRangeQueryNegativeScoreHitLoss.java $LUCENE/lucene/queries/src/test/org/apache/lucene/queries/function/
cd $LUCENE && ./gradlew :lucene:queries:test --tests TestFunctionRangeQueryNegativeScoreHitLoss -Ptests.seed=DEADBEEF -Ptests.asserts=false
# assertions on (-Ptests.asserts=true) fails earlier, with AssertionError at WANDScorer.scaleMaxScore

# gradle, stock 645d4fe14a20, -Ptests.seed=DEADBEEF -Ptests.asserts=false (stack trimmed)
TestFunctionRangeQueryNegativeScoreHitLoss > testMinShouldMatchKeepsNegativeInfinityDoc FAILED
    java.lang.AssertionError: hits of search(q, 10) expected:<2> but was:<1>
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:D7A0144D2DA9FECF]:0)
        at junit@4.13.2/org.junit.Assert.assertEquals(Assert.java:647)
        at org.apache.lucene.queries.function.TestFunctionRangeQueryNegativeScoreHitLoss.testMinShouldMatchKeepsNegativeInfinityDoc(TestFunctionRangeQueryNegativeScoreHitLoss.java:66)

# the same with -Ptests.asserts=true
TestFunctionRangeQueryNegativeScoreHitLoss > testMinShouldMatchKeepsNegativeInfinityDoc FAILED
    java.lang.AssertionError
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:D7A0144D2DA9FECF]:0)
        at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.search.WANDScorer.scaleMaxScore(WANDScorer.java:92)
        at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.search.WANDScorer$2.matches(WANDScorer.java:336)
        at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.search.Weight$DefaultBulkScorer.scoreTwoPhaseIterator(Weight.java:311)

# the numbers behind it (a main() probe on the same two documents, not part of the repro)
query: (frange(double(d)):[* TO *] body:a body:b)~2
count(q) = 2
search(q, 10): totalHits=1 hits hits: doc1=1.3150668
exhaustive (totalHitsThreshold MAX_VALUE): totalHits=2 hits hits: doc1=1.3150668 doc0=-3.4028235E38
frange alone, search(frange, 10): totalHits=2 hits hits: doc1=1.0 doc0=-3.4028235E38
FunctionQuery(d) alone, search(fq, 10): totalHits=2 hits hits: doc1=1.0 doc0=0.0
# with the clamp: search(q, 10): totalHits=2 hits hits: doc1=1.3150668 doc0=0.31506687

• The contract. MIGRATE.md:1368-1372 ("Scorer must produce positive scores (LUCENE-7996)": "Scorers are no longer allowed to produce negative scores"); CHANGES.txt:6636 (8.0.0, API Changes: "Queries are now required to produce positive scores"); CHANGES.txt:6732-6733 ("FunctionQuery and FunctionScoreQuery now return a score of 0 when the function produces a negative value"). On main the test framework enforces it (AssertingScorer.java:131 assert Float.compare(score, 0f) >= 0, AssertingScorable.java:36).
• Core relies on it. WANDScorer asserts maxScore >= 0 (WANDScorer.java:92) and throws "Scores must be positive or null" for a negative max score (:70-71).
• The class says it mirrors FunctionQuery. ValueSourceScorer.java:86 "(same as FunctionQuery, but no qWeight)" and :28 "This is similar to FunctionQuery". a8a63464e7d (LUCENE-7996) replaced FunctionQuery's identical -Float.MAX_VALUE mapping with the 0 clamp; ValueSourceScorer and FunctionRangeQuery are not among its 22 files.
• Two APIs disagree on the match set. count(q) = 2, search(q, 10) = exactly 1 hit.
• Precedent. Negative scores in other code were fixed as bugs: #12727, #16139, #12342, #11184.

The strongest case: FunctionRangeQuery.java:33 says "The score is the float value", and ValueSourceScorer.java:26 and FunctionValues.java:224-227 say the same, all @lucene.experimental. Scorable.score() states no sign, and since #13939 (10.1.0) core TopScoreDocCollector no longer asserts score >= 0. A second argument: Lucene tolerates negative scores from IndriDirichletSimilarity, which its similarity test base exempts.

Why it fails: those javadocs come from LUCENE-6720 (2015), two years before the rule, and LUCENE-7996 changed FunctionQuery's identical raw-value code. #13939 moved the assertion into the test framework (AssertingScorable); it did not drop it. The LUCENE-7996 discussion (#9044, 19 comments) never mentions this class, so it looks missed rather than exempted; that is an inference from silence, nobody said so. Even if a maintainer preferred to document negative scores, WANDScorer would still lose the hit, so a javadoc change alone cannot fix it. The Indri exemption is local to that class and is itself the cause of another hit-loss bug (LFV-190).

Option A was built and run through gradle. B (document negative scores) would leave the lost hit, C (clamp only inside FunctionRangeQuery) is a narrower variant of A, and D (make WANDScorer tolerate negative scores) works against the documented rule. Workarounds that need no fix: put a FunctionRangeQuery that only restricts results in a FILTER clause or a ConstantScoreQuery, use a finite lower bound where documents valued -Infinity need not match, or reject non-finite values at index time.

ValueSourceScorer.score() (ValueSourceScorer.java:91) returns the value only when it is positive, else 0, the rule FunctionQuery applies. The same change updates the javadocs: "The score is the float value, or 0 if it is negative or NaN" in FunctionRangeQuery, a sentence in the ValueSourceScorer class javadoc, and "or 0 where that is negative or NaN" in FunctionValues.getScorer and getRangeScorer (3 files, +12/-10).

// Scores must not be negative (LUCENE-7996): map negative values, -0.0 and NaN to 0. This
// conditional handles NaN since comparisons with NaN are always false.
return score > 0 ? score : 0f;

Trade-offs

• Behaviour change. Documents with negative values now tie at 0 instead of being ordered by their negative value; users who need that order should sort by the value. Every ValueSourceScorer that does not override score() changes the same way: the getRangeScorer implementations in FunctionValues, DoubleDocValues, LongDocValues, IntDocValues, DocTermsIndexDocValues and EnumFieldSource, FunctionValues.getScorer, and downstream subclasses. Worth a CHANGES.txt entry.
• -0.0. It becomes 0 here; FunctionQuery lets -0.0 through, which is the separate LFV-273.
• Matching unchanged. matches() is separate, so count(), filters and ConstantScoreQuery uses do not change.
• Cost. One comparison per scored document; no benchmark was run.

What the checks validated

Applied to a scratch worktree of 645d4fe14a20 and run through gradle with OpenJDK 25.0.3, seed DEADBEEF (2026-10-31; the worktree was removed afterwards):

• stock: the minimal test fails with assertions on and off;
• with the fix: the minimal test passes with assertions on and off;
• the closest suites TestFunctionRangeQuery, TestValueSources, TestFunctionQuerySort, TestFunctionQueryExplanations, TestDocValuesFieldSources and TestFieldScoreQuery pass (64 tests, 0 failures);
• the whole :lucene:queries:test passes (51 classes, 512 tests, 0 failures, 5 skipped), and so do :lucene:expressions:test (170 tests) and :lucene:spatial-extras:test (117 tests, 5 skipped); no module outside lucene/queries uses FunctionRangeQuery, ValueSourceScorer or getRangeScorer;
• checkGoogleJavaFormat, ecjLintMain, forbiddenApisMain and renderJavadoc for queries pass.
• Earlier, the code-only clamp made the finder's negative-score test, an independent reproducer's tests, the 255-check security probe and all three follow-up shapes pass.

Change no code; say in the javadocs that FunctionRangeQuery may return negative scores.

Trade-offs

Matches today's "The score is the float value" wording, but breaks the global rule, the test framework keeps rejecting the score, and WANDScorer keeps losing the hit. Not run.

Wrap the scorer that FunctionRangeWeight.scorerSupplier returns (FunctionRangeQuery.java:168-174) so that it clamps, and leave ValueSourceScorer as it is.

Trade-offs

Narrower: other users of getRangeScorer/getScorer keep raw scores, but a scorer that can return negative scores stays in the API, and it is more code than the first option. Not run.

For example clamp the scaled lead score at 0 in WANDScorer.matches().

Trade-offs

Hides this symptom on one path only, against the documented rule, in a hot core loop; other scorers and collectors may make the same assumption. Not run.

Method: non-formal (the hunt's tier for findings from directed testing and code reading). The hunt unit compared range-bound behaviour across query paths.

• Assertion. Its cross-path FunctionRangeQuery checks ran under the test framework's asserting searcher, and AssertingScorer rejected a negative score.
• Trace. Code and history reading led to LUCENE-7996 (a8a63464e7d), which clamped FunctionQuery, BoostedQuery and FunctionScoreQuery but not ValueSourceScorer; a public-API JUnit on the stock jar (one document, d = -5.0) failed with assertions on and off.
• Hit loss. After the verifier panel, the follow-up's security screen ran a randomized probe (20,000 documents, 17 query shapes, 255 checks) and found the minimumShouldMatch >= 2 hit loss (361 missing documents, all valued -Infinity). Three minimal checks then mapped it across releases, and a 2026-10-29 minimization cut it to the two-document test above.