An index-sort range query on an int-sorted field silently misses or adds documents when a bound is Long.MIN_VALUE, Long.MAX_VALUE or any other value outside the int range

IndexSortSortedNumericDocValuesRangeQuery takes long bounds and, when the index is sorted by the queried field, binary-searches the doc-ID range of the matches instead of running its fallback query. When that sort is SortField.Type.INT (or a SortedNumericSortField with Type.INT), the doc-values binary search narrows the bound with fieldComparator.setTopValue((int) topValue), and when the field has 4-byte points (IntField) the points binary search packs IntPoint.pack((int) lowerValue) / IntPoint.pack((int) upperValue) (lines 633 and 461-462 on main 645d4fe14a20). A bound outside the int range keeps only its low 32 bits: (int) Long.MIN_VALUE is 0 and (int) Long.MAX_VALUE is -1, the documented open ends of the doc-values range queries this class wraps. The search then covers the wrong doc-ID range: [Long.MIN_VALUE, 10] over the values -5, 3 and 20 returns 1 document instead of 2, [0, Long.MAX_VALUE] returns 0 instead of 2, count() agrees with the wrong result, other bounds add documents, and on the points path some bounds throw IllegalArgumentException. The class javadoc requires the same documents as the fallback, and no documented int-range precondition was found. Every core release from 9.5.0 to 10.6.0 and main are affected; matching nothing when the range lies outside the int range and clamping the bounds otherwise fixes it.

All lines are IndexSortSortedNumericDocValuesRangeQuery.java on main 645d4fe14a20.

1. Entry. scorerSupplier (:160-168, through getDocIdSetIteratorOrNull, :517-545) tries the points binary search first (getDocIdSetIteratorOrNullFromBkd, :430-515), then, for an INT or LONG primary sort on the field, the doc-values binary search (getDocIdSetIterator, :559-619). Only when neither applies does the fallback run. Weight#count (:177-226) uses the points search only when every document has a point (:193), and the doc-values search only when that holds or the sort's missing value lies outside the range (:214-215); otherwise it returns the fallback's count (:225). In the minimal test neither holds, and the fallback's count is -1 there (no doc-values skip index), so IndexSearcher.count counts the documents the query's scorer returns, which come from the wrong range.
2. Doc-values path. getDocIdSetIterator binary-searches the first document with value >= lower (:569-583) and the first with value > upper (:585-602). Each probe compares against a comparator from loadComparator (:626-646), which for Type.INT does fieldComparator.setTopValue((int) topValue) (:632-633): the int comparator needs an Integer, and the cast keeps the low 32 bits of the long.
3. Points path. For 4-byte points, :460-462 pack IntPoint.pack((int) lowerValue) and IntPoint.pack((int) upperValue) and then binary-search the point tree (:479-504). A wrapped upper end below the wrapped lower end can make the start doc greater than the end doc, and DocIdSetIterator.range then throws "minDoc must be < maxDoc" (DocIdSetIterator.java:47-50).
4. The repro's numbers. In index-sort order the documents are -5, 3, 20. (int) Long.MIN_VALUE = 0, so the first document with value >= 0 is the one with 3, and the first with value > 10 is the one with 20: the returned range holds one document.

rewrite() turns [Long.MIN_VALUE, Long.MAX_VALUE] into a FieldExistsQuery (:131-133), so only one open end at a time reaches the binary search. A bound inside the int range survives the cast unchanged. A bounded-exhaustive check (14 bound values, 8 inside and 6 outside the int range, both long extremes included; values Integer.MIN_VALUE, -5, 0, 3, Integer.MAX_VALUE; forward and reverse sort; with and without a document missing the field; three missing values) against a brute-force count found, on the three supported INT-sort setups (NumericDocValuesField, SortedNumericDocValuesField, IntField), 2,382 wrong results in 7,056 checks, every one with a bound outside the int range (0 wrong of the 2,304 in-range checks). search() and count() are wrong together, or throw together (138 cases, all on the points path). Examples on the IntField path: [Long.MIN_VALUE, -2147483649] should match nothing and returns 3 documents; [Long.MIN_VALUE, -6] throws. With the fix, 0 of all 14,112 checks are wrong. (The run also covers IntField under a LONG sort, 798 more wrong results; SortField.Type.LONG requires LongPoint, so those are left out of the claim.)

• Who is hit. Applications that (a) sort the index by an int field, either SortField.Type.INT on a NumericDocValuesField or SortedNumericSortField with Type.INT on an IntField, and (b) construct IndexSortSortedNumericDocValuesRangeQuery themselves with a long bound outside the int range. The natural case is an open end written as Long.MIN_VALUE / Long.MAX_VALUE, the convention of the long-typed doc-values range factories this query wraps.
• Default vs opt-in. The index sort is opt-in configuration, and the query is an expert @lucene.experimental class built by hand. Within that: default codec, no scale, assertions on or off, single thread.
• What is wrong. Silently missed and extra documents, and a wrong count() / totalHits; on the points path some bounds throw IllegalArgumentException. Deterministic for a given index and bound.
• Not affected. IntField.newRangeQuery (it passes int bounds), any LONG sort in a setup that SortField.Type.LONG allows (doc values only, or LongPoint / LongField), and bounds inside the int range (the cast leaves them unchanged). An IntField under a LONG sort, a setup SortField.Type.LONG rules out, does take the 4-byte points cast. The INTEGER field mappers of two major downstream search servers pass int bounds too.
• How likely: rare. It needs the hand-built query; no matching public report was found in the recorded searches (2026-10-29, re-checked 2026-10-30); the code shipped in 9.2.0 (sandbox, the doc-values cast) and 9.5.0 (core).

TestIndexSortIntSortLongBound (50 lines with the license header, one test method, public API only). The fallback assertion on line 44 passes and the query assertion on line 46 fails. As a regression test the method can go into TestIndexSortSortedNumericDocValuesRangeQuery unchanged (with its imports). :lucene:core:checkGoogleJavaFormat passes with it in the tree.

The test also fails on the 10.6.0, 10.5.2, 9.12.3 and 9.5.0 release jars (first run with the hunt's copy of it, same code with other comments, then with this test itself). An independent reproducer's own public-API test outside the Lucene package, with the other open end ([0, Long.MAX_VALUE] over 42, -7, 1), returns 0 instead of 2 on main, 10.6.0, 10.5.2 and 9.12.3.

cp $REPRO/TestIndexSortIntSortLongBound.java $LUCENE/lucene/core/src/test/org/apache/lucene/search/
cd $LUCENE && ./gradlew :lucene:core:test --tests org.apache.lucene.search.TestIndexSortIntSortLongBound -Ptests.seed=DEADBEEF

# gradle, main 645d4fe14a20, -Ptests.seed=DEADBEEF
TestIndexSortIntSortLongBound > testOpenLowerBoundOnIntSort FAILED
    java.lang.AssertionError: expected:<2> but was:<1>
        at org.apache.lucene.search.TestIndexSortIntSortLongBound.testOpenLowerBoundOnIntSort(TestIndexSortIntSortLongBound.java:46)

# standalone runner, unpatched main jars
main 645d4fe14a20, -ea, seed DEADBEEF   tests_run=1 failures=1  expected:<2> but was:<1>
main 645d4fe14a20, -da, seed DEADBEEF   tests_run=1 failures=1  expected:<2> but was:<1>
main 645d4fe14a20, -da, seed 1234ABCD   tests_run=1 failures=1  expected:<2> but was:<1>

# count() probe, same data (NumericDocValuesField / IntField with SortedNumericSortField INT)
[Long.MIN_VALUE, 10]   fallback=2  search=1  totalHits=1  count=1
[0, Long.MAX_VALUE]    fallback=2  search=0  totalHits=0  count=0

• Contracts. The class javadoc (IndexSortSortedNumericDocValuesRangeQuery.java:43-58): the optimization applies when "The sort field is of type SortField.Type.LONG or SortField.Type.INT", and "This fallback must be an equivalent range query -- it should produce the same documents and give constant scores". Its example builds the query directly from long bounds (:59-65). The constructor takes long bounds and checks nothing (:81-85); the superclass is "A Query over a range of long values" (NumericDocValuesRangeQuery.java:22). rewrite() treats Long.MIN_VALUE / Long.MAX_VALUE as open ends (:131-133) and says "This query matches the same documents as its fallback" (:136).
• The fallback's convention. NumericDocValuesField.newSlowRangeQuery, the natural fallback for a doc-values-only int field: "You can have half-open ranges ... by setting lowerValue = Long.MIN_VALUE or upperValue = Long.MAX_VALUE" (NumericDocValuesField.java:94-95; the same in SortedNumericDocValuesField.java:90-91).
• A legal setup. SortField.Type.INT: "Fields must either be not indexed, or indexed with IntPoint" (SortField.java:76-80); the repro's field has doc values only.
• No precondition found. No int-range precondition was found in the javadocs, CHANGES or MIGRATE entries, tests or review threads that were read (#11502 / #749, #687, #12078, #14732).
• History. The doc-values cast came with LUCENE-10466 (#11502 / PR #749), whose stated expectation was that the query "should not fail with class cast but correctly convert the numeric values". Its review discussed which sort types to support, not bounds; #687 (the points-path cast) did not discuss bounds either.
• Tests. The upstream INT-sort test testSameHitsAsPointRangeQueryIntSort uses Integer.MIN_VALUE / Integer.MAX_VALUE as its open ends (TestIndexSortSortedNumericDocValuesRangeQuery.java:106-150), while the LONG tests use the long extremes as open ends (:93-95, :780-782): the case is untested, not asserted.

The strongest case for "caller error": with an INT sort the values are ints (SortField.Type.INT: "Sort values are Integer"), IntField.newRangeQuery only ever passes int bounds, the upstream INT tests use Integer sentinels, the class is @lucene.experimental, a maintainer wrote in 2022 that it "should no longer be exposed to users" (jpountz on #749, 2022-03-30), and its deprecation was floated on #16699 (romseygeek, 2026-09-22).

Why it fails: the class is public in core, its javadoc shows users constructing it from long bounds, the constructor accepts any long, no documented int-range precondition was found, and the class's own rewrite() and its natural fallback use the long extremes as open ends. Narrow use and a possible future deprecation limit the impact, not the correctness: today the query silently returns other documents than the fallback the javadoc says it must equal. The intended-behaviour reviewer from another model family rated the argument moderate, the devil's-advocate check moderate-to-weak; both called the bug real.

One fix was validated with gradle in a scratch worktree at 645d4fe14a20 (JDK 25, -Ptests.seed=DEADBEEF); the other options were not built here.

IndexSortSortedNumericDocValuesRangeQuery.java, +17/-3: an early IteratorAndCount.empty() on the 4-byte points path and, for Type.INT, at the top of getDocIdSetIterator; a clampToInt helper in place of the three casts.

// 4-byte points path, and the same early return for Type.INT in getDocIdSetIterator:
if (lowerValue > Integer.MAX_VALUE || upperValue < Integer.MIN_VALUE) {
  return IteratorAndCount.empty(); // no int value can be in the range
}
queryLowerPoint = IntPoint.pack(clampToInt(lowerValue)).bytes;
queryUpperPoint = IntPoint.pack(clampToInt(upperValue)).bytes;
// loadComparator:
fieldComparator.setTopValue(clampToInt(topValue));

private static int clampToInt(long value) {
  return (int) Math.max(Integer.MIN_VALUE, Math.min(Integer.MAX_VALUE, value));
}

Trade-offs

• It assumes the field's values are ints, which is what an INT sort sorts (SortField.Type.INT: "Sort values are Integer"; the sort's missing value is an Integer). For int values, clamping a bound to the int range does not change which documents match, and a range that misses the int range entirely matches none. The assumption is not enforced: NumericDocValuesField accepts any long, and the fix was not tested with stored values outside the int range under an INT sort (the setup of the separate LFV-779, where the sort compares only the low 32 bits). Ask the maintainers to confirm it, or pick the fallback option.
• Keeps the index-sort shortcut for open-ended bounds; a few comparisons per segment (the range check once, and one clamp each time the binary search loads a comparator, O(log maxDoc) times), nothing per document.

What the checks validated

• Gradle, :lucene:core:test with the minimal test and the closest suites: TestIndexSortIntSortLongBound 1, TestIndexSortSortedNumericDocValuesRangeQuery 29, TestIndexSorting 62, TestSortOptimization 31, document.TestField 38: 161 tests, 0 failures; :lucene:core:checkGoogleJavaFormat passes. Without the fix the same gradle run of the minimal test fails. The whole core suite was not run.
• Earlier runs of the same diff on 645d4fe14a20: the minimal test with -ea and -da; the earliest finder's five tests; the bounded-exhaustive check, 0 wrong of 14,112. The cross-model reviewers' own tests pass on other bases: the intended-lens reviewer's with this fix on the older main ea57360912ed; the refute-lens reviewer's with its own copy of the same change on ea57360912ed, and again with this fix on 645d4fe14a20.

Replace the three casts with a clamp and nothing else. An independent reproducer's shadow class did exactly this and its test passed.

Trade-offs

Incomplete: a range entirely above the int range, such as [2^31, 2^32], clamps to [Integer.MAX_VALUE, Integer.MAX_VALUE] and matches the document whose value is exactly Integer.MAX_VALUE; the same at the low end. Executed with a clamp-only shadow on 645d4fe14a20, on the IntField and the doc-values path: [2^31, 2^32] returns the Integer.MAX_VALUE document, [-2^32, -2^31-1] and [Long.MIN_VALUE, -2147483649] the Integer.MIN_VALUE document, instead of none; the recommended fix returns none.

Return null from the two binary-search helpers for an INT sort or 4-byte points when a bound is outside the int range, so the equivalent fallback runs.

Trade-offs

Correct by the class's own contract and the smallest change in behaviour: for a bound outside the int range the result is the fallback's, whatever the stored values (no int-value assumption). But open-ended long bounds, the common case, lose the shortcut.

romseygeek suggested on #16699 (2026-09-22) moving the index-sort shortcut into the point and doc-values range queries and deprecating this class as redundant; HoustonPutman, the PR's author, agreed and is aiming for 11.0 (the PR's milestone is 11.0.0); the PR is labelled Stale and nothing has landed.

Trade-offs

Does not fix 9.x and 10.x, where the class stays public; can be combined with the first option.

Method: semi-formal. The hunt's hunt on point and doc-values query equivalence (2026-10-25) raised it from code reading while writing a Z3 translation-validation model of the bound handling; the model's obligations were satisfiable for both casts and unsatisfiable once the bounds are restricted to the int range, and a bounded-exhaustive detector on the stock jar and replayed witnesses confirmed it.

• A second hunt, on count() and totalHits shortcuts (2026-10-25), found the same root while modelling the count shortcuts with a bit-precise Z3 check; both findings are collapsed into this one.
• An adjudication unit reduced the earliest finder's five tests to the one-method test, ran the 14,112-check bounded-exhaustive differential against a brute-force count, and wrote the fix.