FunctionRangeQuery over Int/Long/EnumFieldSource turns an exclusive bound at the type limit into an inclusive one

FunctionRangeQuery with includeLower=false or includeUpper=false means a strict bound (> or <). For int, long and enum value sources, getRangeScorer implements it by moving the endpoint one step (lower++, upper--) and then testing inclusively, but it skips the step when the bound is already MAX_VALUE (or MIN_VALUE) to avoid an overflow. The bound then stays inclusive, so n > Integer.MAX_VALUE matches the document whose value is exactly Integer.MAX_VALUE: 1 hit instead of 0, silently, with assertions on and off.

It affects IntDocValues, LongDocValues and EnumFieldSource (six lines), every checked release with FunctionRangeQuery (5.4.0 to 10.6.0) and main, and the public FunctionValues.getRangeScorer since 4.0.0-ALPHA. Only a document whose value is exactly the limit is over-matched, so it is a rare, low-priority bug. Making the range empty when an exclusive bound sits at the limit fixes it; that fix passes the repro, the module's tests and check.

1. Entry. FunctionRangeQuery keeps the bounds as strings plus the two flags (FunctionRangeQuery.java:55-80; the Number constructor accepts Integer.MAX_VALUE directly), prints false as { / } (:102-112) and, per segment, calls functionValues.getRangeScorer(context, lowerVal, upperVal, includeLower, includeUpper) (:172). IntFieldSource returns an IntDocValues, LongFieldSource a LongDocValues.
2. The endpoint adjustment. IntDocValues.getRangeScorer (docvalues/IntDocValues.java:81-117) says "instead of using separate comparison functions, adjust the endpoints" (:90), then runs if (!includeLower && lower < Integer.MAX_VALUE) lower++; (:96) and if (!includeUpper && upper > Integer.MIN_VALUE) upper--; (:103), and matches with val >= ll && val <= uu (:114).
3. At the limit. The condition lower < Integer.MAX_VALUE stops lower++ from wrapping to Integer.MIN_VALUE (which would match everything). But when lower is MAX_VALUE nothing happens at all: the bound stays 2147483647, and val >= 2147483647 admits the MAX_VALUE document. n > 2147483647 becomes the same test as n >= 2147483647. The upper bound at MIN_VALUE is the mirror image.
4. Same lines elsewhere. docvalues/LongDocValues.java:99 (comment), :105, :112 (guards with Long.MAX_VALUE / Long.MIN_VALUE), :123 (inclusive test); valuesource/EnumFieldSource.java:143, :148, :154, :165 (int guards on the enum's int value). By inheritance (read, not executed): MultiValuedIntFieldSource and MultiValuedLongFieldSource extend IntFieldSource / LongFieldSource and read real numeric doc values, so they are affected the same way. The count sources (DocFreqValueSource, JoinDocFreqValueSource, MaxDocValueSource, NumDocsValueSource, TermFreqValueSource, TotalTermFreqValueSource, SumTotalTermFreqValueSource) also return an IntDocValues or LongDocValues, but are not practical triggers: their values are never negative and cannot realistically reach MAX_VALUE (document counts are at most IndexWriter.MAX_DOCS = Integer.MAX_VALUE - 128).
5. The contrast. The default FunctionValues.getRangeScorer (FunctionValues.java:224-292) and DoubleDocValues (docvalues/DoubleDocValues.java:86-147) honour a strict bound with strict comparisons (docVal > l, docVal < u), so the float and double sources are right at the limit.

• Who is hit. Users of FunctionRangeQuery (lucene/queries, @lucene.experimental) or of FunctionValues.getRangeScorer directly, over an IntFieldSource, LongFieldSource (or their multi-valued subclasses) or EnumFieldSource. Not default and not in lucene/core.
• What it takes. Two things at once: an exclusive bound exactly at Integer/Long MIN_VALUE or MAX_VALUE, and a document whose value is exactly that limit. Nobody types n > 2147483647 by hand; such bounds come from generated queries, for example "greater than the last value seen" over a field that uses MAX_VALUE as a sentinel (an example route, not executed). One document is enough; no scale is needed.
• What goes wrong. One extra value matches, silently: no exception and the same result with assertions on and off. Where the range is used as a filter, the limit-valued documents slip through it.
• Enum. The EnumFieldSource case needs an enum whose int value is exactly Integer.MIN_VALUE or Integer.MAX_VALUE, which is contrived; the int and long cases are the ones that matter.
• Likelihood: rare. No public report found since the guard entered Lucene in 2011.

Plain IndexWriterConfig and IndexSearcher. The test's own inputs are fixed (it calls no random()); the test framework still picks a seeded random codec, similarity, locale and time zone, and the result is the same under any seed tried. The package is org.apache.lucene.queries.function only for locality.

As the regression test it needs only the ASF license header; with it, :lucene:queries:check -x test passes, and it fails on stock and passes with the recommended fix.

TestFunctionRangeQueryExclusiveLimit > testExclusiveLowerBoundAtIntMax FAILED
    java.lang.AssertionError: frange(int(n)):{2147483647 TO *] expected:<0> but was:<1>
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:25D5DFBD05250EC1]:0)
        at junit@4.13.2/org.junit.Assert.fail(Assert.java:89)
        at junit@4.13.2/org.junit.Assert.failNotEquals(Assert.java:835)
        at junit@4.13.2/org.junit.Assert.assertEquals(Assert.java:647)
        at org.apache.lucene.queries.function.TestFunctionRangeQueryExclusiveLimit.testExclusiveLowerBoundAtIntMax(TestFunctionRangeQueryExclusiveLimit.java:29)

:lucene:queries:test (FAILURE): 1 test, 1  failure

# the same failure with -Ptests.asserts=false, and with the standalone runner on main and the 10.5.2 and 9.12.3 jars

• The comment. "instead of using separate comparison functions, adjust the endpoints" (IntDocValues.java:90, LongDocValues.java:99, EnumFieldSource.java:143): the adjustment must give the same answer as docVal > lower, which is no match for lower = MAX_VALUE. The default FunctionValues.getRangeScorer and DoubleDocValues do exactly that.
• The author's own test. The guard was written in SOLR-939 (6bd49091023, 2009-03-23, Solr's frange). The same commit's TestRangeQuery.testRandomRangeQueries builds, for random bounds with incl=false incu=false, both field:{lower TO upper} and the frange query and asserts they match the same documents (sameDocs). It indexes values 5 to 24 and draws bounds from 0 to 29, so it never reaches the type limit. The same commit's testRangeQueries also asserts that an exclusive frange lower bound at the largest indexed value matches 0 documents.
• The same corner case, fixed as a bug. Commit d820e34a260 (2009-06-26, NumericRangeQuery): "Fix the special corner case, that an exclusive range starting/ending with MAX_VALUE/MIN_VALUE overflows the bounds. Return a empty TermEnum in this case", with tests asserting EMPTY_DOCIDSET for an exclusive range starting at Integer.MAX_VALUE or ending at Integer.MIN_VALUE. That class was then one week old and unreleased, and there minBound++ wrapped around rather than saturating; the fix made the range empty. LUCENE-7111 (#8166, 2016) fixed the same corner case in the sandbox DocValuesRangeQuery (there the +1 overflowed and the query matched every document) with a patch that returns no documents, which Yonik Seeley, the author of this guard, +1'd. FunctionRangeQuery.java:38 still names DocValuesRangeQuery as similar; that javadoc reference is stale, as the class no longer exists on main.
• The other range code we checked on main. Facet LongRange rejects such a range as matching nothing (IllegalArgumentException, LongRange.java:58-76, Range.java:37-40); the float and double function sources return 0 hits (executed).
• Not documented or tested where we looked. No javadoc, CHANGES.txt or MIGRATE.md entry says an exclusive bound at the limit is inclusive; TestFunctionRangeQuery uses bounds between 2 and 10 and TestValueSources uses MIN..MAX inclusive. No javadoc sentence defines the limit case the other way either; the case for "empty" rests on the comment, the default implementation and the tests above.
• Legal input. Public constructors, a valid int or long value, no documented precondition. Out-of-range literals are rejected (Integer.parseInt / Long.parseLong throw NumberFormatException), so the exact limit values are the valid boundary inputs. EnumFieldSource resolves a bound through its label map (unknown labels fall back to its default value), so the enum case needs an enum that maps a label to Integer.MIN_VALUE or Integer.MAX_VALUE, as the probe's enum does.

The strongest case: the guard is deliberate overflow protection and saturating at the limit is a conscious trade-off; n > Integer.MAX_VALUE is a meaningless query, so garbage in, garbage out; the class is @lucene.experimental, and open issue #16820 lists ValueSource among deprecation candidates for Lucene 11. The cross-model review rated this argument weak.

Why it fails: preventing the overflow is right, but keeping the bound inclusive contradicts the comment above it, the author's tests, the 2009 NumericRangeQuery and 2016 LUCENE-7111 fixes, and the comparators we checked on main (the default FunctionValues scorer and DoubleDocValues match nothing; facet LongRange rejects the range). No javadoc sentence defines the limit case, so this rests on that code and test evidence. A generated "after the last value" bound is a valid question whose answer is empty. @lucene.experimental allows API changes, not wrong results. It is a reason for low priority, not for keeping the behaviour.

The recommended fix was run in a scratch worktree created at 645d4fe14a20 (OpenJDK 25.0.3, seed DEADBEEF) and removed afterwards; the script does not record the worktree's revision, which is corroborated by the diff applying cleanly to the 645d4fe14a20 files. An independent fact check re-ran the key steps in its own worktree with the revision recorded (645d4fe14a20): the repro fails on stock (assertions on and off, and a random seed) and passes with the fix (on and off); TestFunctionRangeQuery and TestValueSources (50 tests) and checkGoogleJavaFormat pass with the fix. "Closest suites" means TestFunctionRangeQuery, TestValueSources, TestDocValuesFieldSources, TestSortedSetFieldSource, TestFunctionQuerySort and TestFieldScoreQuery in lucene/queries.

In each of the three getRangeScorer overrides, replace the saturating guard with an explicit check; when an exclusive bound is at the limit, set an empty range (lower > upper), for which the existing inclusive test matches nothing. The upper bound at MIN_VALUE, LongDocValues and EnumFieldSource get the same change. It is the outcome Lucene already chose for the same corner case in NumericRangeQuery (d820e34a260, 2009) and in Ishan Chattopadhyaya's LUCENE-7111 patch (#8166, 2016).

if (!includeLower) {
  if (lower == Integer.MAX_VALUE) {
    matchesNothing = true; // nothing is greater than Integer.MAX_VALUE
  } else {
    lower++;
  }
}
// ... the same for the upper bound at Integer.MIN_VALUE, then:
if (matchesNothing) {
  lower = 1; // an empty range (lower > upper)
  upper = 0;
}

Trade-offs

• Setup-time only, no per-document cost; inclusive bounds and bounds inside the range behave as before.
• The sentinel range 1..0 needs its comment to read clearly; returning a scorer that matches nothing would state the intent more directly but repeats code in three places (not run).
• Open ends are deliberately left alone: a null bound still becomes MIN_VALUE / MAX_VALUE, inclusive, whatever its include flag (an open end has no value to exclude); only explicit bounds change.

What the checks validated

• Stock 645d4fe14a20: the repro fails (1 of 1) with assertions on and off; the closest suites pass (62 tests).
• With the fix: the repro passes with assertions on and off; the closest suites pass (62 tests); the whole :lucene:queries:test task passes (512 tests, 5 skipped, 0 failures); :lucene:queries:check -x test (google-java-format, ecj lint, forbidden APIs, license checks) passes with the license-headed regression test in place, which passes with the fix and fails on stock. Targeted runs, not the full Lucene test suite.
• The all-sites probe with the three fixed files shadowed gives all 13 rows correct (int, long, enum at MIN and MAX: 0 hits; controls 1; float and double 0).

The tie-breaker's verification sketch for IntDocValues and LongDocValues: the same check, then if (matchNone) return false; before the value test. With it shadowed, the tie-breaker's own int/long/double probe passes all its 13 rows, the minimal test passes, and 54 upstream tests pass.

Trade-offs

Same result, one extra branch per document; EnumFieldSource needs the same change.

On LUCENE-7111 (#8166), Robert Muir suggested Math.addExact / Math.subtractExact for the old DocValuesRangeQuery, so that an overflow throws instead of passing silently. Catching the exception to return an empty range is our own variation; the patch that landed there checked the limit explicitly and returned no documents.

Trade-offs

Same semantics, but uses an exception for control flow; not run.

Four scorer variants per class.

Trade-offs

A larger change in three classes for the same result; not run.

"matches nothing".

Trade-offs

Not recommended: turns a valid empty question into an error, unlike the float and double sources, and breaks callers that generate bounds.

Method: non-formal (code reading, then executed tests).

• During the 2026-10-22 study, an AI verifier checking the flexible StandardQueryParser bug where an exclusive int/long point bound at the limit wraps around and matches everything (LFV-050) read IntDocValues.getRangeScorer and saw that its guard avoids the wrap but keeps the bound inclusive. Its sibling test gave 1 hit for n > MAX32, n < MIN32 and m > MAX64.
• A follow-up of the study executed it with its own test (testFunctionRangeAtLimits, with the control n > MAX32 - 1) and rated it new and low, with a separate root cause.
• The hunt then cut the repro to one test, re-ran it on each new main, and an independent tie-breaker wrote its own probe and checked the intent evidence.