LRUQueryCache's MinSegmentSizePredicate overflows maxDoc * 2, so segments of 2^30+ docs are never cached

LRUQueryCache(int maxSize, long maxRamBytesUsed) installs MinSegmentSizePredicate(10000) as its rule for which segments to cache. Its javadoc says items are cached on leaves that have more than 10k documents and more than half of the average documents per leaf, which "should guarantee that all leaves from the upper TieredMergePolicy tier will be cached". The predicate checks "more than half of the average" as return maxDoc * 2 > averageTotalDocs; with maxDoc an int. For every segment of 2^30 documents or more (a real segment holds at most IndexWriter.MAX_DOCS = 2,147,483,519) the product is negative, so the comparison is false whatever the average, and the segment is never cached, however large the cache. The rule came with #12147 (9.6.0), the fix for #12140, where the largest segments of an index were never cached; the overflow brings that symptom back for the very largest segments. Search results stay correct, and the segment is counted neither as a cache hit nor as a miss. The fix is 2L * maxDoc.

• Leaf / segment: a part of the index with its own documents, numbered 0 to maxDoc() - 1. An int holds at most 2,147,483,647; IndexWriter.MAX_DOCS is 2,147,483,519.
• leavesToCache: the Predicate<LeafReaderContext> that LRUQueryCache asks before it caches anything on a segment. The two-argument constructor uses MinSegmentSizePredicate(10000); the four- and six-argument constructors take your own.
• RAM gate: before the predicate, the cache checks that five dense bit sets for the whole index (maxDoc / 8 bytes each) fit in the budget (on main, in a sixteenth of it, one of 16 partitions).

1. MinSegmentSizePredicate.test reads the segment's maxDoc as an int, returns false below 10,000, computes averageTotalDocs = topLevel.maxDoc() / leaves.size(), and returns maxDoc * 2 > averageTotalDocs (LRUQueryCache.java:287-294 on main).
2. For maxDoc from 2^30 on (up to MAX_DOCS for a real segment; any int up to 2^31 - 1 behaves the same) the product 2 * maxDoc is at least 2^31 and wraps to 2 * maxDoc - 2^32, between -2,147,483,648 and -2. The average is never negative, so the answer is always false, whatever the other segments are. It never errs the other way.
3. CachingWrapperWeight.shouldCache is the RAM gate && this predicate (:804-808). scorerSupplier and count check it (:823, :910) and, when it is false, run the query uncached, before the cache lookup and before the caching policy is asked (:834, :838). No policy can override it, and since no lookup happens, no miss is counted.

One real segment of exactly 1,073,741,824 documents, built through the public API, LRUQueryCache(100, 64 GiB), an always-cache policy, ConstantScoreQuery(TermQuery) searched twice: 256 of 256 hits (correct) and cacheCount=0 hitCount=0 missCount=0, on main and on 10.5.2, with assertions on and off. With 1,073,741,823 documents (one of the 256 copies has one document fewer): cacheCount=1 hitCount=1 missCount=1. With 2L * maxDoc: cacheCount=1 hitCount=1. Driven directly, the predicate accepts a single segment of 10,000, 2^29 and 2^30 - 1 documents and rejects 2^30, 2^30 + 1, 2,000,000,000 and 2,147,483,519.

• Who is hit. Users who enable query caching with LRUQueryCache(int, long), the form in the class javadoc example and in MIGRATE.md ("To enable caching back ..."), and have a segment of 2^30 or more documents. Every otherwise cache-eligible query runs uncached on that segment, on every search: cached filters never help on exactly the biggest, most expensive segment.
• Default vs opt-in. Main has no default query cache (GITHUB#14187). In 9.6.0-10.6.0 the default is LRUQueryCache(1000, min(32 MiB, heap / 20)), whose RAM gate already refuses any index above 53,687,095 documents. So it takes an opt-in cache with a large budget: for an index of exactly 2^30 documents more than 671,088,640 bytes (640 MiB) on 9.6.0-10.6.0, and at least 10,737,418,256 bytes (just over 10 GiB) on main, where each of 16 partitions gets a sixteenth. Bigger indexes need more.
• How such a segment arises. forceMerge(1) of a large index (maxNumSegments wins over the merge policy's size cap), addIndexes(CodecReader...) (one merged segment by default), a raised setMaxMergedSegmentMB, or a custom merge policy. The default 5 GiB cap is in bytes, so it only stops this for documents averaging more than about 5 bytes on disk. Lucene's own @Monster test TestIndexWriterMaxDocs.testExactlyAtTrueLimit force-merges MAX_DOCS documents into one segment.
• Visibility. None: no exception, and the segment adds nothing to the hit, miss and cache counts (they count the whole cache; in the fresh-cache runs all three stay 0).
• Not affected. Caches built with their own leavesToCache predicate.

The predicate reads only the leaf's maxDoc(), the top-level reader's maxDoc() and the number of leaves (LRUQueryCache.java:286-294). The wrapped leaf is its own top-level reader, so the average is 2^30: the smallest single-segment input that wraps. The two cache helpers return null only because FilterLeafReader requires them. The same answer was checked on a real single segment of 2^30 documents, built with IndexWriter.addIndexes(CodecReader...) of 256 copies of a 2^22-document segment and searched through LRUQueryCache(100, 64 GiB) (about 6 s and 15 MB of disk), on main and 10.5.2; that probe is evidence, not the proposed test.

As the regression test: the same test, for example as a new method in TestLRUQueryCache.

cp TestMinSegmentSizePredicateOverflow.java $LUCENE/lucene/core/src/test/org/apache/lucene/search/
cd $LUCENE && ./gradlew :lucene:core:test --tests org.apache.lucene.search.TestMinSegmentSizePredicateOverflow -Ptests.seed=DEADBEEF
# assertions off: add -Ptests.asserts=false (same result)

# gradle, main 645d4fe14a20, seed DEADBEEF (assertions on; the same with -Ptests.asserts=false)
TestMinSegmentSizePredicateOverflow > testSingleSegmentOf2Pow30Docs FAILED
    java.lang.AssertionError: expected true for the only segment (2^30 docs >= 10000 and > half the average 2^30), got false
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:211FF782ABBD45E1]:0)
        at org.junit.Assert.fail(Assert.java:89)
        at org.junit.Assert.assertTrue(Assert.java:42)
        at org.apache.lucene.search.TestMinSegmentSizePredicateOverflow.testSingleSegmentOf2Pow30Docs(TestMinSegmentSizePredicateOverflow.java:55)

# with `return 2L * maxDoc > averageTotalDocs;`: the test passes (assertions on and off)

# real single segment, LRUQueryCache(100, 64 GiB), always-cache policy, ConstantScoreQuery searched twice
maxDoc=1073741824 (2^30):      hits=256/256 cacheCount=0 hitCount=0 missCount=0   (main and 10.5.2, -ea and -da)
maxDoc=1073741823 (2^30 - 1):  hits=256/256 cacheCount=1 hitCount=1 missCount=1
maxDoc=1073741824 with 2L fix: hits=256/256 cacheCount=1 hitCount=1 missCount=1

• Javadoc of LRUQueryCache(int, long) (LRUQueryCache.java:243-250): "Items will only be cached on leaves that have more than 10k documents and have more than half of the average documents per leave of the index. This should guarantee that all leaves from the upper TieredMergePolicy tier will be cached." A single 2^30-document segment meets both conditions and is the upper tier.
• History. #12140 (type:bug, by dnhatn) reported an index of 34 segments of 5 GB that was never cached under the old 3% rule. In that thread jpountz proposed the current rule: "maybe it should even be half the average segment size to make sure it includes all segments from the upper tier?" #12147 (type:bug) implemented it; its commit message: "This change adjusts the cache policy to ensure that all segments in the max tier to be cached." Nothing there excludes very large segments.
• The old rule had no cutoff. 9.5.0 compared (float) maxDoc / topLevelMaxDoc with .03f, which cannot overflow.
• No documented limit. Nothing in the class, MIGRATE.md or CHANGES.txt mentions a size cap other than the separate RAM gate.
• No test covers it. Upstream TestLRUQueryCache.testMinSegmentSizePredicate uses segments of at most 55 documents.

The strongest case for "intended" (a reviewer from another model family, OpenAI GPT-5.6, rated it "moderate"): LRUQueryCache is @lucene.experimental; caching is an optional optimisation, off by default on main; "will only be cached on leaves that ..." is a necessary condition, not a promise that every such leaf is cached, and other gates can reject entries too; and a maintainer could accept extra misses at this scale, "especially for unusually large cache entries". A related practical objection: a dense cached entry for a 2^30-document segment is about 128 MiB and can evict many smaller entries.

Why it fails: the javadoc's next sentence states the design goal ("This should guarantee that all leaves from the upper ... tier will be cached"), and the issue and PR it came from say the same; every stated condition is met here, and the predicate says no only because of the wrap; @lucene.experimental allows the API to change, not the arithmetic to be wrong; the scale is legal and exercised by Lucene's own tests; and entry size already has its own policy, the RAM gate, which admits the index only when its share of the budget has room for five worst-case entries, so the predicate is not the place that limits it. These arguments limit severity, not validity. The same reviewer noted that "the exact signed-overflow boundary has no plausible policy rationale".

Two equivalent one-line fixes; both were run through gradle in a scratch worktree of 645d4fe14a20.

In MinSegmentSizePredicate.test (LRUQueryCache.java:294).

-      return maxDoc * 2 > averageTotalDocs;
+      return 2L * maxDoc > averageTotalDocs;

Trade-offs

No correctness, API or format trade-off found: the same answer as today for every segment below 2^30 documents and "more than half of the average" for every legal size; one long multiply per segment per caching decision. By design it starts caching on such segments: a dense entry for 2^30 documents is about 128 MiB and can evict other entries, within the existing RAM, entry-count and LRU limits.

What the checks validated

• Gradle, scratch worktree of 645d4fe14a20: without the fix the repro fails with assertions on and off.
• With the fix: it passes with assertions on and off (-Ptests.asserts=false).
• Closest suites: every core test class that uses LRUQueryCache (TestLRUQueryCache, including testMinSegmentSizePredicate, TestUsageTrackingFilterCachingPolicy, TestBooleanScorer, TestDocValuesOrdinalSetIterator): 4 classes, 88 tests, 0 failures, 3 skipped (@AwaitsFix).
• ./gradlew :lucene:core:check -x test (google-java-format, ecj lint, forbidden APIs) passes with the repro test in place. The full test suite was not run.
• Earlier, shadowed into the stock main jars: the minimal test passes with assertions on and off, and the real 2^30-document segment is cached (cacheCount=1 hitCount=1).

Stays in int and cannot overflow.

-      return maxDoc * 2 > averageTotalDocs;
+      return maxDoc > averageTotalDocs / 2;

Trade-offs

For non-negative integers 2 * m > a holds exactly when m > floor(a / 2), so it gives the same answers as the long product for every input. Slightly less direct to read as "more than half of the average".

What the checks validated

Gradle in the same scratch worktree: the repro and TestLRUQueryCache pass with assertions on (41 tests, 0 failures, 3 skipped as @AwaitsFix). Assertions off, the other suites and the static checks were not run for this option.

Detects the overflow instead of avoiding it.

Trade-offs

Turns the silent miss into an ArithmeticException on every search of such a segment. Not tried.

Method: non-formal (code reading, then executed tests). In the 2026-10-22 study, a verifier saw the int multiplication as a side observation. The study's follow-up wrote three tests: the package-private predicate driven directly with a FilterLeafReader that reports a large maxDoc (single leaf, and a 2^30-document leaf next to a 20,000-document one), and an end-to-end search through LRUQueryCache(100, 64 GB) with an always-cache policy. All three fail with assertions on and off. The hunt then cut it to one test, re-ran it on current main and on release jars, and a tie-breaker built a real single segment of exactly 2^30 documents with IndexWriter.addIndexes to rule out an artefact of the reader wrapper.