CachingCollectorManager (new in 10.6.0) does not say it is single-use: a reused instance replays every earlier search

CachingCollectorManager is new in 10.6.0 (#16247, @lucene.experimental). It wraps a first-pass CollectorManager, caches each slice's hits and lets a second pass replay them instead of re-running the query. The caches live in one list per instance that newCollector() appends to and nothing clears, while isCached() and replay() read the whole list. So an instance used for a second search replays the hits of both searches, and one earlier overflow keeps isCached() false for every later search, silently. With a delegate that is itself reusable, each search's own result is correct. The javadoc describes one search and never says an instance is single-use, although Lucene says so for TopScoreDocCollectorManager and TopFieldCollectorManager, whose state affects results, and a code comment in TotalHitCountCollectorManager calls reuse generally supported. This is a documentation gap, not a correctness bug: no contract promises reuse. GroupingSearch, the only in-tree non-test caller, creates a new manager per search and is not affected.

• Class javadoc: the manager "caches all collected documents (and optionally scores) per slice, so they can be replayed to a second-pass CollectorManager without re-running the query" (CachingCollectorManager.java:25-27). The example runs one search, then isCached(), then replay() or a re-run (:35-46). @lucene.experimental (:48).
• isCached(): "Returns true if the search has been run and all per-slice caches are intact ... false if the search has not yet been run or any cache overflowed" (:103-107).
• Nothing says what happens on a second search, either way. CollectorManager itself says nothing about reusing a manager (CollectorManager.java:23-46).

1. One list per instance: private final List<CachingCollector> cachingCollectors = new ArrayList<>();, commented "One CachingCollector per slice" (CachingCollectorManager.java:58-59).
2. newCollector() wraps a new delegate collector in a CachingCollector and calls cachingCollectors.add(cache) (:82-91). No method ever removes an entry.
3. IndexSearcher.search(Query, CollectorManager) calls newCollector() once per slice and then reduce with exactly those collectors (IndexSearcher.java:750-791). reduce() unwraps them and calls the delegate (CachingCollectorManager.java:95-101), so with a reusable delegate each search's own result is right.
4. isCached() is "list not empty and every cache intact" (:108-111), and replay() replays every cache in the list into a fresh second-pass collector (:118-130). After search N, both cover searches 1..N.

10 documents in one segment, no executor, so one slice per search. Search k:a adds cache 1 (docs 0-2); search k:b on the same instance adds cache 2 (docs 3-9). isCached() is true (both intact) and replay() replays both caches: [0..9]. With a 5-document budget, cache 1 of a k:b search (7 hits) overflows; cache 2 of a later k:a search (3 hits) is intact, but isCached() checks both and stays false. A reused instance also keeps every earlier cache (4 or 8 bytes per hit, CachingCollector.java:32) reachable (read, not measured).

• Opt-in. The class is used only when an application builds it itself (or through GroupingSearch, which creates a new one per search, GroupingSearch.java:167-176). No setting or scale is needed: 10 documents suffice.
• Which delegates. A reusable first-pass manager: a user manager that keeps no state, or FirstPassGroupingCollectorManager, which the grouping package docs suggest wrapping in CachingCollectorManager (package-info.java:49-58); the intended-behaviour check reproduced the replay of both searches with it. With TopScoreDocCollectorManager or TopFieldCollectorManager as delegate, reuse already breaks their own documented single-use rule.
• Effect. Silent. The second pass receives documents the latest query does not match, and duplicates where searches overlap (the independent reproduction: 21 entries with 5, 15 and 25 twice instead of 15 odd ids, with one slice and with 3 slices on a 2-thread pool). After one overflow the manager never reports a usable cache again, so the query is re-run every time. Earlier caches stay in memory. Each first-pass result is correct (with a reusable delegate).
• Releases. 10.6.0 (released 2026-10-29 from RC1) is the first release with the class; main has it too.
• Likelihood: rare. Few direct users of a new experimental class, and reuse with the common stateful delegates is already documented as wrong.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected:<1> but was:<2>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:647)
       org.junit.Assert.assertEquals(Assert.java:633)
       org.apache.lucene.search.TestCachingCollectorManagerReuse.testReplayAfterSecondSearch(TestCachingCollectorManagerReuse.java:43)

• Lucene documents single use where it applies. TopScoreDocCollectorManager.java:26 and TopFieldCollectorManager.java:27: "Note that a new collectorManager should be created for each search due to its internal states." (added by #240, LUCENE-10002, 2023).
• A code comment states a reuse norm. TotalHitCountCollectorManager.java:87-89 (an implementation comment in reduce(), not javadoc; #13542, 2024): "Make the same collector manager instance reusable across multiple searches. It isn't a strict requirement but it is generally supported as collector managers normally don't hold state, as opposed to collectors." It is qualified and is no interface contract.
• The rule a reviewer stated (as javanna wrote in the #13542 review, 2024-07-22). "Because the collector manager holds state, either we clean it in-between searches ... or we declare that collector managers cannot be re-used across multiple searches (potential breaking change)." The same comment goes on: "I am unsure whether it is necessary to make a breaking change for this, perhaps clearing state in reduce is not that bad." So javanna leaned toward cleaning state over a breaking declaration (said of an already released manager, as this one now is in 10.6.0), which supports the code option below at least as much as the javadoc one. javanna also reviewed and approved #16247 (2026-07-08). CachingCollectorManager holds state, does not clean it and does not declare it non-reusable.
• Never discussed. The #16247 review (39 inline comments) covered the list's concurrency ("looks like this list is needed for the replay functionality"; newCollector is called from one thread), the volatile cached flag and isCached() before any search, never a second search.
• No test either way. Upstream TestCachingCollectorManager (testCacheOverflow, testNotCachedBeforeSearch, testBasic, testConstructor) uses each instance for at most one search.
• What is not claimed. No contract promises that a reused manager replays only its latest search, so this is filed as a javadoc gap, not a correctness bug.

The strongest case (the intended-behaviour check and the refute-lens cross-model review): the class is a per-search result holder by design. Its javadoc speaks of "the search" (CachingCollectorManager.java:104) and shows a single search (:35-46); "caches all collected documents" (:25) is literally what a reused instance does; it is @lucene.experimental; CollectorManager promises nothing about reuse; TotalHitCountCollectorManager calls reuse "not a strict requirement"; and GroupingSearch uses one instance per search. The refute-lens reviewer (OpenAI GPT-5.6) rated it not real, with high confidence, as a correctness bug.

Why it fails against the documentation claim: it defeats a correctness framing, which is not made here, but not the gap. No text says one instance must not serve two searches; Lucene writes that sentence for TopScoreDocCollectorManager and TopFieldCollectorManager, whose state affects results; a code comment calls reuse generally supported; and the failure is silent. The refute-lens reviewer itself agreed that a sibling-style sentence would reduce surprise. Remaining risk: maintainers may find the singular "the search" sufficient (judge confidence medium). The hunt's own noise audit first triaged it as a noise candidate (documented/defensible) before a challenger kept it as a Low documentation claim, and the credibility audit expects a one-line javadoc PR to be welcome but push-back on any bug or regression wording.

Both options were built in a scratch worktree of 645d4fe14a20 and run with gradle. The javadoc sentence matches the advice of the adjudication and the verifiers; upstream may prefer the small code change, whose regression test is the repro.

In the class javadoc of CachingCollectorManager, after the usage example (1 file, +4).

  * </pre>
  *
+ * <p>Note that a new CachingCollectorManager should be created for each search: it keeps the
+ * per-slice caches of every search it is used for, and {@link #isCached()} and {@link #replay}
+ * cover all of them.
+ *
  * @lucene.experimental

Trade-offs

Smallest change, mirrors existing wording, no behaviour change. Reuse stays a silent misuse, and a reused instance still keeps earlier caches in memory.

What the checks validated

• :lucene:core:check -x test (checkGoogleJavaFormat, ecjLint, forbiddenApis) passes.
• :lucene:core:renderJavadoc passes (its log records only BUILD SUCCESSFUL); the independent fact check rebuilt the javadoc and found the note in the rendered class page.
• The 8 upstream TestCachingCollector* tests pass; the repro still fails, as it must for a javadoc-only change.

newCollector() empties the replayable set when a search starts, and reduce() publishes exactly the collectors it receives, which are this search's (1 file, +10/-4, including one class-javadoc line: "isCached() and replay refer to the most recent search run with this manager"). The excerpt below has verbatim diff lines with shortened hunk headers and leaves out the javadoc hunk.

-  // One CachingCollector per slice
-  private final List<CachingCollector> cachingCollectors = new ArrayList<>();
+  // One CachingCollector per slice of the most recent search: set by reduce, emptied when a new
+  // search starts
+  private volatile List<CachingCollector> cachingCollectors = List.of();
@@ newCollector()
+    // a new search starts: the caches of an earlier search must not be replayed
+    cachingCollectors = List.of();
@@
-    cachingCollectors.add(cache);
@@ reduce()
-    return delegate.reduce(originals);
+    R result = delegate.reduce(originals);
+    cachingCollectors = List.copyOf(collectors);
+    return result;

Trade-offs

• With a reusable delegate, reuse just works: a reused instance replays only its latest search and no longer keeps earlier caches alive. It does not make a stateful delegate (such as TopScoreDocCollectorManager) reusable. GroupingSearch and every single-use caller behave as before.
• A slightly different edge: after a search that throws before reduce(), isCached() is false (today it may report earlier caches).
• Two concurrent searches through one instance stay unsupported, as today.
• Touches the same method as the LFV-910 fix (independent logic, a trivial rebase).

What the checks validated

• Stock + test: fails with assertions on and off.
• + fix: the test passes with assertions on and off; core TestCachingCollector, TestCachingCollectorManager, the new test, TestIndexSearcher, TestMultiCollector, TestMultiCollectorManager (39 tests, 1 skipped) and the whole lucene/grouping module (56 tests), 0 failures, assertions on and off.
• :lucene:core:check -x test passes after one re-wrap of the javadoc line.
• The independent reproduction's 3 tests (one slice, 3 slices on a 2-thread pool, overflow then fit) fail 3 of 3 on stock 645d4fe14a20 and pass 3 of 3 with the patched class.
• Not run: the full test suite, nightly tests, a benchmark.

newCollector() throws IllegalStateException once the instance has been reduced.

Trade-offs

Turns silent misuse into an error, but is stricter than the sibling managers, which only document it, and goes against the "generally reusable" norm.

• Earlier sightings (this hunt). A unit on concurrent collector managers saw the effect in a scratch probe (3 + 7 = 10 replayed hits instead of 7) and left it unreported as a grey zone. In planning round 12, an ideation pack by an independent model from another family (OpenAI GPT-5.6) and a release-review probe proposed it again on main a9779ef3c193.
• Hunt unit. Read the per-search state while modelling the replay decision, reduced it to the JUnit in this doc (a delegate that keeps no state, so only the CachingCollectorManager carries state across searches), and classified it as a documentation gap, since no contract promises reuse.
• Method tier. Non-formal: code reading and executed tests.