Range grouping labels the last bucket below max a full width wide, so it overlaps the bucket for values >= max

LongRangeFactory(min, width, max) and DoubleRangeFactory turn a numeric value into the range that LongRangeGroupSelector and DoubleRangeGroupSelector group by. Their javadoc promises ranges of width between min and max, "with the exception of the final range which may be up to this width", each inclusive at the lower end and exclusive at the upper end, and one range for everything above max. getRange never shortens the final range: it always sets the bucket's upper bound to its lower bound + width, while values >= max go to [max, MAX_VALUE). Whenever max - min is not a multiple of width, the last bucket below max is therefore labelled a full width wide and overlaps the next one: new LongRangeFactory(10, 10, 25) labels 22 as LongRange(20, 30) and 27 as LongRange(25, MAX). Group membership, counts and order are right; only that label is wrong, and a range query built from it, such as a drill-down, also returns the other group's documents. Present since the classes were added in 8.6.0, in every release through 10.6.0 and on main; a small fix (one code line for doubles, two for longs) ends the bucket at max.

1. LongRangeFactory.getRange computes the bucket and never caps its end (LongRangeFactory.java:62-64; DoubleRangeFactory.java:62-64 is the same with Math.floor):

   long bucket = (value - min) / width;
   reuse.min = min + (bucket * width);
   reuse.max = reuse.min + width;   // never capped at max

1. Values at or above max get [max, Long.MAX_VALUE) (:57-61; Double.MAX_VALUE for doubles).
2. With an unaligned max, the last in-range label [k, k + width) therefore contains [max, k + width), where the "values >= max" label starts. With an aligned max (k + width == max) this overlap does not occur (for doubles: integral values, as tested; decimal widths have a separate rounding issue, LFV-412).
3. Membership is decided by label equality, so it stays right: LongRangeGroupSelector calls getRange once per document (LongRangeGroupSelector.java:72) and keeps a document in the second pass if its label is one of the top groups (:76); LongRange and DoubleRange compare both bounds (LongRange.java:42-53, DoubleRange.java:44-55). Only the reported bounds of that one bucket are wrong.
4. The constructors accept any (min, width, max) without validation (LongRangeFactory.java:36-40, DoubleRangeFactory.java:36-40). This page assumes a positive width, min < max, finite double parameters and no long overflow in value - min (a width of 0, for example, is a long division by zero).

• LongRangeFactory(10, 10, 25): 20 to 24 get LongRange(20, 30), 25 to 40 get LongRange(25, MAX); DoubleRangeFactory(10, 10, 25) gives DoubleRange(20.0, 30.0) and DoubleRange(25.0, Double.MAX_VALUE).
• Prices 12, 22, 27, 40 grouped with that factory: groups {12}, {22}, {27, 40}; the drill-down price:[20 TO 29] from the label LongRange(20, 30) returns 22 and 27. With the recommended fix the label is LongRange(20, 25) and the drill-down price:[20 TO 24] returns 22 only.
• A bounded-exhaustive check of the real factories (min and max in [-6, 6] with min < max, width 1 to 13, values -20 to 20; 1,014 configurations per factory) finds 823 configurations per factory that break the javadoc's partition, every one with (max - min) % width != 0, and none with the fix.

• DoubleRangeFactory labels the below-min bucket with Double.MIN_VALUE as its lower bound (DoubleRangeFactory.java:54; LFV-411).
• With a decimal width, DoubleRangeFactory rounds the bucket choice and the bounds separately, so a returned range can miss its value: DoubleRangeFactory(0, 0.1, 10).getRange(0.6) is DoubleRange(0.5, 0.6) (LFV-412). Capping at max does not change that.
• LongRangeFactory computes value - min without an overflow check, and [max, Long.MAX_VALUE) cannot contain Long.MAX_VALUE (a representation limit).

• Who. Range grouping through GroupingSearch(Supplier) or the grouping collector managers with an unaligned factory. Ordinary settings such as ages 18 to 65 by 10 or prices 0 to 950 by 100 are unaligned, the case the javadoc explicitly allows ("the final range which may be up to this width"); the examples are ours, not the javadoc's. A read-only code search on 2026-10-26 found no use of the two factories or the two range selectors in Elasticsearch, Solr or OpenSearch (default branches).
• What goes wrong. On every search, with assertions on or off (the label is computed per document from its value, so the index and its size do not matter): the last bucket below max is reported up to one width too wide. A UI shows "20-30" next to "25 and up"; a drill-down that turns the label into a range filter returns that bucket's documents plus those in [max, reported max) that pass its other clauses, which belong to the "values >= max" group of the same results.
• What stays right. Which documents are in which group, group counts, group sort and the documents within each group. Aligned factories, the only ones in Lucene's tests, are unaffected.
• How likely. Plausible within a rarely used API: no report since 8.6.0 (2020), but the trigger is a plain documented setting and shows as soon as the label is displayed or turned into a query.

Same package as Lucene's grouping tests. The two factories are separate test methods because they are separate fix sites: with both assertions in one method, the DoubleRangeFactory one would never run on stock main. The seed only picks the test framework's locale and settings, which the test does not use. The same test is the suggested regression test.

End to end through GroupingSearch (not part of the repro): with documents 22 and 27, the group LongRange(20, 30) holds 1 document while LongPoint.newRangeQuery("v", 20, 29) over its bounds counts 2 (documents in LongRange(20, 30) expected:<1> but was:<2>, the hunt's test, re-run on 645d4fe14a20).

cp $REPRO/org/apache/lucene/search/grouping/TestRangeFactoryFinalRange.java \
   $LUCENE/lucene/grouping/src/test/org/apache/lucene/search/grouping/
cd $LUCENE && ./gradlew :lucene:grouping:test --tests org.apache.lucene.search.grouping.TestRangeFactoryFinalRange \
  -Ptests.seed=DEADBEEF -Ptests.asserts=true
# also with -Ptests.asserts=false (same failures); the test uses no randomness

# gradle, main 645d4fe14a20, -Ptests.seed=DEADBEEF, -Ptests.asserts=true (identical with =false)
TestRangeFactoryFinalRange > testLongRangeFactory FAILED
    java.lang.AssertionError: expected:<LongRange(20, 25)> but was:<LongRange(20, 30)>
TestRangeFactoryFinalRange > testDoubleRangeFactory FAILED
    java.lang.AssertionError: expected:<DoubleRange(20.0, 25.0)> but was:<DoubleRange(20.0, 30.0)>
2 tests completed, 2 failed

# standalone runner: the same 2 failures on main (-ea, -da), 10.6.0 (-ea, -da), 10.5.2 and 9.12.3
# with the fix: 2 tests, 0 failures (assertions on and off)

• The javadoc describes this case. LongRangeFactory.java:31-34 (and DoubleRangeFactory.java): "@param width a standard width; all ranges between {@code min} and {@code max} are this wide, with the exception of the final range which may be up to this width. Ranges are inclusive at the lower end, and exclusive at the upper end." and "@param max a maximum value; all longs above this value are grouped into a single range". The final-range clause only matters for an unaligned max, and with the current code it can never apply.
• The range classes. LongRange.java:22: "Represents a contiguous range of long values, with an inclusive minimum and exclusive maximum"; :28: "The exclusive maximum value of this range" (DoubleRange.java:22-31 the same).
• Lucene's tests use the bounds as a range. BaseGroupSelectorTestCase checks each group's documents against filterQuery(groupValue) (:50, :71, :108, :160, :193, :215, :261), built as LongPoint.newRangeQuery("long", groupValue.min, groupValue.max - 1) (TestLongRangeGroupSelector.java:57) and DoublePoint.newRangeQuery("double", groupValue.min, Math.nextDown(groupValue.max)) (TestDoubleRangeGroupSelector.java:57). Every upstream factory is aligned: (100, 100, 900) ("groups are 100 wide from 100 to 900", :37, :46) and (10, 10, 50) (TestLongRangeFactory.java:26, TestDoubleRangeFactory.java:26). The shorter final range was never tested.
• History. The javadoc and the unclamped line came in the same commit, 7c350d22c707 (LUCENE-7889); the 2017 JIRA patch already had the line. The PR (apache/lucene-solr#1484) has no review comments, and issue #8940 does not discuss the final range. No CHANGES, MIGRATE, test or comment endorses overlapping ranges.

The strongest case (the cross-model reviews, the intended-behaviour checker and the adjudication): the labels are opaque equality keys and membership is right; GroupingSearch, GroupDocs, TopGroups and SearchGroup are @lucene.experimental; every upstream test uses an aligned max; and changing a label is a behaviour change for applications that store it.

Why it fails: the factories, LongRange and DoubleRange carry no experimental tag, and experimental status allows API change, not wrong documented values. The javadoc expects an unaligned max and states the shorter final range; Lucene's own tests read the bounds as a range, not a key. The result also matches neither consistent convention of Solr's range faceting: facet.range.hardend=true ends the last range at the end, false extends it and starts the "after" bucket where it ends; Lucene extends the label like false but starts the "above max" bucket at max like true. The reviews rated the intended case weak. Verdict: a defect.

One fix was validated in a scratch worktree of 645d4fe14a20 with gradle. The hunt's shorter long form also fixes the test but overflows at the extremes and breaks labels that stock gets right.

In both getRange methods, cut the bucket's upper bound at max. In LongRangeFactory a wrapped reuse.min + width (only possible when the true end is past Long.MAX_VALUE, so past max) also means "cut to max"; for doubles Math.min suffices. 2 files, +6/-2.

@@ LongRangeFactory#getRange
     reuse.min = min + (bucket * width);
-    reuse.max = reuse.min + width;
+    long end = reuse.min + width;
+    // the final range ends at max (it "may be up to this width");
+    // end < reuse.min only when reuse.min + width overflows
+    reuse.max = (end < reuse.min || end > max) ? max : end;
@@ DoubleRangeFactory#getRange
     reuse.min = min + (bucket * width);
-    reuse.max = reuse.min + width;
+    // the final range ends at max (it "may be up to this width")
+    reuse.max = Math.min(reuse.min + width, max);

Trade-offs

• Behaviour change. For a positive width without overflow in value - min, only the label of the last bucket below an unaligned max changes (LongRange(20, 30) becomes LongRange(20, 25); the top-edge wrap below is that same bucket when max = Long.MAX_VALUE); membership, counts and every other label are unchanged, because the new upper bound depends only on the bucket's lower bound. LongRange and DoubleRange expose min and max as public fields, so applications that store, compare or display old labels see the new value.
• Also fixes a stock wrap at the top edge: LongRangeFactory(0, 10, Long.MAX_VALUE) labels Long.MAX_VALUE - 3 as LongRange(9223372036854775800, -9223372036854775806) on stock and LongRange(9223372036854775800, 9223372036854775807) with the fix.
• Cost: one comparison per call; no benchmark was run.

What the checks validated

• Stock + test: 2 of 2 fail with assertions on and off (gradle).
• + fix, :lucene:grouping:check with assertions on: the whole module, 15 suites (14 upstream, including the four range factory and selector suites, + the test), 58 tests, 0 failures; checkGoogleJavaFormat, ecjLint and forbiddenApis pass.
• + fix, :lucene:grouping:test with assertions off: the same 58 tests, 0 failures.
• + fix, standalone runner: the test passes 2 of 2 with -ea and -da.
• Side probe (not a test to add): 6 of 6 labels right with the fix, including factories with max = Long.MAX_VALUE and min = Long.MIN_VALUE.
• Not run: the full test suite, a benchmark.

reuse.max = max - reuse.min < width ? max : reuse.min + width in LongRangeFactory (DoubleRangeFactory as above). The hunt records that it passes the test, the 56 upstream grouping tests and the exhaustive check (the exhaustive log labels its lines only WITH-FIX).

Trade-offs

max - reuse.min overflows when the span from the bucket to max exceeds Long.MAX_VALUE, and then it breaks labels that stock gets right: LongRangeFactory(-1000, 10, Long.MAX_VALUE).getRange(-995) is LongRange(-1000, -990) on stock and LongRange(-1000, 9223372036854775807) with this form; max = Long.MAX_VALUE is a natural "no upper bucket" setting. (Math.min(reuse.min + width, max) for longs fails at the top edge instead; not run.)

What the checks validated

The side probe shows the two wrong labels; the test and the 56 grouping tests pass (the hunt's run on ea57360912ed).

Keep full-width labels and move the >= max boundary to the end of the last bucket, like Solr's hardend=false.

Trade-offs

Contradicts "all longs above this value are grouped into a single range" and changes group membership.

Say in the javadoc that the last bucket below max may overlap the bucket for values >= max.

Trade-offs

Keeps a label that contradicts LongRange's own [min, max) javadoc and the final-range clause.

• First signal (hunt unit on range bounds across code paths). While extending a sweep that compares a range as reported by one API with the same range in another to grouping by range (a group's reported [min, max) versus a point range query over the same field), the finder read getRange and saw that the bucket's end is never capped at max.
• Bounded-exhaustive check of the real factories on the stock main jar: min and max in [-6, 6], width 1 to 13, values -20 to 20, 1,014 configurations per factory; 823 violate the javadoc's partition, all with (max - min) % width != 0, 0 with the fix.
• Then a public-API JUnit, independent verifiers, cross-model reviews (reading only) and an adjudication; the hypothesis came from reading, so the finding counts as non-formal.
• An earlier grouping hunt had noted the same observation from code reading and skipped it as "labels only"; a later unit found it again (same root cause and fix). Both are our own findings.