The grouping package overview says groupOffset 3 with topNGroups 10 returns 7 groups, but the collector managers it names return 10

The lucene-grouping package overview defines the two paging inputs of a grouped search: topNGroups is "how many top groups to keep. For example, 10 means the top 10 groups are computed", and groupOffset 3 "means you'll get 7 groups back (assuming topNGroups is 10). This is useful for paging, where you might show 5 groups per page". Since #16385 (10.6.0) the same page names FirstPassGroupingCollectorManager as the first pass and builds BlockGroupingCollectorManager(groupSort, groupOffset, topNGroups, ...). Both managers, like GroupingSearch, treat topNGroups as the number of groups to return after the offset, so (3, 10) returns 10 groups, ranks 4 to 13. The "7 groups" rule holds only for the plain FirstPassGroupingCollector and BlockGroupingCollector, whose topNGroups includes the offset, and the 10.6 page names neither. The code is correct and intended; the text needs fixing. The bullet has also disagreed with the page's own example code since 3.2.

• :37-41: "topNGroups: how many top groups to keep. For example, 10 means the top 10 groups are computed." / "groupOffset: which "slice" of top groups you want to retrieve. For example, 3 means you'll get 7 groups back (assuming topNGroups is 10). This is useful for paging, where you might show 5 groups per page."
• :49-52: "the first pass (FirstPassGroupingCollectorManager) gathers the top groups, and the second pass (TopGroupsCollectorManager) gathers documents within those groups".
• :129-137: new BlockGroupingCollectorManager<>(groupSort, groupOffset, topNGroups, needsScores, lastDocPerGroup, withinGroupSort, docOffset, docsPerGroup). No plain collector is named anywhere on the page.

// FirstPassGroupingCollectorManager.java:106-125
public FirstPassGroupingCollector<T> newCollector() throws IOException {
  return new FirstPassGroupingCollector<>(
      groupSelectorFactory.get(), groupSort, groupOffset + topNGroups, ignoreDocsWithoutGroupField);
}
... reduce(...): allGroups.add(collector.getTopGroups(0)) for each collector, then
return SearchGroup.merge(allGroups, groupOffset, topNGroups, groupSort);

• SearchGroup.merge keeps a queue of offset + topN (SearchGroup.java:281), skips the first offset groups (if (count++ >= offset), :304) and stops when it holds topN (:309-310).
• BlockGroupingCollectorManager does the same: new BlockGroupingCollector(groupSort, groupOffset + topNGroups, ...) (BlockGroupingCollectorManager.java:141-144), then TopGroups.mergeBlockGroups(shardGroupsList, groupSort, groupOffset, topNGroups, withinGroupSort) (:158-159).
• GroupingSearch documents this meaning: "@param groupLimit The number of groups to return from the specified group offset" (GroupingSearch.java:123), and passes groupOffset, groupLimit to the first-pass manager (:148).
• Where "7" is right: the plain collectors take a pool size that includes the offset, "@param topNGroups How many top groups to keep" (FirstPassGroupingCollector.java:72, :86; BlockGroupingCollector.java:204), and the offset goes to getTopGroups (FirstPassGroupingCollector.java:136; BlockGroupingCollector.java:260-261).
• The managers' own javadoc reads like the bullet: "@param groupOffset The offset in the collected groups" and "@param topNGroups the number of top groups to collect" (FirstPassGroupingCollectorManager.java:66-67, :82-83; the first is word for word FirstPassGroupingCollector.getTopGroups's @param, :133), and "the number of top groups to collect" (BlockGroupingCollectorManager.java:88). Only GroupingSearch is unambiguous.

13 one-document groups g0 to g12 by index order, (groupOffset 3, topNGroups 10): FirstPassGroupingCollectorManager returns 10 groups, g3 to g12 (the minimal test; the first group checked in this doc's fixed-text run). 15 groups g00 to g14 (the independent reproduction's test): the manager returns g03 to g12, BlockGroupingCollectorManager 10 groups, GroupingSearch.search(searcher, q, 3, 10) 10 groups from g03, and the plain FirstPassGroupingCollector(selector, sort, 10).getTopGroups(3) 7. Paging from the text, groupOffset 5p and topNGroups 5p+5: page0=[g00..g04], page1=[g05..g14], page2=[g10..g14].

• Who: code written against the two collector managers from the overview's inputs list. Users of GroupingSearch, and anyone who passes the page size as topNGroups (the meaning GroupingSearch documents for its groupLimit), get the intended page size.
• Default, not a special setting: no index size, codec or flag is involved. The minimal repro uses 13 one-document groups, and 11 already show the mismatch: with (3, 10) the first-pass manager returns 6, 7, 8, 9 and 10 groups for 9, 10, 11, 12 and 13 groups, so from 11 groups on it returns more than the sentence's 7. Since 10.6.0 the page names the managers and no plain collector, so the overview now leads its readers to them.
• Effect: silent. No exception; pages look plausible. Nothing excluded or deleted appears: every group comes from the same query, filters and reader. The first pass also does somewhat more work than meant (each collector keeps about 2 x groupOffset + pageSize groups instead of groupOffset + pageSize).
• Likelihood: plausible but limited. The managers are new (10.5.0) and @lucene.experimental, most users go through GroupingSearch, and no one has reported the mismatch in the roughly 15 years the bullet has disagreed with the page's examples.

• Smallest input. 13 groups are the fewest for which the manager returns its full topNGroups (10); 11 or 12 would also differ from 7 but not show the full 10.
• Releases. The same test fails the same way on the 10.6.0 and 10.5.0 release jars, assertions on and off. It needs the managers, so it does not apply before 10.5.0, and on 10.5.x the page did not name them yet.
• Not a regression test. It asserts the documented promise, so it is evidence for a doc fix: with the fix it would be dropped, or kept with its one assertion changed to the corrected text's example (10 groups, the first being g3), which this doc ran.

cp $REPRO/TestGroupingPackageDocOffset.java $LUCENE/lucene/grouping/src/test/org/apache/lucene/search/grouping/
cd $LUCENE
./gradlew :lucene:grouping:test --tests org.apache.lucene.search.grouping.TestGroupingPackageDocOffset -Ptests.seed=DEADBEEF -Ptests.asserts=true
# assertions off: -Ptests.asserts=false (same failure)

# gradle, main 645d4fe14a20, seed DEADBEEF, -Ptests.asserts=true
TestGroupingPackageDocOffset > testOffsetThreeOfTopTenGivesSevenGroups FAILED
    java.lang.AssertionError: expected:<7> but was:<10>
        at org.apache.lucene.search.grouping.TestGroupingPackageDocOffset.testOffsetThreeOfTopTenGivesSevenGroups(TestGroupingPackageDocOffset.java:52)
BUILD FAILED
# -Ptests.asserts=false: the same AssertionError
# release jars 10.6.0 and 10.5.0, assertions on and off: 1 run, 1 failed, expected:<7> but was:<10>
# the same test with its assertion changed to the fixed text (10 groups, first g3), fix A applied: passes, assertions on and off

• Self-contradiction since 2011: LUCENE-1421's two-pass example passed groupOffset+topNGroups to FirstPassGroupingCollector, and LUCENE-3129's Block example new BlockGroupingCollector(groupSort, groupOffset+topNGroups, ...) with getTopGroups(withinGroupSort, groupOffset, ...). Run with topNGroups 10 and groupOffset 3, that example returns 10 groups on 9.12.3, 10.4.0, 10.5.2, 10.6.0 and main.
• The code is intended: in the #15936 review a reviewer asked whether the Block manager should "also use groupOffset", and the author changed it to groupOffset+topNGroups to match GroupingSearch. TestGrouping's oracle computes limit = Math.min(groupOffset + topNGroups, groups.size()) and returns limit - groupOffset groups (TestGrouping.java:676, :680), and passes groupOffset, topNGroups straight to both managers (:1110-1112, :1300-1309).
• Nothing endorses the bullet for the managers: #16385 rewrote the class names and the example at a reviewer's request and left the inputs list; no review comment discusses it, no test uses (3, 10) or asserts the bullet's 7 groups (the assertEquals(7, ...) calls in TestGrouping.java:173-174 and TestGroupingSearch.java:125-126 check hit counts).

Strongest case (a separate intended-behaviour verifier and a cross-model reviewer, OpenAI GPT-5.6, works-as-designed lens): the inputs list is a 2011 conceptual description of the low-level collectors; "how many top groups to keep" is their @param word for word, and for them "7 groups" is exactly right; the managers' meaning was decided in review and is tested; GroupingSearch documents it; the looseness is 15 years old and unreported.

Why it fails: all of that shows the code is right, which is the claim. The 10.6 page names no plain collector; it names the managers and shows a manager example, and for every paging API it names (both managers and GroupingSearch) its example "3 means you'll get 7 groups back" is false. The managers' own @param texts read like the bullet, so a manager user has nothing that corrects it.

The behaviour is intended, so every option is a text change. Option A was applied in a scratch worktree of 645d4fe14a20; option B was built on top of it.

Replace package-info.java:37-41 with the text below. A shorter variant keeps only the first two bullets plus one sentence on the plain collectors.

 *   <li><code>topNGroups</code>: how many groups to return, counted from <code>groupOffset</code>.
 *       For example, 10 means up to 10 groups are returned.
 *   <li><code>groupOffset</code>: which "slice" of top groups you want to retrieve. For example, 3
 *       with <code>topNGroups</code> 10 returns the groups ranked 4 to 13. This is useful for
 *       paging, where you might show 5 groups per page: page <code>p</code> (counting from 0) uses
 *       <code>groupOffset</code> 5*p and <code>topNGroups</code> 5. This is how {@link
 *       org.apache.lucene.search.grouping.GroupingSearch} and the collector managers below read
 *       these inputs. The low-level collectors ({@link
 *       org.apache.lucene.search.grouping.FirstPassGroupingCollector}, {@link
 *       org.apache.lucene.search.grouping.BlockGroupingCollector}) instead keep a number of groups
 *       that includes the offset: create them with <code>groupOffset + topNGroups</code> and pass
 *       <code>groupOffset</code> to <code>getTopGroups</code>.

Trade-offs

Text only. Keeps the page's paging example and makes it concrete; names both plain collectors, as the adjudication and the cross-model works-as-designed review asked (the hunt's first diff named only the first-pass one). "The collector managers below" means the two that take these inputs (FirstPassGroupingCollectorManager, BlockGroupingCollectorManager); the other managers on the page (TopGroupsCollectorManager, AllGroupHeadsCollectorManager, TermGroupFacetCollectorManager) take neither.

What the checks validated

• :lucene:grouping:checkGoogleJavaFormat and :lucene:grouping:renderJavadoc pass; the rendered package summary shows the new text with working links to GroupingSearch, FirstPassGroupingCollector and BlockGroupingCollector.
• The minimal test fails before the fix with assertions on and off; the same test with its one assertion changed to the new text's example (10 groups, first g3, ranks 4 to 13) passes with assertions on and off.
• The whole :lucene:grouping:test with assertions on: 15 classes, 57 tests, 0 failures (TestGrouping 7/7); TestGrouping again with assertions off: 0 failures. Seed DEADBEEF, OpenJDK 25.0.3.

FirstPassGroupingCollectorManager (both constructors): @param groupOffset "how many top groups to skip", @param topNGroups "how many groups to return after the skipped ones"; BlockGroupingCollectorManager: @param topNGroups "how many groups to return, starting at groupOffset".

Trade-offs

Removes the ambiguity at the source a manager user reads first; five @param lines reworded in three constructor javadocs (no lines added).

What the checks validated

With A applied: checkGoogleJavaFormat and renderJavadoc pass for the grouping module.

Making the managers' topNGroups include the offset would break GroupingSearch's documented groupLimit, the TestGrouping oracle and every existing manager caller, and reverse the choice made in the #15936 review. Deleting only the "7 groups" sentence would leave "how many top groups to keep" as ambiguous as the managers' @param texts.

Trade-offs

Not run.

• First signal: reading the package text against a hunt unit's site model (int offset + limit sums in grouping), 2026-10-28. No model produced or witnessed the defect, so the finding is non-formal.
• Repro: the finder's JUnit (15 one-document groups, both managers and a plain-collector control) failed 2 of 3 on main with assertions on and off and on the 10.6.0 release commit; the control passed.
• Minimal repro (2026-10-29): cut to one method, the first-pass manager only, 13 groups; fails on main 645d4fe14a20 with assertions on and off.