Block grouping reports the wrong group maxScore when you page inside groups: the score of the first document on the page, or -Infinity for an empty page (regression in 10.5.0)

With block grouping (GroupingSearch(Query groupEndDocs), BlockGroupingCollector or BlockGroupingCollectorManager) and the default relevance order inside groups, a request for a later page inside each group (setGroupDocsOffset(n), withinGroupOffset > 0) reports each group's maxScore as the score of the first document on that page, or -Infinity when the page is past the end of the group, and TopGroups.maxScore inherits the wrong value. GroupDocs.maxScore is documented as "Max score in this group" and TopGroups.maxScore as "Highest score across all hits". The cause is #15942 (first released in 10.5.0), an optimisation that reads the group maximum from the top hit of the page; that is right only for offset 0, the default. In the repro, blocks with scores 5, 3, 1 and 4, 2 and page 2 at 2 per page give maxScores 1 and -Infinity (1 overall) instead of 5 and 4 (5 overall). The returned documents, their order and the hit counts are correct.

• Block grouping: documents of one group are indexed together with IndexWriter.addDocuments, and a query (groupEndDocs) matches the last document of each block. GroupingSearch(Query) builds a BlockGroupingCollectorManager for it (GroupingSearch.java:221-237).
• Within-group page: withinGroupOffset (setGroupDocsOffset) and the page size (setGroupDocsLimit); the package docs describe the offset as "which 'slice' of top documents you want to retrieve from each group" (package-info.java:45-46).
• maxScore: GroupDocs.maxScore, "Max score in this group" (GroupDocs.java:27); TopGroups.maxScore, "Highest score across all hits, or Float.NaN if scores were not computed" (TopGroups.java:59).

1. GroupingSearch.groupByDocBlock passes groupDocsOffset as withinGroupOffset and groupDocsOffset + groupDocsLimit as maxDocsPerGroup (GroupingSearch.java:234-235); the manager calls getTopGroups(withinGroupSort, 0, withinGroupOffset, maxDocsPerGroup) (BlockGroupingCollectorManager.java:152).
2. In BlockGroupingCollector.getTopGroups, groupMaxScore starts at Float.NEGATIVE_INFINITY (BlockGroupingCollector.java:302). The loop over the group's documents takes Math.max only when the within-group sort is not relevance (:309-311, added by #15942).
3. topDocs = collector.topDocs(withinGroupOffset, maxDocsPerGroup) (:324) is the requested page, which starts after the offset. For a relevance sort, groupMaxScore = topDocs.scoreDocs[0].score (:325-327, added by #15942): the (offset+1)-th best score. An empty page assigns nothing, so -Infinity stays.
4. TopGroups.maxScore is groups[0].maxScore() with a relevance group sort (:344-346) or the maximum of the per-group values otherwise (:339-341), so it inherits the wrong per-group values.

• Only GroupDocs.maxScore and TopGroups.maxScore are wrong. The pages, their order, the per-group hit counts and the group order match an exact model (an executed probe: 40 random indexes per target, some with several segments, with random deletions and a FILTER clause).
• A field sort inside groups still takes the maximum over every document and is right.
• Offset 0, the default, is right.

• Who is hit. Code that pages inside block groups under relevance order and normalises or shows scores per group (score / maxScore) or uses TopGroups.maxScore. The value is wrong, deterministically, whenever the first document on the requested page scores below the group's best (with distinct scores, every group on every such page), and it is -Infinity for every empty page. It is right when that document ties the group's best: with tied top scores (groups 5, 5, 1 and 4, 4, offset 1, 2 per page) block grouping reports 5, 4 and 5 on main (executed). With constant-score or filter-only queries every document ties, so there only the empty pages are wrong.
• Default or opt-in. Relevance order inside groups is the default (GroupingSearch.java:51-52); paging inside groups is opt-in (default offset 0, unaffected).
• Effect. A lower number than the real maximum, or -Infinity for a group that has hits. Scores normalised by it are relative to the page, not the group: the page's first hit gets 1 (with offset 1, 3/3 instead of 3/5), and only a score from an earlier page of the group would get a ratio above 1. A positive score divided by -Infinity gives -0.0. No error.
• Scale. None needed: 5 documents in the repro.
• How likely: rare. A GitHub code search (exact class names, default branches) found no use of BlockGroupingCollector or BlockGroupingCollectorManager in Solr, Elasticsearch or OpenSearch; it cannot see private applications. The bug has shipped only since 10.5.0, and the searches below found no user report.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: group maxScore expected:<2.0> but was:<1.0>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:577)
       org.apache.lucene.search.grouping.TestBlockGroupingMaxScoreOffset.testMaxScoreWithGroupDocsOffset(TestBlockGroupingMaxScoreOffset.java:58)

• Contracts. GroupDocs.java:27 "Max score in this group" (the same record's totalHits counts every hit of the group); TopGroups.java:59 "Highest score across all hits"; GroupingSearch.java:330 "Whether to include the score of the most relevant document per group".
• Legal trigger. package-info.java:45-46 documents withinGroupOffset, the block example at :129-137 passes docOffset, and BlockGroupingCollectorManager.java:93 documents and :120-122 validates it.
• Siblings. Two-pass TopGroupsCollector.java:177-190 reads allTopDocs.scoreDocs[0] and then slices from withinGroupOffset; TopGroups.merge (#15879, by the same author) reads mergedTopDocs.scoreDocs[0] (TopGroups.java:239-246) before slicing by docOffset (:250-260).
• History. Block grouping reported the group maximum in every release run from 8.0.0 to 10.4.0 (8.0.0, 8.11.4, 9.12.3, 10.0.0, 10.3.2, 10.4.0; executed). The releases in between were not run; none of them contains the #15942 backport.
• Intent. lucene/CHANGES.txt:1093 lists #15942 under 10.5.0 Optimizations. Its PR text: "For the groupMaxScore, we can get the maxScore from the top scoreDoc in the merged top docs", which is equivalent only for offset 0. The commit changed only BlockGroupingCollector.java and CHANGES.txt, with no test.
• Why tests missed it. TestGrouping.java:1632-1633 has the maxScore comparison as a commented-out TODO since 2011; TestBlockGrouping and TestGroupingSearch never assert maxScore.

The strongest case for "intended" (the works-as-designed reviewer from another model family, OpenAI GPT-5.6, and the intended-behaviour devil's advocate): #15942 was a deliberate, reviewed change; the grouping API is @lucene.experimental; no test pins maxScore with an offset; and maxScore could be read as the best score on the returned page.

Why it fails: every javadoc says whole group or all hits; experimental allows API changes, not values that contradict their own javadoc; the same optimisation on the two other paths takes the maximum before the offset; the CHANGES entry announces no change in meaning; and -Infinity for a group with 2 hits is not a page maximum either. The refute reviewer and the works-as-designed reviewer rated the intended argument weak; the devil's advocate concluded that no intended argument survives.

Two fixes were validated; a third was not built. Either validated fix also corrects TopGroups.maxScore, which reads the per-group values. That holds for a search with one slice: the separate TopGroups.mergeBlockGroups problem with an executor and several slices (LFV-239, TopGroups.java:404-420) is not touched by either.

In BlockGroupingCollector.getTopGroups (1 file, +5/-2). With offset 0 the page is never empty (a group has at least one hit and maxDocsPerGroup >= 1 is validated), so the shortcut stays exact there; for an offset above 0 the loop that already visits every document takes the maximum. The hunt's judge proposed this shape (the devil's advocate asked that a fix keep the offset-0 saving); it was first built and run for this doc.

// The first hit of a relevance-sorted page is the group's best hit only if the page starts at
// the group's first document
final boolean maxScoreFromFirstHit = withinGroupSortByRelevance && withinGroupOffset == 0;
...
  if (!maxScoreFromFirstHit) {
    groupMaxScore = Math.max(groupMaxScore, fakeScorer.score);
  }
...
if (maxScoreFromFirstHit && topDocs.scoreDocs.length > 0) {
  groupMaxScore = topDocs.scoreDocs[0].score;
}

Trade-offs

Keeps #15942's optimisation for the default offset 0; slightly more logic than a plain revert.

What the checks validated

Scratch worktree of 645d4fe14a20, gradle, JDK 25.0.3: stock + test 1 of 1 fails (assertions on and off); fix + test: the whole :lucene:grouping:test (15 suites, 57 tests, incl. TestBlockGrouping, TestGrouping, TestGroupingSearch, TestTopGroups) passes with -Ptests.asserts=true and false; :lucene:grouping:check -x test (google-java-format, ecjLint, forbiddenApis) succeeds. The finder's 3 tests (incl. the offset-0 control) and an independent 5-test suite (incl. three controls) pass with the fixed class.

Always take Math.max in the loop and drop the assignment from scoreDocs[0] (+1/-6). The value then no longer depends on the sort.

if (needsScores) {
  fakeScorer.score = og.scores[docIDX];
  groupMaxScore = Math.max(groupMaxScore, fakeScorer.score);
}

Trade-offs

Simplest. Gives up #15942's saving: one Math.max per document of each returned group, in a loop that runs anyway (not measured).

What the checks validated

The finder's fix: their test, the cross-model refute reviewer's own test and an independent 5-test suite pass; the refute review ran upstream TestBlockGrouping, TestGroupingSearch and TestTopGroups green; 10.5.2 with the #15942 hunks reverted passes. This doc's test passes with it.

Take collector.topDocs() once, read scoreDocs[0].score as the group maximum, then slice from withinGroupOffset, as TopGroupsCollector.java:177-190 does.

Trade-offs

Consistent with the sibling path, but more code, and the page is then built by slicing instead of topDocs(start, howMany), which a reviewer would have to check for equivalence.

Method: semi-formal (a hypothesis while writing a harness's exact reference semantics, then witnessed by the harness on the stock jar).

• Harness. A bounded-exhaustive translation-validation harness for grouping: tiny indexes with groups in {A, B, none} and values {0, 1, 2}, every split into segments, 7 slicings, every group sort x within-group sort x group page x document page, compared with an exact reference model and with two-pass term grouping.
• Signal. The kinds BREF:GROUP_MAXSCORE, BLOCK_VS_TERM:GROUP_MAXSCORE and BDIST:GROUP_MAXSCORE reported mismatches in block cases with a within-group offset above 0 and a relevance within-group sort (scope block5: 19,683 indexes, 13,988,052 checks, 29 s; 1,208,571, 1,107,897 and 211,137 mismatches, counts not split by root cause). With the hunt unit's combined grouping fixes shadowed, the BREF:GROUP_MAXSCORE kind disappears.
• Repro. Minimised by hand to two blocks; this doc's one-method test is a further reduction.