MultiCollectorManager wrapping exactly one composite manager hands that manager the wrong collectors in reduce

MultiCollectorManager runs several collector managers in one search and returns one result per manager. Since 9.0.0 its newCollector() returns MultiCollector.wrap(collectors), and wrap returns a single collector unchanged. So when the manager has exactly one child whose collector is itself a MultiCollector (a nested MultiCollectorManager with two or more children, or a custom manager that returns MultiCollector.wrap(...)), the outer manager's collector is the child's own MultiCollector. reduce cannot tell the two apart: it unwraps every MultiCollector it receives and hands the child only the first sub-collector. The inner manager then reduces its first child correctly and every later child over the first child's collector: on 2 matching documents, new MultiCollectorManager(new MultiCollectorManager(top-1, top-2)) returns 0 hits for top-2 instead of 2, and children of different types throw ClassCastException inside a well-typed reduce. The mix-up happens on every search, with default settings, assertions on and off, in every slicing. Two outer children work, and 8.x works: LUCENE-10000 (#196) introduced it in 9.0.0, and 9.0.0 to 10.6.0 and main are affected. Reach is narrow (no in-tree non-sandbox caller builds the shape); the fix is to pass the collectors through unchanged when there is one child.

1. newCollector() wraps with MultiCollector.wrap (MultiCollectorManager.java:49-56): one collector per child, returned as MultiCollector.wrap(collectors) (:55).
2. wrap of one collector returns it unwrapped, as documented: "If the input contains 1 real collector (i.e. non-null), it is returned" (MultiCollector.java:47; the n == 1 branch at :68-77). The constructor is private (:93), so every MultiCollector has two or more sub-collectors.
3. So with one child the outer collector is the child's own. For outer = MCM(inner), inner = MCM(A, B): outer.newCollector() is wrap([inner.newCollector()]), which is inner's MultiCollector{a, b}. Collection is right: a and b both see every hit.
4. reduce unwraps any MultiCollector (MultiCollectorManager.java:58-76): for child i, if (collector instanceof MultiCollector mc) reducibleCollector.add(mc.getCollectors()[i]); else reducibleCollector.add(collector); (:64-72). Its comment gives the reason: "MultiCollector will not actually wrap the collector if only one is provided, so we check the instance type here" (:65-66). That is the manager's own single-collector shortcut; the type check cannot tell it apart from a child's own MultiCollector. With one child, outer takes inner's MultiCollector for its own and passes inner.reduce the list [a].
5. inner.reduce([a]) runs the same loop: a is not a MultiCollector, so child 0 gets [a] (right) and child 1 also gets [a] (wrong); b is never reduced.
6. Why top-2 is empty. TopScoreDocCollectorManager.reduce calls topDocs() on each collector and merges (TopScoreDocCollectorManager.java:103-110). TopScoreDocCollector keeps its hits in a heap (TopScoreDocCollector.java:36, :44), and topDocs() (TopDocsCollector.java:94-99) pops that heap (populateResults, TopScoreDocCollector.java:188-193). After the top-1 manager popped a's only entry, topDocsSize() (:177-185) is 0, so topDocs returns newTopDocs(null, 0) (TopDocsCollector.java:148-149): an empty hit list that still reports totalHits = 2 (TopScoreDocCollector.java:51-55). From 9.0.0 to 10.2.x the collector kept its hits in a HitQueue instead; the repro fails the same way on 9.10.0, 9.12.3 and 10.0.0.
7. Why a mixed pair throws. A child typed CollectorManager<TotalHitCountCollector, Integer> receives a TopScoreDocCollector through the raw (CollectorManager[]) cast (MultiCollectorManager.java:46), and its own reduce throws ClassCastException.
8. Why two outer children work. wrap then builds a real MultiCollector with one slot per outer child, so getCollectors()[i] is child i's collector even when that collector is itself a MultiCollector.

• A custom manager whose newCollector() returns MultiCollector.wrap(c1, c2) and whose reduce casts back to MultiCollector, the pattern LUCENE-10244 (9.1.0) made public and that Lucene's own TestCollectorManager.CompositeCollectorManager uses (TestCollectorManager.java:127-147), wrapped alone: ClassCastException on main, 9.1.0 and 10.5.2.
• The sandbox FacetOrchestrator with no facet builders wraps the caller's main manager alone (FacetOrchestrator.java:66-82); with MCM(top-5, hit count) as the main manager it throws ClassCastException on main.
• MCM(MCM(top-5, TotalHitCountCollectorManager)) on 10 matching documents: TopScoreDocCollector cannot be cast to class org.apache.lucene.search.TotalHitCountCollector.

It is in MultiCollectorManager itself: an independent reproducer saw it calling newCollector()/reduce() directly, without IndexSearcher, with one and with two collectors, and the finder's harness saw it in every slicing of every index of 1-3 segments x 1-6 documents, sequentially and with a thread pool.

• What goes wrong. For an affected composition every search hands the inner manager's second and later children the first child's collectors. What they return then depends on the children: with top-k children, an empty top-k list with no error whenever the query has hits; a value computed from the first child's collectors, which can happen to be right (two hit-count children return the right count, and a query with no hits returns the right empty lists, executed); or a ClassCastException for that request when the children's collector types differ. Nothing is persisted.
• Configuration. Default settings; assertions on and off; any slicing or executor. No index content or scale is needed: the repro has 2 empty documents.
• In-tree callers. GroupingSearch can build a one-child MultiCollectorManager (GroupingSearch.java:149-165), but its child produces plain collectors; the facet module and DrillSideways always pass two managers. The sandbox FacetOrchestrator builds the shape when there are no facet builders.
• Downstream. None of the downstream projects read for this (Solr, Elasticsearch, OpenSearch and four others; code reading only) builds the shape; Solr keeps its own copy of the pre-9.0 design.
• Likelihood. Rare: no report was found since 9.0.0 (tagged 2021-12-06). The workaround is trivial: do not wrap a single manager, or flatten the tree.

The class sits in org.apache.lucene.search, next to TestMultiCollectorManager, and uses nothing package-private. ByteBuffersDirectory and an IndexSearcher without an executor: one segment, one slice, sequential. It also fails 3 of 3 with a second seed. The test body uses no random input, but LuceneTestCase still randomizes the default codec, locale and time zone per seed; the diagram probe, a plain main() outside the test framework, shows the same 0 hits.

It compiles on 9.10.0 and later (the first release with TopScoreDocCollectorManager). For 9.0.0 to 9.9.x the follow-up's version-neutral test covers the same shape.

Regression test: this same test (as its own class or as one method in TestMultiCollectorManager). With the fix it passes, together with the core format, ECJ and forbidden-apis checks. For the upstream test on main, use MatchAllDocsQuery.INSTANCE: the new MatchAllDocsQuery() constructor is deprecated there (MatchAllDocsQuery.java:26-34; INSTANCE exists since 10.4.0). The INSTANCE variant fails the same way on stock main and passes with the fix (executed). The standalone repro keeps the constructor so that it also compiles on 9.10.0 to 10.3.x.

cp $REPRO/TestMultiCollectorManagerSingleNested.java $LUCENE/lucene/core/src/test/org/apache/lucene/search/
cd $LUCENE && ./gradlew :lucene:core:test --tests org.apache.lucene.search.TestMultiCollectorManagerSingleNested -Ptests.seed=DEADBEEF
# assertions off fails the same way: add -Ptests.asserts=false (the recorded runs added --offline --no-daemon)

# gradle, scratch worktree of 645d4fe14a20, seed DEADBEEF, assertions on
TestMultiCollectorManagerSingleNested > testSingleNestedManager FAILED
    java.lang.AssertionError: expected:<2> but was:<0>
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:B9D11D6158E04470]:0)
        at org.junit.Assert.fail(Assert.java:89)
        at org.junit.Assert.failNotEquals(Assert.java:835)
        at org.junit.Assert.assertEquals(Assert.java:647)
        at org.junit.Assert.assertEquals(Assert.java:633)
        at org.apache.lucene.search.TestMultiCollectorManagerSingleNested.testSingleNestedManager(TestMultiCollectorManagerSingleNested.java:44)

# standalone runner, seed DEADBEEF: 1 of 1 failed, same message, on
main 645d4fe14a20 (-ea and -da), 10.6.0, 10.5.2, 10.0.0, 9.12.3, 9.10.0

# with the recommended fix: the test passes (assertions on and off)

• The contract. CollectorManager: newCollector() "must return a NEW collector which will be used to collect a certain set of leaves", and reduce "will be used to reduce the results of individual collections into a meaningful result" (CollectorManager.java:28-32); reduce is typed by the manager's own collector type (T reduce(Collection<C> collectors), :55). Here a child receives another child's collector, and a well-typed child throws ClassCastException.
• The class promises composition. "A composite CollectorManager which wraps a set of CollectorManager instances, akin to how MultiCollector wraps Collector instances" (MultiCollectorManager.java:24-27), and MultiCollector itself nests fine. The constructor accepts any non-null managers, at least one (:34-47). TestMultiCollectorManager.testCollection tests "only wrapping one of the collector managers" (TestMultiCollectorManager.java:58-63), with a plain child.
• The comment at MultiCollectorManager.java:65-66 explains the type check by the manager's own single-collector shortcut. It does not mention a child that returns its own MultiCollector, and the check cannot tell the two apart.
• Inconsistent by arity. MCM(MCM(A, B), C) works and MCM(MCM(A, B)) does not (executed on main, 9.0.0 and 10.5.2).
• Regression. From 6.4.0 to 8.11.4, newCollector() returned an object of the manager's own Collectors class (a public inner class with a private constructor) and reduce indexed collectors.collectors[i] with no type test, so nesting was unambiguous. #196's CHANGES entry is about CollectionTerminatedException and setMinCompetitiveScore parity (CHANGES.txt:4923-4924, 9.0.0), and its review never discusses nesting.
• The second trigger uses public API added later. LUCENE-10244 (9.1.0) made MultiCollector#getCollectors public, "allowing users to access the wrapped collectors" (CHANGES.txt:4344-4345; package-private in 9.0.0). Since then a manager can return MultiCollector.wrap(...) and unwrap it in its own reduce, as Lucene's TestCollectorManager.CompositeCollectorManager does. That makes the pattern public API; it does not mean every way of nesting it was considered.
• Nothing documents a restriction. No javadoc, test, CHANGES or MIGRATE entry declares the shape unsupported.

The strongest case for "intended" (a works-as-designed cross-model review and a devil's-advocate verifier): CollectorManager is @lucene.experimental (CollectorManager.java:42); wrap's single-collector shortcut is documented and the reduce comment shows the author knew it; nesting was never promised; and wrapping a single manager is redundant, so a maintainer could call it an unsupported, degenerate composition with a trivial workaround.

Why it fails: experimental status allows API changes, not silently wrong results; the restriction is written nowhere; one-child MultiCollectorManagers arise from dynamic construction (GroupingSearch, whose child cannot trigger the bug, and the sandbox FacetOrchestrator, whose caller-supplied main manager can); the nested-manager composition worked in 8.x (the custom-manager route needs getCollectors, public only since 9.1.0); and a two-child outer manager with the same nested child works today. The refute review, the independent reproducer, the devil's-advocate verifier and the adjudication rated the case weak; the works-as-designed review still called the bug real (medium). The cross-model fact check of this doc (OpenAI GPT-5.6) rated the case moderate: "won't fix" or "document the restriction" would be a plausible maintainer answer for a real but narrow, easily avoided regression. Verdict: not intended, a regression.

One fix was validated through gradle in a scratch worktree of 645d4fe14a20; it is the finder's fix with a reworded comment. The alternative was suggested by the reviewers and not built. Whichever is chosen, the invariant is: a child's reduce must receive exactly the collectors its own newCollector() returned.

With one child, newCollector() returns that child's collector as is, so reduce hands the same objects back instead of guessing from their runtime type. The multi-child loop is unchanged.

final Object[] results = new Object[collectorManagers.length];
if (collectorManagers.length == 1) {
  // newCollector() returned the single child's own collector (MultiCollector.wrap does not wrap
  // a single collector), even if it is itself a MultiCollector: pass it through unchanged
  results[0] = collectorManagers[0].reduce(reducibleCollectors);
  return results;
}

Trade-offs

• Smallest change, no hot-path cost: reduce runs once per search, after collection.
• The loop's comment ("MultiCollector will not actually wrap the collector if only one is provided ...", :65-66) then describes a case the loop no longer sees for one child; a committer may want to reword it.
• Not covered and not claimed: a child manager whose newCollector() returns null would shift indices in the multi-child path because wrap drops nulls, but CollectorManager does not allow null collectors.

What the checks validated

• Gradle, scratch worktree of 645d4fe14a20, OpenJDK 25.0.3, seed DEADBEEF (2026-10-31). Stock: the repro fails. With the fix: it passes with assertions on and off.
• The repro plus the 8 closest suites (TestMultiCollectorManager, TestMultiCollector, TestCollectorManager, TestIndexSearcher, TestCachingCollector, TestCachingCollectorManager, TestTopDocsCollector, TestTotalHitCountCollector): 57 tests, 1 skipped, 0 failures.
• :lucene:core:test over org.apache.lucene.search.*: 2,340 tests, 49 skipped, 0 failures; :lucene:grouping:test (56), :lucene:facet:test (306), :lucene:join:test (104), :lucene:sandbox:test over org.apache.lucene.sandbox.facet.* (61), :lucene:demo:test (23): 0 failures.
• checkGoogleJavaFormat, ecjLintMain, ecjLintTest (with the repro test in place), forbiddenApisMain, forbiddenApisTest: pass.
• Earlier, with the finder's version: the finder's 3-test repro (3 of 3), the independent reproducer's 7-test JUnit (7 of 7), the cross-model reviewer's own test (2 of 2) and upstream TestMultiCollectorManager passed.

Return the manager's own wrapper even for one child (as before 9.0, or through a package-private MultiCollector factory that always wraps), so reduce never has to guess from the runtime type.

Trade-offs

For one child it adds a delegation layer on every collected hit that wrap currently avoids. The factory variant touches MultiCollector (its constructor is private, MultiCollector.java:93). A manager-owned wrapper, as before 9.0, stays in MultiCollectorManager.java, but it must re-implement the CollectionTerminatedException, setMinCompetitiveScore and score-caching handling that #196 got by delegating to MultiCollector, not just bring back the old type. Suggested by the reviewers as what a committer might prefer; not built or run.

Method: semi-formal (bounded-exhaustive translation validation, then public-API JUnit tests).

• A hunt unit on concurrent collector managers wrote a harness that runs the real collector managers on every index of 1-3 segments x 1-6 documents (258 shapes) under every distinct IndexSearcher slicing (3,750), sequentially and with a 3-thread pool, and compares each result with the inner manager searched directly.
• Reading MultiCollectorManager.reduce's instanceof MultiCollector check while writing it, the finder suspected the check cannot tell the manager's own wrapper from a child's MultiCollector, and added nested specs. So the hypothesis came from code reading; the harness confirmed it: MultiCollectorManager(MultiCollectorManager(top-1, top-3)) gave a wrong result in every slicing (30,000 times with assertions on and with them off; 0 with the fix), while the two-child nested spec passed.
• The finder reduced it to a one-segment public-API JUnit. A cross-model review (OpenAI GPT-5.6), an independent reproducer, a works-as-designed review, a devil's-advocate verifier and an adjudication checked it; the follow-up added the history, prior-art and security checks, and the repro was minimized to one test.