Bulk NumericDocValues#longValues throws on a valid index for one batch size at 16/24/40/48/56 bits: its size guard checks the unpadded count (10.5.0+)

Since 10.5.0 (#16129), NumericDocValues#longValues on a dense numeric field stored as one fixed byte-aligned width reads all requested values with one readBytes into a byte[], plus 1 to 3 padding bytes so that 24-, 40-, 48- and 56-bit values can be decoded with 4- or 8-byte loads. Lucene90DocValuesProducer.bulkDecodeByteAlignedValues first checks that the request fits in a Java array, but it checks the byte count without the padding (size * bytesPerValue <= Integer.MAX_VALUE) and then adds the padding in int. For 48-bit values and a batch of 357,913,941 docs the padded count is 2^31, which wraps to Integer.MIN_VALUE; the negative length passes the slice and allocation checks, and the read throws EOFException: read past EOF (pos=0) on a valid index. 40-bit values wrap the same way at 429,496,729 docs; for 56, 24 and 16 bits one size each asks for a byte[] the JVM cannot allocate (on JDK 25), because the guard compares with Integer.MAX_VALUE rather than an allocatable length. The guard's own fallback, the per-document loop, would return every value.

Lucene90DocValuesProducer.bulkDecodeByteAlignedValues (main 645d4fe14a20) runs when the field has one fixed width that is a multiple of 8 bits (:644-646) and the requested docs are contiguous (:648-650). The decoder reads 4 bytes per 24-bit value and 8 bytes per 40/48/56-bit value, so the last value needs 1, 3, 2 or 1 padding bytes after it (paddingBytesNeededForBulkDecode, :652-659); the writer stores those bytes on disk.

final long byteCountLong = (long) size * bytesPerValue;                    // :676
if (byteCountLong > Integer.MAX_VALUE) {                                   // :677  checks the count WITHOUT padding
  return null;                                                             //       null = use the per-document loop
}
final int byteCount = (int) byteCountLong;
final int readByteCount =
    byteCount == 0 ? 0 : byteCount + paddingBytesNeededForBulkDecode(entry.bitsPerValue);  // :681-682, int
if (offset + readByteCount > slice.length()) { return null; }              // :684  a negative length passes
if (bytes.length < readByteCount) { bytes = new byte[readByteCount]; }     // :687-688
slice.readBytes(offset, bytes, 0, readByteCount);                          // :691

• The guard admits sizes up to Integer.MAX_VALUE / bytesPerValue; only that largest size gets close enough to 2^31 for the padding (or, at 16 bits, the JVM's array limit) to push it over. One doc fewer fits; one doc more is sent to the fallback. This holds for JDK 25's array limit; only the 40/48-bit wrap is independent of the JVM. On a JVM whose largest byte[] is smaller, a few more sizes just below these would also fail with OutOfMemoryError (by arithmetic; not run).
• On JDK 25 the largest byte[] that allocates is Integer.MAX_VALUE - 2, so the 56/24/16-bit requests are refused outright; no heap is used.
• With JDK 25's limit, 8-, 32- and 64-bit widths have no failing size (Z3 model of the arithmetic).
• With NIOFSDirectory or the in-heap ByteBuffersDirectory the negative read does nothing and the decoder reads the iterator's scratch array instead. On its first bulk call that array is empty, and the decoder throws ArrayIndexOutOfBoundsException: Index 0 out of bounds for length -7 (40-bit and 48-bit runs). If an earlier bulk call left a larger array there, the decoder first decodes those stale bytes into part of the caller's values and then throws (by reading). Every directory tried ended in an exception; no call that returns gives wrong values, because the decoder's last 8-byte read would need bytes up to offset 2^31, beyond any Java array.
• Reach: a dense single-valued SortedNumericDocValues field is served by the same iterator (DocValues.singleton(getNumeric(entry)), :2002-2003), so code that unwraps it with DocValues.unwrapSingleton reaches the same path; wrappers built on FilterNumericDocValues that do not override longValues run the per-document loop. The JDK 25 Panama decoder handles only 64-bit values and passes every other width to the default decoder, so the runtime's vector support changes none of this.

• Who is hit. Application or library code that reads a huge contiguous run of docs in one longValues call, in practice a whole segment's column, on a segment of exactly that many docs, or a run of exactly that many contiguous docs anywhere in a larger segment (isContiguous compares only the first and the last doc). In Lucene itself, CheckIndex uses batches of 16 with gaps and the sandbox HistogramCollector batches of 64; the JMH benchmark NumericDocValuesBulkDecodeBenchmark uses 128 or 1,024; TermScorer and MultiNormsLeafSimScorer call it on norms, which a different producer serves.
• Default, not opt-in. The default codec, IndexWriterConfig and directory suffice. The field must be dense and stored as one fixed width: after subtracting the minimum and dividing by the gcd its values need 13-16, 21-24, 33-40, 41-48 or 49-56 bits, and per-block widths would not save 10% or more of the space. Dictionary-encoded fields (at most 256 distinct values) use at most 8 bits and are never affected.
• Scale. The caller's own int[] and long[] arrays take 12 bytes per doc: about 3.7 GB (56-bit) to 12.9 GB (16-bit), 4.3 GB at 48 bits.
• Symptoms. An exception at once, with assertions on or off. The 40/48-bit message, "read past EOF" on a valid file, points users at index corruption. A host that treats every OutOfMemoryError as fatal could exit on the 16/24/56-bit sizes.
• Not affected. No call that returns gives wrong values, and the index is not damaged; 8-, 32- and 64-bit fields, sparse fields, non-contiguous doc lists and (on JDK 25) every other batch size work.

The value pattern (i & 1) << 47 | i makes every 16,384-doc block need 48 bits, so the default codec stores the field as one dense 48-bit width and longValues takes the byte-aligned bulk path; the stack frames (bulkDecodeByteAlignedValues:691) confirm it. forceMerge(1) makes the single segment. 48 bits is the smallest int-wrap case and does not depend on the JVM's array limit. The size is inherent: the wrap needs a request of about 2^31 bytes, so the test is @Monster, like Lucene's own Test2BNumericDocValues; run it with -Ptests.monster=true.

As the regression test: the same test; it fails without the fix and passes with it. It checks only that the call returns, not the values: those are covered by the upstream testDenseNumericLongValuesBulkFetch (bulk vs per-document values) and by the finder's @Monster suite, which compares every value with the per-document loop and passed with the fix at 40, 48 and 56 bits.

# gradle, main 645d4fe14a20, seed DEADBEEF, -Ptests.monster=true -Ptests.heapsize=8g
TestNumericDocValuesBulkLongValuesSize > testLongValuesOfAllDocsWith48BitValues FAILED
    java.lang.AssertionError: expected all 357913941 values, but it threw java.io.EOFException: read past EOF (pos=0): MemorySegmentIndexInput(path="$TMP/_47_Lucene90_0.dvd") [slice=randomaccess]
        at org.apache.lucene.index.TestNumericDocValuesBulkLongValuesSize.testLongValuesOfAllDocsWith48BitValues(TestNumericDocValuesBulkLongValuesSize.java:54)
        Caused by:
        java.io.EOFException: read past EOF (pos=0): MemorySegmentIndexInput(path="$TMP/_47_Lucene90_0.dvd") [slice=randomaccess]
            at org.apache.lucene.store.MemorySegmentIndexInput.handlePositionalIOOBE(MemorySegmentIndexInput.java:147)
            at org.apache.lucene.store.MemorySegmentIndexInput$SingleSegmentImpl.readBytes(MemorySegmentIndexInput.java:790)
            at org.apache.lucene.codecs.lucene90.Lucene90DocValuesProducer.bulkDecodeByteAlignedValues(Lucene90DocValuesProducer.java:691)
            at org.apache.lucene.codecs.lucene90.Lucene90DocValuesProducer$4.longValues(Lucene90DocValuesProducer.java:1007)
            at org.apache.lucene.index.NumericDocValues.longValues(NumericDocValues.java:84)
1 test completed, 1 failed

# the same with assertions off (repro harness): same exception and frames
# 10.5.2: readBytes:791 <- bulkDecodeByteAlignedValues:583 <- $4.longValues:899

# with the fix, assertions on and off
:lucene:core:test (SUCCESS): 1 test

• Contract. NumericDocValues.java:43: "This API behaves as if implemented as below, which is the default implementation", followed by the advanceExact/longValue loop (:45-58). The only stated precondition (:60-61): the docs array "is required to be sorted in ascending order with no duplicates." No javadoc, CHANGES or MIGRATE text limits the batch size. The javadoc's own example (:69-75) even suggests calling longValues over a dense run up to docIDRunEnd(), which on a dense field can be the whole segment. (The usual iterator rules still apply, as the test framework's asserting wrapper checks: size >= 0, docs from the current docID() up to maxDoc - 1; the repro meets them.)
• The code handles oversized requests. The guard at Lucene90DocValuesProducer.java:677-679 returns null, and the callers then run the per-document loop (:1009-1010), which strongly suggests that oversized requests were meant to work (it does not by itself promise that any size fits in memory; here the caller's arrays were already allocated, and the loop needs no more). It measures the wrong number: the count without padding, against Integer.MAX_VALUE instead of an allocatable length.
• Not monotonic. N - 1 and N + 1 work, N fails.
• Lucene has a constant for this. ArrayUtil.MAX_ARRAY_LENGTH (util/ArrayUtil.java:32-34) got its current definition, Integer.MAX_VALUE minus the array header, from LUCENE-5844 / #6906 (2014): "ArrayUtil.grow should not pretend you can actually allocate array[Integer.MAX_VALUE]". It was first added in 2013 (LUCENE-5296, as Integer.MAX_VALUE - 256) and is a deliberately conservative bound, not the JVM's exact limit.
• History. The review of #16129 (one approving review, two comments about backporting, no inline comments) never discusses large requests or padding; its test uses 512 docs per width.

Strongest case (an intended-behaviour checker and reviews by another model family): the bulk API is a performance tool for small batches, nobody passes hundreds of millions of docs in one call, callers should chunk, and giant allocations may fail anyway.

Why it fails: none of that is documented, and the code itself sends oversized requests to the fallback, so oversized requests were evidently meant to work. The caller's own 4.3 GB of arrays were allocated fine; the failure is a wrong exception on a valid index (40/48 bits), or a request for an array the JVM refuses to allocate while the documented fallback exists (16/24/56 bits), not resource exhaustion. Both refute reviews rated the intended-behaviour argument weak. A later read-only review by the same family rated the case for leaving it alone moderate as an API-design defence and strong only under a stricter bar that sets aside loud failures at extreme sizes, while agreeing that the 40/48-bit wrap is hard to call intended.

One option was validated; the others are listed with their trade-offs.

Add the padding before the check, in long, and compare with Lucene's allocatable array limit instead of Integer.MAX_VALUE. size == 0 is the same test as the old byteCount == 0, because bytesPerValue >= 1 on this path.

final long byteCountLong = (long) size * bytesPerValue;
// The padding bytes are read into the same array, so they must fit as well.
final long readByteCountLong =
    size == 0 ? 0 : byteCountLong + paddingBytesNeededForBulkDecode(entry.bitsPerValue);
if (readByteCountLong > ArrayUtil.MAX_ARRAY_LENGTH) {
  return null;
}
final int byteCount = (int) byteCountLong;
final int readByteCount = (int) readByteCountLong;

Trade-offs

Requests whose padded size lies between ArrayUtil.MAX_ARRAY_LENGTH (Integer.MAX_VALUE minus the array header, a deliberately conservative bound) and the JVM's real limit used to take the fast path and now take the per-document loop: same values, slower (for example 16-bit batches of 1,073,741,816 to 1,073,741,822 docs). Normal batch sizes should see no difference: still one long addition and one comparison per call (argued from the code; not benchmarked).

What the checks validated

• Gradle in a scratch worktree of 645d4fe14a20: without the fix the repro fails; with it the repro passes with assertions on and off (-Ptests.asserts=false).
• The 9 closest suites pass, 601 tests, 0 failures: TestLucene90DocValuesFormat and its MergeInstance variant (both with the upstream bulk test testDenseNumericLongValuesBulkFetch), TestLucene90DocValuesFormatVariableSkipInterval, TestDocValues, TestDocValuesIndexing, TestMultiDocValues, TestOverlayNumericDocValues, TestNumericDocValuesUpdates and TestCheckIndex.
• ./gradlew :lucene:core:check -x test passes with the repro test in place (google-java-format, ecj lint, forbidden APIs).
• The hunt's sketch of the same change also passed its 40-, 48- and 56-bit tests, and a Z3 model of the fixed arithmetic has no failing size.

Fixes the 40/48-bit wrap.

Trade-offs

The 56/24/16-bit sizes still request new byte[Integer.MAX_VALUE] or Integer.MAX_VALUE - 1 and fail with OutOfMemoryError. Not enough.

Split a contiguous request into pieces of bounded size and reuse one bounded scratch buffer.

Trade-offs

Keeps the fast path for every size and bounds the scratch array, which the instance keeps after the call (bulkBytes = bytes, today up to about 2 GiB). A bigger change for a rare case that needs a benchmark. Not tried.

Turns the wrap into an ArithmeticException.

Trade-offs

Still an exception on a valid request. Not a fix.

Method: non-formal (code reading made exact by a solver). The hunt plan for the numeric doc-values bulk path (a hunt unit) listed the lead from reading: "byteCountLong is checked against Integer.MAX_VALUE before padding is added", naming the 40- and 48-bit sizes.

• The finder wrote a Z3 bit-vector model of the byte-count, offset and padding arithmetic with exact Java int/long wrap, IndexWriter.MAX_DOCS and contiguous in-segment docs as preconditions and the measured JDK 25 byte[] limit, and enumerated every violating size with blocking clauses: the two wrap sizes plus three sizes at the JVM array limit (16, 24 and 56 bits) that the lead did not name, and none for 8, 32 and 64 bits. With the fix the model has 0 violations.
• A public-API @Monster JUnit on the stock jars then witnessed all five sizes on a job host. The first job-host run was vacuous (its value pattern made the writer pick per-block widths, which never reach the path) and was discarded.
• A bounded-exhaustive translation check of the bulk decoder on tiny segments (about 185 million checks over every encoding) found no small-scale mismatch.